使用说明

项目简介

khivemcp 是一个Python库，旨在简化 Model Context Protocol (MCP) 服务器的开发。它构建于高性能的 FastMCP 服务器之上，通过提供配置驱动的方式和装饰器，让开发者能够更便捷地定义和管理 MCP 服务器的资源、工具和 Prompt 模板。开发者可以使用简单的Python类和配置文件来构建功能丰富的 MCP 服务，而无需关注底层的协议细节和服务器搭建。

主要功能点

配置驱动的服务结构： 通过 YAML 或 JSON 配置文件声明式地定义 MCP 服务的结构、服务组实例以及工具命名，易于管理和扩展服务。
装饰器驱动的工具定义： 使用 '@khivemcp.operation' 装饰器将 Python 异步方法暴露为 MCP 工具（operations），简化工具注册流程。
动态加载服务组： 根据配置文件动态加载服务组类 ('class_path')，实现模块化设计，方便组织和复用不同的工具集。
基于Pydantic的Schema验证： 支持使用 Pydantic Schema ('@operation(schema=...)') 对 MCP 操作的输入进行自动验证，提升工具接口的清晰度和健壮性。
集成FastMCP： 基于高效的 FastMCP 库构建，继承了 FastMCP 的高性能和稳定的 MCP 协议通信能力。
有状态的服务组： 服务组类会被实例化，允许工具（operations）在同一个组实例中保持状态，满足更复杂的服务场景需求。

安装步骤

确保已安装 Python 3.10+ 和 'uv' (或 'pip')。

创建虚拟环境 (推荐):

uv venv
source .venv/bin/activate

使用 'uv' 或 'pip' 安装 'khivemcp':

uv pip install khivemcp

服务器配置

MCP 客户端需要配置 MCP 服务器的启动命令才能连接到 'khivemcp' 服务器。以下是一个配置示例，通常在 MCP 客户端的配置文件（如 JSON 格式）中 'mcpServers' 字段下进行配置：

{
  "mcpServers": {
    "my-khivemcp-server": {  // 服务器名称，客户端用于引用
      "command": "uv",      // 启动服务器的命令，这里使用 uv
      "args": [             // 命令参数列表
        "run",              // uv run 子命令，用于运行 Python 模块
        "python",           // 使用 python 解释器
        "-m",               // 运行模块
        "khivemcp.cli",     // 模块名，khivemcp 的命令行接口
        "/path/to/your/service_config.json" // 你的服务配置文件路径 (或 group_config.json)
      ]
    }
  }
}

基本使用方法

定义服务组 (Service Group):

创建 Python 文件（例如 'my_group.py'），定义一个继承自 'khivemcp.ServiceGroup' 的类。
使用 '@khivemcp.operation' 装饰器标记类中的异步方法，使其成为 MCP 工具。
可以使用 Pydantic 'BaseModel' 定义输入 schema，用于参数校验和接口文档生成。

# my_group.py
from khivemcp import operation, ServiceGroup
from pydantic import BaseModel

class MyInputSchema(BaseModel):
    text: str

class MyGroup(ServiceGroup):
    @operation(name="echo", description="Echoes back the input text.", schema=MyInputSchema)
    async def echo_text(self, *, request: MyInputSchema) -> dict:
        return {"message": request.text}

创建配置文件:

创建 JSON 或 YAML 配置文件（例如 'my_service_config.json'），描述服务组的配置信息，包括服务组名称、类路径等。

// my_service_config.json
{
  "name": "my-service",
  "description": "My first khivemcp service",
  "groups": {
    "my_group_instance": {  // 服务组实例的逻辑名称
      "name": "mygroup",     // MCP 工具的前缀，例如 mygroup.echo
      "class_path": "my_group:MyGroup", // Python 类路径，指向 MyGroup 类
      "description": "My echo group"
    }
  }
}

启动 MCP 服务器:

使用 'khivemcp' 命令行工具，指定配置文件路径来启动服务器。

uv run python -m khivemcp.cli /path/to/my_service_config.json

客户端调用:
- 在 MCP 客户端中配置连接到 'khivemcp' 服务器，并调用定义好的 MCP 工具，例如 'mygroup.echo'。

通过以上步骤，即可快速搭建基于 'khivemcp' 的 MCP 服务器，并提供自定义的工具供 LLM 客户端调用。

关键词

使用说明

信息