Cortexflow AI MCP

HTTP流MCP模板

用于构建具有HTTP流功能的MCP（模型上下文协议）服务器的基础结构。

概述

此模板使用Streamable HTTP传输协议提供了一个完整的、生产就绪的MCP服务器实现。它包括Hello world功能、全面的测试覆盖率和清晰的文档，可作为开发人员构建自己的MCP服务器的起点。

该模板实现了MCP协议版本2025-06-18，并遵循所有安全最佳实践，使其适用于开发和生产使用。

特性

• ✅ MCP协议2025-06-18合规性 -全面实施最新的MCP规范
• ✅ HTTP流式传输 -POST/GET支持，可选服务器发送事件（SSE）
• ✅ Hello world工具实现 -带有参数处理的完整示例工具
• ✅ 全面的测试覆盖率 -通过单元和集成测试，线路覆盖率达到95%以上
• ✅ 具有严格模式的TypeScript -完全类型安全和现代JavaScript功能
• ✅ 安全最佳实践 -源验证、本地主机绑定、输入净化
• ✅ 可扩展架构 -易于添加新工具和自定义行为
• ✅ 生产就绪 -错误处理、日志记录、正常关机和配置

快速开始

先决条件

• Node.js 18+（推荐：Node.js 20 LTS）
• npm 9+或纱1.22+

安装

1. 克隆或下载模板：

   git clone  my-mcp-server
   cd my-mcp-server

1. 安装依赖项：

   npm install

1. 启动开发服务器：

   npm run dev

服务器将于启动 http://127.0.0.1:3000 默认情况下。

验证安装

用一个简单的HTTP请求测试服务器：

# Test server health
curl http://127.0.0.1:3000/mcp

# Test MCP initialization (requires proper MCP client)
curl -X POST http://127.0.0.1:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": {"name": "test-client", "version": "1.0.0"}
    }
  }'

配置

环境变量

可以使用环境变量配置服务器：

# Server configuration
export MCP_PORT=3000              # Server port (default: 3000)
export MCP_HOST=127.0.0.1         # Server host (default: 127.0.0.1)

# Start server with custom configuration
npm start

程序化配置

import { MCPServer, createDefaultConfig } from './src/index.js';

const config = {
  ...createDefaultConfig(),
  port: 8080,
  host: '0.0.0.0',  // WARNING: Only use in secure environments
  allowedOrigins: ['localhost', '127.0.0.1', 'myapp.com'],
  serverInfo: {
    name: 'my-custom-mcp-server',
    version: '2.0.0'
  }
};

const server = new MCPServer(config);
await server.start();

配置选项

用法

使用Hello工具

该模板包括一个Hello工具，用于演示基本的MCP功能：

# List available tools
curl -X POST http://127.0.0.1:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'

# Call Hello tool without parameters
curl -X POST http://127.0.0.1:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "hello",
      "arguments": {}
    }
  }'

# Call Hello tool with name parameter
curl -X POST http://127.0.0.1:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "hello",
      "arguments": {"name": "Alice"}
    }
  }'

添加自定义工具

1. 创建新的工具类：

   // src/tools/my-tool.ts
   import { ToolImplementation, ToolResult } from '../types/index.js';

   export class MyTool implements ToolImplementation {
     name = 'my-tool';
     description = 'My custom tool';
     inputSchema = {
       type: 'object',
       properties: {
         input: { type: 'string' }
       }
     };

     async execute(args: any): Promise {
       return {
         content: [{ type: 'text', text: `Processed: ${args.input}` }],
         isError: false
       };
     }
   }

1. 注册工具：

   // In your server setup
   import { MyTool } from './tools/my-tool.js';

   const server = new MCPServer(config);
   server.registerTool(new MyTool());
   await server.start();

发展

可用脚本

项目结构

├── src/
│   ├── types/              # TypeScript type definitions
│   │   ├── index.ts        # Main type exports
│   │   ├── mcp.ts          # MCP protocol types
│   │   └── server.ts       # Server configuration types
│   ├── protocol/           # MCP protocol implementation
│   │   ├── errors.ts       # Error handling and standard error codes
│   │   ├── initialization.ts # MCP initialization handshake
│   │   └── jsonrpc.ts      # JSON-RPC message handling
│   ├── transport/          # HTTP transport layer
│   │   ├── http-server.ts  # Main HTTP server implementation
│   │   ├── content-negotiation.ts # Accept header handling
│   │   └── security-middleware.ts # Origin validation & security
│   ├── server/             # MCP server orchestration
│   │   ├── mcp-server.ts   # Main server class
│   │   └── tools-handler.ts # Tool request routing
│   ├── tools/              # Tool implementations
│   │   ├── hello-tool.ts   # Hello world tool example
│   │   ├── registry.ts     # Tool registration and management
│   │   └── index.ts        # Tool exports
│   └── index.ts            # Main entry point and exports
├── tests/
│   ├── unit/               # Unit tests
│   └── integration/        # Integration tests
├── examples/               # Usage examples
├── dist/                   # Compiled JavaScript (generated)
└── coverage/               # Test coverage reports (generated)

