@monoes/mcp

Standalone MCP server engine — Version 1.0.1. Supports stdio, HTTP, and WebSocket transports with tool registry, resources, prompts, sessions, rate limiting, and connection pooling. Zero @monomind/* dependencies.

Part of the Monomind ecosystem.

Package Architecture & Versioning

The Monomind MCP Subsystem is split across two core packages:

1. @monoes/mcp (v1.0.1) (This package): Standalone MCP protocol engine powering stdio, HTTP (Express/Cors/Helmet), and WebSocket (ws) transports, connection pooling, prompt/resource registries, rate limiting, and session lifecycle management.
2. @monoes/monomindcli (v2.9.0): Implements CLI integration, binary entry points (monomind-mcp), MCP server manager, MCP client loader, and 30+ domain tool modules (src/mcp-tools/).

• Protocol Version: Returns protocolVersion: '2024-11-05' per standard MCP specification release (packages/@monomind/cli/src/mcp-server.ts:532 & packages/@monomind/mcp/src/server.ts:91).
• Server Identity Version Drift: The binary monomind-mcp hardcodes server identity VERSION = '3.0.0' in its JSON-RPC initialize response (serverInfo: { name: 'monomind', version: '3.0.0' } at packages/@monomind/cli/bin/mcp-server.js:13), decoupled from package versioning (v2.9.0).

Server Entry Points

| Entry Point / Module | Location | Description & Role | |---|---|---| | bin/mcp-server.js | packages/@monomind/cli/bin/mcp-server.js | Direct stdio MCP server binary (monomind-mcp). Reads lines from process.stdin and handles JSON-RPC calls (initialize, tools/list, tools/call, ping, notifications/initialized) with hardcoded version 3.0.0 protocol handshake behavior for direct Claude Code integration. | | commands/mcp.ts | packages/@monomind/cli/src/commands/mcp.ts | User-facing CLI command handler for monomind mcp subcommands (start, stop, status, list, call, toggle, health, logs, metrics, test). | | mcp-server.ts | packages/@monomind/cli/src/mcp-server.ts | Implements MCPServerManager class managing server process lifecycle, PID file management (~/.monomind/mcp-server.pid), background daemonization, and health monitoring. |

Install

npm install @monoes/mcp

Quick start

import { quickStart, defineTool } from '@monoes/mcp';

const server = await quickStart({
  transport: 'stdio',
  name: 'My MCP Server',
});

server.registerTool(defineTool(
  'greet',
  'Greet a user',
  { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
  async ({ name }) => ({ message: `Hello, ${name}!` })
));

await server.start();

Transports

Note: Monomind's monomind-mcp binary uses direct stdio transport (bin/mcp-server.js) for minimal latency with Claude Code. The @monoes/mcp package provides full transport modularity (stdio, HTTP, WebSocket) for custom or standalone integrations.

import { createMCPServer } from '@monoes/mcp';

// stdio (default — for Claude Code integration)
const server = createMCPServer({ transport: 'stdio', name: 'My Server' }, logger);

// HTTP with auth
const server = createMCPServer({
  transport: 'http',
  host: 'localhost',
  port: 3000,
  corsEnabled: true,
  auth: { enabled: true, method: 'token', tokens: ['secret'] },
}, logger);

// WebSocket
const server = createMCPServer({
  transport: 'websocket',
  host: 'localhost',
  port: 3001,
  maxConnections: 100,
}, logger);

Tool registry

import { createToolRegistry, defineTool } from '@monoes/mcp';

const registry = createToolRegistry(logger);

registry.register({
  name: 'add',
  description: 'Add two numbers',
  inputSchema: { type: 'object', properties: { a: { type: 'number' }, b: { type: 'number' } }, required: ['a', 'b'] },
  handler: async ({ a, b }) => ({ result: a + b }),
});

const result = await registry.execute('add', { a: 2, b: 2 });

Resources & prompts

import { createTextResource, definePrompt, textMessage } from '@monoes/mcp';

// Resources
const { resource, handler } = createTextResource('file://readme.txt', 'README', 'Hello!');
server.getResourceRegistry().registerResource(resource, handler);

// Prompts
const prompt = definePrompt('summarize', 'Summarize text', [
  { name: 'text', description: 'Text to summarize', required: true }
], (args) => ({ messages: [textMessage(`Summarize: ${args.text}`)] }));
server.getPromptRegistry().registerPrompt(prompt);

Server API

interface IMCPServer {
  start(): Promise<void>;
  stop(): Promise<void>;
  registerTool(tool: MCPTool): boolean;
  registerTools(tools: MCPTool[]): { registered: number; failed: string[] };
  getHealthStatus(): Promise<{ healthy: boolean; error?: string }>;
  getMetrics(): MCPServerMetrics;
  getSessions(): MCPSession[];
}

Built-in tools

| Tool | Description | |------|-------------| | system/info | Server information | | system/health | Health status | | system/metrics | Server metrics | | tools/list-detailed | List all tools with details |

Links

• GitHub
• MCP Specification
• Issues

License

MIT