cmmv-mcp

Contract-Model-Model-View (CMMV)
Building scalable and modular applications using contracts.

Documentation • Report Issue

Description

The @cmmv/mcp module implements the Model Context Protocol (MCP) for CMMV applications, allowing standardized interactions between LLMs (Large Language Models) and your application. MCP provides a structured interface for defining tools usable by AI models in a standard format.

Features

• LLM Integration: Facilitates bidirectional communication between your application and language models.
• Flexible Transport: Supports transport via Server-Sent Events (SSE) or Standard I/O.
• API Decorator-Based: Intuitive decorators like @MCPTool to register tools.
• Validation with Zod: Input schema validation using Zod.
• Connection Management: Robust implementation for handling multiple concurrent connections.

Installation

Install @cmmv/mcp via pnpm:

$ pnpm add @cmmv/mcp

Configuration

Configure the MCP module in your .cmmv.config.cjs or using ConfigSchema:

import { ConfigSchema } from '@cmmv/core';

export const MCPConfig: ConfigSchema = {
  mcp: {
    name: {
      type: 'string',
      required: true,
      default: 'mcp',
    },
    version: {
      type: 'string',
      required: true,
      default: '0.0.1',
    },
    port: {
      type: 'number',
      required: true,
      default: 8765,
    },
    transport: {
      type: 'string',
      required: true,
      default: 'sse', // 'sse' or 'stdio'
    },
    jwtSecret: {
      type: 'string',
      required: true,
      default: 'your-secret-key',
    },
    pingInterval: {
      type: 'number',
      required: true,
      default: 30000,
    },
    connectionTimeout: {
      type: 'number',
      required: true,
      default: 300000,
    },
  },
};

Setting Up the Application

In your main file, include the MCPModule and configure your application:

import { Application, Config } from '@cmmv/core';
import { DefaultAdapter, DefaultHTTPModule } from '@cmmv/http';
import { MCPModule } from '@cmmv/mcp';
import { MCPHandlers } from './mcp-handlers';

Application.create({
    httpAdapter: DefaultAdapter,
    modules: [MCPModule],
    providers: [MCPHandlers],
});

Creating MCP Tool Handlers

Use the @MCPTool decorator to register tools callable by LLMs:

import { MCPTool, z } from '@cmmv/mcp';

export class MCPHandlers {
    @MCPTool('greet', {
        name: z.string(),
        age: z.number(),
    })
    public async greet({ name, age }: { name: string; age: number }) {
        return {
            content: `Hello \${name}, you are \${age} years old`,
        };
    }
}

Using the MCP Client

The MCP client can connect to your server using the SSE endpoint:

curl -X POST http://localhost:8765/messages \\
  -H "Content-Type: application/json" \\
  -d '{"type":"tool_call","name":"greet","arguments":{"name":"John","age":30}}'

Decorators

@MCPTool(name: string, schema: Record<string, z.ZodSchema>)

Registers a method as an MCP tool with a name and validation schema.

Best Practices

• Define Schemas Clearly: Use Zod schemas to clearly define parameters for each tool.
• Provide Meaningful Responses: Return structured and helpful responses for LLMs.
• Handle Errors Gracefully: Implement robust error handling in your handlers.
• Security First: Consider using JWT for public endpoints.
• Performance: Use timeouts and keep handlers lightweight and fast.