Development Framework

MCP服务器开发框架

一个全面的TypeScript框架，用于构建自定义MCP（模型上下文协议）服务器，通过专门的工具、资源和提示扩展AI助手。

特性

• 🚀 轻松设置：使用CLI工具快速初始化项目
• 🔧 工具注册表：注册并执行具有模式验证的自定义工具
• 📚 资源管理：提供动态内容和数据资源
• 💬 提示模板：使用参数创建可重用的提示模板
• ⚙️ 配置管理：具有环境支持的灵活配置
• 🧪 测试工具：MCP协议合规性的内置测试框架
• 📝 TypeScript支持：声明文件完全支持TypeScript
• 🔍 调试工具：全面的日志记录和连接测试

安装

npm install mcp-server-dev

快速开始

1.初始化新项目

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

2.定义您的服务器

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.启动服务器

npm run build
npm start

CLI使用情况

该框架包括一个用于服务器管理的强大CLI：

启动服务器

# 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

初始化项目

# Create new project in current directory
mcp-server init my-server

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

验证配置

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

测试连接

mcp-server test-connection

api参考

MCP服务器

协调所有MCP功能的主服务器类。

import { MCPServer, ServerConfig } from 'mcp-server-dev';

const server = new MCPServer(config: ServerConfig);

方法

• start(): Promise -启动MCP服务器
• stop(): Promise -优雅地停止服务器
• toolRegistry: ToolRegistry -访问工具管理
• resourceManager: ResourceManager -访问资源管理
• promptManager: PromptManager -访问快速管理

工具注册表

注册并管理可由AI助手执行的自定义工具。

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
      }]
    };
  }
});

资源管理器

提供动态内容和数据资源。

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
      }]
    };
  }
});

快速经理

使用动态参数创建可重用的提示模板。

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}` : ''}:`
      }
    }];
  }
});

配置

服务器配置

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

配置文件示例

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

测试

该框架包括全面的测试工具：

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();

例子

文件系统工具

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剪贴资源

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'
      }]
    };
  }
});

代码生成提示

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}`
      }
    }];
  }
});

调试

启用调试日志记录

# Via CLI
mcp-server start --debug

# Via environment
LOG_LEVEL=debug mcp-server start

# Via configuration
{
  "logging": {
    "level": "debug"
  }
}

连接测试

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);
}

协议遵从

该框架确保完全符合MCP协议：

• ✅ JSON-RPC 2.0消息格式
• ✅ MCP初始化握手
• ✅ 能力协商
• ✅ 工具执行协议
• ✅ 资源服务协议
• ✅ 提示模板协议
• ✅ 错误处理标准
• ✅ 平滑关闭

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 添加新功能的测试
5. 确保所有测试通过
6. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

支持

• 📖 文档
• 🐛 问题追踪
• 💬 讨论

更新日志

v1.0.0

• 初始版本
• 核心MCP协议实现
• 工具、资源和及时管理
• CLI实用程序
• 测试框架
• TypeScript支持