Skip to content

A comprehensive framework for developing Model Context Protocol (MCP) servers with TypeScript/Node.js. Includes project specifications, architectural guidelines, and development tools for building production-ready MCP implementations.

License

Notifications You must be signed in to change notification settings

ankitjha-webdev/MCP-Server-Development-Framework

Repository files navigation

MCP Server Development Framework

A comprehensive TypeScript framework for building custom MCP (Model Context Protocol) servers that extend AI assistants with specialized tools, resources, and prompts.

Features

  • 🚀 Easy Setup: Quick project initialization with CLI tools
  • 🔧 Tool Registry: Register and execute custom tools with schema validation
  • 📚 Resource Management: Serve dynamic content and data resources
  • 💬 Prompt Templates: Create reusable prompt templates with arguments
  • ⚙️ Configuration Management: Flexible configuration with environment support
  • 🧪 Testing Utilities: Built-in testing framework for MCP protocol compliance
  • 📝 TypeScript Support: Full TypeScript support with declaration files
  • 🔍 Debugging Tools: Comprehensive logging and connection testing

Installation

npm install mcp-server-dev

Quick Start

1. Initialize a New Project

npx mcp-server init my-custom-server cd my-custom-server npm install

2. Define Your Server

import { MCPServer } from 'mcp-server-dev'; const server = new MCPServer({ name: 'my-custom-server', version: '1.0.0' }); // Register a simple tool server.toolRegistry.registerTool({ name: 'greet', description: 'Greet a user with a custom message', inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'Name to greet' }, greeting: { type: 'string', description: 'Greeting message', default: 'Hello' } }, required: ['name'] }, handler: async (args) => { return { content: [{ type: 'text', text: `${args.greeting}, ${args.name}!` }] }; } }); export default server;

3. Start Your Server

npm run build npm start

CLI Usage

The framework includes a powerful CLI for server management:

Start Server

# Start with default configuration mcp-server start # Start with custom config mcp-server start --config ./my-config.json # Start with debug logging mcp-server start --debug # Start in HTTP mode (default is stdio) mcp-server start --http --port 3000

Initialize Project

# Create new project in current directory mcp-server init my-server # Create in specific directory mcp-server init my-server --directory ./projects

Validate Configuration

mcp-server validate --config ./mcp-config.json

Test Connection

mcp-server test-connection

API Reference

MCPServer

The main server class that orchestrates all MCP functionality.

import { MCPServer, ServerConfig } from 'mcp-server-dev'; const server = new MCPServer(config: ServerConfig);

Methods

  • start(): Promise<void> - Start the MCP server
  • stop(): Promise<void> - Stop the server gracefully
  • toolRegistry: ToolRegistry - Access to tool management
  • resourceManager: ResourceManager - Access to resource management
  • promptManager: PromptManager - Access to prompt management

Tool Registry

Register and manage custom tools that can be executed by AI assistants.

import { ToolRegistry, ToolDefinition } from 'mcp-server-dev'; const toolRegistry = new ToolRegistry(); // Register a tool toolRegistry.registerTool({ name: 'file-reader', description: 'Read file contents', inputSchema: { type: 'object', properties: { path: { type: 'string', description: 'File path to read' } }, required: ['path'] }, handler: async (args) => { const fs = await import('fs/promises'); const content = await fs.readFile(args.path, 'utf-8'); return { content: [{ type: 'text', text: content }] }; } });

Resource Manager

Serve dynamic content and data resources.

import { ResourceManager } from 'mcp-server-dev'; const resourceManager = new ResourceManager(); // Register a resource resourceManager.registerResource({ uri: 'file://logs/{date}', name: 'Daily Logs', description: 'Access daily log files', mimeType: 'text/plain', provider: async (uri) => { const date = uri.match(/file:\/\/logs\/(.+)/)?.[1]; const logContent = await getLogForDate(date); return { contents: [{ type: 'text', text: logContent }] }; } });

Prompt Manager

Create reusable prompt templates with dynamic arguments.

