ResearchTwin MCP Server

ResearchTwin MCP Server — это постоянный уровень действий для ResearchTwin, агента долгосрочных исследовательских проектов. Он предоставляет агенту, размещённому в OpenTrek, реальные MCP-инструменты для записи исследовательской работы, сохранения состояния проекта и требований научного руководителя, а также для формирования отчётов о прогрессе на основе фактических данных.

Репозиторий задуман как эталонная реализация уровня конкурса: RAG отвечает на вопросы по исследовательским материалам, а MCP выполняет явные, проверяемые изменения в записи проекта.

Все приведённые примеры вымышлены и анонимизированы. Операционные данные должны находиться в runtime_data/ и намеренно исключены из Git.

Обзор

Исследовательский ассистент должен делать больше, чем просто отвечать на один вопрос. ResearchTwin ведёт долговременную запись того, что происходило в развивающемся проекте:

• конкретные действия, результаты, блокеры и следующие шаги;

• текущий этап проекта, задачи, риски и решения;

• структурированные требования научного руководителя;

• еженедельные, встречные или этапные отчёты, собираемые из сохранённых фактов.

Сервер предназначен для вызова агентом ResearchTwin в OpenTrek. Он не заменяет агента, 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 с учётом часового пояса.

• Структурированные ответы об успехе и ошибках, подходящие для обработки инструментами агента.

• Инструкции по запуску, тестированию, смоук-тесту и интеграции с OpenTrek в Windows PowerShell.

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

Первый результат from 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 на другом доверенном устройстве в локальной сети используйте соответствующий IPv4-адрес хоста Windows. Также доступен вспомогательный скрипт:

.\scripts\start_server.ps1

Streamable HTTP — обычный режим. Для явной совместимости с SSE запустите python server.py --transport sse и зарегистрируйте полученную конечную точку /sse, как описано в руководстве по интеграции с OpenTrek. SSE — это отдельно выбранный режим транспорта, а не альтернативный URL для регистрации рядом с /mcp.

Тестирование

Запустите модульные тесты из корня репозитория:

pytest -v

Запустите локальный смоук-тест MCP Streamable HTTP после установки зависимостей:

python scripts\smoke_test.py

Смоук-тест проверяет фактическое подключение по протоколу, обнаружение инструментов и цикл записи/списка действий. Он использует изолированные временные данные, а не вашу директорию runtime_data/.

Интеграция с OpenTrek

Регистрация в OpenTrek должна использовать выбор STREAMABLE в интерфейсе и такой формат URL:

http://<LAN_IPV4>:8000/mcp

Не придумывайте значение transportType JSON вручную. Выберите STREAMABLE на странице регистрации MCP в OpenTrek, введите URL, сохраните и убедитесь, что все шесть инструментов обнаружены. См. docs/open_trek_integration.md о поиске IPv4 в локальной сети, совместимости с SSE, проверках VPN и безопасном процессе устранения неполадок брандмауэра.

Демонстрационный сценарий

Сквозная демонстрация может показать разницу между извлечением знаний и постоянным действием:

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/ безопасны для коммита. Перед любым коммитом или push проверьте:

git status
git diff --check

Никогда не коммитьте реальные сообщения научного руководителя, реальное содержимое статей, стенограммы чатов, ключи, данные VPN или личную информацию.

Дорожная карта

• Перейти от JSON-файлов к долговечному многопользовательскому хранилищу, когда потребуется.

• Добавить точки интеграции ResearchTwin Memory и ResearchTwin_Core.

• Добавить рабочие процессы интеллектуального анализа статей и цитирования вокруг существующего уровня RAG.

• Добавить защищённую панель для просмотра истории проекта и отчётов.

• Улучшить демонстрационную историю для конкурса, не раскрывая реальные исследовательские данные.

Документация

• Архитектура

• Справочник MCP-инструментов

• Интеграция с OpenTrek

• Демонстрационный поток

• Вымышленные примеры данных