item-wms-public-api-tool 2.0.4

package/AI_INTEGRATION_GUIDE.md

@@ -0,0 +1,492 @@
+# AI工具集成指南
+
+## 1. MCP与AI工具的交互原理
+
+### 1.1 核心机制
+
+MCP (Model Control Plane) 通过以下机制实现与AI工具的集成：
+
+1. **配置驱动发现**：AI工具通过读取 `mcp.json` 文件发现可用工具
+2. **标准化调用**：支持标准MCP JSON-RPC（stdio）以及动态CLI调用（基于OpenAPI）
+3. **结构化输出**：返回JSON格式结果，便于AI工具解析
+4. **自描述接口**：每个工具都包含详细的描述和参数定义
+
+### 1.2 标准MCP (stdio/JSON-RPC)
+
+当进程运行在非TTY模式（例如通过管道或由AI Agent启动）时，服务会进入标准MCP模式，支持 `initialize`、`tools/list`、`tools/call`、`resources/list`、`prompts/list` 等JSON-RPC方法。
+
+示例请求/响应（按行发送JSON）：
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","clientInfo":{"name":"agent","version":"1.0.0"}}}
+```
+
+```json
+{"jsonrpc":"2.0","id":2,"method":"tools/list"}
+```
+
+```json
+{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"post_v1_public_user_login","arguments":{"username":"testuser","password":"testpass"},"options":{"baseUrl":"https://wms-staging.item.com/api/public"}}}
+```
+
+### 1.3 Prompts（代码生成提示）
+
+提供内置提示模板，帮助模型生成更贴合接口的代码：
+
+```json
+{"jsonrpc":"2.0","id":4,"method":"prompts/list"}
+```
+
+```json
+{"jsonrpc":"2.0","id":5,"method":"prompts/get","params":{"name":"wms_call_flow","arguments":{"language":"zh","include_examples":"true"}}}
+```
+
+该提示用于指导模型基于接口定义实现真实可用的 HTTP 调用，而不是调用 MCP 工具。
+
+### 1.4 CLI交互流程
+
+```
+CLI/脚本 → 读取 openapi.yaml → 动态生成命令 → 直接调用 HTTP API
+```
+
+说明：工具名称由 OpenAPI 自动生成（`<method>_<path>`），CLI 与 MCP 使用同一套工具名。可用 `list/describe` 查看工具详情。
+
+## 2. mcp.json文件分析
+
+`mcp.json` 是AI工具与MCP交互的核心配置文件，包含以下关键信息：
+
+### 2.1 基本信息
+
+```json
+{
+  "id": "wms.item.public",
+  "name": "item-wms-public-api-tool",
+  "version": "0.1.0",
+  "description": "Public APIs for auth, EDI import, queries, uploads, and item master data.",
+  "entrypoint": "item-wms-public-api-tool",
+  "tools": [ /* 工具列表 */ ]
+}
+```
+
+- **id**：MCP唯一标识符
+- **name**：MCP名称
+- **version**：版本号
+- **description**：功能描述
+- **entrypoint**：CLI入口（动态工具）
+- **tools**：可用工具列表
+
+### 2.2 工具定义结构
+
+每个工具包含完整的元数据：
+
+```json
+{
+  "name": "post_v1_public_user_login",
+  "description": "User authentication and access token retrieval for system access",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "username": { "type": "string" },
+      "password": { "type": "string" }
+    },
+    "required": ["username", "password"]
+  }
+}
+```
+
+- **name**：工具名称，用于MCP调用与工具查找
+- **description**：工具功能描述，帮助AI工具理解用途
+- **inputSchema**：JSON Schema定义，包含：
+  - **properties**：参数列表及类型
+  - **required**：必传参数列表
+
+## 3. AI工具集成步骤
+
+### 3.1 步骤1：发现MCP
+
+AI工具通过读取 `mcp.json` 文件发现MCP及其工具：
+
+```javascript
+const fs = require('fs');
+const mcpConfig = JSON.parse(fs.readFileSync('mcp.json', 'utf8'));
+
+console.log('发现MCP:', mcpConfig.name);
+console.log('可用工具数量:', mcpConfig.tools.length);
+```
+
+### 3.2 步骤2：选择工具
+
+AI工具根据用户需求选择合适的工具：
+
+```javascript
+// 根据功能描述匹配工具
+const loginTool = mcpConfig.tools.find(tool => 
+  tool.description.includes('authentication') || 
+  tool.name === 'post_v1_public_user_login'
+);
+
+// 根据名称精确匹配
+const orderQueryTool = mcpConfig.tools.find(tool => 
+  tool.name === 'post_v1_public_edi_outbound_order_level_search_by_paging'
+);
+```
+
+### 3.3 步骤3：解析参数
+
+AI工具解析工具的输入参数：
+
+```javascript
+// 获取工具参数信息
+const toolParams = loginTool.inputSchema.properties;
+const requiredParams = loginTool.inputSchema.required;
+
+console.log('工具参数:', Object.keys(toolParams));
+console.log('必传参数:', requiredParams);
+```
+
+### 3.4 步骤4：构造MCP调用
+
+AI工具根据工具名称和参数构造 MCP `tools/call` 请求：
+
+```javascript
+// 工具名由 <method>_<path> 生成
+const toolName = 'post_v1_public_user_login';
+
+const request = {
+  jsonrpc: '2.0',
+  id: 1,
+  method: 'tools/call',
+  params: {
+    name: toolName,
+    arguments: {
+      username: 'testuser',
+      password: 'testpass'
+    },
+    options: {
+      baseUrl: 'https://wms-staging.item.com/api/public'
+    }
+  }
+};
+
+console.log('构造的请求:', JSON.stringify(request));
+```
+
+说明：`baseUrl` 可省略，默认使用 `https://wms-staging.item.com/api/public`。CLI 可通过 `list/describe` 获取工具列表与参数。
+
+### 3.5 步骤5：执行命令
+
+AI工具执行动态CLI命令并获取结果：
+
+```javascript
+const child_process = require('child_process');
+
+function executeMCPCommand(command) {
+  return new Promise((resolve, reject) => {
+    child_process.exec(command, (error, stdout, stderr) => {
+      if (error) {
+        reject(new Error(`命令执行失败: ${stderr}`));
+        return;
+      }
+      
+      try {
+        // 解析JSON结果
+        const result = JSON.parse(stdout);
+        resolve(result);
+      } catch (parseError) {
+        reject(new Error(`结果解析失败: ${stdout}`));
+      }
+    });
+  });
+}
+
+// 使用示例
+const result = await executeMCPCommand(command);
+```
+
+### 3.6 步骤6：处理结果
+
+AI工具处理和使用命令执行结果：
+
+```javascript
+if (result.success) {
+  console.log('登录成功');
+  console.log('获取到的token:', result.onAuthToken);
+  
+  // 使用token调用其他工具
+  const orderResult = await executeMCPCommand(
+    `${mcpConfig.entrypoint} call post_v1_public_edi_outbound_order_level_search_by_paging --json '{"Paging":{"page":1,"pageSize":10}}' --token ${result.onAuthToken}`
+  );
+  
+  console.log('订单查询结果:', orderResult);
+} else {
+  console.error('登录失败:', result.message);
+}
+```
+
+## 4. AI工具集成验证
+
+### 4.1 验证脚本
+
+项目包含 `test-ai-integration.js` 脚本，用于验证AI工具集成：
+
+```bash
+node test-ai-integration.js
+```
+
+### 4.2 验证内容
+
+脚本验证以下关键集成点：
+
+1. ✅ mcp.json格式正确性
+2. ✅ 工具定义完整性
+3. ✅ CLI动态调用可用性
+4. ✅ 工具发现机制
+5. ✅ 命令构造正确性
+6. ✅ 参数映射有效性
+7. ✅ 输出格式兼容性
+
+### 4.3 验证结果
+
+```
+=== AI工具集成测试 ===
+
+1. 检查mcp.json格式和内容
+   ✅ MCP ID: wms.item.public
+   ✅ MCP名称: item-wms-public-api-tool
+   ✅ 版本: 0.1.0
+   ✅ 描述: Public APIs for auth, EDI import, queries, uploads, and item master data.
+   ✅ 入口点: item-wms-public-api-tool
+   ✅ 工具数量: <N>
+
+2. 验证工具定义
+   1. post_v1_public_user_login
+      描述: User authentication and access token retrieval for system access
+      输入Schema: 有效
+      必传参数: ["username","password"]
+   ...
+
+=== 测试总结 ===
+✅ mcp.json格式正确，包含完整的工具定义
+✅ 所有工具都有清晰的描述和输入Schema
+✅ 每个工具都明确指定了必传参数
+✅ CLI 工具列表可通过 list/describe 获取
+✅ AI工具可以通过读取mcp.json发现所有工具
+✅ AI工具可以构造正确的命令调用MCP
+✅ MCP返回结构化数据，便于AI工具解析
+
+结论: 该MCP可以被AI工具正常发现和调用!
+```
+
+## 5. AI工具调用示例
+
+### 5.1 完整集成示例
+
+```javascript
+const fs = require('fs');
+const child_process = require('child_process');
+
+class MCPIntegration {
+  constructor(mcpPath) {
+    this.mcpConfig = JSON.parse(fs.readFileSync(mcpPath, 'utf8'));
+    this.token = null;
+  }
+
+  async executeCommand(toolName, params = {}) {
+    const args = ['call', toolName, '--json', JSON.stringify(params)];
+    if (this.baseUrl) {
+      args.push('--baseUrl', this.baseUrl);
+    }
+    if (this.token) {
+      args.push('--token', this.token);
+    }
+
+    console.log('执行命令:', this.mcpConfig.entrypoint, args.join(' '));
+
+    const result = await this.execCommand(args);
+    return result;
+  }
+
+  execCommand(args) {
+    return new Promise((resolve, reject) => {
+      child_process.execFile(this.mcpConfig.entrypoint, args, (error, stdout, stderr) => {
+        if (error) {
+          reject(new Error(`命令执行失败: ${stderr}`));
+          return;
+        }
+        
+        try {
+          const result = JSON.parse(stdout);
+          resolve(result);
+        } catch (parseError) {
+          reject(new Error(`结果解析失败: ${stdout}`));
+        }
+      });
+    });
+  }
+
+  // 登录方法
+  async login(username, password, baseUrl) {
+    this.baseUrl = baseUrl;
+    const result = await this.executeCommand('post_v1_public_user_login', {
+      username,
+      password
+    });
+    
+    if (result.success && result.onAuthToken) {
+      this.token = result.onAuthToken;
+      console.log('登录成功，token已保存');
+    }
+    
+    return result;
+  }
+
+  // 订单查询方法
+  async queryOrders(params) {
+    return this.executeCommand('post_v1_public_edi_outbound_order_level_search_by_paging', params);
+  }
+
+  // 发现工具
+  findTool(condition) {
+    if (typeof condition === 'string') {
+      return this.mcpConfig.tools.find(tool => tool.name === condition);
+    }
+    return this.mcpConfig.tools.find(condition);
+  }
+
+  // 获取所有工具
+  getAllTools() {
+    return this.mcpConfig.tools;
+  }
+}
+
+// 使用示例
+async function main() {
+  // 初始化MCP集成
+  const mcp = new MCPIntegration('./mcp.json');
+  
+  // 登录
+  await mcp.login('testuser', 'testpass', 'https://wms-staging.item.com/api/public');
+  
+  // 查询订单
+  const orders = await mcp.queryOrders({
+    Paging: {
+      page: 1,
+      pageSize: 10
+    }
+  });
+  
+  console.log('订单查询结果:', orders);
+}
+
+main().catch(console.error);
+```
+
+### 5.2 工具发现示例
+
+```javascript
+// 初始化MCP集成
+const mcp = new MCPIntegration('./mcp.json');
+
+// 获取所有工具
+const allTools = mcp.getAllTools();
+console.log('所有工具:', allTools.map(tool => tool.name));
+
+// 按功能查找工具
+const uploadTools = mcp.getAllTools().filter(tool => 
+  tool.description.includes('upload')
+);
+console.log('文件上传相关工具:', uploadTools.map(tool => tool.name));
+
+// 精确查找工具
+const loginTool = mcp.findTool('post_v1_public_user_login');
+console.log('登录工具:', loginTool.name, '-', loginTool.description);
+```
+
+## 6. 最佳实践
+
+### 6.1 AI工具开发建议
+
+1. **错误处理**：妥善处理命令执行错误和JSON解析错误
+2. **参数校验**：根据inputSchema生成/校验参数
+3. **结果缓存**：对频繁调用的结果进行缓存
+4. **异步执行**：使用异步方式执行命令，避免阻塞
+5. **日志记录**：记录命令执行日志，便于调试
+6. **版本兼容**：考虑MCP版本升级带来的变化
+
+### 6.2 MCP使用建议
+
+1. **环境变量**：可通过环境变量覆盖默认的 baseUrl、token、CompanyID、FacilityID、CustomerID
+2. **默认租户配置**：CompanyID/FacilityID/CustomerID 默认为 LT/889/FLAANT0001，可通过 CLI 参数或环境变量覆盖
+3. **参数优先级**：命令行参数 > 环境变量 > 默认值
+4. **安全考虑**：避免在日志中记录敏感信息
+5. **超时设置**：为命令执行设置合理的超时时间
+6. **重试机制**：对网络请求失败的情况实现重试
+
+## 7. 故障排除
+
+### 7.1 常见问题
+
+1. **命令未找到**：确保MCP已安装或使用npx执行
+2. **认证失败**：检查用户名密码是否正确，或token是否过期
+3. **参数错误**：检查参数名称和类型是否与inputSchema一致
+4. **JSON解析失败**：检查命令输出是否为有效的JSON格式
+5. **网络错误**：检查baseUrl是否可访问，网络连接是否正常
+
+### 7.2 调试技巧
+
+1. **查看帮助信息**：执行 `item-wms-public-api-tool --help` 或 `item-wms-public-api-tool describe <toolName>`
+2. **测试单个命令**：在终端手动执行命令，检查输出
+3. **验证mcp.json**：使用JSON验证工具检查mcp.json格式
+4. **查看CLI源码**：检查 `src/index.ts` / `src/cli.ts` 了解命令处理逻辑
+
+## 8. 集成验证清单
+
+| 验证项 | 验证方法 | 预期结果 |
+|--------|----------|----------|
+| mcp.json存在 | 检查文件是否存在 | 文件存在 |
+| mcp.json格式正确 | 使用JSON验证工具 | 格式有效 |
+| 工具定义完整 | 检查每个工具是否包含name、description和inputSchema | 所有工具定义完整 |
+| CLI动态工具可用 | 执行 `item-wms-public-api-tool list` | 输出工具列表 |
+| 命令格式正确 | 构造并执行简单命令 | 命令执行成功 |
+| 输出为JSON格式 | 执行命令并检查输出 | 输出为有效的JSON |
+| 工具发现正常 | 使用AI工具代码读取mcp.json | 成功发现所有工具 |
+| 参数映射正确 | 检查命令参数与inputSchema的对应关系 | 映射正确 |
+| 必传参数检查 | 检查 inputSchema 的 required 字段 | 必传参数清晰可见 |
+| 结果解析正常 | AI工具解析命令输出 | 成功解析结果 |
+
+## 9. 版本兼容性
+
+### 9.1 当前版本支持
+
+- ✅ 支持基于mcp.json的工具发现
+- ✅ 支持动态CLI调用
+- ✅ 支持JSON格式输出
+- ✅ 支持环境变量配置
+- ✅ 支持动态工具发现（OpenAPI）
+
+### 9.2 未来扩展
+
+- 支持API调用方式
+- 支持事件驱动架构
+- 支持更复杂的参数类型
+- 支持更友好的工具别名/分组
+
+## 10. 联系与支持
+
+如需集成帮助或遇到问题，请：
+
+1. 查看 [HELP.md](HELP.md) 获取详细使用说明
+2. 查看 [README.md](README.md) 获取项目概述
+3. 检查 [openapi.yaml](openapi.yaml) 获取API文档
+4. 运行 `node test-ai-integration.js` 进行集成测试
+
+## 11. 结论
+
+本MCP设计符合AI工具集成的最佳实践，通过：
+
+1. **自描述配置**：完整的工具定义和参数说明
+2. **标准化接口**：统一的工具命名规则（`<method>_<path>`）
+3. **结构化输出**：JSON格式结果
+4. **清晰的文档**：详细的集成指南
+
+AI工具可以轻松发现、调用和使用本MCP提供的所有功能，实现高效、可靠的集成。