MCP API 服务

Model Context Protocol (MCP) 服务器，用于与内部系统 API 进行交互。

系统架构

概览

MCP API 服务是一个基于 Model Context Protocol (MCP) 协议运行的中间服务器，帮助连接 Claude AI 和内部系统 API。该系统：

1. 接收来自 Claude 的指令：用户通过 Claude 请求执行某项任务。
2. 处理和转换：MCP 将用户的请求转换为内部 API 格式。
3. 调用 API：调用内部系统的 API。
4. 返回结果：结果被格式化并返回给 Claude，以显示给用户。

工作机制

MCP 服务器通过 stdio（标准输入/输出）进行通信：

• Standard Input (stdin)：接收来自 Claude 的请求（例如：搜索员工命令）。
• Standard Output (stdout)：将结果返回给 Claude（例如：找到的员工信息）。
• Standard Error (stderr)：记录错误日志（例如：API 连接错误）。

当一个请求发送时的流程：

1. Claude 通过 stdin 发送 JSON 格式的请求。
2. MCP 服务器处理请求并调用适当的 API。
3. MCP 服务器通过 stdout 将结果返回给 Claude。
4. Claude 显示结果给用户。

功能（场景）

现有场景包括：

• check_connection - 检查与 API 服务器的连接。
• search_employee - 按名称或代码搜索员工。
• register_breakfast - 为员工注册早餐。
• update_hoa_chat - 按班次更新化学品信息。
• chuyen_nhan_vien_thi_cong - 转移施工承包员工。

添加新场景

1. 添加 Endpoint

在 src/config.ts 中定义新的 endpoint：

export const CONFIG = {
  // ...existing code...
  TOOLS: {
    // ...existing code...
    TEN_NHOM_API: {
      ACTION_API: '/api/services/app/TenService/TenAction'
    }
  }
}

2. 添加 Interface

在 src/types.ts 中为输入/输出数据创建接口：

export interface TenActionInput {
  Param1: string;
  Param2: number;
  // 其他参数...
}

3. 创建新服务或将内容添加到现有服务

在 src/services/ 中创建新文件或将内容添加到现有服务：

// src/services/ten-service.service.ts
import { TenActionInput } from '../types.js';
import { ApiClient } from '../utils/api-client.js';
import { Logger } from '../utils/logger.js';
import { CONFIG } from '../config.js';

export class TenService {
  private logger = new Logger();

  async tenAction(input: TenActionInput) {
    try {
      this.logger.debug('Calling ten action API', {
        url: CONFIG.TOOLS.TEN_NHOM_API.ACTION_API,
        input
      });
      
      const response = await ApiClient.post(
        CONFIG.TOOLS.TEN_NHOM_API.ACTION_API, 
        null,
        { params: input }
      );
      
      this.logger.info('Action completed successfully', { input });
      return response.result;
    } catch (error) {
      this.logger.error('Error performing action', { error, input });
      throw error;
    }
  }
}

4. 更新 Index

在 src/index.ts 中：

• 添加新服务（如果有）。
• 在工具列表中定义新工具。
• 在 handleToolCall 函数中添加 case 处理逻辑。

开发

安装库：

npm install

构建服务器：

npm run build

以开发模式运行并自动重新构建：

npm run watch

调试

挑战

调试 MCP 存在困难，因为：

• 无法像普通应用程序一样设置断点。
• 难以跟踪输入/输出的数据流。
• 错误日志可能与输出混淆。

解决方案

使用 MCP Inspector 来：

• 跟踪发送到服务器的请求。
• 查看每个请求的返回结果。
• 单独检查错误日志。
• 监控性能。

启动 Inspector：

npm run inspector

Inspector 将提供访问 Web 界面的 URL 以监控系统活动。

最佳实践

1. 一致性

   • 遵循现有的命名结构。
   • 使用已建立的代码模板。

2. 错误处理

   • 始终实现 try/catch。
   • 记录完整的错误信息。
   • 返回明确的错误消息。

3. 日志记录

   • 完整记录步骤：调用 API 前记录 debug 日志，成功时记录 info 日志。
   • 日志中包含完整的参数。

4. 验证

   • 检查必填参数。
   • 验证输入数据类型。

更多详细信息请参阅 docs/add-new-scenario.md。