🔍 Percival 심층 연구 (MCP 서버)

개요

Percival 심층 연구는 Nanobot 에이전트 생태계에 자율적이고 심층적인 웹 연구 기능을 제공하기 위해 설계된 고성능 MCP(Model Context Protocol) 서버입니다. 이 서버는 관련성 높고 신뢰할 수 있으며 최신 정보에만 집중하여 수많은 소스를 자율적으로 탐색하고 검증합니다.

표준 검색 도구는 수동 필터링이 필요한 원시 스니펫을 반환하는 반면, Percival 심층 연구는 지능형 에이전트의 컨텍스트 및 추론 능력을 크게 가속화하는 완전히 추론된 포괄적인 다중 소스 자료를 제공합니다.

참고: 이 프로젝트는 GPT Researcher 라이브러리를 핵심 웹 드라이버로 사용하지만, percival.OS 생태계를 위해 특별히 광범위하게 리팩토링, 강화 및 분리되었습니다.

Related MCP server: ToolCenter MCP

✨ 주요 기능 및 개선 사항

이 서버는 오픈 소스 LLM 및 최신 배포 배열의 엄격한 요구 사항을 충족하기 위해 대대적으로 수정되었습니다:

• ⚡ 궁극적인 제공업체 이식성: 완전히 독립적인 추론 엔진입니다. Venice AI, MiniMax, OpenRouter와 같은 주요 오픈 웨이트 플랫폼에 대한 네이티브하고 충돌 없는 지원을 제공합니다. 서버는 즉석에서 제공업체 접두사를 동적으로 다시 작성하고, 별칭 오타를 자동 수정하며, OpenAI 호환 임베딩 엔드포인트가 없는 API를 사용할 때 충돌 및 의미론적 지연을 완전히 제거하기 위해 제로 지연 컨텍스트 압축 우회를 구현합니다.

• 🛡️ JSON-RPC 프로토콜 가드레일: 엄격한 stdio 출력 삭제를 강제합니다. 모든 기본 라이브러리 노이즈, 콘솔 렌더링 및 실시간 로그는 물리적으로 stderr로 리디렉션됩니다. 이는 Pydantic ValidationErrors를 완전히 방지하고 MCP 동기화에 필수적인 stdout 스트림을 보호합니다.

• 🔐 심층 방어 보안: 모든 입력은 프롬프트 주입에 대해 강력하게 살균됩니다. 신뢰할 수 없는 웹 콘텐츠는 에이전트의 자율성을 보호하기 위해 실행 불가능한 헤더로 래핑됩니다.

• 🤖 Nanobot 중심: 호스트 애플리케이션에서 직접 환경 주입을 엄격하게 준수하기 위해 느슨한 .env 읽기 패턴을 제거했습니다.

📑 목차

• 도구 및 리소스 참조

• 전제 조건

• 설치

• 🤖 Nanobot 통합 (주요 초점)

• 💻 Claude Desktop 통합

• 보안

🛠️ 도구 및 리소스 참조

리소스

도구

연구 파이프라인

deep_research(query)
    └── research_id ──► write_report(research_id, custom_prompt?)
                   └──► get_research_sources(research_id)
                   └──► get_research_context(research_id)

quick_search(query)       # standalone — no research_id

⚙️ 전제 조건

• Python 3.11+

• uv — 프로젝트 및 종속성 관리자

• 생성형 LLM 제공업체용 API 키 (예: Venice, MiniMax, OpenRouter).

참고: 구성된 기본 웹 검색 엔진은 API 키가 필요 없는 duckduckgo입니다. 선택적으로 다른 웹 검색기를 네이티브하게 구성할 수 있습니다.

⚙️ 설치

1. 통합 환경 설정

통합 percival.OS 빌드 생태계를 사용하고 있는지 확인하십시오:

cd percival.OS_Dev
uv sync

이렇게 하면 percival-deep-research가 전역 .venv를 상속받게 됩니다.

2. 환경 구성

