MCP 框架

MCP-Framework 是一个用于以优雅的方式在 TypeScript 中构建模型上下文协议（MCP）服务器的框架。

MCP-Framework 提供开箱即用的架构，支持基于目录的工具、资源和提示的自动发现。您可以使用我们强大的 MCP 抽象来以优雅的方式定义工具、资源或提示。我们的 CLI 使您轻松上手自己的 MCP 服务器。

特性

• 🛠️ 自动发现并加载工具、资源和提示
• 多种传输方式支持（stdio、SSE、HTTP 流）
• 以 TypeScript 为先的开发，具有完全的类型安全性
• 基于官方 MCP SDK 构建
• 易于使用的工具、提示和资源基类
• 为 SSE 端点提供开箱即用的身份验证（OAuth 2.1、JWT、API 密钥）

使用 MCP 框架构建的项目

以下项目和服务是使用 MCP 框架构建的：

• tip.md

  一个加密货币打赏服务，允许 AI 助手帮助用户直接从聊天界面向内容创作者发送加密货币打赏。该 MCP 服务支持：
  • 检查用户的钱包类型
  • 为用户/代理准备加密货币打赏以完成交易 各种客户端（Cursor、Sage、Claude Desktop）的设置说明可在其 MCP 服务器文档 中找到。

支持我们的工作

在此阅读完整文档

使用 MCP 框架创建仓库

使用 CLI（推荐）

# 全局安装框架
npm install -g mcp-framework

# 创建一个新的 MCP 服务器项目
mcp create my-mcp-server

# 进入您的项目
cd my-mcp-server

# 您的服务器已准备就绪！

CLI 使用方法

该框架提供了一个功能强大的 CLI 来管理您的 MCP 服务器项目：

项目创建

# 创建新项目
mcp create <您的项目名称>

# 使用新的实验性 HTTP 传输方式创建新项目
注意：这会将 CORS 允许的源设置为“*”，如果您需要，请在 index 文件中进行修改。
mcp create <您的项目名称> --http --port 1337 --cors

选项：

--http：使用 HTTP 传输方式代替默认的 stdio

--port <数字>：指定 HTTP 端口（默认：8080）

--cors：启用带有通配符 (*) 访问的 CORS

添加工具

# 添加新工具
mcp add tool price-fetcher

构建与验证

该框架提供了全面的验证，以确保您的工具被正确地记录并正常运行：

# 推荐使用自动验证进行构建
npm run build

# 使用自定义验证设置进行构建
MCP_SKIP_TOOL_VALIDATION=false npm run build  # 强制验证（默认）
MCP_SKIP_TOOL_VALIDATION=true npm run build   # 跳过验证（不推荐）

验证工具

# 验证所有工具是否具有适当的描述（针对 Zod 模式）
mcp validate

此命令会检查所有使用 Zod 模式的工具，确保每个字段都有描述。验证会在构建时自动运行，但您也可以单独运行它：

• ✅ 构建时：npm run build 会自动验证工具
• ✅ 单独运行：mcp validate 可用于手动验证
• ✅ 开发时：使用 defineSchema() 辅助函数可获得即时反馈
• ✅ 运行时：服务器会在启动时验证工具

验证错误示例：

❌ 工具验证失败：
  ❌ PriceFetcher.js：price_fetcher 中的 symbol 和 currency 字段缺少描述。
  使用 Zod 对象模式时，所有字段都必须有描述。
  请对每个字段使用 .describe() 方法，例如 z.string().describe("字段描述")。

将验证集成到 CI/CD 流程中：

{
  "scripts": {
    "build": "tsc && mcp-build",
    "test": "jest && mcp validate",
    "prepack": "npm run build && mcp validate"
  }
}

添加提示

# 添加新提示
mcp add prompt price-analysis

添加资源

# 添加新资源
mcp add resource market-data

开发工作流

1. 创建您的项目：

   mcp create my-mcp-server
   cd my-mcp-server
   

2. 添加工具：

   mcp add tool data-fetcher
   mcp add tool data-processor
   mcp add tool report-generator
   

3. 定义您的工具模式并进行自动验证：

   // tools/DataFetcher.ts
   import { MCPTool, MCPInput as AddToolInput } from "mcp-framework";
   import { z } from "zod";
   
   const AddToolSchema = z.object({
     a: z.number().describe("要相加的第一个数字"),
     b: z.number().describe("要相加的第二个数字"),
   });
   
   class AddTool extends MCPTool {
     name = "add";
     description = "加法工具描述";
     schema = AddToolSchema;
   
     async execute(input: AddToolInput<this>) {
       const result = input.a + input.b;
       return `结果：${result}`;
     }
   }
   
   export default AddTool;
   

