MCP-Weave

Weave your code into MCP servers - seamlessly
Like Swagger for Model Context Protocol

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

✨ Features

• 🎯 Simple Decorators - Transform any class into an MCP server with intuitive annotations
• 🔄 Two-Way Flow - Code-first or Spec-first development approach
• 📝 YAML Spec - Define your MCP server in a readable mcp-spec.yaml file
• 🚀 Multiple Frameworks - NestJS and Express support
• 🔌 Multiple Transports - stdio, SSE, and WebSocket
• � Authentication - API key support with request tracking and scopes
• �🛠️ Powerful CLI - Generate, extract, and manage your MCP servers with hot reload
• 🧪 Testing Utilities - Mock servers and assertions for easy testing
• 🎨 Web UI Dashboard - Interactive testing of tools, resources, and prompts
• 📦 TypeScript First - Full type safety and excellent DX

🚀 Quick Start

Installation

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

# Using npm
npm install @mcp-weave/nestjs

# Using yarn
yarn add @mcp-weave/nestjs

Basic Usage

Transform your existing code into an MCP server with simple decorators:

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})`,
        },
      ],
    };
  }
}

📦 Packages

| Package | Description | Version | | ------------------------------------------ | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | @mcp-weave/core | Core functionality - parser, validator, generator | | | @mcp-weave/cli | Command-line interface | | | @mcp-weave/nestjs | NestJS integration with decorators | | | @mcp-weave/express | Express middleware and server | | | @mcp-weave/testing | Testing utilities and mocks | | | @mcp-weave/webui | Web UI dashboard for testing | |

🔄 Two Development Flows

Code-First

Start with decorated code, extract the spec:

Annotated Code → Scanner → Metadata → Generator → MCP Server

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

Spec-First

Start with a YAML spec, generate boilerplate:

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

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

📝 Spec Format

Define your MCP server in 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 Commands

# 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

🎨 Decorators API

Class Decorators

| Decorator | Description | | --------------------- | ------------------------------ | | @McpServer(options) | Marks a class as an MCP server |

Method Decorators

| Decorator | Description | | ----------------------- | --------------------------------- | | @McpTool(options) | Marks a method as an MCP tool | | @McpResource(options) | Marks a method as an MCP resource | | @McpPrompt(options) | Marks a method as an MCP prompt |

Parameter Decorators

| Decorator | Description | | --------------------- | ----------------------- | | @McpInput() | Injects tool input | | @McpParam(name) | Injects URI parameter | | @McpPromptArg(name) | Injects prompt argument |

📚 Documentation

• Getting Started Guide
• API Reference
• Spec Format Reference
• NestJS Integration
• CLI Reference
• Examples

🧪 Testing

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();
  });
});

🔐 Authentication

MCP-Weave supports API key authentication to secure your MCP server endpoints.

Basic Setup

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'] }],
  },
});

Authentication Methods

API keys can be provided via:

• Header: x-api-key: your-api-key
• Bearer Token: Authorization: Bearer your-api-key
• Query Parameter: ?api_key=your-api-key

Advanced Configuration

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 Middleware

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

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

📁 Examples

| Example | Description | | --------------------------------------- | ---------------------------------------------------- | | calculator | Basic calculator with arithmetic tools | | user-service | Full CRUD service with tools, resources, and prompts |

# 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

🗺️ Roadmap

v0.1.0 - MVP ✅

• [x] Core spec parser and validator
• [x] NestJS decorators (@McpServer, @McpTool, @McpResource, @McpPrompt)
• [x] CLI with generate, init, start, extract commands
• [x] Stdio transport
• [x] CI/CD with GitHub Actions
• [x] Examples (calculator, user-service)
• [x] Testing utilities package

v0.2.0 ✅

• [x] Express support (@mcp-weave/express)
• [x] SSE transport
• [x] Enhanced testing utilities with McpTestClient
• [x] Hot reload (mcp-weave start --watch)

v0.3.0 ✅

• [x] WebSocket transport
• [x] Web UI dashboard for testing (@mcp-weave/webui)
• [x] 235 unit tests passing

v0.4.0 (Current) ✅

• [x] API key authentication with request tracking
• [x] Auth support for Express middleware and WebUI
• [x] 265+ unit tests passing

v0.5.0+

• [ ] Python/FastAPI support
• [ ] Go/Gin support
• [ ] Plugin system

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

# 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

📄 License

MIT © 2026 MCP-Weave

🔗 Links

• MCP Specification
• Anthropic MCP Announcement
• Discord Community
• GitHub Discussions

Made with ❤️ by the MCP-Weave community