kaaromcp (Karx)

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

🛠️ 安装

1. 克隆存储库:

git clone 
cd kaaroMCP

1. 安装依赖项:

npm install

1. 构建项目:

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"]
  }
}

🔧 配置

服务器可以通过环境变量进行配置：

生产配置

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

🚀 发展

添加新工具

1. 修改 src/services/mcpServer.ts
2. 在中添加工具注册 setupTools()
3. 包括日志记录和错误处理
4. 添加单元测试

添加新资源

1. 修改 src/services/mcpServer.ts
2. 在中添加资源注册 setupResources()
3. 包含正确的URI模板
4. 添加集成测试

代码的风格

• 使用TypeScript严格模式
• 遵循ESLint配置
• 包括全面的错误处理
• 为所有主要操作添加日志记录

📝 脚本

🐛 故障排除

常见问题

1. 端口已在使用中:

   PORT=8080 npm start

1. TypeScript编译错误:

   npm run lint

1. 测试失败:

   DEBUG=true npm test

调试模式

启用详细日志记录：

DEBUG=true npm run dev

🤝 贡献

1. 创建要素分支
2. 为新功能编写测试
3. 确保所有测试通过
4. 更新文档
5. 提交拉取请求

开发工作流程

# Start development server
npm run dev

# Run tests
npm test

# Check types
npm run lint

# Build for production
npm run build

📄 许可证

该项目根据ISC许可证获得许可。

🙋‍♂️ 支持

如有疑问或问题：

1. 检查故障排除部分
2. 查看日志 DEBUG=true
3. 检查现有问题
4. 创建包含详细信息的新问题

______________________________________________________________________

由以下材料制成❤️ Kaaro Brain项目