企业 AI Agent 接入方案调研报告

假设：你的工单系统已有以下 REST API

实操步骤

1. 打开你的 Swagger UI（通常在 https://your-api.com/swagger）
2. 筛选出高频使用的接口（优先：查询类 > 状态更新类 > 创建类）
3. 确认每个接口的认证方式（Bearer Token / API Key / Cookie）
4. 导出 OpenAPI 3.0 JSON —— 后续自动生成 MCP Tool Schema 的依据
5. 与后端确认：哪些字段需要脱敏（手机号、身份证、地址）

{ "name": "ticket-mcp-server", "version": "1.0.0", "type": "module", "scripts": { "build": "tsc", "start": "node dist/index.js" }, "dependencies": { "@modelcontextprotocol/sdk": "^1.0.0", "zod": "^3.22.0" }, "devDependencies": { "typescript": "^5.4.0", "@types/node": "^20.0.0" } }

// ticket-mcp-server/src/index.ts import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { z } from "zod"; // ========== 配置 ========== const API_BASE = process.env.TICKET_API_URL || "http://localhost:8080/api"; const API_TOKEN = process.env.TICKET_API_TOKEN || ""; // ========== 内部 API 调用封装 ========== async function callAPI(path: string, options: RequestInit = {}) { const res = await fetch(`${API_BASE}${path}`, { ...options, headers: { "Content-Type": "application/json", "Authorization": `Bearer ${API_TOKEN}`, ...options.headers, }, }); if (!res.ok) throw new Error(`API error: ${res.status} ${await res.text()}`); return res.json(); } // ========== 数据脱敏 ========== function maskPhone(phone: string): string { return phone.replace(/(\d{3})\d{4}(\d{4})/, "$1****$2"); } function maskIdCard(id: string): string { return id.replace(/(\d{6})\d{8}(\d{4})/, "$1********$2"); } // ========== 创建 MCP Server ========== const server = new McpServer({ name: "ticket-system", version: "1.0.0", }); // ────────────────────────────────────── // Tool 1: 搜索工单 // ────────────────────────────────────── server.tool( "search_tickets", "搜索内部工单系统的工单，支持按状态、优先级、负责人筛选", { status: z.enum(["pending", "in_progress", "resolved", "closed"]) .optional().describe("工单状态筛选"), priority: z.enum(["P0", "P1", "P2"]) .optional().describe("优先级筛选"), assignee: z.string().optional().describe("负责人姓名"), page: z.number().default(1).describe("页码"), limit: z.number().default(20).describe("每页数量"), }, async ({ status, priority, assignee, page, limit }) => { const params = new URLSearchParams(); if (status) params.set("status", status); if (priority) params.set("priority", priority); if (assignee) params.set("assignee", assignee); params.set("page", String(page)); params.set("limit", String(limit)); const data = await callAPI(`/tickets?${params}`); // 脱敏处理 data.tickets.forEach((t: any) => { if (t.reporter_phone) t.reporter_phone = maskPhone(t.reporter_phone); }); return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2), }], }; } ); // ────────────────────────────────────── // Tool 2: 获取工单详情 // ────────────────────────────────────── server.tool( "get_ticket_detail", "获取指定工单的完整详情，包括评论历史和操作记录", { ticket_id: z.string().describe("工单编号，如 T-1234"), }, async ({ ticket_id }) => { const data = await callAPI(`/tickets/${ticket_id}`); // 脱敏 if (data.reporter_phone) data.reporter_phone = maskPhone(data.reporter_phone); if (data.reporter_id_card) data.reporter_id_card = maskIdCard(data.reporter_id_card); return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2), }], }; } ); // ────────────────────────────────────── // Tool 3: 更新工单状态 // ────────────────────────────────────── server.tool( "update_ticket", "更新工单的状态、负责人或优先级，每次操作自动记录审计日志", { ticket_id: z.string().describe("工单编号"), status: z.enum(["pending", "in_progress", "resolved", "closed"]) .optional().describe("新状态"), assignee: z.string().optional().describe("新负责人姓名"), priority: z.enum(["P0", "P1", "P2"]) .optional().describe("新优先级"), comment: z.string().optional().describe("操作备注"), }, async ({ ticket_id, status, assignee, priority, comment }) => { // 构建更新体 const body: Record<string, any> = {}; if (status) body.status = status; if (assignee) body.assignee = assignee; if (priority) body.priority = priority; if (comment) body.comment = comment; const data = await callAPI(`/tickets/${ticket_id}`, { method: "PATCH", body: JSON.stringify(body), }); // 审计日志（自动记录到内部系统） await callAPI("/audit-logs", { method: "POST", body: JSON.stringify({ action: "update_ticket", target: ticket_id, changes: body, source: "mcp-agent", timestamp: new Date().toISOString(), }), }); return { content: [{ type: "text" as const, text: JSON.stringify({ success: true, ticket_id, updated_fields: Object.keys(body), ...data, }, null, 2), }], }; } ); // ========== 启动服务 ========== const transport = new StdioServerTransport(); await server.connect(transport); console.error("Ticket MCP Server running on stdio");