4. 使用自动验证进行构建：

   npm run build  # 自动验证模式并编译
   

5. 可选：单独运行验证：

   mcp validate  # 独立检查所有工具
   

6. 测试您的服务器：

   node dist/index.js  # 服务器会在启动时验证工具
   

7. 添加到 MCP 客户端（参见下方 Claude Desktop 示例）

实用技巧：

• 在开发过程中使用 defineSchema() 以获得即时反馈
• 构建过程会自动捕获缺失的描述
• 服务器启动时会验证所有工具，然后才接受连接
• 使用 TypeScript 的自动补全功能配合 MCPInput<this> 以提升开发体验

与 Claude Desktop 配合使用

本地开发

将以下配置添加到您的 Claude Desktop 配置文件中：

MacOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "${projectName}": {
      "command": "node",
      "args":["/绝对路径/to/${projectName}/dist/index.js"]
    }
  }
}

发布后

将以下配置添加到您的 Claude Desktop 配置文件中：

MacOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "${projectName}": {
      "command": "npx",
      "args": ["${projectName}"]
    }
  }
}

构建与测试

1. 对您的工具进行更改
2. 运行 npm run build 进行编译
3. 服务器将在启动时自动加载您的工具

环境变量

该框架支持以下环境变量进行配置：

变量	描述	默认值
MCP_ENABLE_FILE_LOGGING	启用文件日志记录（true/false）	false
MCP_LOG_DIRECTORY	日志文件将存储的目录	logs
MCP_DEBUG_CONSOLE	在控制台显示调试级别消息（true/false）	false

示例用法：

# 启用文件日志记录
MCP_ENABLE_FILE_LOGGING=true node dist/index.js

# 指定自定义日志目录
MCP_ENABLE_FILE_LOGGING=true MCP_LOG_DIRECTORY=my-logs node dist/index.js

# 在控制台启用调试信息
MCP_DEBUG_CONSOLE=true node dist/index.js

快速入门

定义工具

MCP 框架使用 Zod 模式来定义工具输入，提供类型安全、验证和自动文档：

import { MCPTool, MCPInput } from "mcp-framework";
import { z } from "zod";

const AddToolSchema = z.object({
  a: z.number().describe("要相加的第一个数"),
  b: z.number().describe("要相加的第二个数"),
});

class AddTool extends MCPTool {
  name = "add";
  description = "加法工具描述";
  schema = AddToolSchema;

  async execute(input: MCPInput<this>) {
    const result = input.a + input.b;
    return `结果：${result}`;
  }
}

export default AddTool;

主要优势：

• ✅ 单一事实来源 - 在一处定义类型和验证规则
• ✅ 自动类型推断 - TypeScript 类型从您的模式中推断出来
• ✅ 丰富的验证功能 - 利用 Zod 强大的验证特性
• ✅ 强制性描述 - 框架会强制要求提供文档说明
• ✅ 更好的 IDE 支持 - 完整的自动补全和类型检查
• ✅ 更整洁的代码 - 无需重复定义类型

高级 Zod 模式特性

该框架支持所有 Zod 特性：

import { MCPTool, MCPInput } from "mcp-framework";
import { z } from "zod";

const AdvancedSchema = z.object({
  // 字符串约束和格式
  email: z.string().email().describe("用户电子邮件地址"),
  name: z.string().min(2).max(50).describe("用户姓名"),
  website: z.string().url().optional().describe("可选的网站 URL"),
  
  // 数字约束
  age: z.number().int().positive().max(120).describe("用户年龄"),
  rating: z.number().min(1).max(5).describe("1 到 5 的评分"),
  
  // 数组和对象
  tags: z.array(z.string()).describe("标签列表"),
  metadata: z.object({
    priority: z.enum(['low', 'medium', 'high']).describe("任务优先级"),
    dueDate: z.string().optional().describe("ISO 格式的截止日期")
  }).describe("附加元数据"),
  
  // 默认值
  status: z.string().default('pending').describe("当前状态"),
  
  // 联合类型和枚举
  category: z.union([
    z.literal('personal'),
    z.literal('work'),
    z.literal('other')
  ]).describe("类别类型")
});

class AdvancedTool extends MCPTool {
  name = "advanced_tool";
  description = "演示高级 Zod 特性的工具";
  schema = AdvancedSchema;

