基于MCP协议与Docker为Claude Code构建Brave搜索服务器Argus

1. 项目概述：为Claude Code打造一个“全视之眼”

如果你和我一样，日常重度依赖Claude Code来辅助编程、查资料、写文档，那你一定遇到过这样的痛点：当Claude需要联网搜索时，要么得手动复制粘贴，要么得依赖一些功能有限或配置复杂的第三方工具。整个过程既不流畅，也打断了原本沉浸式的对话体验。我一直在寻找一个方案，能让Claude Code像调用本地函数一样，丝滑、强大且可控地访问互联网信息。

这就是我动手构建Argus的初衷。它是一个基于Model Context Protocol (MCP)的服务器，专门为Claude Code等AI助手提供对Brave Search API的完整访问能力。简单来说，它让Claude Code“长”出了搜索的眼睛和耳朵。这个名字源自希腊神话中的百眼巨人“阿耳戈斯”，寓意着它能像那位永不疲倦的守卫一样，从互联网的各个角落为你搜集和整合信息。

与官方或其他第三方方案不同，Argus的设计哲学是“极简部署，完整控制”。它被打包成一个Docker容器，你只需要几条命令就能跑起来。更重要的是，它直接返回Brave Search API的原始、完整的JSON响应，而不是经过预处理的“精选”结果。这意味着Claude Code能获得最丰富的一手信息，并运用其强大的推理能力来为你筛选和解读——事实证明，Claude非常擅长处理这种原始数据，往往能给出更贴合你需求的答案。

2. 核心设计思路与架构解析

在动手写代码之前，我花了相当长时间来思考这个工具应该以何种形态存在。市面上已经有一些MCP搜索服务器，但总感觉差那么点意思。要么绑定特定平台，要么功能阉割，要么配置起来令人头大。我的目标是打造一个开箱即用、功能全面、且资源消耗智能的解决方案。

2.1 为什么选择MCP和Docker？

MCP (Model Context Protocol)是Anthropic推出的一套协议，它定义了AI助手（如Claude）如何与外部工具、数据源安全、标准化地交互。你可以把它想象成AI世界的“USB接口”标准。为Claude Code开发MCP服务器，意味着你的工具能无缝集成到Claude的侧边栏，通过自然语言调用，体验原生且流畅。

而选择Docker作为交付形式，则是出于对部署便利性和环境一致性的极致追求。无论你的开发机是Mac、Windows还是Linux，无论上面装着什么版本的Python或Node.js，一个docker-compose up -d就能解决所有环境依赖问题。容器化也带来了更好的可观察性，日志、资源占用一目了然，这比一个黑盒的npx包要让人安心得多。

2.2 双密钥架构：安全与灵活性的平衡

这是Argus设计中的一个关键细节，值得展开讲讲。Brave Search API有多种订阅计划（如Data for Search, Data for AI），每种都需要独立的API密钥。如何管理这些密钥，既保证安全，又不失灵活？

我采用了“双密钥架构”：

1. 启动密钥（Startup Key）：存放在项目的.env文件中。它的唯一作用是在Docker容器启动时，调用一次Brave的配额查询接口，从而在日志中为你展示准确的API使用情况（如“已用141/2000次”）。这个密钥不是运行时必需的，如果你不提供，日志只会显示0/2000，但所有搜索功能完全正常。
2. 运行时密钥（Runtime Keys）：存放在给Claude Code使用的.mcp.json配置文件中。这些密钥会通过HTTP请求头，在每次Claude调用搜索工具时发送。这意味着密钥永远不会被持久化在容器内部，是真正的无状态（Stateless）设计。

这样设计的好处是什么？

• 安全性：最敏感的运行时密钥只存在于你的本地配置文件中，不会被打包进镜像或写入容器。
• 灵活性：你可以随时在.mcp.json里更换密钥，无需重启容器。
• 可观测性：通过可选的启动密钥，你可以在容器日志里随时监控各API套餐的剩余额度，做到心中有数。

2.3 “AI节省策略”：智能管理你的免费额度

Brave Search为每个API套餐提供了慷慨的免费额度（例如Data for Search每月2000次）。但“Data for AI”套餐的额度同样珍贵，因为它驱动着能返回6倍上下文信息的增强搜索工具。如何让有限的资源用在刀刃上？

