speculate-mcp 0.2.0__tar.gz

speculate_mcp-0.2.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+.venv/
+.env
+*.egg-info/
+dist/
+build/
+
+# uv
+.uv/
+
+# Node
+node_modules/
+.next/
+out/
+
+# Env files (keep examples, ignore actuals)
+.env.local
+!.env.local.example
+!.env.example
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# Claude Code internal config
+CLAUDE.md
+AGENTS.md
+
+# Local notes (not for repo)
+NOTES.md

speculate_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: speculate-mcp
+Version: 0.2.0
+Summary: MCP server for any OpenAPI-described API — resolve, search, and execute
+Project-URL: Homepage, https://speculateapi.dev
+Project-URL: Repository, https://github.com/mgalobll/speculate-app
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# speculate-mcp
+
+MCP server for any OpenAPI-described API. Gives AI agents the ability to resolve, explore, and execute calls against any REST API with an OpenAPI spec — without writing custom integration code.
+
+## What it does
+
+Five tools, covering the full integration loop:
+
+| Tool | What it does |
+|---|---|
+| `resolve_spec` | Load any API by name ("Stripe"), doc URL, or direct spec URL |
+| `describe_auth` | Return exact auth headers, OAuth2 flows, and credential instructions |
+| `search_endpoints` | Find relevant endpoints with a natural language query |
+| `get_endpoint_schema` | Return path params, body fields, types, enums, and required flags |
+| `execute_call` | Execute a live API call and return the response |
+
+## Install
+
+The recommended way — no global install needed:
+
+```bash
+uvx speculate-mcp
+```
+
+Or install globally:
+
+```bash
+pip install speculate-mcp
+# or
+uv tool install speculate-mcp
+```
+
+## Configure your AI IDE
+
+### Claude Code (`~/.claude.json` or project `.claude/settings.json`)
+
+```json
+{
+  "mcpServers": {
+    "speculate": {
+      "command": "speculate-mcp",
+      "env": {
+        "SPECULATE_API_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+### Cursor (`.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "speculate": {
+      "command": "speculate-mcp",
+      "env": {
+        "SPECULATE_API_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "speculate": {
+      "command": "speculate-mcp",
+      "env": {
+        "SPECULATE_API_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+Get your API key at [speculateapi.dev](https://speculateapi.dev). Free tier works without a key (rate-limited).
+
+## Usage example
+
+Once connected, your agent can do things like:
+
+```
+Load the Stripe API, find the endpoint to create a payment intent,
+and make a test call with amount=1000, currency=usd.
+```
+
+The agent will call `resolve_spec("stripe")`, then `search_endpoints(...)`,
+then `execute_call(...)` — all automatically.
+
+## Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `SPECULATE_API_URL` | `https://mcp.speculateapi.dev` | Backend URL (for self-hosted deployments) |
+| `SPECULATE_API_KEY` | _(empty)_ | Your Speculate API key |
+| `MCP_TRANSPORT` | `stdio` | Set to `http` to run as an HTTP server instead of stdio |
+| `PORT` | `8080` | Port to listen on when `MCP_TRANSPORT=http` |
+
+## Self-hosting
+
+Run the backend yourself:
+
+```bash
+cd backend
+cp .env.example .env
+# Set OPENAI_API_KEY in .env
+uv run uvicorn app.main:app --host 0.0.0.0 --port 8000
+```
+
+Then point the MCP server at your instance:
+
+```bash
+SPECULATE_API_URL=http://localhost:8000 speculate-mcp
+```
+
+## Publishing to PyPI
+
+Releases are automated via GitHub Actions. To publish a new version:
+
+1. Update `version` in `pyproject.toml`
+2. Tag and push:
+   ```bash
+   git tag mcp-v0.3.0
+   git push --tags
+   ```
+
+The `publish-mcp.yml` workflow builds and publishes via PyPI trusted publishing (no stored secret needed — requires a configured PyPI environment named `pypi`).
+
+## License
+
+MIT

speculate_mcp-0.2.0/README.md

@@ -0,0 +1,135 @@
+# speculate-mcp
+
+MCP server for any OpenAPI-described API. Gives AI agents the ability to resolve, explore, and execute calls against any REST API with an OpenAPI spec — without writing custom integration code.
+
+## What it does
+
+Five tools, covering the full integration loop:
+
+| Tool | What it does |
+|---|---|
+| `resolve_spec` | Load any API by name ("Stripe"), doc URL, or direct spec URL |
+| `describe_auth` | Return exact auth headers, OAuth2 flows, and credential instructions |
+| `search_endpoints` | Find relevant endpoints with a natural language query |
+| `get_endpoint_schema` | Return path params, body fields, types, enums, and required flags |
+| `execute_call` | Execute a live API call and return the response |
+
+## Install
+
+The recommended way — no global install needed:
+
+```bash
+uvx speculate-mcp
+```
+
+Or install globally:
+
+```bash
+pip install speculate-mcp
+# or
+uv tool install speculate-mcp
+```
+
+## Configure your AI IDE
+
+### Claude Code (`~/.claude.json` or project `.claude/settings.json`)
+
+```json
+{
+  "mcpServers": {
+    "speculate": {
+      "command": "speculate-mcp",
+      "env": {
+        "SPECULATE_API_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+### Cursor (`.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "speculate": {
+      "command": "speculate-mcp",
+      "env": {
+        "SPECULATE_API_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "speculate": {
+      "command": "speculate-mcp",
+      "env": {
+        "SPECULATE_API_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+Get your API key at [speculateapi.dev](https://speculateapi.dev). Free tier works without a key (rate-limited).
+
+## Usage example
+
+Once connected, your agent can do things like:
+
+```
+Load the Stripe API, find the endpoint to create a payment intent,
+and make a test call with amount=1000, currency=usd.
+```
+
+The agent will call `resolve_spec("stripe")`, then `search_endpoints(...)`,
+then `execute_call(...)` — all automatically.
+
+## Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `SPECULATE_API_URL` | `https://mcp.speculateapi.dev` | Backend URL (for self-hosted deployments) |
+| `SPECULATE_API_KEY` | _(empty)_ | Your Speculate API key |
+| `MCP_TRANSPORT` | `stdio` | Set to `http` to run as an HTTP server instead of stdio |
+| `PORT` | `8080` | Port to listen on when `MCP_TRANSPORT=http` |
+
+## Self-hosting
+
+Run the backend yourself:
+
+```bash
+cd backend
+cp .env.example .env
+# Set OPENAI_API_KEY in .env
+uv run uvicorn app.main:app --host 0.0.0.0 --port 8000
+```
+
+Then point the MCP server at your instance:
+
+```bash
+SPECULATE_API_URL=http://localhost:8000 speculate-mcp
+```
+
+## Publishing to PyPI
+
+Releases are automated via GitHub Actions. To publish a new version:
+
+1. Update `version` in `pyproject.toml`
+2. Tag and push:
+   ```bash
+   git tag mcp-v0.3.0
+   git push --tags
+   ```
+
+The `publish-mcp.yml` workflow builds and publishes via PyPI trusted publishing (no stored secret needed — requires a configured PyPI environment named `pypi`).
+
+## License
+
+MIT

speculate_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "speculate-mcp"
+version = "0.2.0"
+description = "MCP server for any OpenAPI-described API — resolve, search, and execute"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.27.0",
+]
+
+[project.scripts]
+speculate-mcp = "speculate_mcp.server:main"
+
+[project.urls]
+Homepage = "https://speculateapi.dev"
+Repository = "https://github.com/mgalobll/speculate-app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["speculate_mcp"]

speculate_mcp-0.2.0/speculate_mcp/__init__.py

@@ -0,0 +1 @@
+"""Speculate MCP server — universal API execution layer for AI agents."""

speculate_mcp-0.2.0/speculate_mcp/server.py

@@ -0,0 +1,243 @@
+"""
+Speculate MCP server.
+
+Exposes three tools to AI agents:
+  resolve_spec       — load any OpenAPI spec by name or URL
+  search_endpoints   — semantic search over a loaded spec
+  execute_call       — execute a live API call against the spec's base URL
+
+Configuration (environment variables):
+  SPECULATE_API_URL   — backend URL (default: https://mcp.speculateapi.dev)
+  SPECULATE_API_KEY   — your Speculate API key (optional on free tier)
+"""
+import json
+import os
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP(
+    "Speculate",
+    instructions=(
+        "Workflow: (1) call resolve_spec to load the API, "
+        "(2) call describe_auth to understand what credentials are needed, "
+        "(3) call search_endpoints to find the right endpoint, "
+        "(4) call get_endpoint_schema for the full parameter and body contract, "
+        "(5) call execute_call with auth in the headers dict. "
+        "Always use the exact path template from search_endpoints (e.g. '/v1/charges/{id}') "
+        "in get_endpoint_schema and execute_call — not the resolved path with real values."
+    ),
+)
+
+_BASE_URL = os.getenv("SPECULATE_API_URL", "https://mcp.speculateapi.dev").rstrip("/")
+_API_KEY = os.getenv("SPECULATE_API_KEY", "")
+_TIMEOUT = 90.0  # spec indexing can take time on cache miss
+
+
+def _headers() -> dict[str, str]:
+    h: dict[str, str] = {"Content-Type": "application/json"}
+    if _API_KEY:
+        h["X-Speculate-Key"] = _API_KEY
+    return h
+
+
+def _raise_for(resp: httpx.Response) -> None:
+    if resp.status_code >= 400:
+        try:
+            detail = resp.json().get("detail", resp.text)
+        except Exception:
+            detail = resp.text
+        raise RuntimeError(f"Speculate API error {resp.status_code}: {detail}")
+
+
+@mcp.tool()
+async def resolve_spec(query: str) -> dict:
+    """
+    Load and index any OpenAPI-described API. Call this first before
+    searching or executing calls.
+
+    Args:
+        query: API name (e.g. "Stripe", "GitHub"), documentation URL,
+               or direct spec URL (JSON or YAML).
+
+    Returns a dict with:
+        session_id     — use this in search_endpoints and execute_call
+        title          — API title from the spec
+        version        — API version
+        endpoint_count — total number of endpoints indexed
+        base_url       — base URL for live API calls
+        cache_hit      — True if the spec was already indexed
+        confidence     — resolution confidence: "high", "medium", or "low"
+    """
+    async with httpx.AsyncClient(timeout=_TIMEOUT) as client:
+        resp = await client.post(
+            f"{_BASE_URL}/mcp/resolve",
+            json={"query": query},
+            headers=_headers(),
+        )
+    _raise_for(resp)
+    return resp.json()
+
+
+@mcp.tool()
+async def search_endpoints(session_id: str, query: str, top_k: int = 8) -> dict:
+    """
+    Search for API endpoints matching a natural language query.
+    Requires a session_id from resolve_spec.
+
+    Args:
+        session_id: from resolve_spec
+        query: natural language description, e.g. "create a payment intent"
+               or "list all users with pagination"
+        top_k: number of results to return (1–20, default 8)
+
+    Returns a dict with:
+        results — list of matching endpoints, each with:
+            method       — HTTP method (GET, POST, etc.)
+            path         — endpoint path, e.g. "/v1/payment_intents"
+            summary      — short description from the spec
+            tags         — spec tags/categories
+            description  — full description (may be empty)
+            score        — relevance score (0–1)
+    """
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        resp = await client.post(
+            f"{_BASE_URL}/mcp/search",
+            json={"session_id": session_id, "query": query, "top_k": top_k},
+            headers=_headers(),
+        )
+    _raise_for(resp)
+    return resp.json()
+
+
+@mcp.tool()
+async def execute_call(
+    session_id: str,
+    method: str,
+    path: str,
+    path_params: dict | None = None,
+    query_params: dict | None = None,
+    body: dict | None = None,
+    headers: dict | None = None,
+) -> dict:
+    """
+    Execute a live API call against the spec's base URL.
+    Requires a session_id from resolve_spec.
+
+    Args:
+        session_id:   from resolve_spec
+        method:       HTTP method — "GET", "POST", "PUT", "PATCH", "DELETE"
+        path:         endpoint path from the spec, e.g. "/v1/charges/{id}"
+        path_params:  values for path template variables, e.g. {"id": "ch_123"}
+        query_params: URL query parameters, e.g. {"limit": "10", "cursor": "abc"}
+        body:         request body as a dict (JSON-encoded automatically)
+        headers:      request headers — include Authorization here,
+                      e.g. {"Authorization": "Bearer sk-..."}
+
+    Returns a dict with:
+        status       — HTTP response status code
+        body         — response body as a string
+        headers      — response headers
+        resolved_url — the full URL that was called
+        truncated    — True if the response was truncated (>10 MB)
+    """
+    async with httpx.AsyncClient(timeout=60.0) as client:
+        resp = await client.post(
+            f"{_BASE_URL}/mcp/execute",
+            json={
+                "session_id": session_id,
+                "method": method,
+                "path": path,
+                "path_params": path_params or {},
+                "query_params": query_params or {},
+                "body": body,
+                "headers": headers or {},
+            },
+            headers=_headers(),
+        )
+    _raise_for(resp)
+    return resp.json()
+
+
+@mcp.tool()
+async def get_endpoint_schema(session_id: str, method: str, path: str) -> dict:
+    """
+    Return the full schema for a specific endpoint: path parameters, query
+    parameters, request body fields with types and constraints, documented
+    response codes, and auth requirements.
+
+    Use the exact path string as returned by search_endpoints
+    (e.g. "/v1/charges/{id}", not "/v1/charges/ch_123").
+
+    Args:
+        session_id: from resolve_spec
+        method:     HTTP method — "GET", "POST", "PUT", "PATCH", "DELETE"
+        path:       endpoint path template, e.g. "/v1/payment_intents/{id}"
+
+    Returns a dict with:
+        method, path, summary, description
+        path_params   — list of path parameters with name, type, required, example
+        query_params  — list of query parameters with name, type, required, example
+        body_schema   — JSON string of an example request body (null if none)
+        body_fields   — list of request body fields with type, required, enum values
+        security      — auth requirements for this endpoint
+        responses     — dict of {status_code: description}
+    """
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        resp = await client.post(
+            f"{_BASE_URL}/mcp/schema",
+            json={"session_id": session_id, "method": method, "path": path},
+            headers=_headers(),
+        )
+    _raise_for(resp)
+    return resp.json()
+
+
+@mcp.tool()
+async def describe_auth(session_id: str) -> dict:
+    """
+    Return complete auth scaffolding for the loaded API.
+
+    Tells you exactly what credentials you need, how to obtain them,
+    and which header/parameter to inject them into. Covers API keys,
+    Bearer tokens, Basic auth, and OAuth2 flows with authorization URLs,
+    token endpoints, and required scopes.
+
+    Args:
+        session_id: from resolve_spec
+
+    Returns a dict with:
+        has_auth  — False if the API has no documented auth
+        schemes   — list of auth schemes, each with:
+            name              — scheme name from the spec
+            type              — "apiKey", "http", "oauth2", "openIdConnect"
+            inject_as         — "header", "query", or "cookie"
+            header_name       — exact header name to set (e.g. "Authorization")
+            instructions      — step-by-step instructions as a string
+            globally_required — True if required by all endpoints
+            oauth2_flows      — OAuth2 flow details (authorization_url, token_url, scopes)
+    """
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        resp = await client.post(
+            f"{_BASE_URL}/mcp/auth",
+            json={"session_id": session_id},
+            headers=_headers(),
+        )
+    _raise_for(resp)
+    return resp.json()
+
+
+def main() -> None:
+    transport = os.getenv("MCP_TRANSPORT", "stdio")
+    if transport == "http":
+        mcp.run(
+            transport="streamable-http",
+            host="0.0.0.0",
+            port=int(os.getenv("PORT", "8080")),
+        )
+    else:
+        mcp.run()
+
+
+if __name__ == "__main__":
+    main()