  async execute(input: MCPInput<this>) {
    // TypeScript 自动知道所有类型！
    const { email, name, website, age, rating, tags, metadata, status, category } = input;
    
    console.log(input.name.toUpperCase()); // ✅ TypeScript 知道这是有效的
    console.log(input.age.toFixed(2));     // ✅ 可以使用数字方法
    console.log(input.tags.length);       // ✅ 可以使用数组方法
    console.log(input.website?.includes("https")); // ✅ 处理可选字段
    
    return `处理了用户：${name}`;
  }
}

自动类型推断

MCPInput<this> 类型会自动从您的模式中推断出正确的输入类型，从而无需手动定义类型：

class MyTool extends MCPTool {
  schema = z.object({
    name: z.string().describe("用户名"),
    age: z.number().optional().describe("用户年龄"),
    tags: z.array(z.string()).describe("用户标签")
  });

  async execute(input: MCPInput<this>) {
    // TypeScript 自动知道：
    // input.name 是 string
    // input.age 是 number | undefined  
    // input.tags 是 string[]
    
    console.log(input.name.toUpperCase()); // ✅ TypeScript 知道这是有效的
    console.log(input.age?.toFixed(2));    // ✅ 正确处理可选字段
    console.log(input.tags.length);       // ✅ 可以使用数组方法
  }
}

再也不需要重复定义接口或泛型类型参数了！

模式验证与描述

所有模式字段都必须有描述。这确保了您的工具文档齐全，并在 MCP 客户端中提供更好的用户体验。

框架会在多个层面验证描述：

1. 构建时验证（推荐）

npm run build  # 在编译过程中自动验证

2. 开发时验证

使用 defineSchema 辅助函数以获得即时反馈：

import { defineSchema } from "mcp-framework";

// 如果缺少描述，此操作会立即抛出错误
const MySchema = defineSchema({
  name: z.string(),  // ❌ 错误：缺少描述
  age: z.number().describe("用户年龄")  // ✅ 好的
});

3. 独立验证

mcp validate  # 检查所有工具是否具有适当的描述

4. 运行时验证

服务器会在启动时自动验证工具。

若要跳过验证（不推荐）：

# 构建时跳过
MCP_SKIP_TOOL_VALIDATION=true npm run build

# 开发时跳过
NODE_ENV=production npm run dev

设置服务器

import { MCPServer } from "mcp-framework";

const server = new MCPServer();

// 或者（互斥！）使用 SSE 传输
const server = new MCPServer({
  transport: {
    type: "sse",
    options: {
      port: 8080            // 可选（默认：8080）
    }
  }
});

// 启动服务器
await server.start();

传输配置

stdio 传输（默认）

如果未提供传输配置，将默认使用 stdio 传输：

const server = new MCPServer();
// 或显式指定：
const server = new MCPServer({
  transport: { type: "stdio" }
});

SSE 传输

要使用服务器发送事件（SSE）传输：

const server = new MCPServer({
  transport: {
    type: "sse",
    options: {
      port: 8080,            // 可选（默认：8080）
      endpoint: "/sse",      // 可选（默认："/sse"）
      messageEndpoint: "/messages", // 可选（默认："/messages"）
      cors: {
        allowOrigin: "*",    // 可选（默认："*"）
        allowMethods: "GET, POST, OPTIONS", // 可选（默认："GET, POST, OPTIONS"）
        allowHeaders: "Content-Type, Authorization, x-api-key", // 可选（默认："Content-Type, Authorization, x-api-key"）
        exposeHeaders: "Content-Type, Authorization, x-api-key", // 可选（默认："Content-Type, Authorization, x-api-key"）
        maxAge: "86400"      // 可选（默认："86400"）
      }
    }
  }
});

HTTP 流传输

要使用 HTTP 流传输：

const server = new MCPServer({
  transport: {
    type: "http-stream",
    options: {
      port: 8080,                // 可选（默认：8080）
      endpoint: "/mcp",          // 可选（默认："/mcp"） 
      responseMode: "batch",     // 可选（默认："batch"），可为 "batch" 或 "stream"
      batchTimeout: 30000,       // 可选（默认：30000毫秒）——批量响应的超时时间
      maxMessageSize: "4mb",     // 可选（默认："4mb"）——消息的最大大小
      
      // 会话配置
      session: {
        enabled: true,           // 可选（默认：true）
        headerName: "Mcp-Session-Id", // 可选（默认："Mcp-Session-Id"）
        allowClientTermination: true, // 可选（默认：true）
      },
      
      // 流的可恢复性（用于处理丢失的消息）
      resumability: {
        enabled: false,          // 可选（默认：false）
        historyDuration: 300000, // 可选（默认：300000毫秒 = 5分钟）——保留消息历史的时间长度
      },
      
      // CORS 配置
      cors: {
        allowOrigin: "*"         // 其他 CORS 选项使用默认值
      }
    }
  }
});