我设计了一个“AI节省策略”逻辑，主要作用于search_images（搜图）、search_videos（搜视频）、search_news（搜新闻）这三个工具。它们既可以用“Data for Search”套餐执行，也可以用“Data for AI”套餐执行。策略的核心目标是：优先消耗Search额度，保护宝贵的AI额度。

其决策树如下：

1. 首先检查AI额度剩余是否超过50%？如果是，为了节省AI额度，优先尝试使用Search额度。
2. 如果AI额度不足50%，则检查Search额度是否还剩余至少10%？如果是，继续使用Search额度。
3. 如果Search额度已低于10%（快用完了），则切换使用AI额度，将剩余的Search额度留给核心的search_web工具。

这个策略通过日志清晰呈现：

INFO - 🖼️ search_images called: query='sad puppy dog', count=1 INFO - 🧠 AI-Saving Policy: AI has 92.8% remaining (>50%) → Using Search to save AI INFO - 🔑 Using Data For Search key

这意味着，一次图片搜索为你节省了一次本可能消耗的AI额度。这个策略是Argus的“智慧”所在，它能让你在免费额度内进行更多次的搜索。

3. 从零开始的完整部署与配置指南

理论讲完了，我们动手把它跑起来。整个过程非常 straightforward，大概只需要10分钟。

3.1 前期准备：获取你的“通行证”

首先，你需要去Brave Search API官网获取密钥。别担心，免费套餐完全够用。

1. 访问 Brave Search API Dashboard 。
2. 注册/登录后，在“Subscription”页面，找到“Data for Search”套餐，点击订阅。是的，即使免费也需要绑定信用卡，这是Brave为了防止滥用设置的标准流程，只要不超量就不会收费。
3. 订阅成功后，在“API Keys”页面，你会看到生成的密钥。强烈建议你同时订阅“Data for AI”免费套餐，这样就能使用返回更多上下文的增强搜索了。Autosuggest和Spellcheck套餐可视需要订阅。
4. 将这几个密钥妥善保存，我们下一步就会用到。

3.2 三步部署：克隆、配置、启动

假设你的系统已经安装了Docker和Docker Compose。

第一步：获取代码

git clone https://github.com/IT-Square-Plus/Argus cd Argus

这会把项目源码拉到本地。

第二步：配置环境这里有两个关键配置文件需要修改：

1. 环境变量文件（供Docker容器使用）：

   cp .env.example .env # 使用你喜欢的编辑器（如VSCode、nano、vim）打开 .env 文件

   找到X_BRAVE_API_KEY_SEARCH=这一行，填入你刚才获取的Data for Search密钥。这一步是可选的，但填了之后，容器启动日志就能显示真实的API用量，强烈建议填写。其他变量如端口、日志等级保持默认即可。

2. MCP客户端配置文件（供Claude Code连接）：

   cp .mcp.json.example .mcp.json # 打开 .mcp.json 文件

   这个文件是告诉Claude Code如何连接到你的Argus服务器。你需要修改headers部分：

   "headers": { "X-Brave-API-Key-Search": "你的_Data_for_Search_密钥", "X-Brave-API-Key-AI": "你的_Data_for_AI_密钥（如果有）", "X-Brave-API-Key-Autosuggest": "你的_Autosuggest_密钥（如果有）", "X-Brave-API-Key-Spellcheck": "你的_Spellcheck_密钥（如果有）" }

   重要提示：X-Brave-API-Key-Search是必须的，否则核心搜索功能无法工作。其他密钥如果没有，可以留空或删除整行。如果你只有一个密钥但订阅了多个套餐，可以在多个header里填写同一个密钥。

第三步：启动服务

docker-compose up -d

这条命令会拉取镜像（如果本地没有）并以后台模式启动容器。你可以用docker-compose logs -f来实时查看启动日志。如果看到类似下面的输出，并且最后有“Application startup complete.”，就说明成功了。

