MCP Weave

MCP-Weave

Weave your code into MCP servers - seamlessly

Like Swagger for Model Context Protocol

Features • Quick Start • Packages • Documentation • Examples • Contributing

______________________________________________________________________

✨ 特性

• 🎯 简单的装饰品 -使用直观的注释将任何类转换为MCP服务器
• 🔄 双向流动 -代码优先或规范优先的开发方法
• 📝 YAML规范 -以可读的方式定义您的MCP服务器 mcp-spec.yaml 文件
• 🚀 多个框架 -NestJS和Express支持
• 🔌 多个传输 -stdio、SSE和WebSocket
• � 认证 -API对请求跟踪和作用域的关键支持
• �🛠️ 强大的CLI -通过热重新加载生成、提取和管理您的MCP服务器
• 🧪 测试工具 -模拟服务器和断言，便于测试
• 🎨 Web UI仪表板 -工具、资源和提示的交互式测试
• 📦 TypeScript优先 -全型安全和卓越的DX

🚀 快速开始

安装

# Using pnpm (recommended)
pnpm add @mcp-weave/nestjs

# Using npm
npm install @mcp-weave/nestjs

# Using yarn
yarn add @mcp-weave/nestjs

基本用法

使用简单的装饰器将现有代码转换为MCP服务器：

import {
  McpServer,
  McpTool,
  McpResource,
  McpPrompt,
  McpInput,
  McpParam,
  McpPromptArg,
} from '@mcp-weave/nestjs';

@McpServer({
  name: 'user-service',
  version: '1.0.0',
  description: 'User management service',
})
export class UserController {
  @McpTool({
    name: 'create_user',
    description: 'Creates a new user in the system',
  })
  async createUser(@McpInput() input: CreateUserDto) {
    const user = await this.userService.create(input);
    return { success: true, userId: user.id };
  }

  @McpResource({
    uri: 'user://{userId}',
    name: 'User Profile',
    mimeType: 'application/json',
  })
  async getUserProfile(@McpParam('userId') userId: string) {
    const user = await this.userService.findById(userId);
    return {
      contents: [
        {
          uri: `user://${userId}`,
          mimeType: 'application/json',
          text: JSON.stringify(user),
        },
      ],
    };
  }

  @McpPrompt({
    name: 'welcome_email',
    description: 'Generate welcome email for new user',
  })
  async generateWelcomeEmail(
    @McpPromptArg('userName') userName: string,
    @McpPromptArg('userEmail') userEmail: string
  ) {
    return {
      messages: [
        {
          role: 'user',
          content: `Generate a welcome email for ${userName} (${userEmail})`,
        },
      ],
    };
  }
}

📦 包裹

🔄 两种开发流程

代码优先

从装饰代码开始，提取规范：

Annotated Code → Scanner → Metadata → Generator → MCP Server

# Extract spec from your code
mcp-weave extract --source ./src --output mcp-spec.yaml

规格优先

从YAML规范开始，生成样板：

mcp-spec.yaml → Parser → Validator → Generator → Boilerplate Code

# Generate server from spec
mcp-weave generate --spec mcp-spec.yaml --output ./server

📝 规范格式

在中定义您的MCP服务器 mcp-spec.yaml:

version: '1.0'

server:
  name: 'user-management'
  version: '1.0.0'
  description: 'User management service'

tools:
  - name: create_user
    description: 'Creates a new user'
    inputSchema:
      type: object
      properties:
        name: { type: string }
        email: { type: string, format: email }
      required: [name, email]
    handler: '/handlers/user/create'

resources:
  - uri: 'user://{userId}'
    name: 'User Profile'
    mimeType: 'application/json'
    handler: '/handlers/user/get'

prompts:
  - name: 'welcome_email'
    description: 'Generate welcome email'
    arguments:
      - name: userName
        required: true
    handler: '/handlers/prompts/welcome'

transport:
  - type: stdio
  - type: sse
    endpoint: '/mcp/sse'

🛠️ CLI命令

# Initialize a new project
mcp-weave init --name my-service --framework nestjs

# Generate server from spec
mcp-weave generate --spec mcp-spec.yaml --output ./server

# Extract spec from annotated code
mcp-weave extract --source ./src --output mcp-spec.yaml

# Start MCP server
mcp-weave start --transport stdio

# Start with SSE transport
mcp-weave start --transport sse --port 3000