响应模式

HTTP 流传输支持两种响应模式：

1. 批量模式（默认）：响应会被收集并作为单个 JSON-RPC 响应发送。这适用于典型的请求-响应模式，在大多数情况下效率更高。

2. 流模式：所有响应都会通过为每个请求打开的持久化 SSE 连接发送。这非常适合长时间运行的操作，或者当服务器需要对单个请求发送多条消息时。

您可以根据具体需求配置响应模式：

// 对于批量模式（默认）：
const server = new MCPServer({
  transport: {
    type: "http-stream",
    options: {
      responseMode: "batch"
    }
  }
});

// 对于流模式：
const server = new MCPServer({
  transport: {
    type: "http-stream",
    options: {
      responseMode: "stream"
    }
  }
});

HTTP 流传输特性

• 会话管理：自动会话跟踪与管理
• 流的可恢复性：可选支持在连接中断后恢复流
• 批量处理：支持 JSON-RPC 批量请求/响应
• 全面的错误处理：提供包含 JSON-RPC 错误码的详细错误响应

身份验证

MCP 框架为 SSE 端点提供了可选的身份验证功能。您可以选择 JWT、API 密钥、OAuth 2.1 身份验证，或实现您自己的自定义身份验证提供程序。

JWT 身份验证

import { MCPServer, JWTAuthProvider } from "mcp-framework";
import { Algorithm } from "jsonwebtoken";

const server = new MCPServer({
  transport: {
    type: "sse",
    options: {
      auth: {
        provider: new JWTAuthProvider({
          secret: process.env.JWT_SECRET,
          algorithms: ["HS256" as Algorithm], // 可选（默认：["HS256"]）
          headerName: "Authorization"         // 可选（默认："Authorization"）
        }),
        endpoints: {
          sse: true,      // 保护 SSE 端点（默认：false）
          messages: true  // 保护消息端点（默认：true）
        }
      }
    }
  }
});

客户端必须在 Authorization 头中包含有效的 JWT 令牌：

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

API 密钥身份验证

import { MCPServer, APIKeyAuthProvider } from "mcp-framework";

const server = new MCPServer({
  transport: {
    type: "sse",
    options: {
      auth: {
        provider: new APIKeyAuthProvider({
          keys: [process.env.API_KEY],
          headerName: "X-API-Key" // 可选（默认："X-API-Key"）
        })
      }
    }
  }
});

客户端必须在 X-API-Key 头中包含有效的 API 密钥：

X-API-Key: your-api-key

OAuth 2.1 身份验证

MCP 框架支持符合 MCP 规范（2025-06-18）的 OAuth 2.1 身份验证，包括受保护资源元数据（RFC 9728）以及使用 JWKS 的正确令牌验证。

OAuth 身份验证同时适用于 SSE 和 HTTP 流传输，并支持两种验证策略：

JWT 验证（推荐用于性能优化）

JWT 验证会从您的授权服务器的 JWKS 端点获取公钥，并在本地验证令牌。由于无需为每个请求都与认证服务器进行往返通信，因此这是最快的选项。

import { MCPServer, OAuthAuthProvider } from "mcp-framework";

const server = new MCPServer({
  transport: {
    type: "http-stream",
    options: {
      port: 8080,
      auth: {
        provider: new OAuthAuthProvider({
          authorizationServers: [
            process.env.OAUTH_AUTHORIZATION_SERVER
          ],
          resource: process.env.OAUTH_RESOURCE,
          validation: {
            type: 'jwt',
            jwksUri: process.env.OAUTH_JWKS_URI,
            audience: process.env.OAUTH_AUDIENCE,
            issuer: process.env.OAUTH_ISSUER,
            algorithms: ['RS256', 'ES256'] // 可选（默认：['RS256', 'ES256']）
          }
        }),
        endpoints: {
          initialize: true,  // 保护会话初始化
          messages: true     // 保护 MCP 消息
        }
      }
    }
  }
});

环境变量：

