Skip to main content
Glama
Native Research MCP

Native Research MCP

by pipiwego

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.

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

Related MCP server: @kyaulabs/deepseek-websearch

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:

{
  "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

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 for data-handling boundaries.

Development

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.

Available Tools

6 tools
deepseek_read_urlB
Read-only

Read a public page for a specific question. A new focus extends earlier evidence. Native tools can truncate long pages.

Inputs: gap (required), url (required), focus (required), research_id (required), +2 more.

research_evidenceA
Read-onlyIdempotent

Read saved evidence by ID without a provider request. Evidence contains model extractions, not raw page bytes.

Inputs: research_id (required), evidence_ids.

research_recoverC
Read-only

Recover from saved visible evidence. This operation uses a model request without search or fetch tools.

Inputs: gap (required), research_id (required), parent_revision (required).

research_startB
Read-only

Start a research task with a goal and scope. Domain preferences do not restrict provider browsing. Budgets apply between requests.

Inputs: goal (required), scope (required), effort, domains, +5 more.

research_statusA
Read-onlyIdempotent

Read the current revision, request status, and evidence count without a provider request.

Inputs: research_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    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

    Related MCP Connectors

    Related MCP Servers