基于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和DockerMCP (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密钥。如何管理这些密钥既保证安全又不失灵活我采用了“双密钥架构”启动密钥Startup Key存放在项目的.env文件中。它的唯一作用是在Docker容器启动时调用一次Brave的配额查询接口从而在日志中为你展示准确的API使用情况如“已用141/2000次”。这个密钥不是运行时必需的如果你不提供日志只会显示0/2000但所有搜索功能完全正常。运行时密钥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额度。其决策树如下首先检查AI额度剩余是否超过50%如果是为了节省AI额度优先尝试使用Search额度。如果AI额度不足50%则检查Search额度是否还剩余至少10%如果是继续使用Search额度。如果Search额度已低于10%快用完了则切换使用AI额度将剩余的Search额度留给核心的search_web工具。这个策略通过日志清晰呈现INFO - ️ search_images called: querysad puppy dog, count1 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官网获取密钥。别担心免费套餐完全够用。访问 Brave Search API Dashboard 。注册/登录后在“Subscription”页面找到“Data for Search”套餐点击订阅。是的即使免费也需要绑定信用卡这是Brave为了防止滥用设置的标准流程只要不超量就不会收费。订阅成功后在“API Keys”页面你会看到生成的密钥。强烈建议你同时订阅“Data for AI”免费套餐这样就能使用返回更多上下文的增强搜索了。Autosuggest和Spellcheck套餐可视需要订阅。将这几个密钥妥善保存我们下一步就会用到。3.2 三步部署克隆、配置、启动假设你的系统已经安装了Docker和Docker Compose。第一步获取代码git clone https://github.com/IT-Square-Plus/Argus cd Argus这会把项目源码拉到本地。第二步配置环境这里有两个关键配置文件需要修改环境变量文件供Docker容器使用cp .env.example .env # 使用你喜欢的编辑器如VSCode、nano、vim打开 .env 文件找到X_BRAVE_API_KEY_SEARCH这一行填入你刚才获取的Data for Search密钥。这一步是可选的但填了之后容器启动日志就能显示真实的API用量强烈建议填写。其他变量如端口、日志等级保持默认即可。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.gather3. 注意资源清理使用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: querypython async await, count10, result_filterweb INFO - Using Data For Search key INFO - Web search: querypython 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 常见问题排查清单在开发和测试过程中我遇到了不少典型问题这里整理成速查表问题现象可能原因解决方案Claude Code中看不到Argus工具1..mcp.json配置错误或路径不对。2. Claude Code未重启。3. Argus容器未成功启动。1. 检查.mcp.json格式确保在Argus项目目录下。2. 完全关闭并重启Claude Code。3. 运行docker-compose ps确认容器状态查看日志。搜索返回“未授权” (401)1..mcp.json中的X-Brave-API-Key-Search密钥错误或过期。2. 该密钥对应的套餐未激活。1. 去Brave API Dashboard验证密钥重新复制粘贴。2. 确认“Data for Search”套餐处于“Active”状态。增强搜索工具不可用或报错1. 未订阅“Data for AI”套餐。2..mcp.json中未配置X-Brave-API-Key-AI。3. Data for AI额度已用尽。1. 前往Dashboard订阅免费套餐。2. 在.mcp.json的headers中添加该密钥。3. 检查日志或/ready端点确认额度。启动日志显示所有额度为0/2000.env文件中未配置X_BRAVE_API_KEY_SEARCH或配置的密钥无效。这是预期行为不影响功能。如需查看真实用量请在.env中填入有效的Search密钥。容器启动失败端口冲突默认端口8081已被其他程序占用。修改docker-compose.yml和.mcp.json中的端口号例如改为8082并确保两者一致。请求速度慢或超时1. 网络问题。2. Brave API服务暂时性故障。1. 检查本地网络。2. 稍后重试。Brave Search API的免费套餐有1次/秒的速率限制频繁请求也可能被限。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测试我个人还在考虑几个方向结果缓存层对于一些常见的、非实时性的查询例如“Python lambda用法”可以引入一个简单的本地缓存如SQLite在短时间内重复相同查询时直接返回缓存结果这能进一步节省API额度并提升响应速度。可配置的搜索偏好目前的一些参数如安全搜索等级safesearch、国家country是硬编码或默认的。未来可以考虑允许用户通过配置文件进行全局设置比如始终将safesearch设为moderate或默认搜索区域设为CN。更丰富的工具描述目前Claude Code通过MCP协议读取工具的名称和描述。可以进一步优化这些描述文本让Claude更精准地理解每个工具最适用的场景从而在用户没有明确指令时做出更智能的工具选择。最后分享一个小技巧如果你在团队中使用可以将配置好的.mcp.json文件共享给队友。他们只需要克隆仓库、配置自己的API密钥、然后启动容器就能获得完全相同的增强版Claude Code体验。这比每个人从头研究如何配置联网搜索要高效得多。工具的本质是延伸人的能力。Argus的目标就是让AI助手的能力边界平滑地扩展到整个互联网。希望这个项目和你分享的这些细节能帮你更高效地获取信息更专注地创造价值。