OAUTH_AUTHORIZATION_SERVER=https://auth.example.com
OAUTH_RESOURCE=https://mcp.example.com
OAUTH_JWKS_URI=https://auth.example.com/.well-known/jwks.json
OAUTH_AUDIENCE=https://mcp.example.com
OAUTH_ISSUER=https://auth.example.com

令牌内省（推荐用于集中控制）

令牌内省通过调用您的授权服务器的内省端点来验证令牌。这提供了集中控制，并在需要实时令牌撤销时非常有用。

import { MCPServer, OAuthAuthProvider } from "mcp-framework";

const server = new MCPServer({
  transport: {
    type: "sse",
    options: {
      auth: {
        provider: new OAuthAuthProvider({
          authorizationServers: [
            process.env.OAUTH_AUTHORIZATION_SERVER
          ],
          resource: process.env.OAUTH_RESOURCE,
          validation: {
            type: 'introspection',
            audience: process.env.OAUTH_AUDIENCE,
            issuer: process.env.OAUTH_ISSUER,
            introspection: {
              endpoint: process.env.OAUTH_INTROSPECTION_ENDPOINT,
              clientId: process.env.OAUTH_CLIENT_ID,
              clientSecret: process.env.OAUTH_CLIENT_SECRET
            }
          }
        })
      }
    }
  }
});

环境变量：

OAUTH_AUTHORIZATION_SERVER=https://auth.example.com
OAUTH_RESOURCE=https://mcp.example.com
OAUTH_AUDIENCE=https://mcp.example.com
OAUTH_ISSUER=https://auth.example.com
OAUTH_INTROSPECTION_ENDPOINT=https://auth.example.com/oauth/introspect
OAUTH_CLIENT_ID=mcp-server
OAUTH_CLIENT_SECRET=your-client-secret

OAuth 功能

• RFC 9728 兼容性：自动提供受保护资源元数据端点 /.well-known/oauth-protected-resource
• RFC 6750 WWW-Authenticate 头部：带有质询头部的正确 OAuth 错误响应
• JWKS 密钥缓存：公钥缓存时间为 15 分钟（可配置）
• 令牌内省缓存：内省结果缓存时间为 5 分钟（可配置）
• 安全性：查询字符串中的令牌将被自动拒绝
• 声明提取：您可以在工具处理程序中通过 AuthResult 访问访问令牌声明。

常见 OAuth 提供商

OAuth 提供商可与任何符合 RFC 标准的 OAuth 2.1 授权服务器配合使用：

• Auth0：使用您的 Auth0 租户的 JWKS URI 和颁发者
• Okta：使用您的 Okta 授权服务器配置
• AWS Cognito：使用您的 Cognito 用户池的 JWKS 端点
• Azure AD / Entra ID：使用 Microsoft Entra ID 端点
• 自定义：任何符合 OAuth 2.1 标准的授权服务器

有关特定提供商的详细设置指南，请参阅 OAuth 设置指南。

客户端使用

客户端必须在 Authorization 头部中包含有效的 OAuth 访问令牌：

# 使用 OAuth 令牌发起请求
curl -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

# 发现 OAuth 配置
curl http://localhost:8080/.well-known/oauth-protected-resource

安全最佳实践

• 生产环境中始终使用 HTTPS：OAuth 令牌绝不应通过未加密的连接传输
• 验证受众声明：防止令牌在不同服务之间重复使用
• 使用短期令牌：降低令牌泄露后的风险
• 启用令牌内省缓存：在保持安全性的前提下减少授权服务器的负载
• 监控令牌错误：跟踪身份验证失败尝试以获取安全洞察。

自定义身份验证

您可以通过实现 AuthProvider 接口来实现自己的身份验证提供程序：

import { AuthProvider, AuthResult } from "mcp-framework";
import { IncomingMessage } from "node:http";

class CustomAuthProvider implements AuthProvider {
  async authenticate(req: IncomingMessage): Promise<boolean | AuthResult> {
    // 实现您的自定义身份验证逻辑
    return true;
  }

  getAuthError() {
    return {
      status: 401,
      message: "身份验证失败"
    };
  }
}

文档 MCP 服务器（@mcpframework/docs）

您可以从任何 Fumadocs 站点或任何包含 llms.txt 的站点启动一个 MCP 文档服务器——AI 代理将获得搜索、浏览和检索您文档的工具。

快速入门（CLI）

# 构建一个新的文档 MCP 服务器项目
npx create-docs-mcp my-api-docs
cd my-api-docs

# 配置您的文档站点 URL
cp .env.example .env
# 编辑 .env → 设置 DOCS_BASE_URL=https://docs.myapi.com

