Kaaro MCP服务器
Kaaro Brain代理接口的健壮模型上下文协议（MCP）服务器实现。这个项目已经过重构，以实现可维护性、可观察性和团队协作。
🚀 特性
- MCP协议支持：全面实施用于AI代理通信的模型上下文协议
- 会话管理：具有自动清理功能的强大会话处理
- 综合录井：调试和监控的详细日志记录
- 健康监测：内置健康检查端点
- TypeScript：全型安全和现代开发经验
- 测试：综合单元和集成测试
- 模块化架构：可维护性关注点的清晰分离
📁 项目结构
kaaroMCP/
├── src/
│ ├── types/ # TypeScript type definitions
│ ├── utils/ # Utility functions (logger, etc.)
│ ├── services/ # Business logic services
│ ├── routes/ # HTTP route handlers
│ ├── middleware/ # Express middleware
│ ├── app.ts # Main application class
│ └── index.ts # Application entry point
├── tests/ # Unit and integration tests
├── dist/ # Compiled JavaScript output
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript configuration
├── jest.config.js # Test configuration
└── README.md # This file🛠️ 安装
- 克隆存储库:
git clone
cd kaaroMCP- 安装依赖项:
npm install- 构建项目:
npm run build🏃♂️ 运行服务器
发展模式
npm run dev生产模式
npm start默认情况下，服务器将在端口3000上启动。您可以使用环境变量进行配置：
PORT=8080 npm start📡 API终点
MCP协议
- POST/mcp -客户端到服务器通信
- GET/mcp -服务器到客户端通知（SSE）
- 删除/mcp -会话终止
健康与监测
- GET/健康 -健康检查端点
- 得到/ -服务器信息
健康响应示例
{
"status": "healthy",
"timestamp": "2024-01-14T01:38:00.000Z",
"server": {
"name": "kaaro-mcp-server",
"version": "1.0.0",
"uptime": 125.5
},
"sessions": {
"activeSessions": 2,
"sessionIds": ["session-123", "session-456"]
}
}🔧 配置
服务器可以通过环境变量进行配置：
| 变量 | 默认值 | 描述 |
|---|---|---|
PORT | 3000 | 服务器端口 |
NODE_ENV | development | 环境模式 |
DEBUG | false | 启用调试日志记录 |
ALLOWED_HOSTS | 127.0.0.1,localhost | 逗号分隔的允许主机 |
生产配置
NODE_ENV=production
PORT=8080
ALLOWED_HOSTS=yourdomain.com,api.yourdomain.com🧪 测试
运行所有测试
npm test在监视模式下运行测试
npm run test:watch生成覆盖率报告
npm run test:coverage测试结构
- 单元测试：单个组件测试
- 集成测试：端到端API测试
- 嘲笑：控制台输出和外部依赖关系
📊 测井和观测
服务器包括用于可观察性的全面日志记录：
日志级别
- 信息：一般信息
- 警告：警告条件
- 错误：错误条件
- 调试：调试信息（仅限开发）
日志上下文
所有日志都包含上下文信息：
{
"timestamp": "2024-01-14T01:38:00.000Z",
"level": "info",
"message": "Session initialized",
"sessionId": "abc-123",
"method": "POST",
"path": "/mcp"
}监控事件
- 会话生命周期（创建、初始化、关闭）
- 请求/响应时间
- 工具调用
- 资源访问
- 错误条件
🔌 MCP工具和资源
可用工具
- 添加：加法计算器
- 乘：乘法计算器
可用资源
- 问候语：//{姓名}：动态问候生成器
- status://server：服务器状态信息
工具使用示例
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "add",
"arguments": {
"a": 5,
"b": 3
}
}
}🚀 发展
添加新工具
- 修改
src/services/mcpServer.ts - 在中添加工具注册
setupTools() - 包括日志记录和错误处理
- 添加单元测试
添加新资源
- 修改
src/services/mcpServer.ts - 在中添加资源注册
setupResources() - 包含正确的URI模板
- 添加集成测试
代码的风格
- 使用TypeScript严格模式
- 遵循ESLint配置
- 包括全面的错误处理
- 为所有主要操作添加日志记录
📝 脚本
| 脚本 | 描述 |
|---|---|
npm start | 启动生产服务器 |
npm run dev | 启动开发服务器 |
npm run build | 将TypeScript构建为JavaScript |
npm test | 运行所有测试 |
npm run test:watch | 在监视模式下运行测试 |
npm run test:coverage | 生成测试覆盖率 |
npm run lint | 不编译的类型检查 |
npm run clean | 清洁建筑和覆盖 |
🐛 故障排除
常见问题
- 端口已在使用中:
PORT=8080 npm start- TypeScript编译错误:
npm run lint- 测试失败:
DEBUG=true npm test调试模式
启用详细日志记录：
DEBUG=true npm run dev🤝 贡献
- 创建要素分支
- 为新功能编写测试
- 确保所有测试通过
- 更新文档
- 提交拉取请求
开发工作流程
# Start development server
npm run dev
# Run tests
npm test
# Check types
npm run lint
# Build for production
npm run build📄 许可证
该项目根据ISC许可证获得许可。
🙋♂️ 支持
如有疑问或问题：
- 检查故障排除部分
- 查看日志
DEBUG=true - 检查现有问题
- 创建包含详细信息的新问题
______________________________________________________________________
由以下材料制成❤️ Kaaro Brain项目