contract-template-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,121 @@
+# Contract Template MCP Server
+
+CRM 合同模版库管理 MCP Server，为智能体（如 CodeBuddy/WorkBuddy）提供合同模板分类管理、合同模板管理和模板文件获取能力。
+
+## 功能概览
+
+| 工具名称 | 功能说明 | 对应后端API |
+|---------|---------|-----------|
+| `list_contract_categories` | 查询合同模板分类列表（支持关键词搜索） | `GET /mcp/contract/category/list` |
+| `create_contract_category` | 创建新的合同模板分类 | `POST /mcp/contract/category/create` |
+| `list_contract_templates` | 查询合同模板列表（支持分类/关键词筛选） | `GET /mcp/contract/template/list` |
+| `get_contract_template` | 获取模板详情及文件下载URL | `GET /mcp/contract/template/detail` |
+| `create_contract_template` | 在分类下创建新模板（含 v1.0 初版） | `POST /mcp/contract/template/create` |
+
+## 安装与配置
+
+### 1. 安装依赖
+
+```bash
+cd contract-template-mcp-server
+npm install
+```
+
+### 2. 配置 MCP Client
+
+在 CodeBuddy/WorkBuddy 的 MCP 配置中添加：
+
+```json
+{
+  "mcpServers": {
+    "contract-template": {
+      "command": "contract-template-mcp-server",
+      "env": {
+        "CONTRACT_TEMPLATE_API_BASE_URL": "http://your-crm-backend:port",
+        "CRM_MCP_ACCESS_KEY": "从管理系统获取的access-key"
+      }
+    }
+  }
+}
+```
+
+### 3. 环境变量
+
+| 变量名 | 必填 | 说明 |
+|--------|------|------|
+| `CONTRACT_TEMPLATE_API_BASE_URL` | 否 | 后端CRM服务地址，默认 `http://localhost:3000` |
+| `CRM_MCP_ACCESS_KEY` | 是 | MCP 访问密钥，从管理系统 `agent/access-key` 获取 |
+
+## 使用示例
+
+### 查询分类
+
+```
+用户: 目前有哪些合同模板分类？
+AI: 调用 list_contract_categories → 返回分类列表
+```
+
+### 创建分类
+
+```
+用户: 在"销售合同"下帮我创建一个"2025版"子分类
+AI: 调用 list_contract_categories（获取"销售合同"的ID）
+    → 调用 create_contract_category（parentId=销售合同ID, categoryName="2025版"）
+```
+
+### 查询模板
+
+```
+用户: 销售合同分类下有哪些模板？
+AI: 调用 list_contract_templates（categoryId=销售合同分类ID）
+```
+
+### 获取模板文件
+
+```
+用户: 我需要"2025年版销售合同模板"，发给我一下
+AI: 调用 list_contract_templates（keyword="2025年销售合同"）找到目标模板
+    → 调用 get_contract_template（templateId=模板ID）
+    → 返回模板详情 + currentFileUrl 文件下载地址
+```
+
+### 创建模板（含文件上传）
+
+```
+用户: 在"2025版"分类下创建"新版销售合同模板"，文件是xxx.docx
+AI: ① 先调用文件上传接口 /resource/nas-center/upload 上传文件，获取 fileId
+    → ② 调用 create_contract_template（categoryId, templateName, fileId, fileName, fileSize）
+    → 模板创建成功（v1.0 草稿状态）
+```
+
+## 数据来源标记
+
+所有通过 MCP Server 创建的分类和模板，数据库 `data_source` 字段会自动标记为 `MCP_SERVER`，
+可通过 `model_name` 字段追溯由哪个 AI 模型创建。
+
+## 文件上传说明
+
+创建模板需要先上传文件获取 `fileId`。文件可通过以下方式上传：
+- **NAS 上传**：`POST /resource/nas-center/upload`（multipart/form-data）
+- **OSS 上传**：`POST /resource/oss/upload`（multipart/form-data）
+
+上传成功后返回的 `fileId`（或 `attachmentId`）即为创建模板时需要的参数。
+
+## 技术架构
+
+```
+┌─────────────────────┐     stdio(MCP协议)     ┌─────────────────────┐
+│  CodeBuddy/智能体    │ ◄──────────────────► │  MCP Server (Node)  │
+└─────────────────────┘                        └──────────┬──────────┘
+                                                          │ HTTP + CrmMcpAccessKey
+                                                          ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  CRM Backend (Spring Boot)                                          │
+│  ├── McpContractTemplateCategoryController  /mcp/contract/category  │
+│  └── McpContractTemplateController          /mcp/contract/template  │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "contract-template-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP Server - CRM合同模版库管理，支持合同模版分类管理、合同模版管理、合同模版版本管理",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "contract-template-mcp-server": "src/index.js"
+  },
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "contract-template",
+    "crm",
+    "codebuddy",
+    "workbuddy"
+  ],
+  "license": "MIT"
+}

package/src/client.js

@@ -0,0 +1,280 @@
+/**
+ * HTTP 客户端 - 与后端 CRM 合同模版库管理服务通信
+ *
+ * 后端服务 API：
+ *   GET  /mcp/contract/category/list?keyword=  - 查询分类平铺列表
+ *   POST /mcp/contract/category/create          - 创建分类
+ *   GET  /mcp/contract/template/list?categoryId=&keyword= - 查询模板列表
+ *   GET  /mcp/contract/template/detail?id=       - 查询模板详情（含文件URL）
+ *   POST /mcp/contract/template/create           - 创建模板
+ *
+ * 认证方式：
+ *   通过环境变量 CRM_MCP_ACCESS_KEY 传递 access-key，
+ *   登录后端管理系统获取 key 后配置到 MCP Server 中。
+ */
+
+const DEFAULT_BASE_URL = "http://localhost:3000";
+
+/**
+ * 从环境变量获取后端服务地址
+ */
+function getBaseUrl() {
+  return process.env.CONTRACT_TEMPLATE_API_BASE_URL || DEFAULT_BASE_URL;
+}
+
+/**
+ * 从环境变量获取认证 token
+ */
+export function getAccessToken() {
+  return process.env.CRM_MCP_ACCESS_KEY || null;
+}
+
+/**
+ * 检查是否已配置认证 token
+ */
+export function hasAuth() {
+  return !!getAccessToken();
+}
+
+/**
+ * 通用 HTTP 请求封装（自动附带认证 token）
+ * @param {string} path    - API 路径
+ * @param {Object} options - fetch 选项
+ * @returns {Promise<Object>} 后端返回结果
+ */
+async function request(path, options = {}) {
+  const baseUrl = getBaseUrl();
+  const url = `${baseUrl}${path}`;
+  const token = getAccessToken();
+
+  const headers = {
+    "Content-Type": "application/json",
+    ...options.headers,
+  };
+
+  // 如果配置了 token，自动添加 CrmMcpAccessKey 头
+  if (token) {
+    headers["CrmMcpAccessKey"] = token;
+  }
+
+  const fetchOptions = {
+    ...options,
+    headers,
+  };
+
+  const response = await fetch(url, fetchOptions);
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    let errorMsg = `HTTP ${response.status}: ${errorText || response.statusText}`;
+
+    // 401 给出更友好的提示
+    if (response.status === 401) {
+      errorMsg = "认证失败：access-token 无效或已过期，请重新登录管理系统获取新的 token。";
+    } else if (response.status === 403) {
+      errorMsg = "权限不足：当前用户没有操作权限。";
+    }
+
+    throw new Error(errorMsg);
+  }
+
+  return response.json();
+}
+
+// ============================================================
+// 分类 API
+// ============================================================
+
+/**
+ * 查询合同模板分类列表
+ * @param {Object} params
+ * @param {string} [params.keyword] - 关键词搜索（可选，模糊匹配分类名称）
+ * @returns {Promise<Object>} 后端返回结果（data 为分类列表数组）
+ */
+export async function listCategories({ keyword } = {}) {
+  const params = new URLSearchParams();
+  if (keyword) params.append("keyword", keyword);
+
+  const queryStr = params.toString();
+  const path = queryStr
+    ? `/mcp/contract/category/list?${queryStr}`
+    : "/mcp/contract/category/list";
+  return request(path, { method: "GET" });
+}
+
+/**
+ * 创建合同模板分类
+ * @param {Object} params
+ * @param {string} params.categoryName - 分类名称（必填）
+ * @param {string} [params.parentId]    - 父分类ID（可选，默认0=顶级分类）
+ * @param {number} [params.sortOrder]   - 排序号（可选，默认0，越小越靠前）
+ * @param {string} [params.modelName]   - AI模型名称（可选）
+ * @returns {Promise<Object>} 后端返回结果（data 为新创建的分类对象）
+ */
+export async function createCategory({ categoryName, parentId, sortOrder, modelName }) {
+  const body = { categoryName };
+  if (parentId) body.parentId = parentId;
+  if (sortOrder !== undefined && sortOrder !== null) body.sortOrder = sortOrder;
+  if (modelName) body.modelName = modelName;
+
+  return request("/mcp/contract/category/create", {
+    method: "POST",
+    body: JSON.stringify(body),
+  });
+}
+
+// ============================================================
+// 模板 API
+// ============================================================
+
+/**
+ * 查询合同模板列表
+ * @param {Object} params
+ * @param {string} [params.categoryId] - 分类ID（可选，筛选指定分类下的模板）
+ * @param {string} [params.keyword]    - 关键词（可选，模糊匹配模板名称）
+ * @returns {Promise<Object>} 后端返回结果（data 为模板列表数组）
+ */
+export async function listTemplates({ categoryId, keyword } = {}) {
+  const params = new URLSearchParams();
+  if (categoryId) params.append("categoryId", categoryId);
+  if (keyword) params.append("keyword", keyword);
+
+  const queryStr = params.toString();
+  const path = queryStr
+    ? `/mcp/contract/template/list?${queryStr}`
+    : "/mcp/contract/template/list";
+  return request(path, { method: "GET" });
+}
+
+/**
+ * 查询合同模板详情（含文件下载URL）
+ * @param {string} id - 模板ID（字符串类型，避免精度丢失）
+ * @returns {Promise<Object>} 后端返回结果（data 为模板详情对象，含 currentFileUrl）
+ */
+export async function getTemplateDetail(id) {
+  return request(`/mcp/contract/template/detail?id=${encodeURIComponent(id)}`, {
+    method: "GET",
+  });
+}
+
+/**
+ * 创建合同模板（在指定分类下）
+ * @param {Object} params
+ * @param {string} params.templateName - 模板名称（必填）
+ * @param {string} params.categoryId   - 分类ID（必填，String类型避免精度丢失）
+ * @param {string} params.fileId       - 文件ID（必填，由文件上传接口返回）
+ * @param {string} params.fileName     - 文件名（必填）
+ * @param {number} [params.fileSize]   - 文件大小（字节，可选）
+ * @param {string} [params.description] - 模板描述（可选）
+ * @param {string} [params.modelName]  - AI模型名称（可选）
+ * @returns {Promise<Object>} 后端返回结果（data 为新创建的模板对象）
+ */
+export async function createTemplate({
+  templateName,
+  categoryId,
+  fileId,
+  fileName,
+  fileSize,
+  description,
+  modelName,
+}) {
+  const body = { templateName, categoryId, fileId, fileName };
+  if (fileSize !== undefined && fileSize !== null) body.fileSize = fileSize;
+  if (description) body.description = description;
+  if (modelName) body.modelName = modelName;
+
+  return request("/mcp/contract/template/create", {
+    method: "POST",
+    body: JSON.stringify(body),
+  });
+}
+
+/**
+ * 上传文件并一步创建合同模板（推荐 MCP 智能体使用）
+ *
+ * 将用户选中的合同文件上传到指定分类下，内部自动完成：
+ * 1. 文件上传到 NAS/OSS，获取 fileId
+ * 2. 在指定分类下创建合同模板记录
+ * 3. 创建初始版本 v1.0
+ *
+ * @param {Object} params
+ * @param {Buffer|ArrayBuffer|Uint8Array} params.fileData - 文件的二进制内容（必填）
+ * @param {string} params.fileName      - 原始文件名，如 "销售合同模板.docx"（必填）
+ * @param {string} params.categoryId    - 目标分类ID（必填）
+ * @param {string} [params.templateName] - 模板名称（可选，不传则使用文件名）
+ * @param {string} [params.description]  - 模板描述（可选）
+ * @param {string} [params.modelName]    - AI模型名称（可选）
+ * @returns {Promise<Object>} 后端返回结果（data 为新创建的模板对象）
+ */
+export async function uploadAndCreateTemplate({
+  fileData,
+  fileName,
+  categoryId,
+  templateName,
+  description,
+  modelName,
+}) {
+  const baseUrl = getBaseUrl();
+  const url = `${baseUrl}/mcp/contract/template/upload-and-create`;
+  const token = getAccessToken();
+
+  // 构建 FormData
+  const formData = new FormData();
+  // 将二进制数据转为 Blob 再附加到 FormData
+  const blob = new Blob([fileData], { type: getMimeType(fileName) });
+  formData.append("file", blob, fileName);
+  formData.append("categoryId", categoryId);
+  if (templateName) formData.append("templateName", templateName);
+  if (description) formData.append("description", description);
+  if (modelName) formData.append("modelName", modelName);
+
+  const headers = {};
+  if (token) {
+    headers["CrmMcpAccessKey"] = token;
+  }
+  // 注意：不要手动设置 Content-Type，让浏览器/运行时自动设置 boundary
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers,
+    body: formData,
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    let errorMsg = `HTTP ${response.status}: ${errorText || response.statusText}`;
+    if (response.status === 401) {
+      errorMsg = "认证失败：access-token 无效或已过期，请重新登录管理系统获取新的 token。";
+    } else if (response.status === 403) {
+      errorMsg = "权限不足：当前用户没有操作权限。";
+    }
+    throw new Error(errorMsg);
+  }
+
+  return response.json();
+}
+
+/**
+ * 根据文件扩展名推断 MIME 类型
+ * @param {string} fileName 文件名
+ * @returns {string} MIME 类型
+ */
+function getMimeType(fileName) {
+  if (!fileName) return "application/octet-stream";
+  const ext = fileName.split(".").pop()?.toLowerCase();
+  const mimeMap = {
+    doc: "application/msword",
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    pdf: "application/pdf",
+    xls: "application/vnd.ms-excel",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    txt: "text/plain",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    zip: "application/zip",
+    rar: "application/x-rar-compressed",
+  };
+  return mimeMap[ext] || "application/octet-stream";
+}

package/src/index.js

@@ -0,0 +1,554 @@
+#!/usr/bin/env node
+
+/**
+ * MCP Server 入口 - CRM 合同模版库管理
+ *
+ * 提供六个工具：
+ *  1. list_contract_categories           - 查询合同模板分类列表
+ *  2. create_contract_category           - 创建新的合同模板分类
+ *  3. list_contract_templates            - 查询合同模板列表
+ *  4. get_contract_template              - 获取合同模板详情及文件下载URL
+ *  5. create_contract_template           - 在分类下创建合同模板（需预传fileId）
+ *  6. upload_file_to_template_category   - 上传文件并一步创建模板（推荐MCP使用）
+ *
+ * 使用方式（在 CodeBuddy/WorkBuddy 的 MCP 配置中）：
+ *  {
+ *    "mcpServers": {
+ *      "contract-template": {
+ *        "command": "contract-template-mcp-server",
+ *        "env": {
+ *          "CONTRACT_TEMPLATE_API_BASE_URL": "http://your-backend-service:port",
+ *          "CRM_MCP_ACCESS_KEY": "从管理系统获取的access-key"
+ *        }
+ *      }
+ *    }
+ *  }
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import {
+  listCategories,
+  createCategory,
+  listTemplates,
+  getTemplateDetail,
+  createTemplate,
+  uploadAndCreateTemplate,
+  hasAuth,
+} from "./client.js";
+
+// 创建 MCP Server 实例
+const server = new McpServer({
+  name: "contract-template-mcp-server",
+  version: "1.0.0",
+});
+
+// ============================================================
+// 工具 1：查询合同模板分类列表
+// ============================================================
+server.tool(
+  "list_contract_categories",
+  "查询合同模板的分类列表。返回系统中所有的合同模板分类（平铺列表形式），支持按分类名称关键词模糊搜索。可用于回答"目前有哪些合同模板分类？""帮我列一下分类"等问题。",
+  {
+    keyword: z
+      .string()
+      .optional()
+      .describe("可选，按分类名称模糊搜索，如"劳动合同"可匹配到"劳动合同模板分类""),
+  },
+  async ({ keyword }) => {
+    try {
+      const result = await listCategories({ keyword });
+      const categoryList = Array.isArray(result.data)
+        ? result.data
+        : Array.isArray(result)
+          ? result
+          : [];
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                success: true,
+                count: categoryList.length,
+                categories: categoryList.map((item) => ({
+                  id: String(item.id),
+                  parentId: item.parentId != null ? String(item.parentId) : "0",
+                  categoryName: item.categoryName,
+                  sortOrder: item.sortOrder,
+                  status: item.status,
+                  createTime: item.createTime,
+                  createBy: item.createBy,
+                })),
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                success: false,
+                message: `查询合同模板分类失败: ${error.message}`,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+  }
+);
+
+// ============================================================
+// 工具 2：创建合同模板分类
+// ============================================================
+server.tool(
+  "create_contract_category",
+  "创建一个新的合同模板分类。可在指定父分类下创建子分类，不指定父分类则创建为顶级分类。创建成功返回新分类的完整信息（含ID）。",
+  {
+    categoryName: z
+      .string()
+      .min(1)
+      .describe("分类名称，如"销售合同"、"采购合同"、"劳动合同"等"),
+    parentId: z
+      .string()
+      .optional()
+      .describe("父分类ID（可选），不传则创建为顶级分类。可从 list_contract_categories 结果中获取"),
+    sortOrder: z
+      .number()
+      .int()
+      .optional()
+      .describe("排序号（可选），数字越小越靠前，默认0"),
+    modelName: z
+      .string()
+      .optional()
+      .describe("创建该分类的AI模型名称（可选），用于追溯数据来源"),
+  },
+  async ({ categoryName, parentId, sortOrder, modelName }) => {
+    try {
+      const result = await createCategory({ categoryName, parentId, sortOrder, modelName });
+      const newCategory = result.data || result;
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                success: true,
+                message: `合同模板分类「${categoryName}」创建成功`,
+                data: newCategory
+                  ? {
+                      id: newCategory.id ? String(newCategory.id) : undefined,
+                      categoryName: newCategory.categoryName,
+                      parentId: newCategory.parentId,
+                      sortOrder: newCategory.sortOrder,
+                    }
+                  : undefined,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                success: false,
+                message: `创建合同模板分类失败: ${error.message}`,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+  }
+);
+
+// ============================================================
+// 工具 3：查询合同模板列表
+// ============================================================
+server.tool(
+  "list_contract_templates",
+  "查询合同模板列表。支持按分类ID筛选指定分类下的模板，支持按模板名称关键词模糊搜索。返回模板基本信息及当前生效版本的文件名、版本号等。可用于回答"目前有哪些合同模板？""销售合同分类下有哪些模板？"等问题。",
+  {
+    categoryId: z
+      .string()
+      .optional()
+      .describe("分类ID（可选），筛选指定分类下的模板。可从 list_contract_categories 结果中获取"),
+    keyword: z
+      .string()
+      .optional()
+      .describe("可选，按模板名称模糊搜索，如"销售"可匹配所有名称包含"销售"的模板"),
+  },
+  async ({ categoryId, keyword }) => {
+    try {
+      const result = await listTemplates({ categoryId, keyword });
+      const templateList = Array.isArray(result.data)
+        ? result.data
+        : Array.isArray(result)
+          ? result
+          : [];
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                success: true,
+                count: templateList.length,
+                templates: templateList.map((item) => ({
+                  id: String(item.id),
+                  categoryId: item.categoryId != null ? String(item.categoryId) : "",
+                  categoryName: item.categoryName,
+                  templateName: item.templateName,
+                  description: item.description,
+                  status: item.status,
+                  currentVersionNo: item.currentVersionNo,
+                  currentFileName: item.currentFileName,
+                  currentFileSize: item.currentFileSize,
+                  createTime: item.createTime,
+                  createBy: item.createBy,
+                })),
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                success: false,
+                message: `查询合同模板列表失败: ${error.message}`,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+  }
+);
+
+// ============================================================
+// 工具 4：获取合同模板详情及文件下载URL
+// ============================================================
+server.tool(
+  "get_contract_template",
+  "获取指定合同模板的详细信息，包含当前生效版本的文件下载URL。可用于回答"我需要xxx模版，发给我一下""帮我下载xxx合同模板"等问题。返回的 currentFileUrl 即为可下载的文件地址。",
+  {
+    templateId: z
+      .string()
+      .describe("合同模板的唯一标识ID，可从 list_contract_templates 返回结果中获取"),
+  },
+  async ({ templateId }) => {
+    try {
+      const result = await getTemplateDetail(templateId);
+      const templateInfo = result.data || result;
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                success: true,
+                template: templateInfo
+                  ? {
+                      id: templateInfo.id ? String(templateInfo.id) : templateId,
+                      categoryId: templateInfo.categoryId != null ? String(templateInfo.categoryId) : "",
+                      categoryName: templateInfo.categoryName,
+                      templateName: templateInfo.templateName,
+                      description: templateInfo.description,
+                      status: templateInfo.status,
+                      currentVersionNo: templateInfo.currentVersionNo,
+                      currentVersionId: templateInfo.currentVersionId != null ? String(templateInfo.currentVersionId) : "",
+                      currentFileName: templateInfo.currentFileName,
+                      currentFileSize: templateInfo.currentFileSize,
+                      currentFileUrl: templateInfo.currentFileUrl,
+                      createTime: templateInfo.createTime,
+                      createBy: templateInfo.createBy,
+                      updateTime: templateInfo.updateTime,
+                    }
+                  : null,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                success: false,
+                message: `获取合同模板详情失败: ${error.message}`,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+  }
+);
+
+// ============================================================
+// 工具 5：创建合同模板
+// ============================================================
+server.tool(
+  "create_contract_template",
+  "在指定分类下创建一个新的合同模板（含初始版本 v1.0）。需要先通过文件上传接口上传合同文件获取 fileId，然后将 fileId 传入此工具完成模板创建。创建成功后模板状态为"草稿"。",
+  {
+    templateName: z
+      .string()
+      .min(1)
+      .describe("模板名称，如"2025年版销售合同模板""),
+    categoryId: z
+      .string()
+      .describe("分类ID，模板所属的分类。可从 list_contract_categories 结果中获取"),
+    fileId: z
+      .string()
+      .describe("文件ID，由文件上传接口（如 /resource/nas-center/upload）返回。先上传合同文件后获得"),
+    fileName: z
+      .string()
+      .min(1)
+      .describe("上传的合同文件名，如"销售合同模板.docx""),
+    fileSize: z
+      .number()
+      .int()
+      .optional()
+      .describe("文件大小（字节），如 204800 表示200KB"),
+    description: z
+      .string()
+      .optional()
+      .describe("模板描述，说明该模板的用途、适用场景等"),
+    modelName: z
+      .string()
+      .optional()
+      .describe("创建该模板的AI模型名称（可选），用于追溯数据来源"),
+  },
+  async ({ templateName, categoryId, fileId, fileName, fileSize, description, modelName }) => {
+    try {
+      const result = await createTemplate({
+        templateName,
+        categoryId,
+        fileId,
+        fileName,
+        fileSize,
+        description,
+        modelName,
+      });
+      const newTemplate = result.data || result;
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                success: true,
+                message: `合同模板「${templateName}」创建成功（v1.0 草稿状态）`,
+                data: newTemplate
+                  ? {
+                      id: newTemplate.id ? String(newTemplate.id) : undefined,
+                      templateName: newTemplate.templateName,
+                      categoryId: newTemplate.categoryId != null ? String(newTemplate.categoryId) : categoryId,
+                      status: newTemplate.status,
+                    }
+                  : undefined,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                success: false,
+                message: `创建合同模板失败: ${error.message}`,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+  }
+);
+
+// ============================================================
+// 工具 6：上传文件并创建合同模板（一步完成）
+// ============================================================
+server.tool(
+  "upload_file_to_template_category",
+  [
+    "将用户选中的合同文件上传到指定模板分类下，一步完成文件上传+模板创建+版本初始化。",
+    "适用于 WorkBuddy 等智能体客户端中「选择文件 → 指定分类」的典型场景。",
+    "内部流程：1) 上传文件到 NAS/OSS 获取 fileId  2) 在指定分类下创建模板记录  3) 创建初始版本 v1.0",
+    "创建成功后返回新模板的完整信息（ID、名称、分类、状态等）。",
+    "使用示例：用户说"帮我把这个文件上传到销售合同分类下"，智能体调用此工具即可一步完成。",
+  ].join("\n"),
+  {
+    fileContent: z
+      .string()
+      .describe(
+        "文件的 Base64 编码内容（必填）。用户选择或拖拽的文件经 Base64 编码后的字符串。" +
+          '例如从 MCP 客户端获取到的附件内容。如果是大文件，确保使用完整的 Base64 字符串。'
+      ),
+    fileName: z
+      .string()
+      .min(1)
+      .describe(
+        "原始文件名（必填），如 \"关于长春市国资国企在线监管平台上线方案_20260506_v0.1.doc\""
+      ),
+    categoryId: z
+      .string()
+      .describe(
+        "目标分类ID（必填）。可先通过 list_contract_categories 查询获取，或使用分类名称让智能体匹配"
+      ),
+    categoryName: z
+      .string()
+      .optional()
+      .describe("目标分类名称（可选，用于日志记录和结果展示）"),
+    templateName: z
+      .string()
+      .optional()
+      .describe("模板名称（可选，不传则使用原始文件名作为模板名）"),
+    description: z
+      .string()
+      .optional()
+      .describe("模板描述（可选），说明该模板的用途和适用场景"),
+    modelName: z
+      .string()
+      .optional()
+      .describe("创建该模板的AI模型名称（可选），用于追溯数据来源"),
+  },
+  async ({
+    fileContent,
+    fileName,
+    categoryId,
+    categoryName,
+    templateName,
+    description,
+    modelName,
+  }) => {
+    try {
+      // 将 Base64 解码为 Buffer
+      const fileData = Buffer.from(fileContent, "base64");
+
+      const result = await uploadAndCreateTemplate({
+        fileData,
+        fileName,
+        categoryId,
+        templateName,
+        description,
+        modelName,
+      });
+      const newTemplate = result.data || result;
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                success: true,
+                message: `文件「${fileName}」已成功上传到${categoryName || categoryId}分类下，模板创建完成（v1.0 草稿状态）`,
+                data: newTemplate
+                  ? {
+                      id: newTemplate.id ? String(newTemplate.id) : undefined,
+                      templateName: newTemplate.templateName,
+                      categoryId:
+                        newTemplate.categoryId != null
+                          ? String(newTemplate.categoryId)
+                          : categoryId,
+                      status: newTemplate.status,
+                    }
+                  : undefined,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                success: false,
+                message: `上传文件并创建模板失败: ${error.message}`,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+  }
+);
+
+// ============================================================
+// 启动 MCP Server（使用 stdio 传输）
+// ============================================================
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  // 输出到 stderr（stdio 模式下 stdout 用于 MCP 协议通信）
+  console.error("✅ CRM 合同模版库管理 MCP Server 已启动");
+  console.error(`   API 地址: ${process.env.CONTRACT_TEMPLATE_API_BASE_URL || "http://localhost:3000"}`);
+  if (hasAuth()) {
+    console.error("   认证状态: ✅ 已配置 CRM_MCP_ACCESS_KEY");
+  } else {
+    console.error("   认证状态: ⚠️  未配置 CRM_MCP_ACCESS_KEY，请求可能被后端拒绝");
+  }
+  console.error("   提供工具: list_contract_categories, create_contract_category, list_contract_templates, get_contract_template, create_contract_template, upload_file_to_template_category");
+}
+
+main().catch((error) => {
+  console.error("❌ MCP Server 启动失败:", error);
+  process.exit(1);
+});