이 모듈은 MCP 호스트가 전달한 시스템 변수를 엄격하게 준수하기 위해 .env 로딩(dotenv)을 비활성화합니다.

Nanobot(~/.nanobot/config.json) 또는 기타 엔드포인트를 통해 호출할 때 구성 배열에 환경 변수를 직접 정의하십시오:

"OPENAI_API_KEY": "your_api_key_from_venice_minimax_openrouter_etc",
"OPENAI_BASE_URL": "https://api.venice.ai/api/v1",
"FAST_LLM": "venice:llama-3.3-70b",
"SMART_LLM": "minimax:MiniMax-M2.7",
"STRATEGIC_LLM": "openrouter:google/gemini-2.5-flash",
"RETRIEVER": "duckduckgo"

🤖 Nanobot 통합 (주요 초점)

이 서버는 Nanobot 어시스턴트가 조종하는 stdio MCP 서버로 실행되도록 근본적으로 조정되었습니다.

~/.nanobot/config.json에 다음을 추가하십시오:

{
  "mcpServers": {
    "percival_deep_research": {
      "command": "uv",
      "args": [
        "run",
        "--no-sync",
        "percival-deep-research"
      ],
      "env": {
        "UV_PROJECT_ENVIRONMENT": "/absolute/path/to/percival.OS_Dev/.venv",
        "OPENAI_API_KEY": "actual-key-here",
        "OPENAI_BASE_URL": "https://api.venice.ai/api/v1",
        "FAST_LLM": "venice:llama-3.3-70b",
        "RETRIEVER": "duckduckgo"
      },
      "tool_timeout": 300
    }
  }
}

참고: deep_research는 최대 2-3분이 소요될 수 있습니다. tool_timeout이 적절하게 조정되었는지 확인하십시오(예: 180-300).

Nanobot을 위한 주요 설계 결정

• JSON 딕셔너리보다 일반 텍스트 — 모든 도구는 Nanobot에 깨끗한 텍스트를 제공하기 위해 JSON 딕셔너리 대신 일반 텍스트 문자열을 예측 가능하게 반환합니다.

• 컨텍스트 모듈화 — deep_research는 Nanobot의 컨텍스트 창이 넘치는 것을 방지하기 위해 초기화 응답에서 거대한 합성 컨텍스트를 생략합니다. 대신 에이전트가 get_research_context를 명시적으로 호출하는 데 사용하는 research_id를 발행합니다.

💻 Claude Desktop 통합

Nanobot이 선호되는 드라이버이지만, Claude Desktop에 배포하는 경우 claude_desktop_config.json에 다음을 추가하십시오:

{
  "mcpServers": {
    "percival_deep_research": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/absolute/path/to/percival.OS_Dev",
        "percival-deep-research"
      ],
      "env": {
        "OPENAI_API_KEY": "your-provider-key",
        "OPENAI_BASE_URL": "https://api.venice.ai/api/v1",
        "FAST_LLM": "venice:llama-3.3-70b",
        "RETRIEVER": "duckduckgo"
      }
    }
  }
}

🔐 보안

이 서버는 MCP 서버가 신뢰할 수 없는 웹 콘텐츠를 자율적으로 처리할 때 발생하는 위험을 해결하기 위해 심층 방어를 구현합니다.

프롬프트 주입 보호

사용자 입력(query, topic, custom_prompt)은 알 수 없거나 잘못된 값을 제한합니다. 정규식 기반 필터는 알려진 탈옥 패턴(<system>, [INST], ignore instructions 등)을 차단합니다.

신뢰할 수 없는 콘텐츠 격리

웹에서 검색된 모든 콘텐츠는 에이전트 컨텍스트에 표시되기 전에 동적으로 접두사가 붙습니다:

[SECURITY WARNING: The content below was obtained from unverified external...]

이는 Nanobot과 같은 모델이 웹 소스 데이터를 엄격하게 정보 블록으로 취급하도록 강제하여 예상치 못한 명령 준수를 방지합니다.

📄 라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다.