MCP服务器 - 资产派发与退库功能集成指南

本文档详细说明如何将大模型与MCP服务器关联，实现对资产派发和退库接口的真实数据处理调用。

项目架构

my-mcp-server/
├── src/
│   ├── server.ts          # MCP服务器主文件
│   ├── tools/
│   │   ├── assetManager.ts # 资产管理工具（核心业务逻辑）
│   │   └── apiClient.ts    # API客户端（与真实资产系统通信）
│   └── client-example.js   # 客户端调用示例
├── package.json
└── tsconfig.json

已实现功能

1. 资产派发：创建资产派发任务，分配资产给特定人员
2. 获取派发列表：查询资产派发记录，支持筛选
3. 资产退库：处理资产回收入库
4. 获取退库列表：查询资产退库记录

集成大模型与真实资产系统的步骤

环境配置

在服务器启动前，需要设置环境变量以支持token验证。您可以创建一个.env文件（基于.env.example）：

# 复制环境变量示例文件
cp .env.example .env

然后编辑.env文件，填写正确的配置：

# 资产系统API基础URL
ASSET_API_BASE_URL=https://your-asset-system-api.com/api

# 资产系统API认证Token (必填)
# 格式可以是完整的Bearer token或纯token值
# 示例1: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
# 示例2: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
ASSET_API_TOKEN=your-auth-token-here

# 资产系统API密钥（如果API需要）
ASSET_API_KEY=your-api-key-here

# 可选：端口配置
PORT=8000

2. 安装依赖

cd my-mcp-server
npm install

3. 编译并启动MCP服务器

# 编译TypeScript代码
npm run build

# 启动服务器
npm start

服务器默认运行在 http://localhost:8000。

4. 使用大模型调用资产操作工具

连接大模型与MCP服务器

不同的大模型服务有不同的连接方式，但基本流程如下：

1. 配置大模型：在大模型服务中注册您的MCP服务器地址
2. 设置工具调用权限：确保大模型有权限调用MCP中定义的工具
3. 定义工具调用参数：按照MCP工具定义提供正确的参数

工具调用示例（以OpenAI为例）

// 使用OpenAI SDK调用MCP工具
const OpenAI = require('openai');

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY
});

async function callAssetTool() {
  const response = await openai.chat.completions.create({
    model: "gpt-4",
    messages: [
      {
        role: "user",
        content: "请帮我派发一批新入职员工的办公设备"
      }
    ],
    tools: [
      {
        type: "function",
        function: {
          name: "distribute_asset",
          description: "创建资产派发任务",
          parameters: {
            type: "object",
            properties: {
              recipient: { type: "string", description: "接收人" },
              recipientDept: { type: "string", description: "接收人部门" },
              createBy: { type: "string", description: "创建人" },
              positionId: { type: "number", description: "职位ID" },
              distributeTime: { type: "string", description: "派发时间" },
              receiptType: { type: "number", description: "单据类型(0:借用,1:发放)" },
              assetIds: { type: "string", description: "资产ID列表，逗号分隔" },
              remark: { type: "string", description: "备注信息", nullable: true }
            },
            required: ["recipient", "recipientDept", "createBy", "positionId", "distributeTime", "receiptType", "assetIds"]
          }
        }
      }
    ],
    tool_choice: "auto"
  });

  // 处理工具调用结果
  if (response.choices[0].tool_calls) {
    const toolCall = response.choices[0].tool_calls[0];
    console.log("工具调用参数:", JSON.parse(toolCall.function.arguments));
    
    // 这里应该将工具调用请求发送到您的MCP服务器
    // 然后将结果回传给大模型进行处理
  }
}

5. 客户端调用示例

查看 src/client-example.js 文件，其中包含了如何通过大模型客户端调用资产操作工具的完整示例。

资产系统API接口说明

我们的MCP服务器通过 apiClient.ts 与真实的资产系统API进行通信。支持以下接口：

资产派发相关

• POST /assets/distribute - 创建派发请求
• GET /assets/distribute/list - 查询派发列表

资产退库相关

• POST /assets/return - 创建退库请求
• GET /assets/return/list - 查询退库列表

Token验证机制说明

我们实现了完整的token验证和自动刷新机制，包括：

1. 自动Token注入：所有API请求都会自动携带有效的token
2. Token过期检测：提前30秒检测token过期并刷新，避免请求失败
3. 自动Token刷新：
   • 当token过期时，自动尝试刷新token
   • 支持使用refreshToken进行刷新
   • 如果没有refreshToken，使用环境变量中的token
4. 请求重试：token刷新后自动重试失败的请求
5. 并发控制：避免同时发起多个token刷新请求

错误处理与调试

日志记录

服务器和API客户端都会记录详细的操作日志，包括：

• 请求参数和URL
• 请求携带的token信息（脱敏显示）
• 响应状态和数据
• 错误信息和token刷新事件

常见问题排查

1. API连接失败

   • 检查环境变量配置是否正确
   • 验证API地址和认证信息是否有效
   • 确认网络连接正常

2. Token认证失败

   • 检查ASSET_API_TOKEN格式是否正确
   • 确认token是否在有效期内
   • 验证token权限是否足够访问请求的资源

3. 参数验证失败

   • 检查调用时提供的参数是否符合工具定义
   • 确保必填参数都已提供

常见问题排查

1. API连接失败

   • 检查环境变量配置是否正确
   • 验证API地址和认证信息是否有效
   • 确认网络连接正常

2. 参数验证失败

   • 检查调用时提供的参数是否符合工具定义
   • 确保必填参数都已提供

3. 权限问题

   • 验证API令牌是否具有足够的权限
   • 检查大模型是否有权限调用MCP工具

安全最佳实践

1. 环境变量管理：

   • 不要将敏感信息硬编码在代码中
   • 生产环境中使用安全的环境变量管理工具
   • 定期轮换token和API密钥

2. Token安全：

   • 设置合理的token过期时间
   • 实施token刷新机制而不是长期有效的token
   • 避免在日志中记录完整的token

3. 参数验证：在服务端对所有输入参数进行严格验证

4. 错误信息：避免在错误信息中泄露系统内部细节

5. 认证授权：确保所有API调用都经过适当的认证和授权

手动更新Token

在某些情况下（如用户登录后），您可能需要手动更新API客户端使用的token。可以使用我们提供的工具函数：

import { updateApiToken } from './tools/apiClient';

// 登录成功后更新token
async function handleLogin(username, password) {
  const loginResponse = await loginApi(username, password);
  
  if (loginResponse.success) {
    const { accessToken, refreshToken, expiresIn } = loginResponse.data;
    
    // 更新API客户端的token
    updateApiToken(accessToken, refreshToken, expiresIn);
    
    return true;
  }
  
  return false;
}

## 扩展建议

1. **添加更多资产操作工具**：如资产查询、转移、维修等
2. **实现缓存机制**：提高频繁查询的响应速度
3. **添加事务支持**：确保复杂操作的原子性
4. **增加监控告警**：实时监控API调用状态

## 总结

通过本指南，您可以成功地将大模型与MCP服务器关联，并使用资产派发和退库功能进行真实的数据处理。整个流程包括：

1. 配置环境变量连接真实资产系统API
2. 启动MCP服务器注册资产操作工具
3. 在大模型服务中配置MCP连接
4. 通过大模型调用资产操作工具处理业务逻辑

如有任何问题，请参考项目代码或联系技术支持。