项目简介

CHUK MCP Runtime 是一个用于构建和运行 Model Context Protocol (MCP) 服务器的 Python 框架。它不仅允许您轻松托管基于 Python 的本地工具和上下文资源，还能作为一个代理层连接并统一管理多个远程 MCP 服务器，为 LLM（大型语言模型）客户端提供一个标准化且功能丰富的后端服务。

主要功能点

托管本地 MCP 工具: 使用简单的 Python 装饰器 '@mcp_tool' 即可将 Python 函数注册为可被 LLM 调用的工具，并自动生成工具的描述和参数 schema。
管理上下文信息: 支持定义和提供 LLM 交互所需的资源（Resources）和 Prompt 模板（Prompts）（虽然文档中工具是重点，但结构支持这些功能）。
代理远程 MCP 服务器: 可以通过 Stdio, SSE 等协议连接到其他 MCP 服务器，并将它们的工具、资源等能力统一暴露给本地的 LLM 客户端。
支持多种传输协议: 服务器本身可以配置为通过 Stdio 或 SSE (作为 Web 服务器) 与客户端通信，未来可能支持 WebSocket。
OpenAI 兼容模式: 可选择将工具名称转换为 OpenAI 函数调用 API 兼容的下划线格式。

安装步骤

推荐使用 'uv' 包管理器进行安装：

# 基础安装
uv pip install chuk-mcp-runtime

# 安装包含 WebSocket 等可选依赖的版本
uv pip install chuk-mcp-runtime[websocket,dev]

# 确保安装 tzdata 以获得正确的时区支持
uv pip install tzdata

服务器配置（供MCP客户端参考）

当您使用 CHUK MCP Runtime 启动一个 MCP 服务器后，您的 MCP 客户端需要知道如何连接到它。以下是 MCP 客户端配置中用于连接到由 'chuk-mcp-runtime' 启动的服务器的典型 JSON 结构示例，以及各参数的说明。请注意，以下是客户端配置示例，不是 CHUK MCP Runtime 本身的 YAML 配置文件。

{
  "servers": {
    "您为服务器指定的名称": {
      "type": "stdio",
      "command": [
        "uv",
        "run",
        "-m",
        "chuk_mcp_runtime.main"
      ],
      "args": [
        "--config",
        "/path/to/您的服务器配置文件.yaml"
      ]
    }
    // 或者，如果配置为SSE服务器:
    // "您的SSE服务器名称": {
    //   "type": "sse",
    //   "url": "http://localhost:8000/sse",
    //   "message_url": "http://localhost:8000/messages/" // 或其他客户端库需要的消息发送URL/路径
    //   // "api_key": "您的可选API密钥" // 如果配置了Bearer认证
    // }
  }
}

参数说明：

'您为服务器指定的名称': 在客户端中标识该服务器的唯一名称。
'type': 服务器的传输协议类型。对于 CHUK MCP Runtime，通常是 '"stdio"' 或 '"sse"'。
'command': (仅用于 '"stdio"') 启动 MCP 服务器进程的命令行及参数列表。客户端会执行此命令来启动服务器并建立 Stdio 连接。
- '"uv", "run", "-m", "chuk_mcp_runtime.main"': 这是使用 'uv' 运行 'chuk_mcp_runtime' 主入口点的标准方式。
- '"--config", "/path/to/您的服务器配置文件.yaml"': 指定 CHUK MCP Runtime 服务器实际加载的 YAML 配置文件路径。客户端需要知道这个路径才能正确启动服务器。
'url': (仅用于 '"sse"') MCP SSE 服务器的订阅端点 URL。
'message_url' / 'message_path': (仅用于 '"sse"') MCP SSE 服务器接收客户端消息（如工具调用请求）的 POST 端点 URL 或路径。具体名称取决于使用的 MCP 客户端库。
'api_key': (可选，仅用于 '"sse"') 如果 SSE 服务器配置了 Bearer 认证，客户端需要在此提供 API 密钥。

基本使用方法

创建工具代码: 编写 Python 函数，使用 '@mcp_tool' 装饰器定义工具名称、描述和参数。

# my_tools/tools.py
from chuk_mcp_runtime.common.mcp_tool_decorator import mcp_tool

@mcp_tool(name="get_current_time", description="Get the current time in a timezone")
async def get_current_time(timezone: str = "UTC") -> str:
    """Get the current time in the specified timezone."""
    from datetime import datetime
    import pytz
    tz = pytz.timezone(timezone)
    now = datetime.now(tz)
    return now.strftime("%Y-%m-%d %H:%M:%S %Z")

（注意：工具函数必须是异步的 'async def'）

创建服务器配置文件: 创建一个 YAML 文件（例如 'config.yaml'），指定服务器类型（stdio 或 sse）和本地工具模块的位置。

# config.yaml
host:
  name: "my-mcp-server"
  log_level: "INFO"

server:
  type: "stdio" # 或 "sse" 并配置端口等

tools:
  registry_module: "chuk_mcp_runtime.common.mcp_tool_decorator"
  registry_attr: "TOOLS_REGISTRY"

mcp_servers:
  local_tools: # 可以给本地工具起个服务器名称
    location: "./my_tools" # 工具模块所在的目录
    tools:
      module: "my_tools.tools" # 工具所在的模块文件 (相对于location的路径，或Python模块名)

启动服务器: 在终端中使用 'uv run' 命令启动服务器，指定配置文件的路径。

# 如果 config.yaml 在当前目录
uv run -m chuk_mcp_runtime.main --config config.yaml

# 或者如果 config.yaml 在其他位置
uv run -m chuk_mcp_runtime.main --config /path/to/your/config.yaml

连接客户端: 服务器启动后，使用兼容 MCP 协议的 LLM 客户端（例如 'chuk-tool-processor'）连接到该服务器（参考上面的客户端配置示例），即可发现并调用您定义的工具。

关键词

AI工具后端, 语言模型集成, 代理服务, 上下文服务

关键词

项目简介

主要功能点

安装步骤

服务器配置（供MCP客户端参考）

基本使用方法

关键词

信息