Pokemon信息查询工具

MCP客户端管理器-口袋妖怪MCP服务器

一种模型上下文协议（MCP）服务器实现，使用PokeAPI提供与Pokemon相关的工具。本项目演示了如何使用FastMCP（Python）创建和测试MCP服务器，并使用MCP客户端管理器SDK（Node.js）对其进行测试。

特性

• 🔍 获取口袋妖怪信息：按名称或ID获取任何口袋妖怪的详细信息
• 🎨 获取口袋妖怪类型：获取有关口袋妖怪类型的信息，并列出该类型的口袋妖怪
• 🎲 获取随机口袋妖怪：从整个Pokedex中随机发现一个口袋妖怪
• ✅ 综合测试：使用Jest的完整测试套件

先决条件

• Node.js （v18或更高版本）
• python （v3.8或更高版本）
• npm 或 纱线
• 点 （Python包管理器）

项目结构

mcp-client-manager/
├── pokemon-mcp.py           # FastMCP server with Pokemon tools
├── tests/
│   └── pokemon-mcp.test.js  # Jest tests for Pokemon MCP
├── package.json             # Node.js dependencies
├── .gitignore              # Git ignore rules
└── README.md               # This file

设置

1.安装Node.js依赖项

npm install

这将安装：

• @mcpjam/sdk -MCP客户端管理器SDK
• jest -测试框架

2.安装Python依赖项

pip install fastmcp requests

• fastmcp -构建MCP服务器的框架
• requests -API调用的HTTP库

运行Pokemon MCP服务器

启动Pokemon MCP服务器：

python pokemon-mcp.py

默认情况下，服务器将以STDIO传输模式启动，准备接收MCP协议消息。

可用工具

1. get_pokemon

获取特定口袋妖怪的详细信息。

参数：

• name （string）：口袋妖怪名称或ID

例子：

await manager.executeTool("pokemon_mcp", "get_pokemon", {
    name: "pikachu"
});

退货：

• 口袋妖怪名称和ID
• 类型
• 身高和体重
• 能力

2. get_pokemon_type

获取有关口袋妖怪类型的信息，并列出该类型的口袋妖怪。

参数：

• type_name （string）：类型名称（例如“火”、“水”、“电”）

例子：

await manager.executeTool("pokemon_mcp", "get_pokemon_type", {
    type_name: "electric"
});

退货：

• 类型名称
• 该类型的前20个口袋妖怪列表

3. get_random_pokemon

获取有关随机口袋妖怪的信息。

参数： 无

例子：

await manager.executeTool("pokemon_mcp", "get_random_pokemon", {});

退货：

• 随机口袋妖怪名称和ID
• 类型

运行测试

运行所有测试：

npm test

运行特定测试文件：

npm test pokemon-mcp.test.js

测试覆盖率

测试套件包括：

• ✅ 按名字获取口袋妖怪
• ✅ 通过ID获取口袋妖怪
• ✅ 处理无效的口袋妖怪名称
• ✅ 获取口袋妖怪类型信息
• ✅ 处理无效类型
• ✅ 获取随机口袋妖怪
• ✅ 列出所有可用工具
• ✅ 验证工具可用性

运作原理

MCP架构

1. 服务器端（Python）:

   • pokemon-mcp.py 使用FastMCP创建MCP服务器
   • 使用定义工具 @mcp.tool() 装饰器
   • 每个工具函数都包含一个文档字符串（用作工具描述）
   • 服务器通过STDIO（标准输入/输出）进行通信

2. 客户端（Node.js）:

   • 测试使用 MCPClientManager 从 @mcpjam/sdk
   • Manager生成Python进程并通过MCP协议进行通信
   • getTools() 从服务器检索可用工具
   • executeTool() 使用参数调用特定工具

通信流

┌─────────────────┐         MCP Protocol          ┌─────────────────┐
│   Jest Tests    │◄─────────(STDIO)──────────────►│  FastMCP Server │
│   (Node.js)     │                                │    (Python)     │
└─────────────────┘                                └─────────────────┘
        │                                                   │
        │ 1. Start server                                  │
        │ 2. Request tools list                            │
        │ 3. Execute tool with params                      │
        │ 4. Receive results                               │
        │                                                   │
        └──────────────────────────────────────────────────┘

示例：工具执行流程

1. 测试电话 manager.executeTool("pokemon_mcp", "get_pokemon", { name: "pikachu" })
2. MCPClientManager通过STDIO向Python服务器发送MCP消息
3. FastMCP接收消息并路由到 get_pokemon() 函数
4. 函数调用PokeAPI： https://pokeapi.co/api/v2/pokemon/pikachu
5. 函数处理响应并返回格式化字符串
6. FastMCP通过MCP协议发回结果
7. 测试接收并验证结果

API 参考

该项目使用免费 PokeAPI 以获取口袋妖怪数据。不需要API密钥！

故障排除

测试挂起或不退出

由于测试客户端和MCP服务器之间的持久连接，这是预期的行为。Jest会对此发出警告，但测试仍然通过。

找不到Python模块

请确保您已安装所需的Python包：

pip install fastmcp requests

连接错误

确保测试中的Python服务器路径与您的实际文件位置匹配：

args: ["pokemon-mcp.py"]  // Relative to project root

贡献

欢迎添加更多与口袋妖怪相关的工具或改进现有的工具！

新工具的想法

• 获取Pokemon进化链
• 获取口袋妖怪动作
• 获取口袋妖怪统计数据比较
• 按世代获取口袋妖怪
• 按栖息地获取口袋妖怪

资源

• FastMCP文档
• 模型上下文协议
• PokeAPI文档
• @mcpjam/sdk