MCP Server: Ollama Deep Researcher

⛔ 已归档 — 代码已迁移

已于 2026-07-23 迁移至 mcpcentral platform monorepo（ADR-043）。

请改在此处进行操作： mcpcentral-io/mcpcentral → apps/deep-researcher/ Worker： mcpcentral-deep-researcher

此仓库为只读状态，仅供查阅历史。请参阅 DEPRECATED.md。

---

Ollama Deep Researcher DXT 扩展

概述

Ollama Deep Researcher 是一款桌面扩展（DXT），由本地 MCP 服务提供支持，可通过网络搜索和大模型综合分析实现高级主题研究。它支持配置研究参数、跟踪状态以及访问资源，并专为与 DXT 生态系统无缝集成而设计。

• 使用网络搜索 API（Tavily、Perplexity、Exa）和大模型（Ollama、DeepSeek 等）研究任意主题
• 配置最大研究循环次数、大模型以及搜索 API
• 跟踪进行中研究的状态
• 通过 MCP 协议将研究结果作为资源访问

功能

• 通过 stdio 实现 MCP 协议，支持本地安全运行
• 防御式编程：错误处理、超时和验证
• 通过 stderr 进行日志记录和调试
• 兼容 DXT 宿主环境

目录结构

.
├── manifest.json         # DXT manifest (see MANIFEST.md for spec)
├── src/
│   ├── index.ts         # MCP server entrypoint (Node.js, stdio transport)
│   └── assistant/       # Python research logic
│       └── run_research.py
├── README.md            # This documentation
└── ...

安装与设置

1. 克隆仓库并安装依赖：

   git clone <your-repo-url>
   cd mcp-server-ollama-deep-researcher
   npm install
   

2. 为助手安装 Python 依赖：

   cd src/assistant
   pip install -r requirements.txt
   # or use pyproject.toml/uv if preferred
   

3. 为网络搜索 API设置必需的环境变量：

   • Tavily：TAVILY_API_KEY
   • Perplexity：PERPLEXITY_API_KEY
   • Exa：EXA_API_KEY（可在 https://dashboard.exa.ai/api-keys 获取）
   • 可选：LANGSMITH_API_KEY、LANGSMITH_TRACING=true、OLLAMA_BASE_URL（默认为 http://localhost:11434）
   • 示例：

     export TAVILY_API_KEY=your_tavily_key
     export PERPLEXITY_API_KEY=your_perplexity_key
     export EXA_API_KEY=your_exa_key
     

   • 不想在磁盘上保存明文密钥？ 请参阅下方的可选：使用 1Password 安全存储密钥。

4. 构建 TypeScript 服务（如有需要）：

   npm run build
   

5. 在本地运行扩展以进行测试：

   node dist/index.js
   # Or use the DXT host to load the extension per DXT documentation
   

用法

• 研究某个主题：
  • 使用 research 工具并传入 { "topic": "Your subject" }
• 获取研究状态：
  • 使用 get_status 工具
• 配置研究参数：
  • 使用 configure 工具，可配置以下任意参数：maxLoops、llmModel、searchApi

清单

完整的 DXT 清单（包括工具架构和资源模板）请参阅 manifest.json。遵循 DXT MANIFEST.md。

日志与调试

• 所有服务日志和错误都会输出到 stderr，以便调试。
• 研究子进程会在 30 分钟后终止，以防止进程卡住。
• 无效请求和配置错误会返回清晰、结构化的错误消息。

安全与最佳实践

• 执行前会验证所有工具架构。
• 网络搜索 API 需要 API 密钥，且绝不会记录这些密钥。
• 使用 MCP 协议通过 stdio 进行本地安全通信。

测试与验证

• 在兼容 DXT 的宿主环境中加载扩展以进行验证。
• 确保所有工具调用都返回有效的结构化 JSON 响应。
• 检查清单能否加载，以及扩展能否注册为 DXT。

故障排除

• 缺少 API 密钥： 根据使用的搜索 API，确保在环境中设置了 TAVILY_API_KEY、PERPLEXITY_API_KEY 或 EXA_API_KEY。
• Python 错误： 检查 Python 依赖项和 stderr 中的日志。
• 超时： 研究子进程的运行时间上限为 30 分钟。

搜索 API 对比

• Tavily： 快速、全面的网络搜索，并提取原始内容
• Perplexity： AI 驱动的搜索，提供自然语言摘要和引文
• Exa： 针对语义搜索优化的神经搜索引擎，并提供重点内容

可选：使用 1Password 安全存储密钥

如果你使用 1Password，可以避免将明文 API 密钥存储在磁盘上或暴露在 AI 编码 Agent 的上下文中。此方案可选且可叠加使用——上述明文配置仍可照常使用。前提条件：1Password for Mac 或 Linux、op CLI（brew install --cask 1password-cli）和 sqlite3。

