pokemcp

🚀 宝可梦MCP服务器

宝可梦MCP服务器是一个基于模型上下文协议（MCP）的服务，通过标准化工具提供宝可梦数据。此单仓库项目包含MCP服务器和数据摄取服务，后者用于从PokeAPI获取宝可梦数据。

🚀 快速开始

前提条件

• Node.js 18+
• PNPM
• Git

安装

1. 克隆仓库：

git clone https://github.com/grovesjosephn/pokemcp.git
cd pokemcp

2. 安装依赖：

pnpm install

3. 配置数据库：

./scripts/setup.sh

4. 构建所有包：

pnpm build

使用方法

运行MCP服务器

# 开发模式（热更新）
pnpm dev

# 生产模式
cd packages/pokemon-mcp-server
pnpm start

使用MCP检查器进行测试

# 可视化GUI测试
cd packages/pokemon-mcp-server
pnpm inspect

# CLI测试
pnpm inspect:cli

数据摄取

# 运行数据摄取
cd packages/pokemon-mcp-ingestion
pnpm start

✨ 主要特性

可用的MCP工具

• get_pokemon - 获取特定宝可梦的详细信息
• search_pokemon - 按名称、类型或其他条件搜索宝可梦
• get_strongest_pokemon - 根据各种统计数据找到最强的宝可梦
• get_pokemon_stats - 获取宝可梦的详细统计数据
• compare_pokemon - 比较两只宝可梦的统计数据
• get_type_effectiveness - 获取属性相克信息

数据覆盖范围

• 来自PokeAPI的完整宝可梦数据
• 统计数据、属性、特性等
• 属性相克关系
• 可按多个条件搜索

📦 安装指南

环境依赖

• Node.js 18 及以上版本
• PNPM
• Git

安装步骤

1. 克隆项目仓库：

git clone https://github.com/grovesjosephn/pokemcp.git
cd pokemcp

2. 安装项目依赖：

pnpm install

3. 初始化数据库：

./scripts/setup.sh

4. 构建所有包：

pnpm build

💻 使用示例

基础用法

启动MCP服务器

# 开发模式（支持热重载）
pnpm dev

# 生产模式
cd packages/pokemon-mcp-server
pnpm start

高级用法

数据摄取

# 运行数据摄取服务
cd packages/pokemon-mcp-ingestion
pnpm start

📚 详细文档

Claude桌面集成

选项1：NPM包（推荐）

全局安装服务器：

cd packages/pokemon-mcp-server
pnpm build
npm link

配置Claude桌面：

{
  "mcpServers": {
    "pokemon": {
      "command": "pokemon-mcp-server",
      "env": {
        "POKEMON_DATA_DIR": "/path/to/pokemcp/data"
      }
    }
  }
}

选项2：直接执行Node命令

{
  "mcpServers": {
    "pokemon": {
      "command": "node",
      "args": ["/path/to/pokemcp/packages/pokemon-mcp-server/dist/server.js"],
      "env": {
        "POKEMON_DATA_DIR": "/path/to/pokemcp/data"
      }
    }
  }
}

选项3：开发模式

{
  "mcpServers": {
    "pokemon": {
      "command": "pnpm",
      "args": ["--filter", "pokemon-mcp-server", "start"],
      "cwd": "/path/to/pokemcp",
      "env": {
        "POKEMON_DATA_DIR": "/path/to/pokemcp/data"
      }
    }
  }
}

开发相关命令

工作区命令

pnpm build         # 构建所有包
pnpm dev           # 在开发模式下运行所有包
pnpm test          # 运行所有包的测试
pnpm lint          # 对所有包进行代码检查
pnpm format        # 格式化所有文件
pnpm format:check  # 检查代码格式

服务器包命令

cd packages/pokemon-mcp-server

pnpm build         # 编译TypeScript代码
pnpm dev           # 使用tsx进行监听模式
pnpm start         # 运行服务器
pnpm inspect       # 运行MCP检查器GUI
pnpm inspect:cli   # 运行MCP检查器CLI
pnpm test          # 运行测试

摄取包命令

cd packages/pokemon-mcp-ingestion

pnpm build         # 编译TypeScript代码
pnpm dev           # 监听模式
pnpm start         # 运行数据摄取
pnpm test          # 运行测试

测试

项目使用Vitest进行测试：

# 运行所有测试
pnpm test

# 运行特定包的测试
pnpm --filter pokemon-mcp-server test
pnpm --filter pokemon-mcp-ingestion test

🔧 技术细节

架构

这是一个PNPM单仓库项目，包含两个主要包：

• pokemon-mcp-server：通过标准化工具公开宝可梦数据的MCP服务器
• pokemon-mcp-ingestion：从PokeAPI获取数据并存储在SQLite中的数据摄取服务

系统使用共享的SQLite数据库（data/pokemon.sqlite）来存储宝可梦数据。

数据库架构

SQLite数据库包含以下表：

• pokemon - 宝可梦基本信息
• stats - 宝可梦统计数据（HP、攻击、防御等）
• types - 宝可梦属性及关系
• abilities - 宝可梦特性
• type_effectiveness - 属性相克关系

🤝 贡献指南

贡献步骤

1. Fork项目仓库。
2. 创建功能分支。
3. 进行代码修改。
4. 添加测试用例。
5. 运行 pnpm format 和 pnpm lint 进行代码格式化和检查。
6. 提交Pull Request。

提交规范

使用常规提交格式：

<类型>[可选范围]: <描述>

示例:
- feat(server): 添加宝可梦进化链工具
- fix(ingestion): 优雅处理缺失的物种URL
- docs: 更新集成指南

📄 许可证

本项目采用MIT许可证，详细信息请参阅 LICENSE 文件。

🔗 相关链接

• 模型上下文协议
• PokeAPI
• Claude桌面版