deepsieve-mcp 0.1.0__tar.gz

deepsieve_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: deepsieve-mcp
+Version: 0.1.0
+Summary: DeepSieve MCP server — give your agent a cited, self-updating research dataset
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.2.0

deepsieve_mcp-0.1.0/README.md

@@ -0,0 +1,50 @@
+# DeepSieve MCP server
+
+Gives any MCP client (Claude Code, Cursor, Claude Desktop, …) nine
+outcome-shaped tools over the DeepSieve `/v1` API: verify the account,
+discover the Blueprint schema, start/poll/cancel research runs, read the
+cited dataset incrementally, export it, and inspect webhooks.
+
+It is a plain API client — it holds **no** privileged access, only the
+scoped key you give it (mint one with the **Agent** preset at
+`/settings/api-keys`; it can run research and read results but can't touch
+your schema or billing).
+
+## Install
+
+```bash
+# Claude Code
+claude mcp add deepsieve \
+  --env DEEPSIEVE_API_KEY=ds_live_... \
+  --env DEEPSIEVE_API_URL=https://your-deployment.example.com \
+  -- uvx --from /path/to/deep-sieve/mcp-server deepsieve-mcp
+```
+
+Manual `mcpServers` JSON (Cursor, Claude Desktop):
+
+```json
+{
+  "mcpServers": {
+    "deepsieve": {
+      "command": "uvx",
+      "args": ["--from", "/path/to/deep-sieve/mcp-server", "deepsieve-mcp"],
+      "env": {
+        "DEEPSIEVE_API_KEY": "ds_live_...",
+        "DEEPSIEVE_API_URL": "https://your-deployment.example.com"
+      }
+    }
+  }
+}
+```
+
+`DEEPSIEVE_API_URL` defaults to `http://localhost:8200` (local dev stack).
+
+## Tools
+
+`get_account` · `get_blueprint` · `start_research` · `get_run_status` ·
+`list_runs` · `cancel_run` · `query_entities` · `export_dataset` ·
+`list_webhooks`
+
+Full API docs: `/developers` on your deployment (also `/llms.txt`).
+PyPI/npm publishing and a hosted Streamable-HTTP OAuth server are tracked
+follow-ups (issue #116 Phase-2).

deepsieve_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "deepsieve-mcp"
+version = "0.1.0"
+description = "DeepSieve MCP server — give your agent a cited, self-updating research dataset"
+requires-python = ">=3.11"
+dependencies = ["mcp>=1.2.0", "httpx>=0.27"]
+
+[project.scripts]
+deepsieve-mcp = "deepsieve_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/deepsieve_mcp"]

deepsieve_mcp-0.1.0/src/deepsieve_mcp/server.py

