Pokedex MCP Monorepo

Pokédex MCP Monorepo

通过构建具有单独服务器和客户端实现的交互式Pokédex系统来学习模型上下文协议（MCP）的演示项目。

什么是MCP？

模型上下文协议（MCP）是一种开放协议，可实现人工智能应用程序和外部数据源或工具之间的无缝集成。它为AI模型提供了一种标准化的方法：

• 访问外部资源（文件、API、数据库）
• 执行工具和功能
• AI模型样本
• 处理客户端和服务器之间的结构化通信

项目概述

此monorepo通过Pokédex应用程序演示了MCP概念，其中：

• 这 MCP服务器 管理宝可梦数据并提供交互工具
• 这 MCP客户端 提供了一个连接到服务器的交互式CLI
• 通过stdio传输上的MCP协议进行通信

建筑

系统架构

graph TB
    subgraph "User Space"
        User[User]
    end
    
    subgraph "Client Package"
        CLI[Interactive CLI
Inquirer.js]
        Client[MCP Client
StdioClientTransport]
        OpenAI[OpenAI Integration
for AI Sampling]
    end
    
    subgraph "Server Package"
        Server[MCP Server
StdioServerTransport]
        Tools[Tools
- catch-pokemon
- discover-wild-pokemon
- list-pokedex
- inspect-server]
        Resources[Resources
- pokemon-list
- pokemon-entry]
        Data[(pokedex.json)]
    end
    
    User --> CLI
    CLI --> Client
    Client  Server
    Server --> Tools
    Server --> Resources
    Tools --> Data
    Resources --> Data
    Client --> OpenAI

MCP通信流程

sequenceDiagram
    participant User
    participant Client
    participant Server
    participant AI as OpenAI

    User->>Client: Start CLI
    Client->>Server: Spawn server process
    Server->>Client: Initialize connection
    
    Client->>Server: List available tools
    Server->>Client: Return tool definitions
    
    User->>Client: Select "Discover Pokémon"
    Client->>Server: Call discover-wild-pokemon tool
    
    Server->>Client: Request AI sampling
    Client->>AI: Generate Pokémon description
    AI->>Client: Return generated content
    Client->>Server: Provide AI response
    
    Server->>Server: Process & save Pokémon
    Server->>Client: Return result
    Client->>User: Display new Pokémon

MCP概念演示

1. 工具 （服务器→ 客户行动）

工具是服务器公开给客户端调用的函数：

// Server defines tools
{
  name: "catch-pokemon",
  description: "Add a new Pokémon to your Pokédex",
  inputSchema: {
    type: "object",
    properties: {
      name: { type: "string" },
      type: { type: "string" },
      description: { type: "string" }
    }
  }
}

2. 资源 （服务器数据暴露）

资源允许客户端访问服务器数据：

// Server exposes resources
{
  uri: "pokedex://pokemon-list",
  name: "Pokémon List",
  mimeType: "application/json"
}

3. 采样 （服务器→ 客户端AI请求）

服务器可以向客户端请求AI协助：

// Server requests AI sampling
const result = await request.sampling.createMessage({
  messages: [{
    role: "user",
    content: "Generate a unique Pokémon..."
  }],
  modelPreferences: { hints: ["gpt-4o-mini"] }
});

4. 运输 （客户↔ 服务器通信）

两者都使用stdio传输进行进程通信：

// Client spawns server
const serverProcess = spawn('pnpm', ['--filter', '@pokedex/server', 'start']);

// Both wrap stdio in MCP transport
const transport = new StdioClientTransport({
  command: 'pnpm',
  args: ['--filter', '@pokedex/server', 'start']
});

项目结构

pokedex-mcp-monorepo/
├── packages/
│   ├── client/          # MCP Client implementation
│   │   ├── src/
│   │   │   ├── index.ts      # CLI entry point
│   │   │   └── logger.ts     # Logging utilities
│   │   └── package.json
│   │
│   └── server/          # MCP Server implementation
│       ├── src/
│       │   ├── index.ts      # Server entry point
│       │   ├── tools.ts      # Tool implementations
│       │   ├── logger.ts     # Server logging
│       │   └── data/
│       │       └── pokedex.json  # Data persistence
│       └── package.json
│
├── package.json         # Monorepo root
├── pnpm-workspace.yaml  # PNPM workspace config
└── CLAUDE.md           # AI assistant instructions

主要特点

服务器功能

• 工具实施：公开4个宝可梦管理工具
• 资源服务：提供对Pokédex数据的访问
• 人工智能集成：向客户的人工智能请求创意内容
• 数据持久层：将捕获的口袋妖怪保存为JSON文件
• 结构化日志记录：具有严重性级别的全面日志记录

客户端功能

• 交互式CLI：Inquirer.js的用户友好提示
• 自动连接：自动生成并连接到服务器
• AI提供商：通过OpenAI处理服务器的AI采样请求
• 实时日志记录：使用颜色编码切换日志显示
• 错误处理：妥善处理连接问题

入门指南

先决条件

• Node.js 18+
• PNPM包管理器
• OpenAI API密钥

安装

1. 克隆存储库：

git clone 
cd pokedex-mcp-monorepo

1. 安装依赖项：

pnpm install

1. 设置环境变量：

# In packages/client/
cp .env.example .env
# Add your OpenAI API key to .env

运行应用程序

# Build the server and run the client
pnpm dev:client

# Or run each separately:
pnpm build:server  # Build server first
pnpm --filter @pokedex/client dev  # Run client

开发工具

# Test server with MCP Inspector
pnpm inspect

# Lint all packages
pnpm lint

# Format code
pnpm format

学习MCP

本项目展示了MCP的核心概念：

1. 服务器实现：了解如何创建公开工具和资源的MCP服务器
2. 客户端实施：学习构建连接到MCP服务器的客户端
3. 双向通信：了解服务器如何向客户端请求人工智能协助
4. 传输层：有关本地进程通信，请参阅stdio传输操作
5. 协议消息：观察基于JSON-RPC的消息交换

MCP协议流

stateDiagram-v2
    [*] --> Initialization
    
    Initialization --> Connected: Handshake
    
    Connected --> ToolExecution: Client calls tool
    Connected --> ResourceAccess: Client reads resource
    Connected --> Sampling: Server needs AI
    
    ToolExecution --> Connected: Return result
    ResourceAccess --> Connected: Return data
    
    Sampling --> ClientProcessing: Client handles request
    ClientProcessing --> Connected: Return AI response
    
    Connected --> [*]: Disconnect

贡献

这是一个学习项目。请随意：

• 添加新的口袋妖怪相关工具
• 实施额外的MCP功能
• 改进错误处理
• 增强CLI体验
• 添加测试

资源

• MCP文件
• MCP-SDK
• OpenAI API

许可证

麻省理工学院