Cmmv MCP

🚀 @cmmv/mcp

The @cmmv/mcp module implements the Model Context Protocol (MCP) for CMMV applications, enabling standardized interactions between Language Models (LLMs) and applications. MCP provides a structured interface for defining tools that can be used by AI models in a standard format.

🚀 Quick Start

The @cmmv/mcp module offers a standardized way for LLMs to interact with applications. Here's a high - level overview of how to get started:

1. Install the @cmmv/mcp module.
2. Configure the MCP settings.
3. Set up your application and register tools.
4. Use the MCP client to call registered tools.

✨ Features

• LLM Integration: Enables two - way communication between LLMs and applications.
• Flexible Transport: Supports data transfer via Server - Sent Events (SSE) or standard input/output (_stdio).
• API Decorator Style: Uses intuitive decorators like @MCPTool to register tools.
• Zod Validation: Validates input schemas using Zod.
• Connection Management: Implements robust connection handling, supporting multiple concurrent connections.

📦 Installation

Install @cmmv/mcp via pnpm:

$ pnpm add @cmmv/mcp

📚 Documentation

Configuration

Configure in the .cmmv.config.cjs file or use 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', // Optional values: 'sse' or 'stdio'
    },
    jwtSecret: {
      type: 'string',
      required: false,
      default: '',
    },
    timeout: {
      type: 'number',
      required: false,
      default: 5000,
    },
    keepAliveInterval: {
      type: 'number',
      required: false,
      default: 60000,
    },
  },
};

Setting up the Application

Set up the application using the Application.create method and import MCPModule and custom handlers MCPHandlers:

import { Application } from '@cmmv/core';
import { MCPModule } from '@cmmv/mcp';
import { MCPHandlers } from './handlers';

const app = new Application({
  name: 'My CMMV App',
  version: '1.0.0',
});

app.use(MCPModule);

app.listen(3000, () => {
  console.log('Application is running on http://localhost:3000');
});

Creating Tool Handlers

Use the @MCPTool decorator to register a class method as a tool that can be called by the LLM:

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

@MCPTool({
  name: 'calculate',
  description: 'Calculates the sum of two numbers.',
  parameters: [
    { name: 'a', type: 'number', required: true },
    { name: 'b', type: 'number', required: true },
  ],
})
export class Calculator {
  async calculate(a: number, b: number): Promise<number> {
    return a + b;
  }
}

Using the MCP Client

Call the registered tools using the MCP client via a curl command:

curl -X POST http://localhost:3000/api/mcp/tools/calculate \
-H "Content-Type: application/json" \
-d '{"a": 10, "b": 20}'

💡 Usage Tip

• Define Parameter Schemas Clearly: Use Zod schemas to clearly define the parameters for each tool.
• Provide Meaningful Responses: Return structured and helpful responses so that the LLM can understand effectively.
• Handle Errors Gracefully: Implement robust error - handling mechanisms in the handlers.
• Prioritize Security: Consider using JWT for authentication on public endpoints.
• Optimize Performance: Set appropriate time limits and ensure that handlers are lightweight and efficient.

By following these best practices, you can build efficient, secure, and maintainable CMMV applications.