Skip to main content
Glama
Native Research MCP

Native Research MCP

by pipiwego
README.md
# Native Research MCP

A stateful MCP server for DeepSeek-native web research and focused page reading.

The server uses the OpenAI Python SDK and the official MCP Python SDK.
The configured provider executes native web tools.
The server stores visible evidence and supports follow-up questions and recovery.

This project is independent of DeepSeek and OpenAI.
It does not include credentials, a private endpoint, or a hosted service.

## Install

Use Python 3.11 or later.

```sh
python -m venv .venv
. .venv/bin/activate
pip install "git+https://github.com/pipiwego/native-research-mcp.git@v0.1.0"
```

## Configure an MCP client

Set `NATIVE_RESEARCH_API_KEY` in the environment that starts the server.
Do not put credentials in a tracked file or command argument.

Use the executable path from your environment in the client's stdio MCP configuration:

```json
{
  "mcpServers": {
    "native_research": {
      "command": "/absolute/path/to/.venv/bin/native-research-mcp"
    }
  }
}
```

Client configuration formats can differ.
If the client does not inherit environment variables, use its credential store or environment-forwarding feature.

The default endpoint is `https://api.deepseek.com/v1`.
The default model is `deepseek-flash`.
A custom endpoint must support Responses streaming and DeepSeek-native web tools.
An OpenAI-compatible text endpoint alone is not sufficient.
Restart the server after you change its environment.

| Environment variable | Function |
|---|---|
| `NATIVE_RESEARCH_API_KEY` | Provider credential; no file fallback |
| `NATIVE_RESEARCH_BASE_URL` | Responses API base URL |
| `NATIVE_RESEARCH_MODEL` | Model identifier |
| `NATIVE_RESEARCH_DATA_DIR` | Local evidence and state directory |
| `NATIVE_RESEARCH_REQUEST_TIMEOUT` | Timeout for provider requests |

When no data directory is set, the server uses the account data directory from `platformdirs`.

## MCP tools

| Tool | Function |
|---|---|
| `research_start` | Create a task with a goal and scope |
| `research_status` | Read the current revision and request state |
| `deepseek_search` | Extend a task through native web research |
| `deepseek_read_url` | Read a public page with a specific focus |
| `research_evidence` | Read saved evidence without a provider request |
| `research_recover` | Organize saved evidence without search or fetch tools |

Each tool describes its input and its place in the workflow.
No separate skill or client-specific prompt is necessary.

For each follow-up, use the task ID and current revision.
Use a new question to extend the task.
Use `refresh` when cached evidence is too old for the question.

## Architecture

```text
MCP client
    |
    v
Official MCP SDK -> Research service -> Official OpenAI SDK
                        |                       |
                        v                       v
                SQLite + JSONL          Native provider tools
```

- `server.py` defines MCP tools and validates input.
- `config.py` reads environment settings.
- `engine.py` controls revisions, append-only history, evidence, and recovery.
- `storage.py` stores task and evidence records in SQLite.
- `transport.py` processes Responses events and reuses the SDK connection pool.
- `urls.py` normalizes source URLs and rejects explicit local addresses.

The server keeps a stable task prefix and appends new questions and visible evidence.
It does not add topic classification templates to every request.
When history exceeds its bound, it creates an explicit checkpoint.
Detailed evidence remains available by ID.

The server records complete evidence lines before final synthesis.
After output interruption, it can organize saved evidence without another web request.
It does not depend on opaque signatures to restore a page.

## Boundaries

- A native request can contain more than one search or page read.
- Token and time limits apply between requests, not inside provider execution.
- Domain preferences keep out-of-domain sources with a label.
- `strict` limits accepted evidence, not provider-side browsing.
- Page text and evidence are untrusted input, not instructions.
- Extracted quotations are model output, not independently verified page bytes.
- Lexical URL checks do not provide DNS, redirect, or remote SSRF isolation.
- A saved source URL does not prove a new claim.
- Native page truncation can still need a focused follow-up.
- Local state and journals can contain sensitive research content.
- This stdio server is not a multi-user isolation service.

See [SECURITY.md](SECURITY.md) for data-handling boundaries.

## Development

```sh
pip install -e ".[dev]"
pytest
ruff check src tests
python -m build
```

Tests use synthetic data and a fake provider.
They do not use credentials or make provider requests.

## License

MIT. See [LICENSE](LICENSE).

TDQS

B3.4/5.0

Scored across 6 tools

Disambiguation4/5

The tools cover distinct research lifecycle stages: start, search, URL read, evidence read, status, and recovery. There is some potential overlap between research_evidence and research_recover, and between deepseek_read_url and research_evidence, but the descriptions clarify saved extraction versus provider fetch versus recovery.

Naming Consistency4/5

All names use snake_case and coherent domain prefixes: research_* for task lifecycle and deepseek_* for provider actions. The only inconsistency is that some research_* names are verbs (start, recover) while others are resource nouns (evidence, status).

Tool Count5/5

Six tools is well within the 3-15 range and each covers a distinct step in the research workflow. No tool appears redundant or filler.

Completeness4/5

Core research lifecycle is covered: start, search, read, inspect evidence/status, and recover. Minor gaps remain, such as no explicit finish/synthesize/cancel or list-evidence operation, but agents can work around these via status and evidence IDs.

Maintenance

ActivityMaintained
ResponsivenessOutdated data