MCP API 服务

用于与内部系统 API 交互的 Model Context Protocol (MCP) 服务器

系统架构

概述

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 = {
  // ...现有代码...
  TOOLS: {
    // ...现有代码...
    TEN_NHOM_API: {
      ACTION_API: '/api/services/app/TenService/TenAction'
    }
  }
}

2. 添加接口

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

在 src/index.ts 中：

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

开发

安装库：

npm install

构建服务器：

npm run build

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

npm run watch

调试

挑战

MCP 的调试面临困难，因为：

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

解决方案

使用 MCP Inspector 来：

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

启动 Inspector：

npm run inspector

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

最佳实践

1. 一致性

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

2. 错误处理

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

3. 日志记录

   • 记录所有步骤：在调用 API 之前进行调试，成功时记录信息
   • 在日志中包含所有参数

4. 验证

   • 检查必需参数
   • 验证输入的类型

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