# Start with hot reload
mcp-weave start --watch

# Export spec in different formats
mcp-weave export --format yaml --output spec.yaml

🎨 装饰师API

类装饰器

方法装饰

参数装饰器

📚 文档

• 入门指南
• api参考
• 规范格式参考
• NestJS集成
• CLI参考
• 例子

🧪 测试

import { McpTestServer, mockTransport } from '@mcp-weave/testing';

describe('UserController', () => {
  let server: McpTestServer;

  beforeEach(() => {
    server = new McpTestServer(UserController);
  });

  it('should create a user', async () => {
    const result = await server.callTool('create_user', {
      name: 'John Doe',
      email: 'john@example.com',
    });

    expect(result.success).toBe(true);
    expect(result.userId).toBeDefined();
  });
});

🔐 认证

MCP-Weave支持API密钥验证，以确保MCP服务器端点的安全。

基本设置

import { McpRuntimeServer, generateApiKey } from '@mcp-weave/nestjs';

// Generate a secure API key with prefix
const apiKey = generateApiKey('myapp'); // myapp_xxxxx...

const server = new McpRuntimeServer(MyServer, {
  transport: 'sse',
  port: 3000,
  auth: {
    enabled: true,
    apiKeys: [{ key: apiKey, name: 'Production', scopes: ['read', 'write'] }],
  },
});

身份验证方法

API密钥可以通过以下方式提供：

• 头球: x-api-key: your-api-key
• 持有者令牌: Authorization: Bearer your-api-key
• 查询参数: ?api_key=your-api-key

高级配置

const server = new McpRuntimeServer(MyServer, {
  auth: {
    enabled: true,
    apiKeys: [
      {
        key: 'prod_key_123',
        name: 'Production',
        scopes: ['read', 'write'],
        expiresAt: new Date('2025-12-31'),
        metadata: { tier: 'premium' },
      },
    ],
    // Optional callbacks
    onAuthSuccess: (req, result) => {
      console.log(`Auth success: ${result.keyName} (${result.requestId})`);
    },
    onAuthFailure: (req, reason) => {
      console.log(`Auth failed: ${reason}`);
    },
    // Custom auth logic
    customAuth: async req => {
      // Return AuthResult or null to fall back to default
      return null;
    },
  },
});

Express中间件

import { createMcpExpressMiddleware } from '@mcp-weave/express';

app.use(
  '/mcp',
  createMcpExpressMiddleware(server, {
    auth: {
      enabled: true,
      apiKeys: [{ key: 'my-api-key', name: 'Default' }],
    },
  })
);

📁 例子

# Run the calculator example
cd examples/calculator
pnpm install && pnpm build && pnpm start

# Run the user-service example
cd examples/user-service
pnpm install && pnpm build && pnpm start

🗺️ 路线图

v0.1.0-MVP✅

• \[x\] 核心规范解析器和验证器
• \[x\] NestJS装饰器(@McpServer, @McpTool, @McpResource, @McpPrompt)
• \[x\] CLI与 generate, init, start, extract 命令
• \[x\] 标准运输
• \[x\] 带有GitHub操作的CI/CD
• \[x\] 示例（计算器、用户服务）
• \[x\] 测试实用程序包

v0.2.0版本✅

• \[x\] 快速支持(@mcp-weave/express)
• \[x\] SSE运输
• \[x\] 增强的测试工具 McpTestClient
• \[x\] 热重载(mcp-weave start --watch)

v0.3.0✅

• \[x\] WebSocket传输
• \[x\] 用于测试的Web UI仪表板(@mcp-weave/webui)
• \[x\] 235个单元测试通过

v0.4.0（当前）✅

• \[x\] 带有请求跟踪的API密钥身份验证
• \[x\] Express中间件和WebUI的身份验证支持
• \[x\] 265+单元测试通过

v0.5.0+

• \[\]Python/FastAPI支持
• \[\]Go/Gin支持
• \[\]插件系统

🤝 贡献

我们欢迎捐款！请查看我们的 贡献指南 了解详情。

# Clone the repo
git clone https://github.com/mcp-weave/mcp-weave.git
cd mcp-weave

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Lint and format
pnpm lint
pnpm format

📄 许可证

麻省理工学院 ©2026 MCP Weave

🔗 链接

• MCP规范
• Anthropic MCP公告
• 不和谐社区

______________________________________________________________________

Made with ❤️ by the MCP-Weave community