Agent Zero MCP 服务器状态查询接口 mcp_servers_status请求契约、双作用域解析与实现细节【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zeroAgent Zero 通过mcp_servers_status这个扁平 API 端点向 WebUI 等调用方提供 MCPModel Context Protocol服务器集群的实时状态快照。本文以该端点的 DOX 契约文档 api/mcp_servers_status.py.dox.md 为主线结合 api/mcp_servers_status.py 与底层 helpers/mcp_handler.py 的源码讲清这个端点的请求/响应契约、全局/项目双作用域的解析机制、tool_count的精确语义以及它背后的认证与 CSRF 保护体系帮助你在开发插件、扩展 WebUI 或排查 MCP 连接故障时准确调用并理解这一接口。端点定位与职责边界按照 DOX 文档api/mcp_servers_status.py.dox.md的定义这个模块的职责非常聚焦独占mcp_servers_status.py这个 API 端点处理全局或项目作用域两种口径下的 MCP 服务器状态请求实现类为McpServersStatuss继承自helpers.api.ApiHandler唯一的业务方法是async process(self, input: dict, request: Request) - dict | ResponseDOX 文件与实现文件刻意保持同目录扁平flat布局并同步维护——因为api/目录的路由是按文件名即端点名解析的DOX 与源码必须一一对应。整个端点的核心实现只有十余行见 api/mcp_servers_status.pyclass McpServersStatuss(ApiHandler): async def process(self, input: dict[Any, Any], request: Request) - dict[Any, Any] | Response: project_name (input or {}).get(project_name) if isinstance(input, dict) else None config MCPConfig.get_project_instance(project_name) if project_name else MCPConfig.get_instance() status config.get_servers_status() return {success: True, status: status}从源码结构看全部业务逻辑可归纳为三步取project_name参数 → 选择对应的MCPConfig实例项目级或全局单例→ 调用get_servers_status()收集快照。值得注意的是源码中被注释掉的try/except分支——端点契约并不返回{success: False, error: ...}这类业务级错误异常统一交给ApiHandler基类以 500 响应兜底见 helpers/api.py。请求契约可选的 project_name 与双作用域解析DOX 的Runtime Contracts一节明确了请求契约的关键点请求体接受可选的project_name字段当该字段存在时状态通过合并后的项目作用域 MCP 配置来解析。这一契约在源码中直接对应上面process方法里的三目分支其下游逻辑都在 helpers/mcp_handler.py 的MCPConfig类中实现全局作用域MCPConfig.get_instance()未携带project_name时走MCPConfig.get_instance()helpers/mcp_handler.py。它是一个带锁保护的进程级单例classmethod def get_instance(cls) - MCPConfig: with cls.__lock: if cls.__instance is None: cls.__instance cls(servers_list[], config_scopeglobal) return cls.__instanceconfig_scope被标记为global其服务器列表在运行时由设置与mcp_servers_apply等端点动态灌入。项目作用域全局 项目配置的按名合并携带project_name时走MCPConfig.get_project_instance()helpers/mcp_handler.py其解析流程是项目名经projects.validate_project_name校验空值直接回退到全局单例读取全局设置里的mcp_servers配置缺省为DEFAULT_MCP_SERVERS_CONFIG即{mcpServers: {}}定义在 helpers/mcp_handler.py再叠加projects.load_project_mcp_servers(project_key)读到的项目级配置merge_config_strings()将两份配置做按服务器名的去重合并同名服务器以项目配置覆盖全局配置未命名的服务器条目被保留在结果前列每个服务器都会被打上scope: global | project标签合并结果序列化后生成cache_key命中缓存则直接复用已构建的MCPConfig实例config_scope project:项目名未命中才重建。这个缓存键机制意味着只要全局或项目配置内容没有变化反复请求状态不会重复构建配置对象。从源码结构看这正是 DOX 所说status resolves through themergedproject-scoped MCP configuration的确切含义——项目作用域的状态永远反映全局 项目合并后的视图而非项目配置的单方面内容。响应结构status 数组里每个服务器的七个字段process返回{success: True, status: list}其中status是MCPConfig.get_servers_status()helpers/mcp_handler.py产出的服务器状态列表。该方法是读快照操作在配置锁内遍历两类服务器对象并汇总已初始化/工作中的服务器self.servers逐个读取运行时状态初始化即失败的服务器self.disconnected_servers从持久化的配置记录中补回保证连接失败但仍在配置里的服务器不会从状态页消失。每个条目的字段语义如下字段含义来源name服务器名合并时已做名称归一化server.name/ 断开记录scope作用域标签global/project/ 实例级config_scopegetattr(server, scope, self.config_scope)type传输类型stdio / http 等getattr(server, type, )description描述文本getattr(server, description, )connected是否连接成功not bool(server.get_error())——以有无错误判定error错误消息无错时为 falsy 值server.get_error()tool_count仅统计已启用工具的数量len(server.get_tools())has_log是否存在服务器日志server.get_log() ! 对disconnected_servers中的条目connected恒为Falseerror取自断开记录tool_count恒为0has_log恒为False——即彻底失败且无运行时对象的服务器不会贡献任何工具计数。源码注释特别点明了一点A server object can exist while its initialization failed即connected不是连接握手状态而是该服务器当前是否携带初始化错误。tool_count 的精确语义disabled_tools 会被排除DOX 强调tool_countreports enabled MCP tools only; tools disabled by a serverdisabled_toolslist stay hidden from agent-facing status counts。这一语义由 helpers/mcp_handler.py 中服务器对象的get_tools()实现保证def get_tools(self) - List[dict[str, Any]]: Get enabled tools from the server with self.__lock: tools self.__client.get_tools() # type: ignore disabled set(self.disabled_tools) return [tool for tool in tools if tool.get(name) not in disabled]disabled_tools是服务器配置的字段disabled_tools: list[str]解析时会经_normalize_disabled_tools归一化前端在设置页切换单个工具开关时也是直接改写这个列表见 webui/components/settings/mcp/client/mcp-servers-store.js 的toggleServerTool。因此在状态响应中tool_count与 Agent 实际可调用的工具数严格一致若需要查看被禁用的工具应走服务器详情接口get_server_detail使用get_all_tools()会为每个工具附加disabled标记。安全契约认证、CSRF 与方法限制DOX 的Work Guidance一节要求保留认证、CSRF、回环、API-key 检查除非端点契约明确变更。由于McpServersStatuss未覆写任何类方法它完整继承 helpers/api.py 中ApiHandler的默认安全契约requires_auth() - True需要登录会话session 中的认证哈希与login.get_credentials_hash()匹配未匹配则重定向登录页requires_csrf() - True默认跟随requires_auth请求必须携带与 session 一致的X-CSRF-Token头或csrf_token_runtime_idcookie否则返回 403get_methods() - [POST]仅接受 POSTrequires_api_key() - False、requires_loopback() - False不要求 API Key也不限制回环地址。路由分发由 helpers/api.py 的register_api_route()统一完成Flask 注册单条/api/path:path规则按api/mcp_servers_status.py文件名加载类缓存 handler 包装函数方法不允许时返回 405handler 不存在时返回 404并按requires_*声明逐层包裹csrf_protect、requires_api_key、requires_auth、requires_loopback装饰器。此外还有一个 watchdog 观察api/目录的.py变更并清除路由缓存意味着修改该文件后无需重启即可生效开发态热更新语义。handle_request基类方法负责 JSON 解析与响应封装process返回 dict 时序列化为application/json的 200 响应返回Response对象时直接透传任何未捕获异常返回 500 纯文本错误helpers/api.py。这也解释了为何端点契约中成功即{success: True, ...}——非 JSON 响应才需要用helpers.api.Response。前端调用方三秒轮询的状态检查仓库内确认的调用方是 WebUI 的 MCP 设置页状态仓库 webui/components/settings/mcp/client/mcp-servers-store.js。其loadStatus()通过API.callJsonApi(mcp_servers_status, this.getStatusPayload())发起请求const resp await API.callJsonApi(mcp_servers_status, this.getStatusPayload()); if (resp?.success) { this.servers resp.status || []; this.servers.sort((a, b) String(a.name || ).localeCompare(String(b.name || ))); }成功时把resp.status作为服务器列表并按名称排序展示轮询由startStatusCheck()驱动间隔STATUS_INTERVAL_MS 30003 秒静默失败不打扰用户。getStatusPayload()会在项目上下文存在时附带project_name从而复用同一端点获取项目作用域的状态——这正是一个端点、两种作用域契约在实际产品中的落地形态。变更维护与验证要点DOX 的Verification一节给出的维护指引值得在改动该端点时遵循何时必须同步 DOX请求负载、认证/CSRF 要求、响应结构、路由副作用或 WebSocket 事件契约中任何一项发生变化时联动更新变更 payload 形状时要同步更新前端调用方、插件调用方与测试测试策略DOX 明确记录No direct test reference was found by name search即当前仓库中没有按名索引到的端点专属测试变更行为时应选择最近的行为测试或对浏览器调用方做一次冒烟验证。小结mcp_servers_status端点以极小的实现体量承载了清晰的契约可选project_name切换全局/项目双作用域、按名合并的 MCP 配置解析、以connected/error/tool_count/has_log为核心的七字段状态快照以及继承自ApiHandler的认证 CSRF POST 限制安全模型。tool_count只计已启用工具的语义disabled_tools过滤保证了状态视图与 Agent 实际能力的一致性。理解了这条从 webui/components/settings/mcp/client/mcp-servers-store.js →/api/mcp_servers_status→ api/mcp_servers_status.py → helpers/mcp_handler.pyMCPConfig的调用链就可以在该端点之上安全地构建监控面板、插件状态检查或故障排查工具。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考