测试

该模板包括全面的测试覆盖率：

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode during development
npm run test:watch

# Run specific test file
npx vitest run tests/unit/tools/hello-tool.test.ts

代码质量

该项目使用ESLint和Prettier来提高代码质量：

# Check for linting issues
npm run lint

# Automatically fix linting issues
npm run lint:fix

# Format code
npm run format

生产部署

生产大楼

# Build the project
npm run build

# Start production server
npm start

Docker部署

创建一个 Dockerfile:

FROM node:20-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

COPY dist/ ./dist/
EXPOSE 3000

CMD ["npm", "start"]

构建并运行：

docker build -t my-mcp-server .
docker run -p 3000:3000 my-mcp-server

流程管理

对于生产部署，使用PM2这样的流程管理器：

# Install PM2
npm install -g pm2

# Start with PM2
pm2 start dist/index.js --name mcp-server

# Monitor
pm2 status
pm2 logs mcp-server

安全考虑

默认安全功能

• 本地主机绑定：默认情况下，服务器绑定到127.0.0.1
• 原产地验证：验证Origin标头以防止DNS重新绑定攻击
• 输入净化：所有工具输入都经过验证和消毒
• 错误处理：防止通过错误消息泄露信息

生产安全

对于生产部署：

1. 使用HTTPS：在生产环境中始终使用TLS
2. 防火墙：限制对MCP端口的访问
3. 认证：添加身份验证中间件（参见示例）
4. 速率限制：对工具调用实施速率限制
5. 监控：添加日志记录和监控

添加身份验证

// Example authentication middleware
import { MCPServer } from './src/index.js';

const server = new MCPServer(config);

// Add authentication hook (implement based on your needs)
server.addAuthenticationHook(async (request) => {
  const token = request.headers.authorization;
  if (!isValidToken(token)) {
    throw new Error('Unauthorized');
  }
});

故障排除

常见问题

服务器无法启动

问题: Error: listen EADDRINUSE :::3000 解决方案：端口3000已在使用中。要么：

• 使用端口3000停止进程： lsof -ti:3000 | xargs kill
• 使用其他端口： MCP_PORT=3001 npm start

问题: Error: listen EACCES :::80 解决方案：1024以下的端口需要root权限。使用端口3000+或使用sudo运行（不推荐）。

连接被拒绝

问题: curl: (7) Failed to connect to 127.0.0.1 port 3000: Connection refused 解决方案:

• 确保服务器正在运行： npm run dev
• 检查服务器日志中的启动错误
• 验证端口配置

原产地验证错误

问题: Error: Invalid Origin header 解决方案：将您的域名添加到 allowedOrigins 在配置中：

const config = {
  ...createDefaultConfig(),
  allowedOrigins: ['localhost', '127.0.0.1', 'yourdomain.com']
};

未找到工具

问题: Method not found: tools/call 解决方案:

• 在调用工具之前，确保服务器已初始化
• 检查工具是否正确登记
• 验证请求中的工具名称

JSON-RPC错误

问题: Parse error 或 Invalid Request 解决方案:

• 确保内容类型为 application/json
• 验证JSON语法
• 包含必需的JSON-RPC字段(jsonrpc, method, id)

调试模式

启用调试日志记录：

# Set debug environment variable
DEBUG=mcp:* npm run dev

# Or in code
process.env.DEBUG = 'mcp:*';

健康检查

服务器提供健康检查端点：

# Basic health check
curl http://127.0.0.1:3000/mcp

# Server statistics
curl -X POST http://127.0.0.1:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"server/stats"}'

性能问题

如果遇到性能问题：

1. 检查测试覆盖率: npm run test:coverage
2. 配置文件内存使用情况：使用Node.js --inspect 旗帜
3. 监控工具执行时间：检查服务器日志
4. 验证输入模式：确保有效验证

获取帮助

1. 检查日志：服务器日志包含详细的错误信息
2. 审查测试用例：测试证明了预期的行为
3. 参考MCP规范: MCP协议文件
4. 查看示例：参见 examples/ 使用模式目录

文档

• 需求 -详细的功能要求
• 设计 -架构和设计决策
• 实施任务 -开发任务分解
• MCP协议规范 -MCP官方文件

贡献

1. 分叉存储库
2. 创建要素分支： git checkout -b feature/my-feature
3. 进行更改并添加测试
4. 确保测试通过： npm test
5. 检查代码质量： npm run lint
6. 提交更改： git commit -am 'Add my feature'
7. 推送到分支： git push origin feature/my-feature
8. 创建拉取请求

许可证

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