使用说明

项目简介

Maoto Agent MCP服务器是基于Maoto Agent框架构建的，实现了Model Context Protocol (MCP) 协议的服务端组件。它允许开发者将基于FastAPI构建的Maoto Agent应用轻松扩展为MCP服务器，从而为LLM客户端提供标准化的工具调用能力。通过集成'fastapi-mcp'库，该服务器能够自动将FastAPI定义的接口转化为MCP工具，并支持使用MCP Inspector进行工具的查看和测试。

主要功能点

MCP协议支持: 实现了MCP协议，能够与MCP客户端进行通信，处理工具发现、调用等请求。
工具注册与发现: 允许开发者将FastAPI endpoint注册为MCP工具，并支持客户端通过MCP协议发现这些工具。
FastAPI集成: 无缝集成FastAPI框架，利用FastAPI的路由和依赖注入等特性构建MCP工具。
MCP Inspector兼容: 支持使用MCP Inspector工具进行工具的浏览、测试和文档查看，方便开发者调试和验证工具功能。
灵活配置: 提供MCP相关的配置选项，例如MCP服务器名称、描述、挂载路径等。

安装步骤

安装 Maoto Agent MCP 扩展: 使用pip安装'maoto-agent'，并指定 'mcp' 扩展以包含MCP服务器功能。
```
pip install "maoto-agent[mcp]"
```

创建 Maoto Agent 应用并启用 MCP: 在你的Python FastAPI应用中，导入 'Maoto' 和 'MCPServer'，并初始化 'MCPServer' 将其绑定到你的 'Maoto' 应用实例。你需要提供Maoto API Key以初始化 'Maoto' 应用。

from maoto_agent.maoto_agent import Maoto
from maoto_agent.mcp import MCPServer
from pydantic import SecretStr

# 创建 Maoto 应用，需要API Key
app = Maoto(apikey=SecretStr("your-api-key-here"))  # 替换为你的实际 API Key
# 初始化 MCP 服务器并绑定到 Maoto 应用
mcp = MCPServer(app)

服务器配置 (MCP客户端配置)

MCP客户端需要配置连接到此MCP服务器的信息。以下是一个JSON格式的配置示例，你需要将其提供给MCP客户端。

{
  "server name": "Maoto Agent MCP Server",
  "command": "uvicorn",
  "args": [
    "<module_path>:Maoto",  //  将 '<module_path>' 替换为你的 Maoto 应用模块路径，例如 'src.maoto_agent.maoto_agent'
    "--reload"              //  可选参数，开启热重载，方便开发调试
  ],
  "env": {
    "MAOTO_APIKEY": "<your_api_key_here>" // 将 '<your_api_key_here>' 替换为你的 Maoto API Key，或者设置为环境变量
  }
}

配置参数说明:

'server name': MCP服务器的名称，可以自定义，用于在MCP客户端中标识服务器。
'command': 启动MCP服务器的命令，这里使用 'uvicorn' 启动FastAPI应用。
'args': 启动命令的参数列表。
- '<module_path>:Maoto': 必须替换。指向你的Maoto应用的模块路径和'Maoto'类名。例如，如果你的'Maoto'类定义在 'src/my_app/main.py' 文件中，则应替换为 'src.my_app.main:Maoto'。
- '--reload': 可选。开启Uvicorn的热重载功能，在开发阶段修改代码后服务器会自动重启。生产环境通常不需要开启。
'env': 环境变量配置。
- 'MAOTO_APIKEY': 必须配置。Maoto Agent 需要API Key进行认证。你需要将 '<your_api_key_here>' 替换为你的实际API Key，或者将 'MAOTO_APIKEY' 设置为系统环境变量。

基本使用方法

启动 MCP 服务器: 根据上述 服务器配置 中的 'command' 和 'args'，启动你的 FastAPI 应用。例如，如果你的模块路径是 'src.maoto_agent.maoto_agent'，则可以使用以下命令：

export MAOTO_APIKEY="your-api-key-here" # 设置API Key环境变量 (或者直接替换配置JSON中的 <your_api_key_here>)
uvicorn src.maoto_agent.maoto_agent:Maoto --reload

注册 MCP 工具: 你可以使用 'mcp.add_tool' 装饰器将你的 FastAPI endpoint 注册为 MCP 工具。例如：

from maoto_agent.maoto_agent import Maoto
from maoto_agent.mcp import MCPServer
from fastapi import APIRouter

app = Maoto(apikey="your-api-key")
mcp = MCPServer(app)
router = APIRouter()

@router.get("/hello")
@mcp.add_tool
async def hello_world():
    """
    一个简单的示例工具，返回 "Hello, world!"。
    """
    return {"message": "Hello, world!"}

app.include_router(router)

使用 MCP Inspector 测试工具: 安装并运行 MCP Inspector，它会自动连接到你的 MCP 服务器并显示注册的工具。你可以通过 Inspector 界面查看工具文档、测试工具，并监控工具执行情况。
```
npx @modelcontextprotocol/inspector python -m src.maoto_agent.mcp.server
```
请确保将命令中的 'src.maoto_agent.mcp.server' 替换为你的 'MCPServer' 类所在的实际模块路径。

通过以上步骤，你就可以将 Maoto Agent 应用配置为一个有效的 MCP 服务器，并使用 MCP 客户端或 Inspector 进行工具的交互和管理。

关键词