{ "mcpServers": { "ticket-system": { "command": "node", "args": ["dist/index.js"], "cwd": "/path/to/ticket-mcp-server", "env": { "TICKET_API_URL": "http://localhost:8080/api", "TICKET_API_TOKEN": "your-internal-api-token" } } } }

$ cd ticket-mcp-server $ npm install $ npm run build $ claude # 启动 Claude Code，自动加载 .mcp.json 中的 MCP Server

// src/security.ts — 安全工具集 // ========== 数据脱敏 ========== export const desensitize = { // 手机号：138****1234 phone: (v: string) => v.replace(/(\d{3})\d{4}(\d{4})/, "$1****$2"), // 身份证：110101********1234 idCard: (v: string) => v.replace(/(\d{6})\d{8}(\d{4})/, "$1********$2"), // 邮箱：z***g@example.com email: (v: string) => { const [local, domain] = v.split("@"); return local[0] + "***" + local.slice(-1) + "@" + domain; }, // 地址：保留省市，隐藏详细地址 address: (v: string) => { const match = v.match(/^(.{2,6}(?:省|市|自治区|特别行政区)?.{2,6}(?:市|区|县|州))/); return match ? match[1] + "****" : "****"; }, }; // 自动脱敏：遍历对象中的敏感字段 const SENSITIVE_FIELDS: Record<string, keyof typeof desensitize> = { phone: "phone", mobile: "phone", reporter_phone: "phone", id_card: "idCard", reporter_id_card: "idCard", email: "email", reporter_email: "email", address: "address", reporter_address: "address", }; export function autoMask(obj: any): any { if (typeof obj !== "object" || !obj) return obj; for (const [key, val] of Object.entries(obj)) { if (typeof val === "string" && SENSITIVE_FIELDS[key]) { obj[key] = desensitize[SENSITIVE_FIELDS[key]](val); } else if (typeof val === "object") { autoMask(val); } } return obj; } // ========== 审计日志 ========== export interface AuditEntry { action: string; target: string; changes: Record<string, any>; operator: string; source: "mcp-agent" | "web-ui" | "api"; timestamp: string; } export async function writeAuditLog( apiBase: string, token: string, entry: AuditEntry ) { await fetch(`${apiBase}/audit-logs`, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify(entry), }); }

FROM node:20-slim AS builder WORKDIR /app COPY package*.json . RUN npm ci COPY . . RUN npm run build FROM node:20-slim WORKDIR /app COPY --from=builder /app/dist ./dist COPY --from=builder /app/node_modules ./node_modules COPY package*.json . # 非 root 用户运行 RUN addgroup --system mcp && adduser --system --group mcp USER mcp CMD ["node", "dist/index.js"]

version: "3.8" services: ticket-mcp: build: . restart: unless-stopped environment: - TICKET_API_URL=http://internal-api:8080/api - TICKET_API_TOKEN=${TICKET_API_TOKEN} # 从 .env 文件读取 logging: driver: json-file options: max-size: "10m" max-file: "3" deploy: resources: limits: cpus: "0.5" memory: 256M healthcheck: test: ["CMD", "node", "-e", "process.exit(0)"] interval: 30s timeout: 10s retries: 3