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（标准输入/输出）进行通信：

• 标准输入 (stdin)：从 Claude 接收请求（例如：搜索员工命令）
• 标准输出 (stdout)：将结果返回给 Claude（例如：找到的员工信息）
• 标准错误 (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. 添加端点

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

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

2. 添加接口

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

export interface TenActionInput {
  Param1: string;
  Param2: number;
  // Các tham số khác...
}

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. 更新索引

在 src/index.ts 中：

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

开发

安装库：

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。