# 构建并运行
npm run build
npm start

快速入门（程序化）

import { DocsServer, FumadocsRemoteSource } from "@mcpframework/docs";

const source = new FumadocsRemoteSource({
  baseUrl: "https://docs.myapi.com",
});

const server = new DocsServer({
  source,
  name: "my-api-docs",
  version: "1.0.0",
});

server.start();

源适配器

适配器	最适合	搜索
FumadocsRemoteSource	Fumadocs 站点	原生 Orama 搜索，备用方案
LlmsTxtSource	包含 llms.txt 的任何站点	本地文本匹配
自定义 DocSource	任何文档后端	您的实现

内置 MCP 工具

工具	描述
search_docs	按关键词或短语搜索文档
get_page	获取页面的完整 Markdown 内容
list_sections	浏览文档的树状结构

添加到您的 MCP 客户端

# Claude 代码
claude mcp add my-api-docs -- node /path/to/my-api-docs/dist/index.js

# 或者使用环境变量
claude mcp add my-api-docs -e DOCS_BASE_URL=https://docs.myapi.com -- node /path/to/my-api-docs/dist/index.js

有关 Claude Desktop / Cursor 的配置和完整文档，请参阅 @mcpframework/docs README。

许可证

MIT

MCP Framework 快速上手指南

MCP Framework 是一个基于 TypeScript 的框架，旨在帮助开发者优雅地构建模型上下文协议（MCP）服务器。它提供了开箱即用的架构、自动目录发现机制以及强大的类型安全支持。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• Node.js: 建议安装 LTS 版本（v18 或更高）。
• npm: 随 Node.js 一同安装。
• 代码编辑器: 推荐使用 VS Code 以获得最佳的 TypeScript 智能提示体验。
• 前置知识: 熟悉 TypeScript 基础及 Zod 库（用于模式验证）将有助于更快上手。

国内加速建议： 如果 npm 安装速度较慢，建议配置国内镜像源（如淘宝镜像）：

npm config set registry https://registry.npmmirror.com

安装步骤

推荐使用官方 CLI 工具快速创建项目，它将自动处理目录结构和依赖初始化。

1. 全局安装框架

   npm install -g mcp-framework
   

2. 创建新项目 运行以下命令创建一个新的 MCP 服务器项目（将 my-mcp-server 替换为您的项目名称）：

   mcp create my-mcp-server
   

3. 进入项目目录并安装依赖

   cd my-mcp-server
   npm install
   

基本使用

以下是创建一个简单工具（Tool）并运行服务器的完整流程。

1. 添加一个新工具

使用 CLI 自动生成工具模板：

mcp add tool add-numbers

这将在 src/tools (或 tools) 目录下创建 AddNumbers.ts 文件。

2. 定义工具逻辑

编辑生成的文件，使用 Zod 定义输入模式并实现执行逻辑。MCP Framework 强制要求所有字段必须包含 .describe() 描述，以确保文档完整性。

// tools/AddNumbers.ts
import { MCPTool, MCPInput } from "mcp-framework";
import { z } from "zod";

// 定义输入模式，每个字段都必须有描述
const AddNumbersSchema = z.object({
  a: z.number().describe("第一个相加的数字"),
  b: z.number().describe("第二个相加的数字"),
});

class AddNumbers extends MCPTool {
  name = "add_numbers";
  description = "将两个数字相加并返回结果";
  schema = AddNumbersSchema;

  async execute(input: MCPInput<this>) {
    const result = input.a + input.b;
    return `计算结果：${result}`;
  }
}

export default AddNumbers;

3. 构建与验证

运行构建命令。框架会自动编译 TypeScript 代码，并自动验证所有工具的 Schema 是否包含必要的字段描述。如果缺少描述，构建将失败并提示错误。

npm run build

4. 运行服务器

构建成功后，启动服务器：

node dist/index.js

服务器启动时会自动扫描并加载 tools 目录下的所有工具。此时，您的 MCP 服务器已准备就绪，可以通过 stdio、SSE 或 HTTP Stream 与客户端（如 Claude Desktop、Cursor 等）进行通信。

5. 集成到客户端（以 Claude Desktop 为例）

若要本地测试，需修改 Claude Desktop 的配置文件。

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

添加如下配置（注意替换绝对路径）：

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/my-mcp-server/dist/index.js"]
    }
  }
}

重启 Claude Desktop 后，即可在对话框中调用您创建的 add_numbers 工具。