contract-template-mcp-server 1.0.0 → 1.1.0

package/README.md

@@ -11,6 +11,7 @@ CRM 合同模版库管理 MCP Server，为智能体（如 CodeBuddy/WorkBuddy）
 | `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` |
+| `upload_file_to_template_category` | 上传文件并一步创建模板（推荐） | `POST /mcp/contract/template/upload-and-create` |
 
 ## 安装与配置
 
@@ -88,6 +89,18 @@ AI: ① 先调用文件上传接口 /resource/nas-center/upload 上传文件，
     → 模板创建成功（v1.0 草稿状态）
 ```
 
+### 上传文件一步创建模板（推荐）
+
+```
+用户: 帮我把这个文件上传到销售合同分类下
+AI: 调用 upload_file_to_template_category（filePath="/path/to/file.docx", categoryId=销售合同分类ID）
+    → 内部自动完成：文件读取 + 上传 NAS/OSS + 模板创建 + 版本初始化
+    → 模板创建成功（v1.0 草稿状态）
+```
+
+> **性能说明**：MCP Server 与 WorkBuddy 同机运行，`upload_file_to_template_category` 直接通过 `filePath` 
+> 读取本地文件，无需客户端做 base64 编码，大文件上传速度大幅提升。
+
 ## 数据来源标记
 
 所有通过 MCP Server 创建的分类和模板，数据库 `data_source` 字段会自动标记为 `MCP_SERVER`，
@@ -95,11 +108,18 @@ AI: ① 先调用文件上传接口 /resource/nas-center/upload 上传文件，
 
 ## 文件上传说明
 
-创建模板需要先上传文件获取 `fileId`。文件可通过以下方式上传：
-- **NAS 上传**：`POST /resource/nas-center/upload`（multipart/form-data）
-- **OSS 上传**：`POST /resource/oss/upload`（multipart/form-data）
+### 方式一：`upload_file_to_template_category`（推荐）
+
+直接传文件本地路径，MCP Server 自动完成文件读取、上传和模板创建：
+- 参数 `filePath`：本地文件的绝对路径
+- 参数 `fileName`：可选，不传则从路径自动提取
+
+### 方式二：手动分步上传
 
-上传成功后返回的 `fileId`（或 `attachmentId`）即为创建模板时需要的参数。
+1. 先上传文件获取 `fileId`：
+   - **NAS 上传**：`POST /resource/nas-center/upload`（multipart/form-data）
+   - **OSS 上传**：`POST /resource/oss/upload`（multipart/form-data）
+2. 使用 `create_contract_template` 传入 `fileId` 创建模板
 
 ## 技术架构
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contract-template-mcp-server",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "MCP Server - CRM合同模版库管理，支持合同模版分类管理、合同模版管理、合同模版版本管理",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -28,6 +28,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+import fs from "fs";
 import {
   listCategories,
   createCategory,
@@ -41,7 +42,7 @@ import {
 // 创建 MCP Server 实例
 const server = new McpServer({
   name: "contract-template-mcp-server",
-  version: "1.0.0",
+  version: "1.1.0",
 });
 
 // ============================================================
@@ -49,12 +50,12 @@ const server = new McpServer({
 // ============================================================
 server.tool(
   "list_contract_categories",
-  "查询合同模板的分类列表。返回系统中所有的合同模板分类（平铺列表形式），支持按分类名称关键词模糊搜索。可用于回答"目前有哪些合同模板分类？""帮我列一下分类"等问题。",
+  "查询合同模板的分类列表。返回系统中所有的合同模板分类（平铺列表形式），支持按分类名称关键词模糊搜索。可用于回答\u201C目前有哪些合同模板分类？\u201D\u201C帮我列一下分类\u201D等问题。",
   {
     keyword: z
       .string()
       .optional()
-      .describe("可选，按分类名称模糊搜索，如"劳动合同"可匹配到"劳动合同模板分类""),
+      .describe("可选，按分类名称模糊搜索，如\u201C劳动合同\u201D可匹配到\u201C劳动合同模板分类\u201D"),
   },
   async ({ keyword }) => {
     try {
@@ -119,7 +120,7 @@ server.tool(
     categoryName: z
       .string()
       .min(1)
-      .describe("分类名称，如"销售合同"、"采购合同"、"劳动合同"等"),
+      .describe("分类名称，如\u201C销售合同\u201D、\u201C采购合同\u201D、\u201C劳动合同\u201D等"),
     parentId: z
       .string()
       .optional()
@@ -187,7 +188,7 @@ server.tool(
 // ============================================================
 server.tool(
   "list_contract_templates",
-  "查询合同模板列表。支持按分类ID筛选指定分类下的模板，支持按模板名称关键词模糊搜索。返回模板基本信息及当前生效版本的文件名、版本号等。可用于回答"目前有哪些合同模板？""销售合同分类下有哪些模板？"等问题。",
+  "查询合同模板列表。支持按分类ID筛选指定分类下的模板，支持按模板名称关键词模糊搜索。返回模板基本信息及当前生效版本的文件名、版本号等。可用于回答\u201C目前有哪些合同模板？\u201D\u201C销售合同分类下有哪些模板？\u201D等问题。",
   {
     categoryId: z
       .string()
@@ -196,7 +197,7 @@ server.tool(
     keyword: z
       .string()
       .optional()
-      .describe("可选，按模板名称模糊搜索，如"销售"可匹配所有名称包含"销售"的模板"),
+      .describe("可选，按模板名称模糊搜索，如\u201C销售\u201D可匹配所有名称包含\u201C销售\u201D的模板"),
   },
   async ({ categoryId, keyword }) => {
     try {
@@ -260,7 +261,7 @@ server.tool(
 // ============================================================
 server.tool(
   "get_contract_template",
-  "获取指定合同模板的详细信息，包含当前生效版本的文件下载URL。可用于回答"我需要xxx模版，发给我一下""帮我下载xxx合同模板"等问题。返回的 currentFileUrl 即为可下载的文件地址。",
+  "获取指定合同模板的详细信息，包含当前生效版本的文件下载URL。可用于回答\u201C我需要xxx模版，发给我一下\u201D\u201C帮我下载xxx合同模板\u201D等问题。返回的 currentFileUrl 即为可下载的文件地址。",
   {
     templateId: z
       .string()
@@ -328,12 +329,12 @@ server.tool(
 // ============================================================
 server.tool(
   "create_contract_template",
-  "在指定分类下创建一个新的合同模板（含初始版本 v1.0）。需要先通过文件上传接口上传合同文件获取 fileId，然后将 fileId 传入此工具完成模板创建。创建成功后模板状态为"草稿"。",
+  "在指定分类下创建一个新的合同模板（含初始版本 v1.0）。需要先通过文件上传接口上传合同文件获取 fileId，然后将 fileId 传入此工具完成模板创建。创建成功后模板状态为\u201C草稿\u201D。",
   {
     templateName: z
       .string()
       .min(1)
-      .describe("模板名称，如"2025年版销售合同模板""),
+      .describe("模板名称，如\u201C2025年版销售合同模板\u201D"),
     categoryId: z
       .string()
       .describe("分类ID，模板所属的分类。可从 list_contract_categories 结果中获取"),
@@ -343,7 +344,7 @@ server.tool(
     fileName: z
       .string()
       .min(1)
-      .describe("上传的合同文件名，如"销售合同模板.docx""),
+      .describe("上传的合同文件名，如\u201C销售合同模板.docx\u201D"),
     fileSize: z
       .number()
       .int()
@@ -424,20 +425,21 @@ server.tool(
     "适用于 WorkBuddy 等智能体客户端中「选择文件 → 指定分类」的典型场景。",
     "内部流程：1) 上传文件到 NAS/OSS 获取 fileId  2) 在指定分类下创建模板记录  3) 创建初始版本 v1.0",
     "创建成功后返回新模板的完整信息（ID、名称、分类、状态等）。",
-    "使用示例：用户说"帮我把这个文件上传到销售合同分类下"，智能体调用此工具即可一步完成。",
+    "使用示例：用户说\u201C帮我把这个文件上传到销售合同分类下\u201D，智能体调用此工具即可一步完成。",
   ].join("\n"),
   {
-    fileContent: z
+    filePath: z
       .string()
       .describe(
-        "文件的 Base64 编码内容（必填）。用户选择或拖拽的文件经 Base64 编码后的字符串。" +
-          '例如从 MCP 客户端获取到的附件内容。如果是大文件，确保使用完整的 Base64 字符串。'
+        "文件的本地绝对路径（必填）。由于 MCP Server 与 WorkBuddy 运行在同一台机器上，" +
+          "直接传文件路径即可，服务端会自动读取文件内容，无需客户端做 base64 编码。" +
+          "例如：\"/Users/user/Desktop/销售合同模板.docx\""
       ),
     fileName: z
       .string()
-      .min(1)
+      .optional()
       .describe(
-        "原始文件名（必填），如 \"关于长春市国资国企在线监管平台上线方案_20260506_v0.1.doc\""
+        "文件名（可选）。不传则从 filePath 中自动提取文件名"
       ),
     categoryId: z
       .string()
@@ -462,7 +464,7 @@ server.tool(
       .describe("创建该模板的AI模型名称（可选），用于追溯数据来源"),
   },
   async ({
-    fileContent,
+    filePath,
     fileName,
     categoryId,
     categoryName,
@@ -471,12 +473,13 @@ server.tool(
     modelName,
   }) => {
     try {
-      // 将 Base64 解码为 Buffer
-      const fileData = Buffer.from(fileContent, "base64");
+      // 直接读取本地文件（MCP Server 与 WorkBuddy 同机运行，无需 base64 编码）
+      const actualFileName = fileName || filePath.split("/").pop() || "unknown";
+      const fileData = fs.readFileSync(filePath);
 
       const result = await uploadAndCreateTemplate({
         fileData,
-        fileName,
+        fileName: actualFileName,
         categoryId,
         templateName,
         description,
@@ -491,7 +494,7 @@ server.tool(
             text: JSON.stringify(
               {
                 success: true,
-                message: `文件「${fileName}」已成功上传到${categoryName || categoryId}分类下，模板创建完成（v1.0 草稿状态）`,
+                message: `文件「${actualFileName}」已成功上传到${categoryName || categoryId}分类下，模板创建完成（v1.0 草稿状态）`,
                 data: newTemplate
                   ? {
                       id: newTemplate.id ? String(newTemplate.id) : undefined,
@@ -511,6 +514,11 @@ server.tool(
         ],
       };
     } catch (error) {
+      let errorMessage = error.message;
+      // 提供更友好的文件不存在错误提示
+      if (error.code === "ENOENT") {
+        errorMessage = `文件不存在或无法访问: ${filePath}`;
+      }
       return {
         content: [
           {
@@ -518,7 +526,7 @@ server.tool(
             text: JSON.stringify(
               {
                 success: false,
-                message: `上传文件并创建模板失败: ${error.message}`,
+                message: `上传文件并创建模板失败: ${errorMessage}`,
               },
               null,
               2