MCP Framework (@chrom-ar/mcp-base)

A TypeScript framework library for building Model Context Protocol (MCP) servers with Express.js integration.

Features

• Easy Setup: Initialize MCP servers with minimal boilerplate
• Express Integration: Built-in Express.js app with MCP endpoints
• Automatic Router Registration: Registers with MCP router automatically
• Health Checks: Built-in health check endpoints
• Extensible: Access to underlying Express app for custom routes
• TypeScript Support: Full TypeScript definitions included

Installation

npm install @chrom-ar/mcp-base

Quick Start

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';
import { randomUUID } from 'crypto';
import { ChromaMCP } from '@chrom-ar/mcp-base';

// Create server info
const serverInfo = {
  id: randomUUID(),
  name: 'my-mcp-server',
  version: '1.0.0',
  description: 'My MCP Server'
};

// Create MCP server instance
const server = new McpServer(serverInfo);

// Add tools
server.tool(
  'say-hello',
  'Say hello with an optional name',
  {
    name: z.string().optional().describe('Name to say hello to')
  },
  async (args) => {
    const name = args.name || 'World';
    return {
      content: [
        {
          type: 'text',
          text: `Hello, ${name}!`
        }
      ]
    };
  }
);

// Create and start the ChromaMCP server
const chromaMcp = new ChromaMCP(server, {
  port: 3001,
  host: '0.0.0.0'
});

// Start the server
async function main() {
  await chromaMcp.start();
  console.log('Server started successfully!');
}

main().catch(console.error);

Configuration

The ChromaMCP class accepts a configuration object with the following options:

interface ChromaMCPConfig {
  port?: number;        // Server port (default: process.env.PORT || 3000)
  host?: string;        // Server host (default: '0.0.0.0')
  routerUrl?: string;   // MCP router URL for registration (default: process.env.MCP_ROUTER_URL)
}

Environment Variables

• PORT: Server port number
• MCP_ROUTER_URL: URL of the MCP router for automatic registration

API Reference

ChromaMCP Class

Constructor

constructor(server: McpServer, config?: ChromaMCPConfig)

Methods

• start(): Promise - Start the server and register with router
• getApp(): express.Application - Get the underlying Express app
• getMcpServer(): McpServer - Get the MCP server instance
• getServerInfo(): ServerInfo - Get server information

Built-in Endpoints

• POST /mcp - Main MCP protocol endpoint
• GET /health - Health check endpoint
• GET /mcp - Returns 405 Method Not Allowed
• DELETE /mcp - Returns 405 Method Not Allowed

Custom Routes

You can add custom Express routes by accessing the underlying app:

const app = chromaMcp.getApp();

app.get('/custom', (req, res) => {
  res.json({ message: 'Custom endpoint' });
});

app.post('/webhook', (req, res) => {
  // Handle webhook
  res.status(200).send('OK');
});

Examples

See the examples/ directory for more usage examples.

Development

# Build the library
npm run build

# Watch for changes
npm run dev

License

ISC