Metadata-Version: 2.5
Name: deepsieve-mcp
Version: 0.3.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<2,>=1.2.0
Description-Content-Type: text/markdown

# DeepSieve MCP server

> **Two ways to connect.** This package is the **stdio + API-key** server —
> ideal for CI, containers, and services. Where a deployment has the **remote
> server with browser login** enabled, that route is easier for a developer at
> their editor — no key to manage. It is not enabled on every deployment, so
> see <https://deepsieve.ai/developers/mcp> for the current endpoint rather
> than assuming one.

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

> 🛑 **0.1.0 does not start, and 0.1.1 fixes it.** 0.1.0 declared an unbounded
> `mcp>=1.2.0`; `mcp` 2.x renamed `FastMCP` to `MCPServer`, so on 0.1.0 `uvx
> deepsieve-mcp` fails with
> `ModuleNotFoundError: No module named 'mcp.server.fastmcp'`. Nothing in this
> package changed — the dependency released a major, months after we published.
>
> **0.1.1 caps the dependency at `mcp<2` and starts normally**, so plain `uvx
> deepsieve-mcp` is correct again. **If you are pinned to 0.1.0**, add one flag:
> `uvx --with 'mcp<2' deepsieve-mcp` (or `"args": ["--with", "mcp<2",
> "deepsieve-mcp"]` in the JSON below).
>
> The port to `mcp` 2.x — which is what will let the cap come off — is tracked
> in **#796**.

```bash
# Claude Code
claude mcp add deepsieve \
  --env DEEPSIEVE_API_KEY=ds_live_... \
  --env DEEPSIEVE_API_URL=https://deepsieve.ai \
  -- uvx deepsieve-mcp
```

Manual `mcpServers` JSON (Cursor, Claude Desktop):

```json
{
  "mcpServers": {
    "deepsieve": {
      "command": "uvx",
      "args": ["deepsieve-mcp"],
      "env": {
        "DEEPSIEVE_API_KEY": "ds_live_...",
        "DEEPSIEVE_API_URL": "https://deepsieve.ai"
      }
    }
  }
}
```

`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` · `list_members`

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).
