foobara-py MCP 服务器实现

关键词

AI服务端资源管理工具执行JSON-RPCSTDIO

使用说明（Markdown 格式）

一、项目简介

  • foobar a-py 的 MCP 服务器实现，面向 LLM 客户端，提供标准化的资源管理、工具注册/执行、以及提示模板的服务能力。服务器端通过 JSON-RPC 2.0 风格的消息进行通信，支持单条请求和批量请求，包含会话管理与能力声明等基础能力。

二、主要功能点

  • MCP 协议核心能力
    • 处理 MCP 请求与响应，支持初始化握手、工具列表与调用、资源列表与读取、提示模板读取，以及心跳（ping）等基础方法。
    • 支持批量请求（数组形式的请求）和普通请求（单条请求），并对通知请求不返回响应。
    • 会话管理、版本协商、服务器能力声明（工具、资源、提示等）以及服务器信息回传。
  • 资源、工具、提示注册与查询
    • 注册资源（add_resource）、注册提示模板（add_prompt）、注册工具（通过域内命令注册为 MCP Tool）。
    • 提供资源清单与逐条读取能力、工具列表与调用能力、Prompts 列表与获取能力。
  • 入口与运行
    • 提供 MCPConnector 类和 create_mcp_server 工厂函数，便于将命令/域/组织挂载到 MCP 服务端，并通过 run_stdio() 在 STDIO 模式下运行。
  • 适配与扩展
    • 设计了会话对象 MCPSession、请求统计、错误码映射等，方便后续扩展传输通道（例如 SSE/WebSocket 的扩展实现）。

三、安装与运行

  • 安装
    • 使用 pip 安装 foobara-py（包含 MCP 服务器组件）。
  • 运行方式（核心点）
    • 该仓库提供 MCP 服务端核心实现与入口工厂 create_mcp_server，运行时需要一个入口脚本来创建 MCPConnector、注册应用的命令/域/组织、再调用 run_stdio() 启动。
    • 注意：仓库中没有现成的命令行入口直接启动 MCP 服务器，需要你编写一个入口脚本或模块，按需注册要暴露的命令与域，并从该入口启动 MCP 服务。
  • 启动示例思路（非代码片段，供理解）
    • 创建一个入口脚本：导入 foobara_py.connectors.mcp.MCPConnector，实例化后注册你的命令域/域/组织，最后调用 MCPConnector.run_stdio() 进入阻塞运行等待 MCP 客户端通过标准输入输出进行 JSON-RPC 通信的交互。
    • 也可以通过 create_mcp_server() 工厂函数搭建服务器对象，注册命令后再以自定义方式启动。

四、服务器配置（给 MCP 客户端的连接配置示例，JSON 格式，供参考） 请注意以下配置是给 MCP 客户端在 Claude/其他工具中接入服务器的示例描述，实际需在你的环境中按入口脚本实现来使用。下列 JSON 用于描述服务器启动信息，包含服务端名称、启动命令及参数等信息（非代码片段，仅供配置参考）： { "serverName": "foobara-py", "type": "stdio", "command": "python", "args": ["-m", "foobara_py.connectors.mcp_entrypoint"] // 必须指向一个实际启动 MCP 的入口脚本/模块 } 注释说明

  • serverName: MCP 服务器在客户端侧显示的名称，建议与实际部署中的服务名称保持一致，便于识别。
  • type: 传输模式，此处采用 stdio（标准输入输出）作为最基本的 MCP 传输通道，仓库实现提供了 run_stdio()。
  • command 与 args: 启动服务器的系统命令及参数，需指向一个能够创建 MCPConnector、注册命令并调用 run_stdio() 的入口脚本。你可以基于仓库提供的 create_mcp_server 与 MCPConnector 的用法，自行实现入口。

五、基本使用方法（操作步骤）

  • 准备阶段
    • 确认已安装 foobara-py 及其 MCP 相关组件。
    • 编写一个入口脚本，创建 MCPConnector、注册需要暴露给 MCP 客户端的命令/域，并调用 run_stdio() 进入阻塞监听客户端请求。
  • 启动阶段
    • 使用上述配置在客户端（如 Claude）中配置 MCP 服务，确保客户端能够通过标准输入输出与服务器交互。
  • 交互阶段
    • 客户端向服务器发送 MCP 请求（如 tools/list、tools/call、resources/list、resources/read、prompts/list、prompts/get、ping 等）。
    • 服务器返回符合 JSON-RPC 2.0 风格的响应，或发送通知（无 id 的请求）等。
  • 运行与扩展
    • 可以通过 create_mcp_server 工厂函数在应用中快速搭建 MCP 服务，按需注册域内命令、域及组织，扩展资源/提示/工具等。

六、注意事项

  • 该实现以 STDIO 为核心传输方式（run_stdio），若需要 SSE/WebSocket 等传输，需要后续扩展实现。
  • MCP 服务端的命名与注册需要与你的命令域结构保持一致，确保 Tools 列表与资源、提示能正确暴露给客户端。
  • 客户端连接时，服务器需要在合适的时机完成 initialize 握手、能力宣告、以及后续请求路由。

七、相关性与扩展性

  • 本仓库中包含的 MCP 相关代码主要集中在 foobara_py/connectors/mcp.py，提供核心的 MCP 服务器实现能力（JSON-RPC 2.0 风格、批量请求、通知、会话、资源/提示/工具等管理、以及初始化握手等）。
  • 该实现具备可运行的服务器骨架与接口设计，但通常需要在实际应用中自建入口脚本来启动服务，并完成命令/域/组织的注册。

七、关键词 AI服务端, 资源管理, 工具执行, JSON-RPC, STDIO

八、分类 6

服务器信息

访问项目