1. 项目概述为Claude Code打造一个“全视之眼”如果你和我一样日常重度依赖Claude Code来辅助编程、查阅文档、解决技术问题那你一定体会过它的一个核心痛点信息滞后。Claude的知识库有截止日期对于瞬息万变的技术世界比如昨天刚发布的某个框架新版本特性或者今天某个云服务商宕机的具体影响它往往无能为力。我们需要的是让这位强大的AI助手能“看到”并理解当下的互联网。这就是我开发Argus的初衷。Argus是一个基于Model Context ProtocolMCP的服务器它充当了Claude Code与Brave Search API之间的桥梁。简单来说它让Claude Code拥有了实时、精准的网页搜索能力。你可以直接在Claude Code的对话窗口里说“帮我搜索一下今天关于React Server Components性能优化的最新文章”或者“找几张适合做登录页背景的极简风格图片”Claude就能通过Argus调用Brave搜索并将结构化的结果融入它的思考过程给出结合了实时信息的答案。项目命名为“Argus”阿格斯源自希腊神话中那位拥有一百只眼睛的巨人有些眼睛永远醒着有些则休息这使他成为完美的守卫者。这个名字完美契合了Brave Search的核心机制——它不依赖于谷歌或必应的索引而是通过自己独立的爬虫网络从无数个视角持续地观察和编录整个互联网。Argus服务器正是将这种“全视”的能力安全、高效地注入到你的AI工作流中。2. 核心设计思路与架构解析在动手编码之前我花了相当长时间来思考整个系统的设计。市面上并非没有现成的搜索MCP服务器Brave官方也提供了自己的版本。但经过仔细评估我发现它们要么功能受限要么与我的使用习惯和需求不符。因此我决定从零开始打造一个更贴合开发者实际工作流、更透明、也更“经济”的解决方案。2.1 为什么选择Brave Search API首先是搜索服务提供商的选择。我对比了多个选项最终锁定Brave Search主要基于以下几点考量独立性与隐私Brave拥有自己的搜索索引不依赖于谷歌或必应。这意味着其搜索结果更具独立性避免了主流搜索引擎可能存在的“信息茧房”或商业排名干扰。同时Brave浏览器以隐私保护著称其搜索API也继承了这一理念默认不追踪用户。慷慨的免费额度对于个人开发者和小型项目成本是必须考虑的因素。Brave Search API为“Data for Search”等核心计划提供了每月2000次请求的免费额度并且速率限制1次/秒对于非高频的AI辅助搜索场景来说完全够用。这比许多其他商业API的免费门槛要友好得多。功能全面且结构清晰其API不仅提供网页搜索还细分出图片、视频、新闻、自动补全、拼写检查等多个端点返回的JSON数据结构化程度高非常容易被AI模型解析和理解。这对于构建一个功能丰富的MCP服务器至关重要。2.2 为什么不用官方Brave Search MCP Server这是一个关键决策点。Brave官方确实提供了一个MCP服务器但经过测试我发现它存在几个不符合我预期的地方强制付费计划官方服务器似乎设计为支持所有付费计划对于只想依赖免费额度的用户不够友好。我的目标是最大化利用免费资源。响应过度修剪官方服务器返回给AI的上下文是经过高度筛选和修剪的。而我更倾向于将完整的、原始的API响应当然是结构化的JSON提供给Claude Code。我相信以Claude的推理能力它完全有能力从丰富的信息中提取最关键的部分有时那些“次要”的元数据反而能提供意想不到的上下文。技术栈偏好官方服务器基于Node.js。而我更擅长并偏好使用Python进行后端开发。使用熟悉的语言能让我更快速地迭代、调试和部署。因此Argus的定位非常明确一个用Python编写、专注于免费计划、提供原始API数据、为Claude Code深度优化的Brave搜索网关。2.3 核心架构双密钥与无状态设计Argus的架构核心是安全和清晰。我设计了一套“双密钥”系统这可能是整个项目中最值得细说的设计决策。通常我们会把API密钥放在环境变量里服务启动时加载然后所有请求都用这个密钥。但这样做有几个问题1) 密钥长期驻留在容器内存中2) 无法灵活地为不同功能搜索、AI增强、拼写检查使用不同的密钥3) 密钥轮换或临时禁用某个功能比较麻烦。Argus的解决方案如下启动密钥.env文件这个密钥X_BRAVE_API_KEY_SEARCH是可选的。它的唯一作用是在Docker容器启动时调用一次Brave的用量查询接口然后将你各个API计划的剩余额度漂亮地打印在日志里。如果没提供这个密钥日志会显示用量为0/2000但这完全不影响后续功能。运行时密钥.mcp.json文件这才是真正用于执行搜索的密钥。它们以HTTP请求头Header的方式由Claude Code在每次调用工具时动态传递给Argus服务器。你可以在.mcp.json中配置多个不同的密钥分别对应搜索、AI增强、拼写检查等不同功能。{ mcpServers: { Argus: { type: http, url: http://localhost:8081/mcp, headers: { X-Brave-API-Key-Search: 你的搜索密钥, X-Brave-API-Key-AI: 你的AI增强密钥可选, X-Brave-API-Key-Autosuggest: 你的自动补全密钥可选, X-Brave-API-Key-Spellcheck: 你的拼写检查密钥可选 } } } }这样设计的好处是什么安全性API密钥不会持久化存储在Argus容器中。它们存在于你的本地配置文件.mcp.json里并且仅通过HTTPS如果配置了的话或本地网络传输。容器本身是无状态的。灵活性你可以随时在Claude Code的配置中更新密钥无需重启Argus容器。你也可以只为部分功能配置密钥比如只提供搜索密钥那么AI增强搜索等功能将自动不可用。清晰的责任分离启动时检查用量是一个“管理行为”而执行搜索是“业务行为”。将它们分开使得系统边界更清晰也便于后续扩展例如未来可以增加一个独立的管理API来查看用量而不干扰业务流。这个设计让Argus变得非常轻量和安全它只是一个纯粹的、无状态的协议转换层和路由层。3. 从零开始环境准备与详细部署指南理论说完了我们动手把它跑起来。整个过程大概需要10-15分钟前提是你已经安装了Docker。3.1 第一步获取Brave Search API密钥这是唯一需要你在第三方网站进行的操作。访问 Brave Search API 控制台 。注册与登录使用你的Brave账户或邮箱注册登录。创建应用在控制台内点击“Create New App”给你的应用起个名字比如“My Claude Code Assistant”。订阅免费计划在应用详情页找到“Subscriptions”部分。你需要至少订阅“Data for Search”这个计划。点击“Subscribe”你会看到免费套餐Free每月有2000次请求。这里Brave会要求你添加支付方式信用卡或PayPal这是为了验证身份和防止滥用只要你不超出免费额度就不会产生任何费用。我用了几个月从未被扣费。生成API密钥订阅成功后回到“Keys”标签页点击“Generate New Key”。系统会为你创建一个API密钥务必立即复制并保存好因为它只显示一次。实操心得建议你一次性把四个免费计划都订阅了“Data for Search”, “Data for AI”, “Autosuggest”, “Spellcheck”。虽然核心搜索只需要第一个但另外三个能解锁非常有用的功能后文会详述而且都有免费额度。反正不要钱何乐而不为呢为每个计划分别生成一个密钥或者如果你愿意也可以用一个密钥关联所有计划在创建密钥时选择所有权限。我更喜欢分开这样在日志里能看到每个功能分别消耗了多少额度。3.2 第二步本地部署Argus服务器拿到密钥后剩下的就全是本地操作了。# 1. 克隆项目仓库 git clone https://github.com/IT-Square-Plus/Argus cd Argus # 2. 复制并配置环境变量模板 cp .env.example .env现在用你喜欢的文本编辑器打开.env文件。你只需要关注一个关键变量# 可选用于启动时显示准确的API用量。不填也能用只是日志里用量显示为0。 X_BRAVE_API_KEY_SEARCHsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx把sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx替换成你刚刚复制的“Data for Search”计划的API密钥。其他变量如服务器端口、日志级别可以保持默认。接下来配置Claude Code如何连接Argus# 3. 复制并配置MCP客户端配置模板 cp .mcp.json.example .mcp.json打开.mcp.json文件这是整个配置的核心{ mcpServers: { Argus: { type: http, url: http://localhost:8081/mcp, headers: { X-Brave-API-Key-Search: sk_你的搜索密钥, X-Brave-API-Key-AI: sk_你的AI增强密钥可选, X-Brave-API-Key-Autosuggest: sk_你的自动补全密钥可选, X-Brave-API-Key-Spellcheck: sk_你的拼写检查密钥可选 } } } }X-Brave-API-Key-Search是必须填写的否则任何搜索功能都无法工作。其他三个键是可选的。如果你订阅了对应的计划并生成了密钥就填上去这样就能解锁增强搜索、自动补全和拼写检查功能。重要注意事项.mcp.json文件通常位于你的 Claude Code 配置目录下。在 macOS 上路径可能是~/Library/Application Support/Claude/claude_desktop_config.json但Argus项目里的这个文件是模板。最稳妥的做法是将配置好的Argus对象合并到你 Claude Code 的全局MCP配置文件中。你可以打开Claude Code的设置找到“开发者设置”或“MCP服务器”部分通常有直接编辑配置文件的入口。将上面这个Argus块复制到mcpServers对象里即可。3.3 第三步启动服务并验证配置完成后一键启动# 4. 使用Docker Compose启动容器-d 表示后台运行 docker-compose up -d第一次运行会拉取Python镜像并构建Argus的Docker镜像稍等片刻。使用以下命令查看日志确认服务已正常启动docker-compose logs -f你应该能看到类似以下的输出特别是如果正确配置了启动密钥会打印出详细的API用量argus-1 | INFO: Started server process [1] argus-1 | INFO: Waiting for application startup. argus-1 | INFO: Application startup complete. argus-1 | INFO: Uvicorn running on http://0.0.0.0:8081 (Press CTRLC to quit) argus-1 | INFO: Argus MCP Server v1.0.1 is ready! argus-1 | INFO: API Usage Overview: argus-1 | INFO: Data For Search: [████████████░░░░░░░░░░░░░░░░░░░░] 150/2000 (7.5%) - 1850 remaining argus-1 | INFO: Data For AI: [██████████████████████████████████] 2000/2000 (100.0%) - 0 remaining argus-1 | INFO: Spellcheck: [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 0/5000 (0.0%) - 5000 remaining argus-1 | INFO: Autosuggest: [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 0/5000 (0.0%) - 5000 remaining最后验证健康端点# 5. 检查服务是否就绪 curl http://localhost:8081/ready如果返回一个包含status: ready的JSON说明一切就绪。3.4 第四步在Claude Code中启用最后一步是重启Claude Code应用让它重新加载MCP配置识别到新添加的Argus服务器。重启后你可以打开Claude Code尝试问它“你现在有哪些工具可以用”或者“列出你的可用工具”。Claude应该会回应在它的工具列表里包含了search_web,search_images等来自Argus的工具。至此你的Claude Code就拥有了“全视之眼”。4. 核心工具详解与高效使用技巧Argus为Claude Code提供了多个工具但最常用、最强大的无疑是网页搜索。理解每个工具的细节和最佳实践能让你和Claude的协作效率倍增。4.1search_web你的主力信息检索工具这是最核心的工具。当你在Claude Code中说“搜索一下关于Python异步编程的最佳实践”Claude就会调用这个工具。关键参数解析query(必需)你的搜索词。尽量清晰、具体。“Python异步编程”就比“异步”好得多。count返回结果数量默认10最大20。对于一般性问题10个足够。如果你在做深度调研可以调到20。result_filter这是控制上下文令牌消耗的阀门这个参数决定了返回哪些类型的结果簇cluster。web(默认约3000令牌)强烈推荐日常使用。只返回普通的网页结果信息量适中足够Claude提取核心内容。(空字符串约10000令牌)返回所有结果类型包括网页、新闻、视频、讨论、FAQ等。这会给Claude提供极其丰富的上下文但代价是消耗大量令牌可能挤占它用于分析和回答的“脑容量”。仅在你需要全方位了解一个话题时使用。其他过滤值如news,videos,discussions等或者组合如web,news。当你明确知道需要找特定类型的内容时使用。使用示例与技巧直接对Claude说“使用search_web工具查询‘如何在Docker中配置Redis持久化’返回5条结果只要网页内容。” Claude会理解并构造正确的调用。避坑指南不要滥用result_filter。10000令牌的上下文非常庞大不仅响应慢而且可能让Claude陷入“信息过载”在无关细节上打转。我的经验是95%的情况下result_filterweb是最佳选择。只有当Claude基于前几轮简单搜索后的回答依然显得片面时再考虑使用全量搜索进行“深挖”。4.2search_web_extra_snippets_for_ai为AI特供的深度搜索这个工具是search_web的增强版需要你拥有“Data for AI”计划的API密钥。它的核心价值在于为每一条搜索结果额外提供最多5个摘要片段snippet。这意味着什么普通搜索只返回一个摘要片段。而这个工具返回的是围绕这个网页核心内容的多个信息切片。比如一个关于“机器学习模型部署”的页面普通摘要可能只提到部署工具而增强搜索的多个片段可能会分别提及工具A的优缺点、工具B的适用场景、一个具体的Docker配置示例、关于模型监控的注意事项等等。这为Claude带来了6倍于普通搜索的上下文素材让它能更全面、更深入地理解目标网页的内容从而给出更精准、更具洞察力的总结或答案。这对于研究性任务、技术方案对比、撰写综合性报告等场景是无可替代的神器。使用场景“使用增强搜索帮我找出三篇对比React和Vue在大型项目中状态管理方案的深度文章。” “用增强搜索查一下AWS Lambda最近一年新增了哪些重要特性每篇找3条结果。”4.3 垂直搜索三剑客search_images,search_videos,search_news这三个工具分别专注于图片、视频和新闻搜索。它们的存在不仅仅是为了功能完整更关乎“AI节省策略”——这是我为Argus设计的一个核心优化逻辑。问题来了当我对Claude说“找一张可爱的猫猫图片”时Claude有两个选择调用通用的search_web或search_web_extra_snippets_for_ai并尝试从网页结果中识别出图片。调用专门的search_images工具。显然第二个选择更高效、结果更精准。但这里有一个成本考量search_web消耗的是“Data for Search”计划的额度而search_web_extra_snippets_for_ai消耗的是更“宝贵”的“Data for AI”计划额度虽然免费但你可能想把它留给更需要深度分析的文本搜索。AI节省策略如何工作Argus在后台实现了一套智能路由逻辑。当Claude调用search_images,search_videos,search_news时服务器会先检查你的API用量情况如果“Data for AI”额度剩余 50%说明你的AI增强搜索额度还很充裕。此时Argus会优先使用“Data for Search”计划的密钥来执行这次图片/视频/新闻搜索。目的是节省“Data for AI”的额度留给真正的增强文本搜索。如果“Data for AI”额度不足50%但“Data for Search”额度剩余 ≥ 10%继续使用“Data for Search”密钥。如果“Data for Search”额度剩余 10%哎呀通用搜索额度快用完了得省着点。这时Argus才会转而使用“Data for AI”计划的密钥来执行这次垂直搜索。这个策略的逻辑是在大部分情况下用通用的搜索额度来处理多媒体的查询把更“高级”的AI额度留给更需要它的文本深度分析任务。你可以在Docker容器的日志中清晰地看到这个决策过程INFO - ️ search_images called: querycute cat, count3 INFO - AI-Saving Policy: AI has 92.8% remaining (50%) → Using Search to save AI INFO - Using Data For Search key ... INFO - Used 1 request from Data For Search quota给你的建议在向Claude描述搜索意图时可以稍微具体一点。例如“用search_images工具找三张展示现代UI设计的截图”就比“找点UI设计图片”更好后者可能会让Claude犹豫该用哪个工具。4.4 辅助工具suggest与spellcheck这两个工具需要额外的API计划但能显著提升交互体验。suggest(自动补全)当你输入一个不完整或常见的查询词时Claude可以调用此工具获取补全建议从而帮你优化搜索词。例如你输入“Py”它可能建议“Python tutorial”、“PyTorch”、“Pygame”。spellcheck(拼写检查)对于非母语使用者尤其有用。它能纠正查询词中的拼写错误确保搜索的准确性。它们通常由Claude在后台智能调用你无需显式指定。5. 高级配置、监控与故障排查当服务稳定运行后你可能需要关注用量、调整配置或者解决一些常见问题。5.1 深入理解配置文件除了基本的密钥配置.env文件中还有一些有用的参数# MCP Server Configuration MCP_SERVER_HOST0.0.0.0 # 监听所有网络接口。如果只在本地使用可改为127.0.0.1以增强安全。 MCP_SERVER_PORT8081 # 服务端口如果冲突可以修改。 LOG_LEVELINFO # 日志级别。DEBUG会打印所有HTTP请求/响应细节用于深度调试但日志量巨大。 # Free Plan Limits (for usage tracking) # 这些数字用于在日志中绘制进度条与实际API限额一致一般无需修改。 DATA_FOR_SEARCH_FREE_PLAN_MAX_USAGE2000 DATA_FOR_AI_FREE_PLAN_MAX_USAGE20005.2 健康检查与用量监控Argus提供了两个HTTP端点非常适合集成到你的监控系统或简单的运维脚本中。GET /health(存活探针)返回简单的存活状态。Kubernetes或Docker Swarm等编排工具会用这个端点来判断容器是否崩溃需要重启。curl -s http://localhost:8081/health | jq . # 输出{status: alive, service: Argus, version: 1.0.1}GET /ready(就绪探针)这是更有用的端点。它不仅检查服务是否运行还汇报其能力状态和实时API用量。这是部署后验证服务是否完全就绪的最佳方式。curl -s http://localhost:8081/ready | jq .你会得到一个详细的JSON包含所有工具是否可用以及各个API计划的已用量、剩余量和百分比。这个信息和你启动时在日志里看到的一致但可以随时获取。5.3 常见问题与解决方案实录在开发和日常使用中我遇到并解决了一些典型问题。这里记录下来希望能帮你快速排雷。问题1Claude Code提示“无法连接到MCP服务器”或工具列表里没有Argus的工具。检查步骤确认Argus容器在运行docker-compose ps应显示argus服务状态为Up。检查端口curl http://localhost:8081/health是否能返回成功。检查Claude配置确保.mcp.json中的配置已正确合并到Claude Code的全局MCP配置文件并且URL端口与Argus服务端口一致。重启Claude Code任何对MCP配置的修改都必须重启Claude Desktop应用才能生效。根本原因99%的情况是Claude Code的配置文件路径不对或没有重启。问题2搜索返回错误日志显示“403 Forbidden”或“Invalid API Key”。检查步骤确认密钥有效前往Brave API控制台确认密钥未被撤销且对应的订阅计划如Data for Search仍处于活跃状态。检查密钥位置确认错误是针对哪个工具。如果是所有工具都报错检查.mcp.json中的X-Brave-API-Key-Search。如果只是search_web_extra_snippets_for_ai报错则检查X-Brave-API-Key-AI。检查密钥格式确保密钥完整复制没有多余的空格或换行。API密钥通常以sk_开头。根本原因API密钥错误、过期或没有对应功能的订阅。问题3用量统计在日志中始终显示为0/2000。原因你没有在.env文件中配置X_BRAVE_API_KEY_SEARCH变量或者配置的密钥无效。这是预期行为不影响功能启动密钥仅用于在日志中展示用量。实际的用量扣减发生在每次通过.mcp.json中密钥发起的请求中。你可以通过调用/ready端点来查看实时用量只要运行时密钥正确。解决方案在.env中填入一个有效的“Data for Search”密钥然后重启容器docker-compose restart。问题4搜索速度感觉有点慢。可能原因网络延迟Brave的API服务器可能在海外。这是无法避免的但通常延迟在可接受范围内200-500ms。结果过滤如果你使用了result_filter全量结果Brave API需要聚合更多数据响应时间会显著增加。Claude处理上下文返回的结果越多Claude需要分析和理解的时间也越长。优化建议默认使用result_filterweb。适当减少count参数比如从10降到5。确保你的本地网络连接稳定。问题5Docker容器启动失败提示端口被占用。解决方案修改.env文件中的MCP_SERVER_PORT变量比如改为8082同时也要修改.mcp.json中的url为http://localhost:8082/mcp。然后重新运行docker-compose up -d。经过几个月的持续使用和迭代Argus已经成为了我开发工作流中不可或缺的一环。它不仅仅是一个搜索工具更是扩展了Claude Code的能力边界让它从一个静态的知识库变成了一个能实时感知互联网脉搏的智能伙伴。从查询最新的错误解决方案到寻找设计灵感再到跟踪技术趋势这个过程变得无比自然流畅。这个项目的代码是完全开源的如果你对Python、FastAPI或MCP协议感兴趣也非常欢迎你查看源码、提出Issue甚至提交PR。未来的计划包括为API用量设置硬性上限以防止意外超支以及完善CI/CD流程。希望Argus这只“百眼巨人”也能为你的AI辅助编程之旅保驾护航。