import { PromptManager } from 'mcp-server-dev'; const promptManager = new PromptManager(); // Register a prompt template promptManager.registerPrompt({ name: 'code-review', description: 'Generate code review prompts', arguments: [ { name: 'language', description: 'Programming language', required: true }, { name: 'focus', description: 'Review focus area', required: false } ], template: async (args) => { return [{ role: 'user', content: { type: 'text', text: `Please review this ${args.language} code${args.focus ? ` focusing on ${args.focus}` : ''}:` } }]; } });

Configuration

Server Configuration

interface ServerConfig { name: string; version: string; description?: string; transport?: 'stdio' | 'http'; port?: number; logging?: { level: 'debug' | 'info' | 'warn' | 'error'; format?: 'json' | 'text'; }; }

Example Configuration File

{ "name": "my-mcp-server", "version": "1.0.0", "description": "Custom MCP server for specialized tasks", "transport": "stdio", "logging": { "level": "info", "format": "json" } }

Testing

The framework includes comprehensive testing utilities:

import { MCPTestClient } from 'mcp-server-dev/testing'; // Create test client const client = new MCPTestClient(); // Test server initialization await client.connect(); const initResult = await client.initialize({ protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'test-client', version: '1.0.0' } }); // Test tool execution const toolResult = await client.callTool('greet', { name: 'World' }); expect(toolResult.content[0].text).toBe('Hello, World!'); // Test resource access const resource = await client.readResource('file://logs/2024-01-01'); expect(resource.contents).toBeDefined(); // Test prompt generation const prompt = await client.getPrompt('code-review', { language: 'typescript' }); expect(prompt.messages).toBeDefined(); await client.disconnect();

Examples

File System Tool

server.toolRegistry.registerTool({ name: 'list-files', description: 'List files in a directory', inputSchema: { type: 'object', properties: { path: { type: 'string', description: 'Directory path' }, pattern: { type: 'string', description: 'File pattern (optional)' } }, required: ['path'] }, handler: async (args) => { const fs = await import('fs/promises'); const path = await import('path'); const files = await fs.readdir(args.path); const filteredFiles = args.pattern ? files.filter(f => f.includes(args.pattern)) : files; return { content: [{ type: 'text', text: filteredFiles.join('\n') }] }; } });

Web Scraper Resource

resourceManager.registerResource({ uri: 'web://{url}', name: 'Web Content', description: 'Scrape content from web pages', mimeType: 'text/html', provider: async (uri) => { const url = uri.replace('web://', 'https://'); const response = await fetch(url); const html = await response.text(); return { contents: [{ type: 'text', text: html, mimeType: 'text/html' }] }; } });

Code Generation Prompt

promptManager.registerPrompt({ name: 'generate-function', description: 'Generate function implementation', arguments: [ { name: 'functionName', required: true }, { name: 'language', required: true }, { name: 'description', required: true }, { name: 'parameters', required: false } ], template: async (args) => { const paramText = args.parameters ? ` with parameters: ${args.parameters}` : ''; return [{ role: 'user', content: { type: 'text', text: `Generate a ${args.language} function named "${args.functionName}"${paramText}. Description: ${args.description}` } }]; } });

Debugging

Enable Debug Logging

# Via CLI mcp-server start --debug # Via environment LOG_LEVEL=debug mcp-server start # Via configuration { "logging": { "level": "debug" } }

Connection Testing

import { ConnectionTester } from 'mcp-server-dev/testing'; const tester = new ConnectionTester(); const result = await tester.testConnection(serverConfig); if (result.success) { console.log('Server is working correctly'); console.log('Capabilities:', result.capabilities); } else { console.error('Connection failed:', result.error); }

Protocol Compliance

The framework ensures full MCP protocol compliance:

  • ✅ JSON-RPC 2.0 message format
  • ✅ MCP initialization handshake
  • ✅ Capability negotiation
  • ✅ Tool execution protocol
  • ✅ Resource serving protocol
  • ✅ Prompt template protocol
  • ✅ Error handling standards
  • ✅ Graceful shutdown

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests for new functionality
  5. Ensure all tests pass
  6. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

Changelog

v1.0.0

  • Initial release
  • Core MCP protocol implementation
  • Tool, resource, and prompt management
  • CLI utilities
  • Testing framework
  • TypeScript support

About

A comprehensive framework for developing Model Context Protocol (MCP) servers with TypeScript/Node.js. Includes project specifications, architectural guidelines, and development tools for building production-ready MCP implementations.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages