ResearchTwin MCP Server

ResearchTwin MCP Server는 ResearchTwin(장기 연구 프로젝트 에이전트)의 영구 작업 계층입니다. OpenTrek에서 호스팅되는 에이전트에게 연구 작업 기록, 프로젝트 상태 및 지도교수 요구사항 유지, 증거 기반 진행 보고서 생성을 위한 실제 MCP 도구를 제공합니다.

이 저장소는 경쟁 수준의 참조 구현으로 설계되었습니다. RAG는 연구 자료에서 질문에 답하고, MCP는 프로젝트 기록에 대한 명시적이고 감사 가능한 변경을 수행합니다.

커밋된 모든 예시는 가상이며 익명화되었습니다. 운영 데이터는 runtime_data/에 속하며 의도적으로 Git에서 제외됩니다.

개요

연구 보조 도구는 단일 질문에 답하는 것 이상을 해야 합니다. ResearchTwin은 진행 중인 프로젝트에서 발생한 일에 대한 지속적인 기록을 유지합니다:

• 구체적인 활동, 결과, 장애 요인 및 다음 단계;

• 현재 프로젝트 단계, 작업, 위험 및 결정;

• 구조화된 지도교수 요구사항;

• 저장된 증거로부터 조합된 주간, 회의 또는 단계 보고서.

이 서버는 OpenTrek의 ResearchTwin 에이전트가 호출하도록 설계되었습니다. 에이전트, 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 통합.

• /mcp에서 기본 MCP 전송으로 Streamable HTTP.

• 시작 시 선택 시 사용 가능한 선택적 명령줄 SSE 호환 전송.

• 모놀리식 서버 스크립트 대신 6개의 집중된 도구.

• 원자적 교체 및 프로세스 내 잠금을 사용한 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이 LAN의 다른 기기에서 실행되는 경우에만 네트워크 액세스 필요

설치

새 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을 사용하십시오. LAN의 다른 신뢰할 수 있는 기기에서 OpenTrek을 사용하는 경우 Windows 호스트의 해당 IPv4 주소를 사용하십시오. 도우미 스크립트도 사용할 수 있습니다:

.\scripts\start_server.ps1

Streamable HTTP가 일반 모드입니다. 명시적 SSE 호환성을 위해 python server.py --transport sse를 실행하고 결과 /sse 엔드포인트를 OpenTrek 통합 지침에 문서화된 대로 등록하십시오. 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을 입력한 후 저장하고 6개 도구가 모두 검색되는지 확인하십시오. LAN 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 통합

• 데모 흐름

• 가상 샘플 데이터