Intent MCP Server

Intent MCP Server

一个模型上下文协议（MCP）服务，可将自然语言意图处理为结构化、可执行的格式。该服务提供稳健的 API，用于管理和处理意图，重点关注可扩展性和可靠性。

概述

本项目实现了一种意图处理架构，可将自然语言输入转换为结构化对象，并生成可执行的工作流。它注重可维护性、类型安全和可扩展性，同时提供简洁的意图管理 API。

功能

• 🎯 意图处理：通过定义完善的 API 创建、检索和处理意图
• 🔍 自然语言理解：解析并理解原始用户意图
• 🧩 意图分解：将意图转换为包含目标和约束的结构化对象
• 💾 灵活存储：可插拔存储系统，内置内存实现
• 📝 类型安全：完整的 TypeScript 实现，并提供全面的类型定义
• 🛡️ 错误处理：稳健的错误处理和日志记录系统
• 🧪 测试：使用 Jest 构建的全面测试套件
• 📚 API 文档：清晰的 API 文档和示例

前置条件

• Node.js（v18 或更高版本）
• npm 或 yarn

安装

1. 克隆仓库：

git clone https://github.com/openpandacodes/intent-mcp-server.git
cd intent-mcp-server

2. 安装依赖：

npm install

3. 在根目录中创建 .env 文件：

cp .env.example .env

4. 使用你的配置设置更新 .env 文件。

配置

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

• NODE_ENV：环境（development、production、test）
• PORT：服务端口（默认值：3000）
• LOG_LEVEL：日志级别（debug、info、warn、error）

使用

开发

启动支持热重载的开发服务：

npm run dev

生产环境

构建并启动生产服务：

npm run build
npm start

测试

运行测试：

npm test

运行测试并生成覆盖率报告：

npm run test:coverage

API 端点

意图管理

• POST /api/intent：创建新意图

  curl -X POST http://localhost:3000/api/intent \
    -H "Content-Type: application/json" \
    -d '{"rawIntent": "Your natural language intent here"}'
  

• GET /api/intent/:id：按 ID 获取意图

  curl -X GET http://localhost:3000/api/intent/YOUR_INTENT_ID
  

其他端点详见 API 规范。

健康检查

• GET /health：检查服务健康状态

架构

该服务遵循整洁架构模式，包含多个独立层：

1. 控制器：处理 HTTP 请求和响应
2. 服务：实现核心业务逻辑和意图处理
3. 存储：通过可插拔实现管理数据持久化
4. 模型：定义数据结构和类型

核心组件

• IntentController：处理与意图相关的 HTTP 端点
• IntentService：用于意图处理的核心服务
• StorageInterface：抽象存储层
• InMemoryStorage：存储接口的参考实现

项目结构

intent-mcp-server/
├── src/
│   ├── controllers/     # HTTP request handlers
│   ├── services/        # Business logic implementation
│   │   └── __tests__/  # Service tests
│   ├── storage/        # Storage implementations
│   ├── models/         # Type definitions
│   └── utils/          # Utility functions
├── tests/              # Test suites
└── config/             # Configuration files

意图结构

系统会将意图组织为正式对象：

interface Intent {
  id: string;
  rawIntent: string;
  processed: {
    goals: Goal[];
    constraints: Constraint[];
    metadata: Record<string, unknown>;
  };
  status: "pending" | "processing" | "completed" | "failed";
  createdAt: Date;
  updatedAt: Date;
}

错误处理

该服务实现了全面的错误处理：

• 针对不同错误类型的自定义错误类
• 正确的 HTTP 状态码和错误响应
• 用于调试和监控的结构化日志记录
• 使用 TypeScript 类型进行验证

贡献

1. Fork 仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'feat: Add some amazing feature'）
4. 将分支推送到远程仓库（git push origin feature/amazing-feature）
5. 创建 Pull Request

请确保你的代码：

• 遵循现有风格和约定
• 包含适当的测试
• 按需更新文档
• 使用约定式提交消息

许可证

MIT License - 详情请参阅 LICENSE 文件