MCP服务器Nuclio模板🚀
用于构建的生产就绪模板 基于Nuclio的MCP（模型上下文协议）服务器此模板提供了一个完整的基础，包括可配置工具、错误处理、缓存和流媒体支持。
特性✨
- 🛠️ 可配置工具系统 -通过配置文件定义工具
- 🔄 流媒体支持 -服务器发送事件和分块响应
- ⚡ 性能优化 -内置缓存和断路器模式
- 🔒 安全第一 -输入验证和输出净化
- 📊 监控就绪 -全面的日志记录和指标
- 🎯 生产就绪 -错误处理、重试和正常关机
- 🔧 开发者友好 -具有热重载功能的本地开发服务器
快速开始🏃♂️
1.克隆和设置
# Clone the template
git clone
cd mcp-server-nuclio-template
# Install dependencies
npm install
# Copy environment configuration
cp .env.example .env
# Edit .env with your settings
nano .env2.配置您的工具
编辑 config/tools.config.js 定义您的MCP工具：
tools: [
{
name: 'your_tool_name',
description: 'What your tool does',
inputSchema: {
type: 'object',
properties: {
// Define input parameters
}
},
outputSchema: {
type: 'object',
properties: {
// Define output structure
}
},
handler: 'lib/tools/your-tool.handler.js'
}
]3.创建工具处理程序
在中创建处理程序文件 lib/tools/:
// lib/tools/your-tool.handler.js
async function execute(args, context) {
const { logger, config } = context;
// Your tool logic here
return {
// Your response data
};
}
module.exports = { execute };4.本地运行
# Start local development server (recommended)
npm run server
# With auto-reload on file changes
npm run server:dev
# Or run the Nuclio function directly
npm start
# Development mode with auto-reload (function only)
npm run dev本地开发服务器(npm run server)提供：
- 完整的Nuclio功能包装
- 热重载能力
- 请求/响应日志记录
- 测试的开发端点
- CORS支持浏览器测试
项目结构📁
mcp-server-nuclio-template/
├── config/ # Global configuration
│ └── server.config.js # Server configuration
├── tools/ # Tool modules (NEW STRUCTURE)
│ ├── echo/ # Echo tool
│ │ ├── config/
│ │ │ ├── main.config.js
│ │ │ └── description.md
│ │ ├── properties/
│ │ │ ├── properties.config.js
│ │ │ └── description.md
│ │ └── handler.js
│ ├── search/ # Search tool
│ │ └── ...
│ └── [your-tool]/ # Your custom tools
├── lib/ # Core library code
│ ├── mcp-handler.js # MCP protocol handler
│ ├── tool-loader.js # Dynamic tool loader
│ └── streamable-transport.js # Streaming support
├── utils/ # Utility modules
│ ├── logger.js # Logging utility
│ ├── circuit-breaker.js # Circuit breaker pattern
│ ├── cache.js # Caching utility
│ └── validation.js # Schema validation
├── test/ # Test files
│ ├── local-server.js # Local development server
│ └── test-mcp.js # Test suite
├── docs/ # Documentation
│ └── TOOL_STRUCTURE.md # Tool structure guide
├── index.js # Main entry point
├── function.yaml # Nuclio configuration
├── package.json
├── .env.example # Environment template
└── README.md配置🔧
服务器配置(config/server.config.js)
{
server: {
name: 'your-server-name',
version: '1.0.0',
description: 'Your server description'
},
performance: {
maxConcurrentRequests: 10,
requestTimeout: 30000,
cacheEnabled: true,
cacheTTL: 3600
},
errorHandling: {
circuitBreaker: {
enabled: true,
failureThreshold: 5,
resetTimeout: 60000
}
}
}环境变量
关键环境变量（参见 .env.example):
MCP_SERVER_NAME-服务器标识符LOG_LEVEL-日志记录级别（错误、警告、信息、调试）CACHE_ENABLED-启用/禁用缓存CIRCUIT_BREAKER_ENABLED-启用/禁用断路器PORT-开发服务器端口
创建自定义工具🛠️
1.定义工具模式
将您的工具定义添加到 config/tools.config.js:
{
name: 'analyze_data',
description: 'Analyze data and return insights',
inputSchema: {
type: 'object',
properties: {
data: { type: 'array' },
metrics: {
type: 'array',
items: { type: 'string' }
}
},
required: ['data', 'metrics']
},
outputSchema: {
type: 'object',
properties: {
insights: { type: 'array' },
summary: { type: 'string' }
}
},
handler: 'lib/tools/analyze-data.handler.js',
config: {
timeout: 60000,
cacheEnabled: true
}
}2.实现处理程序
创建 lib/tools/analyze-data.handler.js:
async function execute(args, context) {
const { logger, config } = context;
const { data, metrics } = args;
logger.info('Analyzing data', { metrics });
// Your analysis logic
const insights = await analyzeData(data, metrics);
return {
insights,
summary: `Analyzed ${data.length} items`
};
}
module.exports = { execute };3.测试你的工具
# Use the test endpoint
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": "1",
"method": "tools/call",
"params": {
"name": "analyze_data",
"arguments": {
"data": [1, 2, 3],
"metrics": ["sum", "average"]
}
}
}'部署到Nuclio🚢
1.创建Nuclio函数
# function.yaml
apiVersion: nuclio.io/v1beta1
kind: Function
metadata:
name: mcp-server
spec:
handler: index:handler
runtime: nodejs
env:
- name: MCP_SERVER_NAME
value: "production-mcp-server"
- name: LOG_LEVEL
value: "info"
resources:
requests:
memory: "128Mi"
cpu: "100m"
limits:
memory: "512Mi"
cpu: "500m"2.部署
# Build and deploy to Nuclio
nuctl deploy \
--path . \
--registry your-registry \
--project-name your-project \
--platform localapi参考📚
MCP协议方法
initialize
初始化MCP服务器并获取功能。
tools/list
获取具有模式的可用工具列表。
tools/call
使用给定的参数执行工具。
{
"jsonrpc": "2.0",
"id": "1",
"method": "tools/call",
"params": {
"name": "tool_name",
"arguments": {
// Tool-specific arguments
}
}
}HTTP端点（开发服务器）
GET /health-健康检查GET /status-服务器状态和指标GET /tools-列出可用工具POST /mcp-主MCP端点
高级功能🔬
断路器
通过停止对失败服务的请求来防止级联故障：
// Automatically managed per tool
// Configurable via environment variables:
CIRCUIT_BREAKER_ENABLED=true
CIRCUIT_BREAKER_THRESHOLD=5
CIRCUIT_BREAKER_RESET=60000缓存
内置支持TTL的缓存：
// Configure in tool definition
config: {
cacheEnabled: true,
cacheTTL: 3600 // seconds
}流媒体支持
为长时间运行的操作启用流媒体：
// In your tool handler
async function execute(args, context) {
const { stream } = context;
// Stream chunks
for (const chunk of data) {
stream(chunk);
await processChunk(chunk);
}
return { complete: true };
}最佳实践💡
- 工具设计
- 保持工具专注于单一职责 - 使用清晰、描述性的名称 - 提供全面的架构
- 错误处理
- 始终返回结构化错误 - 用上下文记录错误 - 使用断路器进行外部服务
- 演出
- 为昂贵的操作启用缓存 - 设置适当的超时 - 使用流媒体处理大量响应
- 安全
- 验证所有输入 - 对输出进行消毒 - 切勿在日志中暴露敏感数据
- 监控
- 使用结构化日志记录 - 跟踪工具执行指标 - 监控断路器状态
例子📝
请参阅 examples/ 目录：
- 复杂的工具实现
- 集成模式
- 测试策略
- 部署配置
故障排除🔍
常见问题
- 工具未加载
- 检查配置中的处理程序文件路径 - 验证导出格式： module.exports = { execute } - 检查日志中的加载错误
- 验证错误
- 确保输入与架构完全匹配 - 检查必填字段 - 验证数据类型
- 性能问题
- 启用缓存 - 增加超时值 - 检查断路器状态
贡献🤝
欢迎投稿！拜托：
- 复刻仓库
- 创建要素分支
- 为新功能添加测试
- 提交拉取请求
许可证📄
MIT许可证-有关详细信息，请参阅许可证文件
支持💬
______________________________________________________________________
内置于❤️ 对于MCP社区