distributed-mcp-server

A minimalistic distributed Model Context Protocol (MCP) server implementation that extends the official MCP SDK with distributed capabilities.

Features

• 🚀 Simple wrapper around @modelcontextprotocol/sdk
• 🔌 Fully compatible with standard MCP protocol
• 🆔 Automatic instance ID generation for distributed scenarios
• 📊 Built-in distributed event logging
• 🎯 TypeScript support with full type definitions
• 🪶 Minimal dependencies

Installation

npm install distributed-mcp-server @modelcontextprotocol/sdk

Usage

Basic Example

import { createDistributedMcpServer } from 'distributed-mcp-server';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

// Create a distributed MCP server
const server = createDistributedMcpServer({
  name: 'my-distributed-server',
  version: '1.0.0',
}, {
  distributed: true,
  instanceId: 'my-instance-1', // Optional: auto-generated if not provided
});

// Register tools, resources, and prompts as usual
server.tool('hello', 'Say hello', async () => {
  return {
    content: [
      { type: 'text', text: 'Hello from distributed MCP server!' }
    ]
  };
});

// Connect to transport
const transport = new StdioServerTransport();
await server.connect(transport);

console.log(`Server running with instance ID: ${server.getInstanceId()}`);

Using as a Class

import { DistributedMcpServer } from 'distributed-mcp-server';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new DistributedMcpServer({
  name: 'my-server',
  version: '1.0.0',
}, {
  distributed: true,
});

// Register handlers
server.resource('config', 'file:///config.json', async (uri) => {
  return {
    contents: [
      { uri: uri.href, text: '{"setting": "value"}', mimeType: 'application/json' }
    ]
  };
});

server.prompt('generate-docs', 'Generate documentation', async () => {
  return {
    messages: [
      { role: 'user', content: { type: 'text', text: 'Generate docs for the project' } }
    ]
  };
});

await server.connect(new StdioServerTransport());

API

createDistributedMcpServer(serverInfo, options)

Creates a new distributed MCP server instance.

Parameters:

• serverInfo: Implementation - Server metadata (name, version)
• options?: DistributedMcpServerOptions - Configuration options
  • instanceId?: string - Unique server instance ID (auto-generated if omitted)
  • distributed?: boolean - Enable distributed features (default: false)

Returns: DistributedMcpServer

DistributedMcpServer

Extends McpServer from @modelcontextprotocol/sdk with distributed capabilities.

Additional Methods:

• getInstanceId(): string - Get the unique instance identifier
• isDistributed(): boolean - Check if distributed mode is enabled

Inherited Methods: All methods from McpServer are available:

• tool() - Register tools
• resource() - Register resources
• prompt() - Register prompts
• connect() - Connect to transport
• close() - Close connection
• sendLoggingMessage() - Send log messages
• And more...

TypeScript Support

Full TypeScript support with exported types:

import type { 
  Implementation,
  Transport,
  ToolCallback,
  RegisteredTool,
  ResourceTemplate,
  CallToolResult,
} from 'distributed-mcp-server';

Distributed Features

When distributed: true is enabled:

• Automatic instance ID tracking
• Distributed event logging on connect/disconnect
• Foundation for future distributed coordination features

Requirements

• Node.js >= 18.0.0
• @modelcontextprotocol/sdk >= 1.0.0

License

MIT

Contributing

Contributions are welcome! This is a minimalistic package designed to be extended for specific distributed use cases.

Related

• Model Context Protocol
• @modelcontextprotocol/sdk