npm package: @shengxian123/my-mcp-server
Description: 本文档详细说明如何将大模型与MCP服务器关联，实现对资产派发和退库接口的真实数据处理调用。
Latest version: 1.0.34

# 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`）：

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

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

```bash
# 资产系统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. 安装依赖

```bash
cd my-mcp-server
npm install
```

### 3. 编译并启动MCP服务器

```bash
# 编译TypeScript代码
npm run build

# 启动服务器
npm start
```

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

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

#### 连接大模型与MCP服务器

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

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

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

```javascript
// 使用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。可以使用我们提供的工具函数：

```javascript
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. 通过大模型调用资产操作工具处理业务逻辑

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