MCP 框架

一个用于构建模型上下文协议 (MCP) 服务器的 TypeScript 框架。

与原始版本的更改

此 fork (@ronangrant/mcp-framework) 包含以下改进：

• 将基于文件的日志记录替换为仅控制台日志记录，以获得更好的兼容性和可靠性
• 删除了对日志文件系统的依赖，消除了 ENOENT 错误
• 简化了日志记录实现，同时保持相同的接口
• 所有日志现在都通过 console.error() 输出到 stderr

安装

npm install @ronangrant/mcp-framework

用法

创建一个新的 MCP 服务器：

import { MCPServer } from '@ronangrant/mcp-framework';

const server = new MCPServer({
  name: "my-server",
  version: "1.0.0"
});

await server.start();

特性

• 易于使用的 API，用于创建 MCP 服务器
• 内置支持工具、提示和资源
• 简化的日志记录系统，带有控制台输出
• 完整的 TypeScript 支持
• 灵活的传输选项

许可证

MIT

MCP-Framework 是一个用于使用 TypeScript 优雅地构建模型上下文协议 (MCP) 服务器的框架。

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

特性

• 🛠️ 自动发现和加载工具、资源和提示
• 多种传输支持（stdio、SSE）
• TypeScript 优先开发，具有完整的类型安全
• 构建在官方 MCP SDK 之上
• 易于使用的工具、提示和资源基类
• SSE 端点的开箱即用身份验证

在此处阅读完整文档

使用 mcp-framework 创建存储库

使用 CLI（推荐）

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

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

# 导航到您的项目
cd my-mcp-server

# 您的服务器已准备好使用！

CLI 用法

该框架提供了一个强大的 CLI，用于管理您的 MCP 服务器项目：

项目创建

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

添加工具

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

添加提示

# 添加一个新提示
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. 构建：

   npm run build
   
   

4. 添加到 MCP 客户端（请阅读下面的 Claude Desktop 示例）

与 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":["/absolute/path/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. 服务器将在启动时自动加载您的工具

快速开始

创建一个工具

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

interface ExampleInput {
  message: string;
}

class ExampleTool extends MCPTool<ExampleInput> {
  name = "example_tool";
  description = "An example tool that processes messages";

  schema = {
    message: {
      type: z.string(),
      description: "Message to process",
    },
  };

  async execute(input: ExampleInput) {
    return `Processed: ${input.message}`;
  }
}

export default ExampleTool;

设置服务器

import { MCPServer } from "mcp-framework";

const server = new MCPServer();

// OR (互斥！) 使用 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"）
      }
    }
  }
});

CORS 配置

SSE 传输支持灵活的 CORS 配置。 默认情况下，它使用适合开发的宽松设置。 对于生产环境，您应该根据您的安全要求配置 CORS：

const server = new MCPServer({
  transport: {
    type: "sse",
    options: {
      // 限制为特定来源
      cors: {
        allowOrigin: "https://myapp.com",
        allowMethods: "GET, POST",
        allowHeaders: "Content-Type, Authorization",
        exposeHeaders: "Content-Type, Authorization",
        maxAge: "3600"
      }
    }
  }
});

// 或具有多个允许的来源
const server = new MCPServer({
  transport: {
    type: "sse",
    options: {
      cors: {
        allowOrigin: "https://app1.com, https://app2.com",
        allowMethods: "GET, POST, OPTIONS",
        allowHeaders: "Content-Type, Authorization, Custom-Header",
        exposeHeaders: "Content-Type, Authorization",
        maxAge: "86400"
      }
    }
  }
});

身份验证

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

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

自定义身份验证

您可以通过实现 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: "Authentication failed"
    };
  }
}

许可证

MIT