创建一个包含以下八个变量的 1Password Environment（四个密钥为机密；其余为非机密配置）：

变量	是否为机密？
TAVILY_API_KEY、PERPLEXITY_API_KEY、EXA_API_KEY、LANGSMITH_API_KEY	是
OLLAMA_BASE_URL、LANGSMITH_TRACING、LANGSMITH_ENDPOINT、LANGSMITH_PROJECT	否

创建 Environment 时，可以直接导入现有的 .env。创建完成后，选择以下三种机制中的任意一种（A 是 AI 编码模式；B 是 1Password 推荐的 MCP 启动方式；C 是无法运行 op 的主机的备用方案）。

A. 挂载 .env + 验证钩子（避免明文进入大模型上下文）

1Password Environments 会将本地 .env 挂载为 UNIX 命名管道（FIFO）：内容会按需流式传输给获授权的读取者，绝不会存储在磁盘上。Claude Code PreToolUse 钩子会在 Agent 执行 Shell 命令前验证挂载。

1. 在 1Password 桌面应用中，打开 Environment → Destinations → Local .env file → Choose file path → .env → Mount。使用 cat .env 验证（通过 Touch ID 授权；授权会持续到 1Password 锁定为止）。
2. .1password/environments.toml（已提交）会告知钩子要验证哪些路径——已设置为 mount_paths = [".env"]。
3. 在本地安装验证钩子：

   git clone https://github.com/1Password/agent-hooks /tmp/agent-hooks
   /tmp/agent-hooks/install.sh --agent claude-code --target-dir .
   

   这会创建 .claude/claude-code-1password-hooks-bundle/ 和 .claude/settings.json（两者均被 gitignore）。该钩子采用失败时放行策略：如果 1Password 或 sqlite3 不可用，它会允许执行，因此不会影响未使用 1Password 的贡献者。
4. 测试：当 1Password 已解锁时，运行 echo '{"command":"echo test","workspace_roots":["'"$PWD"'"]}' | .claude/claude-code-1password-hooks-bundle/bin/run-hook.sh 1password-validate-mounted-env-files → 返回 {"permission":"allow"}；锁定时则返回 deny，并附上修复说明。

B. 使用 op run --environment 启动 MCP 服务

复制 .mcp.json.1password.example → .mcp.json（被 gitignore），将 <ENVIRONMENT_ID> 替换为你的 Environment ID，MCP 主机便会在启动时通过 op run 解析密钥。非机密配置保留在 env 块中；密钥则从 Environment 注入。模板使用完整路径 /opt/homebrew/bin/op，因为通过 GUI 启动的主机（例如 Claude Desktop）不会继承 Shell 的 $PATH——如果 op 位于其他位置，请相应调整（which op）。

如果你的 op CLI 不支持 --environment，请使用备用方案（environment 子命令属于 1Password Environments beta，某些版本中并不存在，例如 op v2.34.x）：改为对包含 op:// 引用的普通 .env 使用 op run --env-file .env。先创建一次条目（op item create --vault "Your Vault" --category "Login" --title "ollama-deep-researcher" "TAVILY_API_KEY[concealed]=..." …），然后创建一个被 gitignore 的 .env 引用文件，并让启动器使用它：

# .env (gitignored) — 仅包含引用，不含明文
# TAVILY_API_KEY=op://Your Vault/ollama-deep-researcher/TAVILY_API_KEY
# …
op run --env-file .env -- node build/index.js

同一个 .env 也可用于 Docker（见下文），因此一个引用文件即可适用于两种启动方式。op run 每次启动时都会提示进行一次 Touch ID 验证。

C. .mcp.json 的 op inject 模板

对于无法使用 op run 的 MCP 主机，请将 .mcp.json.template 复制到一个工作文件中，将 <vault> 替换为你的保管库名称，然后将 {{ op://... }} 引用转换为实际值：

op inject -i .mcp.json.template -o .mcp.json

op inject 会以文件模式 0600 写入输出文件。.mcp.json 已加入 Git 忽略列表。在 1Password 中轮换密钥后，请重新编译。（需要支持标准项目/保管库的 op CLI；选项 B 中的 op run --environment 形式还需要 1Password Environments beta。）

Docker

docker-compose.yml 会从环境中插入全部 8 个变量。通过 op run --env-file 运行 compose，以便解析 .env 中的 op:// 引用（或者，如果你在 A 中设置了 FIFO 挂载，则解析其中的引用），并将其转发到容器中：

op run --env-file .env -- docker compose up

参考资料

• DXT 架构概述
• DXT 清单规范
• DXT 扩展示例
• Model Context Protocol SDK

---