第十章：MCP 协议实现

🔌 本章详细介绍 MiniClaw 如何实现 MCP（Model Context Protocol）协议。

10.1 MCP 协议概述

10.1.1 什么是 MCP？

MCP（Model Context Protocol）是 Anthropic 开发的开放协议，用于连接 AI 模型与外部工具和数据源。

┌─────────────────────────────────────────────────────────────────────┐
│                    MCP 协议概述                                      │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│    ┌─────────────────────────────────────────────────────────────┐ │
│    │                    MCP 架构                                  │ │
│    │                                                             │ │
│    │    ┌─────────────┐         ┌─────────────┐                  │ │
│    │    │   MCP Host  │         │ MCP Server  │                  │ │
│    │    │ (Claude等)  │ ◄─────► │ (MiniClaw)  │                  │ │
│    │    └─────────────┘         └─────────────┘                  │ │
│    │           │                       │                          │ │
│    │           │                       │                          │ │
│    │           ▼                       ▼                          │ │
│    │    ┌─────────────┐         ┌─────────────┐                  │ │
│    │    │   AI 模型   │         │  工具/资源  │                  │ │
│    │    │ (Claude等)  │         │  (本地数据) │                  │ │
│    │    └─────────────┘         └─────────────┘                  │ │
│    │                                                             │ │
│    └─────────────────────────────────────────────────────────────┘ │
│                                                                     │
│  MCP 核心概念：                                                     │
│  • Resources  → 可读取的数据源                                      │
│  • Tools      → 可执行的函数                                        │
│  • Prompts    → 预定义的提示词模板                                  │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

10.1.2 MCP 通信方式

┌─────────────────────────────────────────────────────────────────────┐
│                    MCP 通信方式                                      │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Stdio 传输（MiniClaw 使用的方式）                                  │
│                                                                     │
│    MCP Host (Claude Code)                                           │
│           │                                                         │
│           │ stdin/stdout                                            │
│           │ (JSON-RPC 消息)                                         │
│           │                                                         │
│           ▼                                                         │
│    MCP Server (MiniClaw)                                            │
│           │                                                         │
│           │ 文件系统                                                │
│           ▼                                                         │
│    ~/.miniclaw/                                                     │
│                                                                     │
│  消息格式：JSON-RPC 2.0                                             │
│  {                                                                    │
│    "jsonrpc": "2.0",                                                │
│    "id": 1,                                                         │
│    "method": "tools/call",                                          │
│    "params": {                                                      │
│      "name": "miniclaw_note",                                       │
│      "arguments": { "content": "..." }                              │
│    }                                                                │
│  }                                                                  │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

10.2 服务器初始化

10.2.1 服务器配置

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

// 创建服务器实例
const server = new Server(
  {
    name: "miniclaw",
    version: "0.5.0",
  },
  {
    capabilities: {
      resources: {},    // 支持资源读取
      tools: {},        // 支持工具调用
      prompts: {},      // 支持提示词
    },
  }
);

// 创建传输层
const transport = new StdioServerTransport();

// 连接服务器
await server.connect(transport);

10.2.2 能力声明

┌─────────────────────────────────────────────────────────────────────┐
│                    能力声明                                          │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  capabilities: {                                                    │
│    resources: {},    // 声明支持资源功能                            │
│    tools: {},        // 声明支持工具功能                            │
│    prompts: {},      // 声明支持提示词功能                          │
│  }                                                                  │
│                                                                     │
│  能力说明：                                                         │
│                                                                     │
│  resources: {}                                                      │
│  ├── ListResourcesRequestSchema   → 列出可用资源                    │
│  └── ReadResourceRequestSchema    → 读取资源内容                    │
│                                                                     │
│  tools: {}                                                          │
│  ├── ListToolsRequestSchema       → 列出可用工具                    │
│  └── CallToolRequestSchema        → 调用工具                        │
│                                                                     │
│  prompts: {}                                                        │
│  ├── ListPromptsRequestSchema     → 列出可用提示词                  │
│  └── GetPromptRequestSchema       → 获取提示词内容                  │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

10.3 核心处理器

10.3.1 资源处理器

// 列出可用资源
server.setRequestHandler(ListResourcesRequestSchema, async () => {
  return {
    resources: [
      {
        uri: "miniclaw://context",
        name: "MiniClaw Context",
        description: "Agent personality core",
      },
      {
        uri: "miniclaw://skills",
        name: "Skills Index",
        description: "All loaded skills",
      },
    ],
  };
});

// 读取资源内容
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
  const { uri } = request.params;
  
  if (uri === "miniclaw://context") {
    const context = await kernel.boot({ minimal: false });
    return { contents: [{ uri, text: context }] };
  }
  
  // ... 其他资源处理
});

10.3.2 工具处理器

// 列出可用工具
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "miniclaw_note",
        description: "Append to today's memory log",
        inputSchema: {
          type: "object",
          properties: {
            content: { type: "string" },
          },
          required: ["content"],
        },
      },
      // ... 其他工具
    ],
  };
});

// 调用工具
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  
  switch (name) {
    case "miniclaw_note":
      return await handleNote(args);
    case "miniclaw_update":
      return await handleUpdate(args);
    // ... 其他工具处理
  }
});

本章小结

┌─────────────────────────────────────────────────────────────────────┐
│                     第十章 核心要点                                  │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  🔌 MCP 协议概念                                                    │
│     • Model Context Protocol                                        │
│     • Anthropic 开发                                                │
│     • 标准化工具接口                                                │
│                                                                     │
│  🏗️ 核心组件                                                        │
│     • Resources - 资源读取                                          │
│     • Tools - 工具调用                                              │
│     • Prompts - 提示词                                              │
│                                                                     │
│  📡 通信方式                                                        │
│     • Stdio 传输                                                    │
│     • JSON-RPC 2.0                                                  │
│     • 本地进程通信                                                  │
│                                                                     │
│  🛠️ 实现细节                                                        │
│     • Server 类                                                     │
│     • StdioServerTransport                                          │
│     • RequestHandler                                                │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

本文档是《MiniClaw 深度解析》系列的第十章，下一章将详细介绍配置与部署。