ResearchTwin MCP Server

ResearchTwin MCP Server 是 ResearchTwin 的持久化操作层，ResearchTwin 是一个长期研究项目智能体。它为 OpenTrek 托管的智能体提供真实的 MCP 工具，用于记录研究工作、保留项目状态和导师要求，并生成基于证据的进度报告。

该仓库被设计为竞赛级参考实现：RAG 从研究材料中回答问题，而 MCP 对项目记录执行显式、可审计的更改。

所有提交的示例均为虚构且已匿名化。运营数据属于 runtime_data/，并有意从 Git 中排除。

概述

研究助手不应只回答单个问题。ResearchTwin 在持续演进的项目中保留持久的工作记录：

• 具体的活动、成果、障碍和后续步骤；

• 当前项目阶段、任务、风险和决策；

• 结构化的导师要求；

• 从持久化证据汇编的周报、会议或阶段报告。

该服务器旨在由 OpenTrek 中的 ResearchTwin Agent 调用。它不替代智能体、LLM 或现有的 ResearchTwin_Docs 知识库。

Related MCP server: AgentBase

为什么选择 MCP

RAG 和 MCP 具有不同的职责：

这种分离使项目记录保持确定性和可审查性。MCP 服务器无需仅为了存储结构化活动或从存储的事实生成报告而运行另一个 LLM。

架构

flowchart LR
    U[Researcher] --> A[OpenTrek ResearchTwin Agent]
    A -->|retrieve and reason| R[ResearchTwin_Docs RAG]
    R --> K[Research papers and technical material]
    A -->|MCP function calls| M[ResearchTwin MCP Server]
    M --> T[Six research-management tools]
    T --> S[JSON persistence layer]
    S --> D[Runtime research records and reports]

组件边界、持久化规则和扩展点请参阅 docs/architecture.md。

功能特性

• 官方 Python MCP SDK 集成。

• 以 Streamable HTTP 作为 /mcp 处的主要 MCP 传输方式。

• 可选的命令行 SSE 兼容传输，在启动时选择。

• 六个聚焦的工具，而非单体服务器脚本。

• 采用原子替换和进程内锁的 UTF-8 JSON 持久化。

• UUID 记录标识符和时区感知的 ISO 8601 时间戳。

• 适合智能体工具处理的结构化成功和错误响应。

• Windows PowerShell 启动、测试、冒烟测试和 OpenTrek 集成指南。

MCP 工具

完整的输入、输出和错误契约见 docs/mcp_tools.md。

项目结构

ResearchTwin-MCP-Server/
├── server.py                         # Repository-root launch entry point
├── src/researchtwin_mcp/
│   ├── config.py                     # RESEARCHTWIN_* settings validation
│   ├── server.py                     # MCP server and transport startup
│   ├── models/                       # Validation helpers and schemas
│   ├── storage/                      # Shared JSON persistence layer
│   └── tools/                        # Activity, status, advisor, and report tools
├── scripts/
│   ├── start_server.ps1
│   └── smoke_test.py
├── tests/
├── docs/
├── examples/sample_data/             # Fictional, commit-safe demo data
└── runtime_data/                     # Local operational data; ignored by Git

要求

• Windows PowerShell（文档化的工作流程）

• Python 3.11 或更新版本；Python 3.11.x 是推荐的竞赛环境

• 仅当 OpenTrek 从局域网上的另一台设备运行时才需要网络访问

安装

在新的 Windows PowerShell 会话中：

Set-Location C:\work\OpenTrek\ResearchTwin-MCP-Server
python --version
where.exe python

python -m venv .venv
.\.venv\Scripts\Activate.ps1

python --version
where.exe python
python -m pip install --upgrade pip setuptools wheel
python -m pip install -e ".[dev]"

激活后，where.exe python 的第一个结果应为虚拟环境解释器。如果 PowerShell 阻止当前会话的激活，请使用其文档化的进程级执行策略过程，然后重新激活环境；不要不必要地削弱系统级策略。

