OpenRouter 에이전트 MCP 서버

OpenRouter용 모델 컨텍스트 프로토콜(MCP) 서버 구현으로, 정교한 연구 에이전트 기능을 제공합니다. 이 서버를 통해 대화형 LLM은 다양한 OpenRouter 모델 기반의 특수 에이전트를 사용하는 Claude 연구 오케스트레이터에 연구를 위임할 수 있습니다.

🚀 새로운 베타 지점 (2025년 3월 29일)

OpenRouter 에이전트 MCP 서버 기술 개요

OpenRouter Agents MCP 서버는 AI 기반 연구를 위한 정교한 오케스트레이션 시스템을 구현합니다. 이 요약에서는 최신 베타 버전(2025년 3월 29일 출시)의 주요 기술 구성 요소와 기능을 간략하게 설명합니다.

핵심 아키텍처

• 모델 컨텍스트 프로토콜(MCP) : STDIO 및 HTTP/SSE 전송을 모두 포함한 전체 구현
• 다중 에이전트 오케스트레이션 : 계획, 연구 및 컨텍스트 에이전트 역할을 갖춘 계층적 시스템
• 벡터 임베딩 데이터베이스 : 의미 지식 저장을 위한 pgvector를 갖춘 PGLite
• 라운드 로빈 부하 분산 : 최적의 결과를 위해 다양한 모델에 걸쳐 연구 작업을 분산합니다.
• 적응형 폴백 시스템 : 기본 연구에 실패하면 비용이 높은 모델에서 낮은 모델로 저하됨

연구 역량

• 다단계 계획 : Claude 3.7 Sonnet는 복잡한 질문을 특수화된 하위 질문으로 분해합니다.
• 병렬 실행 : 포괄적인 결과를 위해 여러 LLM에 걸친 동시 연구
• 컨텍스트 인식 개선 : 초기 조사의 격차를 식별하고 메우는 2단계 계획
• 의미 지식 기반 : 벡터 검색을 통해 관련 과거 연구를 찾아 새로운 질의를 강화합니다.
• 적응형 합성 : 상황별 에이전트가 결과를 사용자 정의 가능한 대상 수준 및 형식과 통합합니다.

최근 개선 사항

• 교차 모델 복원력 : 포괄적인 오류 처리를 통해 개별 모델 오류에도 불구하고 연구가 원활하게 진행됩니다.
• 동적 캐싱 : 쿼리 복잡성에 따른 지능형 TTL 및 캐시 최적화
• DB 복원력 : 데이터베이스 작업을 위한 지수 백오프를 사용한 재시도 논리
• 방어적 프로그래밍 : 코드베이스 전체에서 Null 안전 작업
• 향상된 사용자 피드백 : 자세한 오류 복구 기능을 갖춘 평가 시스템
• 종합 테스트 : 5가지 MCP 도구 모두에서 기능이 검증됨

베타 버전은 기존 구현 방식의 플러그 앤 플레이 간편함을 유지하면서 아키텍처 개선을 통해 안정성과 연구 품질을 모두 향상시킵니다. 이 시스템은 VS Code의 Cline 및 Claude Desktop App과 완벽하게 통합되어, 엔터프라이즈급 연구 기능을 자체적으로 제공하는 패키지입니다.

이러한 개선 사항은 서버의 사용 편의성을 유지하면서 더욱 안정적이고 강력한 연구 환경을 제공합니다. 베타 버전을 사용해 보시려면:

지엑스피1

🌟 이 프로젝트를 지원하세요

이 프로젝트가 도움이 되셨다면 GitHub에서 별점을 남겨주세요! 여러분의 후원은 이 프로젝트를 더욱 발전시키는 데 큰 도움이 됩니다.

여러분의 피드백과 기여를 언제나 환영합니다!

필수 조건

