Metadata-Version: 2.5
Name: deepsieve-mcp
Version: 0.11.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, …) outcome-shaped
tools over the DeepSieve `/v1` API. With them an agent can check the account,
discover and propose Blueprints, estimate, start and follow research runs, read
and export the cited dataset, review held and conflicting cells, manage
re-research and monitoring, work with reports and chat, and record what your team
knows about the field. The full list is below.

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, read results and create Blueprints,
but it can't change an active Blueprint's schema or your billing.

## Install

> **Pinned to 0.1.0?** Upgrade. It doesn't start, because it allowed `mcp` 2.x,
> which renamed `FastMCP`. Later versions cap the dependency at `mcp<2`, so plain
> `uvx deepsieve-mcp` works. If you can't upgrade, run
> `uvx --with 'mcp<2' deepsieve-mcp`. The port to `mcp` 2.x 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

- **Orientation:** `get_account` · `list_blueprints` · `get_blueprint` · `list_members`
- **Subscription:** `cancel_subscription` (only when your human asked). There is no resume tool on
  purpose: resuming re-arms a charge, so it is for an admin on the billing page, or an
  API key with `billing:write` over the API or CLI.
- **Research:** `estimate_research` · `start_research` · `get_run_status` · `list_runs` ·
  `cancel_run` · `retry_run`. `estimate_research` and `start_research` require `blueprint_id`
  (an id from `list_blueprints`); the API refuses a real run that does not name one.
- **Re-research and monitoring:** `get_reruns` · `approve_reruns` · `set_rerun_auto_approve` ·
  `list_monitoring` · `set_monitoring`
- **Data:** `query_entities` · `export_dataset` · `get_column_changes` · `get_cell_changes` · `list_changes` · `undo_change` · `list_held_cells` · `apply_cell_finding` · `keep_cell_value` · `release_cell` · `list_conflicting_cells` · `choose_cell_value` · `preview_merge` · `merge_records` · `remove_link`
- **Domain knowledge:** `list_knowledge` · `add_knowledge` · `edit_knowledge` · `retire_knowledge` ·
  `restore_knowledge` · `delete_knowledge` · `get_run_knowledge` · `get_knowledge_usage`. Writing
  needs `knowledge:write` and a member role; it changes what later runs are told, never a stored
  value.
- **Reports:** `list_reports` · `get_report_columns` · `create_report` · `get_report_data`
- **Chat:** `ask_research_agent` · `get_chat_thread` · `confirm_chat_action` · `dismiss_chat_action` · `revert_chat_action`
- **Blueprints:** `propose_blueprint_change` · `create_blueprint` · `get_blueprint_draft` ·
  `answer_blueprint_question` · `adjust_blueprint` · `approve_blueprint`
- **Webhooks:** `list_webhooks`

A new draft stops at `ready` or at `awaiting_input`. `awaiting_input` means it has follow-up
questions, and only `answer_blueprint_question` (or approving as it stands) moves it on.

Full API docs: `/developers` on your deployment (also `/llms.txt`).