配置

服务器从进程环境读取以下环境变量：

.env.example 仅作为参考/模板；服务器不会自动加载 .env 文件。在 PowerShell 会话中设置值，或者如果您的部署已有外部环境加载器，则使用它：

$env:RESEARCHTWIN_HOST = "0.0.0.0"
$env:RESEARCHTWIN_PORT = "8000"
$env:RESEARCHTWIN_DATA_DIR = "runtime_data"
$env:RESEARCHTWIN_LOG_LEVEL = "INFO"

不要将密钥、个人标识符或用户特定的 IP 地址放入源代码或已提交的配置中。

运行

在虚拟环境激活的情况下：

python server.py

默认主端点为：

http://<LAN_IPV4>:8000/mcp

仅限本地机器时，将 <LAN_IPV4> 替换为 127.0.0.1。对于另一台受信任局域网设备上的 OpenTrek，请使用 Windows 主机适用的 IPv4 地址。辅助脚本也可用：

.\scripts\start_server.ps1

Streamable HTTP 是正常模式。如需显式 SSE 兼容性，请运行 python server.py --transport sse 并按照 OpenTrek 集成指南 中的说明注册生成的 /sse 端点。SSE 是单独选择的传输模式，不是与 /mcp 并列注册的替代 URL。

测试

从仓库根目录运行单元测试：

pytest -v

安装依赖后运行本地 MCP Streamable HTTP 冒烟测试：

python scripts\smoke_test.py

冒烟测试验证实际协议连接、工具发现以及活动记录/列表往返。它使用隔离的临时数据，而非您的 runtime_data/ 目录。

OpenTrek 集成

OpenTrek 注册应使用 UI 的 STREAMABLE 选项和以下 URL 格式：

http://<LAN_IPV4>:8000/mcp

不要手工编造 transportType JSON 值。在 OpenTrek MCP 注册页面上选择 STREAMABLE，输入 URL，保存，并验证所有六个工具均被发现。有关局域网 IPv4 发现、SSE 兼容性、VPN 检查和安全的防火墙故障排除过程，请参阅 docs/open_trek_integration.md。

演示场景

端到端演示可以展示知识检索与持久化操作之间的区别：

1. 智能体使用 RAG 解释一篇虚构的 RNN-PPO 论文或方法笔记。

2. 研究人员表示 RNN-PPO 实验已完成，但训练仍不稳定。

3. 智能体调用 record_research_activity 记录结果、问题和后续步骤。

4. 使用 record_advisor_instruction 记录一条虚构的导师要求，要求关注泛化能力。

5. 智能体检查项目状态，然后调用 generate_research_report 生成组会报告。

生成的 Markdown 报告基于持久化记录，而非单轮回答。带解说的运行手册见 docs/demo_flow.md。

隐私与 Git 安全

仓库的 .gitignore 排除了 .venv/、pycache/、Python 字节码、.env、pytest 和 Ruff 缓存、runtime_data/ 以及日志文件。这些路径可能包含本地研究活动、导师上下文、报告、凭据或机器特定数据。

只有 examples/sample_data/ 中的虚构、匿名固定数据可以安全提交。在任何提交或推送之前，请检查：

git status
git diff --check

切勿提交真实的导师消息、真实论文内容、聊天记录、密钥、VPN 详情或个人身份信息。

路线图

• 在需要时将 JSON 文件迁移到持久的多用户存储后端。

• 添加 ResearchTwin Memory 和 ResearchTwin_Core 集成点。

• 在现有 RAG 层之上添加论文智能和引用工作流。

• 添加用于审查项目历史和报告的保护仪表板。

• 在不暴露真实研究数据的情况下改进竞赛演示故事。

文档

• 架构

• MCP 工具参考

• OpenTrek 集成

• 演示流程

• 虚构示例数据