• Node.js(v18 이상 권장) 및 npm
• 깃
• OpenRouter API 키( https://openrouter.ai/ 에서 받으세요)

특징

• 클로드 3.7 소네트(사고 모드)를 활용한 연구 계획
• 다양한 OpenRouter LLM으로 구동되는 여러 연구 에이전트
• 연구 과제에 대한 모델의 라운드 로빈 할당
• 다양한 연구 요구 사항에 맞게 구성 가능한 비용 옵션(높음/낮음)
• 외부 데이터베이스 종속성 없이 자체적으로 포함됨
• 빠른 응답 시간을 위한 메모리 내 캐싱
• 영구 저장 및 유사성 검색을 위한 벡터 확장 기능이 있는 PGLite

작동 원리

1. 연구 질문을 보내면 기획 담당자(Claude 3.7 Sonnet)는 이를 여러 전문 연구 질문으로 분류합니다.
2. 각 연구 질문은 고비용 또는 저비용 LLM을 사용하는 다른 연구 에이전트에게 할당됩니다.
3. 모든 에이전트의 결과는 포괄적인 연구 보고서로 종합됩니다.
4. 결과는 메모리에 캐시되고 내장된 벡터 검색 기능을 통해 지속적으로 저장됩니다.
5. 최종 상황화된 보고서가 귀하에게 반환됩니다.

설치(Node.js/Standard)

이 방법은 VS Code에서 Cline과 같은 MCP 클라이언트와 통합하는 데 권장됩니다.

1. 이 저장소를 복제하세요:
   git clone https://github.com/wheattoast11/openrouter-deep-research-mcp.git cd openrouter-agents
2. 종속성 설치:
   npm install
3. 다음 예제에서 .env 파일을 만듭니다.
   cp .env.example .env
   (Windows에서는 copy .env.example .env 사용할 수 있습니다.)
4. .env 파일을 편집하고 OpenRouter API 키를 추가하세요.
   OPENROUTER_API_KEY=your_api_key_here
   (이 파일이 프로젝트의 루트 디렉토리에 저장되었는지 확인하세요)

Cline / VS Code MCP 통합(권장)

VS Code에서 이 서버를 Cline과 함께 사용하려면 MCP 설정 파일에 추가해야 합니다.

1. Cline MCP 설정 파일을 찾으세요.
   • 일반적으로 다음 위치에 있습니다. Windows의 c:\Users\YOUR_USERNAME\AppData\Roaming\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json macOS의 경우 ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json . YOUR_USERNAME 여기에 맞게 바꾸세요.
2. cline_mcp_settings.json 파일을 편집하세요. 다음 구성 객체를 기본 mcpServers 객체에 추가하세요. "YOUR_PROJECT_PATH_HERE" 이 저장소를 복제한 절대 경로로, "YOUR_OPENROUTER_API_KEY_HERE" 실제 API 키로 바꾸세요.
   { "mcpServers": { // ... potentially other existing servers ... "openrouter-research-agents": { "command": "cmd.exe", "args": [ "/c", "YOUR_PROJECT_PATH_HERE/start-mcp-server.bat" ], "env": { // IMPORTANT: Replace with your actual OpenRouter API Key "OPENROUTER_API_KEY": "YOUR_OPENROUTER_API_KEY_HERE" }, "disabled": false, // Ensure the server is enabled "autoApprove": [ "conduct_research", "research_follow_up", "get_past_research", "rate_research_report", "list_research_history" ] } // ... potentially other existing servers ... } }
   • 배치 파일을 사용하는 이유는 무엇인가요? 배치 파일을 사용하면 서버가 적절한 환경과 디렉터리 컨텍스트에서 시작되도록 할 수 있습니다.
   • env 에 API 키가 있는 이유는 무엇인가요? 서버는 dotenv 사용하여 .env 파일을 로드하지만, env 블록에 키를 제공하면 서버 프로세스가 항상 해당 파일에 접근할 수 있습니다.
3. 설정 파일을 저장하세요. Cline이 새 서버 구성을 자동으로 감지합니다. 설정이 바로 나타나지 않으면 VS Code 또는 Cline 확장 프로그램을 다시 시작해야 할 수 있습니다.

설정이 완료되면 Cline에서 사용 가능한 conduct_research 및 기타 조사 도구가 표시됩니다. 다음과 같이 사용할 수 있습니다.

또는 비용 선호도를 지정하세요.

사용 가능한 모델

고가 모델

• 난제/소나 심층 조사
• 퍼플렉시티/소나프로
• 난해함/소나 추론 프로
• openai/gpt-4o-검색-미리보기

저가 모델

• 당혹감/소나 추론
• openai/gpt-4o-mini-search-미리보기
• 구글/제미니-2.0-플래시-001

사용자 정의

.env 파일을 편집하여 사용 가능한 모델을 사용자 정의할 수 있습니다.

.env 파일에서 데이터베이스 및 캐시 설정을 사용자 정의할 수도 있습니다.

대체 설치: Claude 데스크톱 앱용 HTTP/SSE

이 서버는 Claude Desktop App과 통합하기 위해 독립형 HTTP/SSE 서비스로 실행할 수도 있습니다.

HTTP/SSE 설치 단계

1. 이 저장소를 복제합니다(아직 복제하지 않았다면):
   git clone https://github.com/wheattoast11/openrouter-deep-research-mcp.git cd openrouter-agents
2. 표준 설치(3단계 및 4단계)에 설명된 대로 .env 파일을 만들고 구성합니다.
3. npm을 사용하여 서버를 시작합니다.
   npm start
4. MCP 서버는 HTTP/SSE를 통해 http://localhost:3002 (또는 .env 에 지정된 포트)에서 실행되고 액세스할 수 있습니다.

Claude 데스크톱 앱 통합(HTTP/SSE)

1. Claude 데스크톱 앱을 엽니다.
2. 설정 > 개발자로 이동하세요.
3. "구성 편집"을 클릭하세요.
4. 구성의 mcpServers 배열에 다음을 추가합니다.
   { "type": "sse", "name": "OpenRouter Research Agents (HTTP)", // Differentiate if also using STDIO "host": "localhost", "port": 3002, // Or your configured port "streamPath": "/sse", "messagePath": "/messages" }
5. 저장하고 클로드를 다시 시작하세요.

지속성 및 데이터 저장

이 서버는 다음을 사용합니다.

• 메모리 내 캐시 : 효율적인 응답 캐싱을 위해(노드 캐시 사용)
• pgvector를 탑재한 PGLite : 연구 보고서의 영구 저장 및 벡터 검색 기능
  • 연구 보고서는 의미적 유사성 검색을 위해 벡터 임베딩과 함께 저장됩니다.
  • 벡터 검색은 새로운 질의에 대한 관련 과거 연구를 찾는 데 사용됩니다.
  • 모든 데이터는 지정된 데이터 디렉토리에 로컬로 저장됩니다(기본값: './researchAgentDB')

문제 해결

• 연결 문제 : Claude의 개발자 설정이 서버 구성과 일치하는지 확인하세요.
• API 키 오류 : OpenRouter API 키가 올바른지 확인하세요
• 에이전트를 찾을 수 없습니다 . 계획이 실패하면 Claude가 XML을 올바르게 구문 분석하고 있는지 확인하십시오.
• 모델 오류 : 지정된 모델이 OpenRouter 계정에서 사용 가능한지 확인하세요.

고급 구성

서버 설정은 config.js 에서 수정할 수 있습니다. 다음 내용을 조정할 수 있습니다.

• 사용 가능한 모델
• 기본 비용 선호도
• 계획 에이전트 설정
• 서버 포트 및 구성
• 데이터베이스 및 캐시 설정

인증 보안

최신 업데이트에 따라 HTTP/SSE 전송에 대한 API 키 인증이 기본적으로 필수가 되었습니다.

1. 프로덕션을 위해 .env 파일에서 SERVER_API_KEY 환경 변수를 설정합니다.
   SERVER_API_KEY=your_secure_api_key_here
2. 개발/테스트용으로만 다음을 설정하여 인증을 비활성화할 수 있습니다.
   ALLOW_NO_API_KEY=true

이를 통해 개발 및 테스트의 유연성을 유지하면서도 프로덕션 배포에 대한 보안을 강화할 수 있습니다.

테스트 도구

저장소에는 구현을 검증하기 위한 여러 테스트 도구가 포함되어 있습니다.

1. 기본 도구 테스트 :
   test-all-tools.bat
   이 스크립트는 5개의 MCP 도구를 모두 개별적으로 테스트하여 올바르게 작동하는지 확인합니다.
2. MCP 서버 테스트 :
   test-mcp-server.js
   모든 전송 옵션을 포함한 MCP 서버 구현을 테스트합니다.
3. 연구원 테스트 :
   test-research-agent.js
   실제 OpenRouter API 호출을 통해 핵심 연구 에이전트 기능을 테스트합니다.

이러한 도구는 모든 구성 요소가 수정 후에도 올바르게 작동하는지 확인하는 데 도움이 됩니다.

특허

MIT