@@ -0,0 +1,284 @@
+"""DeepSieve MCP server (#116 item 14) — stdio transport.
+
+Nine outcome-shaped tools over the public ``/v1`` REST API. Deliberately NOT a
+1:1 endpoint wrap: flat arguments, summaries + fetch handles, read-only by
+default. Every call rides the same auth + tenancy + scope guards as any other
+API client — the server holds no privileged access, only the key you give it:
+
+    export DEEPSIEVE_API_KEY=ds_live_...        (required)
+    export DEEPSIEVE_API_URL=https://<your-deployment>   (default local dev)
+
+Install for Claude Code:
+    claude mcp add deepsieve --env DEEPSIEVE_API_KEY=ds_live_... \
+        -- uvx --from /path/to/deep-sieve/mcp-server deepsieve-mcp
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import uuid as _uuid
+from typing import Any
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("deepsieve")
+
+DEFAULT_URL = "http://localhost:8200"
+
+
+def _client() -> httpx.Client:
+    key = os.environ.get("DEEPSIEVE_API_KEY")
+    headers = {"Authorization": f"Bearer {key}"} if key else {}
+    return httpx.Client(
+        base_url=os.environ.get("DEEPSIEVE_API_URL", DEFAULT_URL),
+        headers=headers,
+        timeout=30,
+    )
+
+
+def _call(method: str, path: str, **kwargs) -> Any:
+    """One API call → parsed JSON, with the typed error surfaced verbatim so
+    the agent can read `code`/`retriable` and self-correct."""
+    with _client() as c:
+        r = c.request(method, path, **kwargs)
+        try:
+            body = r.json()
+        except ValueError:
+            r.raise_for_status()
+            return {"raw": r.text}
+        if not r.is_success:
+            err = body.get("error") or {}
+            return {
+                "error": True,
+                "code": err.get("code", str(r.status_code)),
+                "message": err.get("message", r.text[:300]),
+                "retriable": err.get("retriable", False),
+                "request_id": err.get("request_id"),
+            }
+        return body
+
+
+@mcp.tool()
+def get_account() -> str:
+    """Verify the API key works: who am I, which workspace, which scopes."""
+    return json.dumps(_call("GET", "/v1/me"), default=str)
+
+
+@mcp.tool()
+def get_blueprint() -> str:
+    """The active Blueprint's entity catalog — the customer-defined schema
+    (entities + columns). Call this before querying data; never guess columns."""
+    return json.dumps(_call("GET", "/v1/data"), default=str)
+
+
+@mcp.tool()
+def start_research(
+    query: str = "",
+    seeds: list[str] | None = None,
+    guidance: str = "",
+    depth: str = "standard",
+    idempotency_key: str = "",
+    dry_run: bool = False,
+) -> str:
+    """Start an async research run from a natural-language query OR a list of
+    seed URLs/names (exactly one). Returns 202 with a run id — the run takes
+    minutes; poll get_run_status, don't wait inline. Runs cost real money:
+    pass an idempotency_key so your retries never double-bill. dry_run=True is
+    FREE: behaves like a real run (202, poll get_run_status, completes in ~15
+    simulated seconds) and returns sample cited rows in the real schema — use
+    it to build/test the whole poll loop before spending credits."""
+    payload: dict[str, Any] = {"depth": depth, "dry_run": dry_run}
+    if query:
+        payload["query"] = query
+    if seeds:
+        payload["seeds"] = seeds
+    if guidance:
+        payload["guidance"] = guidance
+    headers = {"Idempotency-Key": idempotency_key} if idempotency_key else {}
+    return json.dumps(_call("POST", "/v1/research/runs", json=payload, headers=headers))
+
+
+def _uuid_or_error(run_id: str) -> str | None:
+    """run_id is interpolated into a URL path — reject non-UUIDs so a value
+    like '../keys' can't reach a different endpoint."""
+    try:
+        return str(_uuid.UUID(run_id))
+    except ValueError:
+        return None
+
+
+@mcp.tool()
+def get_run_status(run_id: str) -> str:
+    """Poll a research run: status, done flag, error, progress, metrics."""
+    rid = _uuid_or_error(run_id)
+    if rid is None:
+        return json.dumps({"error": True, "code": "invalid_request", "message": "run_id must be a UUID"})
+    return json.dumps(_call("GET", f"/v1/research/runs/{rid}"), default=str)
+
+
+@mcp.tool()
+def list_runs(status: str = "", limit: int = 20) -> str:
+    """Recent research runs (newest first). Optional status filter:
+    queued|running|cancelling|completed|failed|cancelled."""
+    params: dict[str, Any] = {"limit": limit}
+    if status:
+        params["status"] = status
+    return json.dumps(_call("GET", "/v1/research/runs", params=params), default=str)
+
+
+@mcp.tool()
+def cancel_run(run_id: str) -> str:
+    """Cancel an in-flight research run."""
+    rid = _uuid_or_error(run_id)
+    if rid is None:
+        return json.dumps({"error": True, "code": "invalid_request", "message": "run_id must be a UUID"})
+    return json.dumps(_call("POST", f"/v1/research/runs/{rid}/cancel"), default=str)
+
+
+@mcp.tool()
+def query_entities(
+    entity_key: str,
+    limit: int = 25,
+    cursor: str = "",
+    updated_since: str = "",
+    fields: str = "",
+    receipts: bool = False,
+) -> str:
+    """Read the cited dataset for one entity (cross-run canonical rows).
+    `updated_since` (ISO timestamp) turns this into an incremental sync;
+    `receipts=True` nests per-cell citations (value, confidence, evidence id,
+    source URLs, retrieved_at); `fields` is a comma-separated column subset.
+    Get entity keys + columns from get_blueprint first."""
+    params: dict[str, Any] = {"limit": limit, "receipts": receipts}
+    if cursor:
+        params["cursor"] = cursor
+    if updated_since:
+        params["updated_since"] = updated_since
+    if fields:
+        params["fields"] = fields
+    return json.dumps(_call("GET", f"/v1/data/{entity_key}", params=params), default=str)
+
+
+@mcp.tool()
+def export_dataset(format: str = "ndjson", entity: str = "") -> str:
+    """Export the whole dataset (or one entity) with citations. Formats:
+    ndjson (default; first line is schema metadata), json, csv (csv requires
+    entity). Large datasets: prefer query_entities pagination."""
+    params: dict[str, Any] = {"format": format}
+    if entity:
+        params["entity"] = entity
+    with _client() as c:
+        r = c.get("/v1/export", params=params)
+        if not r.is_success:
+            try:
+                err = r.json().get("error") or {}
+            except ValueError:
+                err = {}
+            return json.dumps(
+                {
+                    "error": True,
+                    "code": err.get("code", str(r.status_code)),
+                    "message": err.get("message", r.text[:300]),
+                    "retriable": err.get("retriable", False),
+                }
+            )
+        text = r.text
+        if len(text) > 200_000:
+            return text[:200_000] + "\n...[truncated — use query_entities to paginate]"
+        return text
+
+
+@mcp.tool()
+def list_reports() -> str:
+    """Saved custom reports (curated cross-run views): id, name, config."""
+    return json.dumps(_call("GET", "/v1/reports"), default=str)
+
+
+@mcp.tool()
+def get_report_columns() -> str:
+    """The valid column vocabulary per entity for building a report config —
+    call before create_report; never guess columns."""
+    return json.dumps(_call("GET", "/v1/reports/columns"), default=str)
+
+
+@mcp.tool()
+def create_report(name: str, config: dict) -> str:
+    """Create a saved report. `config` = {"tabs": [{"id", "name", "entity_key",
+    "columns": [...]}]} using columns from get_report_columns."""
+    return json.dumps(
+        _call("POST", "/v1/reports", json={"name": name, "config": config}), default=str
+    )
+
+
+@mcp.tool()
+def get_report_data(report_id: str, tab_id: str) -> str:
+    """Fresh cross-run rows for one report tab (with per-cell evidence)."""
+    rid = _uuid_or_error(report_id)
+    if rid is None:
+        return json.dumps({"error": True, "code": "invalid_request", "message": "report_id must be a UUID"})
+    return json.dumps(_call("GET", f"/v1/reports/{rid}/tabs/{tab_id}/data"), default=str)
+
+
+@mcp.tool()
+def create_blueprint(prompt: str, idempotency_key: str = "") -> str:
+    """Start creating a NEW Blueprint from a natural-language description of
+    the research domain. Returns a session id — poll get_blueprint_draft until
+    status 'ready' (review the draft + follow-up questions), optionally
+    adjust_blueprint, then approve_blueprint. Editing an ACTIVE Blueprint is
+    human-only; this creates a new one."""
+    headers = {"Idempotency-Key": idempotency_key} if idempotency_key else {}
+    return json.dumps(
+        _call("POST", "/v1/blueprints/onboarding", json={"prompt": prompt}, headers=headers),
+        default=str,
+    )
+
+
+@mcp.tool()
+def get_blueprint_draft(session_id: str) -> str:
+    """Poll an onboarding session: status, draft Blueprint, follow-up questions."""
+    sid = _uuid_or_error(session_id)
+    if sid is None:
+        return json.dumps({"error": True, "code": "invalid_request", "message": "session_id must be a UUID"})
+    return json.dumps(_call("GET", f"/v1/blueprints/onboarding/{sid}"), default=str)
+
+
+@mcp.tool()
+def adjust_blueprint(session_id: str, message: str) -> str:
+    """Ask the Blueprint-inference agent for a change to the DRAFT (e.g. 'add a
+    founded_year column to companies'). 202 — poll get_blueprint_draft until
+    status returns to 'ready', then re-review."""
+    sid = _uuid_or_error(session_id)
+    if sid is None:
+        return json.dumps({"error": True, "code": "invalid_request", "message": "session_id must be a UUID"})
+    return json.dumps(
+        _call("POST", f"/v1/blueprints/onboarding/{sid}/adjust", json={"message": message}),
+        default=str,
+    )
+
+
+@mcp.tool()
+def approve_blueprint(session_id: str) -> str:
+    """Approve the draft → real tables are created and the workspace activates.
+    When acting for a human, show them the draft first — this instantiates
+    schema. Poll get_blueprint_draft until status 'active'."""
+    sid = _uuid_or_error(session_id)
+    if sid is None:
+        return json.dumps({"error": True, "code": "invalid_request", "message": "session_id must be a UUID"})
+    return json.dumps(_call("POST", f"/v1/blueprints/onboarding/{sid}/approve"), default=str)
+
+
+@mcp.tool()
+def list_webhooks() -> str:
+    """Registered webhook endpoints for this workspace (run.completed/failed/
+    cancelled + dataset.updated events, Standard Webhooks signatures)."""
+    return json.dumps(_call("GET", "/v1/webhooks"), default=str)
+
+
+def main() -> None:
+    mcp.run()  # stdio transport
+
+
+if __name__ == "__main__":
+    main()