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 support (Express, FastAPI coming soon)
🛠️ Powerful CLI - Generate, extract, and manage your MCP servers
🧪 Testing Utilities - Mock servers and assertions for easy testing
📦 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/testing | Testing utilities and mocks | |

🔄 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

# 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

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

� 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] 152 unit tests passing
[x] CI/CD with GitHub Actions
[x] Examples (calculator, user-service)
[x] Testing utilities package

v0.2.0

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

v0.3.0+

[ ] Python/FastAPI support
[ ] WebSocket transport
[ ] Web UI for testing
[ ] Go/Gin support

🤝 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

🔗 Links

Made with ❤️ by the MCP-Weave community

MCP Servers