# Valstorm Hosted MCP Server (valstorm-mcp)

> Stateless Streamable HTTP, SSE, and stdio Model Context Protocol (MCP) server exposing 16 granularly scoped Valstorm VFS, SQL, and CRM tools.

- **GitHub Repository:** https://github.com/Valstorm-Corp/valstorm-mcp
- **License:** PolyForm Noncommercial License 1.0.0 (https://polyformproject.org/licenses/noncommercial/1.0.0)
- **Installation:** `uv tool install git+https://github.com/Valstorm-Corp/valstorm-mcp`
- **Language/Stack:** Python 3.12+ (FastMCP, Starlette, HTTPX)
- **Web Documentation:** https://www.valstorm.com/free-tools/valstorm-mcp

## Key Capabilities
- **Hybrid Vector Search & Server-Side Gemini RAG:** Exposes vfs_search (dense vector + metadata chunk retrieval) and vfs_ask (synthesized RAG answers with citations) across your private Knowledge Vaults.
- **Full SQL & Mongo Aggregation Engine:** Run Valstorm SQL queries (with dynamic dates like last_n_days:7 and owner = ME) or raw MongoDB aggregation pipelines directly from your AI IDE.
- **Out-of-Band S3 Binary Transfer Orchestrator:** Prevents JSON-RPC context window bloat on large files by returning presigned S3 upload/download URLs and terminal execution recipes.
- **Granular Token Scope Enforcement:** Every tool call validates token scopes (vfs:read, vfs:write, record:read, record:write, query:execute) before proxying to the core API.

## Quickstart
```bash
# 1. Run locally over stdio (for Claude Desktop / Cursor local config)
uv run valstorm-mcp --transport stdio

# 2. Run stateless Streamable HTTP + SSE server on port 8660
uv run valstorm-mcp --transport streamable-http --host 0.0.0.0 --port 8660

# 3. Example MCP Tool Call: Execute Valstorm SQL with ME keyword
# Tool: record_query_sql
{
  "query": "SELECT id, name, status FROM deal WHERE owner = ME ORDER BY created_date DESC LIMIT 10"
}
```