INFO - 🚀 Starting Argus MCP Server... INFO - 📊 API Quota Check: INFO - Data For Search: [██░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 144/2000 ( 7.2%) INFO - Data For AI: [████████████████████████████████████████] 2000/2000 (100.0%) INFO - ✅ Argus is ready at http://0.0.0.0:8081

第四步：验证与连接在终端里快速验证一下服务是否健康：

curl http://localhost:8081/ready

你会得到一个详细的JSON响应，包含服务状态、版本、支持的工具以及API用量（如果你在.env里配置了密钥的话）。

最后，重启你的Claude Code应用。重启后，Claude Code会自动加载当前目录下的.mcp.json配置文件。你应该能在Claude Code的界面上看到新的工具出现。

4. 核心工具详解与高效使用心法

现在，你的Claude Code已经拥有了联网搜索的超能力。我们来深入看看这些工具怎么用，以及如何用得巧。

4.1 主力工具：search_web与search_web_extra_snippets_for_ai

这是你将会最频繁使用的两个工具。它们的基础功能都是网页搜索，但输出“营养”不同。

• search_web：这是标准搜索。它会返回网页的标题、链接、摘要（snippet）。对于大多数查询，这已经足够了。一个关键参数是result_filter，它帮你过滤结果类型。默认是"web"，这通常能返回最相关、信息量最集中的结果（约3000个tokens）。如果你设为空字符串""，则会返回所有聚类的结果（新闻、视频、问答等），但token消耗会激增至约10000，除非你确实需要全景信息，否则不建议。

  实操技巧：当你让Claude“查一下某某概念”时，它默认会调用这个工具。你可以通过描述来引导它使用更专业的工具，例如“用search_news工具帮我找找关于这个事件的最新报道”。

• search_web_extra_snippets_for_ai：这是增强版搜索，需要Data for AI套餐。它除了标准摘要，还会为每个结果额外返回多达5个精华片段（excerpt）。这相当于给Claude提供了原始网页中更密集、更相关的信息块，总上下文量是标准版的6倍。当你需要Claude进行深度分析、总结或对比时，这个工具能极大提升回答的质量和准确性。

  注意事项：这个工具消耗的同样是Data for AI套餐的额度。虽然AI节省策略不适用于它，但它带来的信息增益对于复杂任务来说是值得的。建议将其用于关键的研究性查询，而日常简单查询用标准的search_web即可。

4.2 垂直搜索工具：专事专办

为什么有了通用的网页搜索，还需要专门的图片、视频、新闻搜索工具？答案是“精度”与“效率”。

• search_images：当你让Claude“找一张XX的图片”时，AI节省策略会生效。这个工具返回的结果结构是专门为图片优化的：高清图URL、缩略图、图片来源、图片尺寸等。Claude可以直接引用这些URL，甚至能根据尺寸等信息进行初步筛选。
• search_videos：同理，搜索视频会返回时长、观看数、发布者等元数据。这对于需要找教程、演讲或最新视频内容的场景非常有用。
• search_news：这个工具能筛选出新闻文章，并标记“突发新闻”。对于追踪时事热点、获取最新资讯至关重要。

使用心法：尽管你可以用search_web并设置result_filter来达到类似效果，但使用专用工具能让Claude更准确地理解你的意图，并且能享受到AI节省策略的福利，智能地为你保护Data for AI的额度。

4.3 辅助工具：suggest与spellcheck

这两个工具需要额外的套餐，但能提升交互体验。

• suggest(需Autosuggest套餐)：提供搜索词自动补全建议。当你只记得部分关键词时，可以让Claude先调用这个工具获取建议，再展开搜索。
• spellcheck(需Spellcheck套餐)：检查并纠正查询词的拼写错误。对于英文搜索尤其有用，能避免因拼写错误导致的搜索结果偏差。

4.4 与Claude Code协作的最佳实践

配置好后，在Claude Code中，你可以像这样自然地进行对话：

• 你：“帮我查一下Python中asyncio模块最近有哪些最佳实践？”
• Claude：（调用search_web或search_web_extra_snippets_for_ai）“……根据最近的几篇技术博客和官方文档更新，Pythonasyncio的最佳实践包括：1. 使用asyncio.run()作为主入口点；2. 优先使用高级API如asyncio.gather；3. 注意资源清理，使用async with上下文管理器……这是来自[Real Python]和[Python官方文档]的信息。”

高级技巧：你可以更精确地指导Claude：

• “用search_news工具，找找过去一周关于‘AI编程助手’的新闻报道，总结三个主要观点。”
• “我想做一个关于日落的演示文稿，用search_images工具找五张高清的日落风景图，并列出它们的来源和尺寸。”

这种交互模式，将搜索从一种需要你手动干预的“外部操作”，变成了AI助手能力的一部分，实现了真正的无缝体验。

5. 运维、监控与故障排查实录

将Argus用于生产或日常重度使用，稳定性与可观测性很重要。这部分分享一些运维层面的经验和踩过的坑。

5.1 健康检查与监控

Argus内置了两个HTTP端点，非常适合集成到监控系统中：

• GET /health(存活探针)：返回简单的{"status": "alive"}。Kubernetes或Docker Swarm等编排工具可以用它来判断容器是否崩溃需要重启。
• GET /ready(就绪探针)：这是更有用的一个。它不仅返回服务状态，还详细列出了所有可用工具，以及当前API配额的使用情况（前提是.env中配置了密钥）。负载均衡器可以用它来判断是否应该将流量导到该实例。

你可以写一个简单的脚本定期检查/ready，或者用Prometheus、Grafana等工具来采集和展示使用量百分比，设置预警（例如使用超过80%时发出通知）。

5.2 日志解读与调试

启动容器时，建议使用docker-compose logs -f argus来跟随日志。Argus的日志设计得比较详细，是排查问题的第一手资料。

• 正常请求日志：你会看到工具被调用、AI节省策略决策、使用的密钥类型、HTTP请求详情和返回状态。

  INFO - 🔎 search_web called: query='python async await', count=10, result_filter='web' INFO - 🔑 Using Data For Search key INFO - 🌐 Web search: query='python async await'... INFO - HTTP Request: GET https://api.search.brave.com/res/v1/web/search?... "HTTP/1.1 200 OK" INFO - ✅ Web search successful: 10 results returned

• 配额警告：如果某个套餐用量超过90%，日志会输出警告，提醒你额度即将用尽。
• 错误日志：如果API密钥无效或请求超时，会明确打印错误信息，例如ERROR - Brave API request failed: 401 Unauthorized。这时你需要检查.mcp.json中的密钥是否正确，或是否已过期。

5.3 常见问题排查清单

在开发和测试过程中，我遇到了不少典型问题，这里整理成速查表：

5.4 资源管理与优化建议

• 资源占用：Argus容器本身非常轻量，内存占用通常在100MB以下。主要的资源消耗在于网络I/O，与Brave API通信。
• 网络考虑：如果你在网络受限的环境中使用，确保主机能够访问api.search.brave.com。
• 额度规划：免费额度对于个人日常使用和轻度开发通常足够。通过/ready端点定期监控，并利用好AI节省策略，可以有效延长额度使用周期。如果用量大，可以考虑Brave的付费套餐。
• 数据安全：所有搜索查询和结果都会通过你的本地Claude Code和Argus容器，再发送到Brave API。Brave的隐私政策宣称不存储个人身份信息与搜索记录的关联。你的API密钥仅存在于本地配置文件中，项目设计确保了密钥不落盘到容器。

6. 项目演进思考与扩展可能性

构建Argus的过程，也是一个不断思考如何让工具更贴合开发者实际需求的过程。目前的版本已经解决了从零到一的问题，但路还很长。

我个人的实际体会是，一个工具的价值不仅在于它实现了什么功能，更在于它如何融入并优化现有的工作流。Argus目前最大的成功，就是让我在Claude Code中几乎忘记了“搜索”这个动作本身的存在——它变成了对话的自然延伸。

关于后续的规划，除了项目README中提到的引入硬性额度限制和CI/CD测试，我个人还在考虑几个方向：

1. 结果缓存层：对于一些常见的、非实时性的查询（例如“Python lambda用法”），可以引入一个简单的本地缓存（如SQLite），在短时间内重复相同查询时直接返回缓存结果，这能进一步节省API额度并提升响应速度。
2. 可配置的搜索偏好：目前的一些参数（如安全搜索等级safesearch、国家country）是硬编码或默认的。未来可以考虑允许用户通过配置文件进行全局设置，比如始终将safesearch设为moderate，或默认搜索区域设为CN。
3. 更丰富的工具描述：目前Claude Code通过MCP协议读取工具的名称和描述。可以进一步优化这些描述文本，让Claude更精准地理解每个工具最适用的场景，从而在用户没有明确指令时做出更智能的工具选择。

最后分享一个小技巧：如果你在团队中使用，可以将配置好的.mcp.json文件共享给队友。他们只需要克隆仓库、配置自己的API密钥、然后启动容器，就能获得完全相同的增强版Claude Code体验。这比每个人从头研究如何配置联网搜索要高效得多。

工具的本质是延伸人的能力。Argus的目标，就是让AI助手的能力边界，平滑地扩展到整个互联网。希望这个项目和你分享的这些细节，能帮你更高效地获取信息，更专注地创造价值。