🔍 Percival Deep Research (MCP 서버)

개요

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

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

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

✨ 주요 기능 및 개선 사항

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

⚡ 궁극적인 제공업체 이식성: 완전히 독립적인 추론 엔진입니다. Venice AI, MiniMax, OpenRouter와 같은 주요 오픈 웨이트 플랫폼에 대한 네이티브하고 충돌 없는 지원을 제공합니다. 연구 오케스트레이션 중 비 OpenAI 모델로 인해 발생하던 악명 높은 JSON 딕셔너리 유효성 검사 실패를 완전히 제거하는 사용자 지정 Persona Bypass를 구현했습니다.
🛡️ JSON-RPC 프로토콜 가드레일: 엄격한 stdio 출력 삭제를 강제합니다. 모든 기본 라이브러리 노이즈, 콘솔 렌더링 및 실시간 로그는 물리적으로 stderr로 리디렉션됩니다. 이는 Pydantic ValidationErrors를 완전히 방지하고 MCP 동기화에 필수적인 stdout 스트림을 보호합니다.
🔐 심층 방어 보안: 모든 입력은 프롬프트 인젝션에 대해 강력하게 살균됩니다. 신뢰할 수 없는 웹 콘텐츠는 에이전트의 자율성을 보호하기 위해 실행 불가능한 헤더로 래핑됩니다.
🤖 Nanobot 중심 설계: 호스트 애플리케이션에서 직접 환경 주입을 엄격하게 준수하기 위해 느슨한 .env 읽기 패턴을 제거했습니다.

📑 목차

🛠️ 도구 및 리소스 참조

리소스

이름	URI 패턴	설명
`research_resource`	`research://{topic}`	주제에 대한 캐시된 또는 실시간 웹 조사 컨텍스트에 MCP 리소스로 직접 액세스합니다. 콘텐츠와 소스가 포함된 Markdown을 반환합니다.

도구

도구	속도	`research_id` 반환	설명
`deep_research`	30–120초	✅ 예	다중 소스 심층 웹 조사. 연구 파이프라인의 진입점입니다.
`quick_search`	3–10초	❌ 아니오	DuckDuckGo를 통한 빠른 원시 스니펫 검색.
`write_report`	10–30초	—	기존 세션에서 구조화된 Markdown 보고서를 생성합니다. `research_id`가 필요합니다.
`get_research_sources`	<1초	—	참조된 모든 소스의 제목, URL 및 콘텐츠 크기를 반환합니다. `research_id`가 필요합니다.
`get_research_context`	<1초	—	보고서를 생성하지 않고 원시 합성 컨텍스트 텍스트를 반환합니다. `research_id`가 필요합니다.

연구 파이프라인

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": "openai:e2ee-qwen-2-5-7b-p",
"SMART_LLM": "openai:minimax-m27",
"STRATEGIC_LLM": "openai:zai-org-glm-4.7-flash",
"RETRIEVER": "duckduckgo"

WARNING

실제 제공업체와 관계없이 LLM 모델 앞에 반드시openai: 접두사를 붙여야 합니다. 이는 구성된 OPENAI_BASE_URL을 안전하게 파이프하는 기본 OpenAI SDK 전송 아키텍처를 사용합니다. 접두사를 사용하지 않으면 JSON 내부 파서가 충돌합니다.

🤖 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": "openai:e2ee-qwen-2-5-7b-p",
        "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": "openai:e2ee-qwen-2-5-7b-p",
        "RETRIEVER": "duckduckgo"
      }
    }
  }
}

🔐 보안

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

프롬프트 인젝션 보호

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

신뢰할 수 없는 콘텐츠 격리

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

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

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

📄 라이선스

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

Percival Deep Research