@code2rich/jpage 1.5.0

package/mcp/constants.js

@@ -0,0 +1,16 @@
+// MCP 模块共享常量。从 mcp-server.js 提取，行为保持不变。
+
+// 资源（jpage://file/{id}）返回正文的大小上限：超过则提示改用 get_file_content 工具。
+const RESOURCE_MAX_BYTES = 256 * 1024;
+
+// upload_file 工具允许的文件扩展名（含 ZIP）。
+const ALLOWED_EXTS = ['.html', '.htm', '.md', '.markdown', '.zip'];
+
+// 上传单文件大小上限（与 routes/files 上传限制一致）。
+const MAX_FILE_SIZE = 50 * 1024 * 1024;
+
+module.exports = {
+  RESOURCE_MAX_BYTES,
+  ALLOWED_EXTS,
+  MAX_FILE_SIZE,
+};

package/mcp/resources.js

@@ -0,0 +1,74 @@
+// MCP 资源：jpage://files（全部文件元数据）/ jpage://file/{id}（单文件内容）。
+// 从 mcp-server.js 提取，行为保持不变。
+
+const { ResourceTemplate } = require('@modelcontextprotocol/sdk/server/mcp.js');
+const { RESOURCE_MAX_BYTES } = require('./constants');
+
+function registerResources(server, { api }) {
+  // --- jpage://files ---
+  server.registerResource(
+    'files',
+    'jpage://files',
+    {
+      title: 'All Files',
+      description: 'jpage 中所有文件的元数据列表（id, name, type, size, is_public, created_at）。适用于快速浏览文件概况，无需逐个查询。',
+      mimeType: 'application/json',
+    },
+    async () => {
+      const data = await api.get('/api/files');
+      return {
+        contents: [
+          {
+            uri: 'jpage://files',
+            mimeType: 'application/json',
+            text: JSON.stringify(data.files, null, 2),
+          },
+        ],
+      };
+    }
+  );
+
+  // --- jpage://file/{id} ---
+  server.registerResource(
+    'file',
+    new ResourceTemplate('jpage://file/{id}', { list: undefined }),
+    {
+      title: 'Single File Content',
+      description:
+        '单文件内容（资源）。仅当文件 ≤ 256KB 时返回正文；超过则返回提示，让模型改用 get_file_content 工具。适用于 AI 上下文注入或轻量内容查看。',
+      mimeType: 'text/plain',
+    },
+    async (uri, vars) => {
+      const id = Number(vars.id);
+      if (!Number.isInteger(id) || id <= 0) {
+        throw new Error(`Invalid file id: ${vars.id}`);
+      }
+      const data = await api.get(`/api/files/${id}/content`);
+      const size = Buffer.byteLength(data.content, 'utf-8');
+      if (size > RESOURCE_MAX_BYTES) {
+        return {
+          contents: [
+            {
+              uri: uri.href,
+              mimeType: 'text/plain',
+              text:
+                `文件过大 (${size} 字节 > ${RESOURCE_MAX_BYTES} 字节)，请改用 get_file_content 工具读取完整内容。`,
+            },
+          ],
+        };
+      }
+      const mimeType = data.file_type === 'markdown' ? 'text/markdown' : 'text/html';
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType,
+            text: data.content,
+          },
+        ],
+      };
+    }
+  );
+}
+
+module.exports = { registerResources };

package/mcp/server.js

@@ -0,0 +1,43 @@
+// MCP server 工厂：创建 McpServer 并注册全部 tools + resources。
+// 从 mcp-server.js 提取，行为保持不变。
+//
+// 注册顺序 = 原文件顺序（list/upload/content/delete/rename/url/versions/tags/star/
+// categories/resources/content-templates）。顺序对 MCP 协议无影响，仅为对照方便。
+
+const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
+const pkgVersion = require('../package.json').version;
+const { registerFileTools } = require('./tools-files');
+const { registerVersionTools } = require('./tools-versions');
+const { registerTagTools } = require('./tools-tags');
+const { registerCategoryTools } = require('./tools-categories');
+const { registerContentTemplateTools } = require('./tools-content-templates');
+const { registerResources } = require('./resources');
+
+/**
+ * 创建并配置 MCP server（注册 17 tools + 2 resources）。
+ * @param {object} opts
+ * @param {number} opts.port
+ * @param {object} opts.api - 进程内 dispatcher 客户端（{get,post,put,del}）
+ * @param {string} opts.mcpIp
+ * @param {string} opts.protocol
+ * @returns {McpServer}
+ */
+function createMcpServer({ port, api, mcpIp, protocol }) {
+  const server = new McpServer(
+    { name: 'jpage', version: pkgVersion },
+    { capabilities: {} }
+  );
+
+  const ctx = { api, port, mcpIp, protocol };
+
+  registerFileTools(server, ctx);
+  registerVersionTools(server, ctx);
+  registerTagTools(server, ctx);
+  registerCategoryTools(server, ctx);
+  registerResources(server, ctx);
+  registerContentTemplateTools(server, ctx);
+
+  return server;
+}
+
+module.exports = { createMcpServer };

package/mcp/tools-categories.js

@@ -0,0 +1,56 @@
+// MCP 分类类工具：list_categories / create_category / set_file_category。
+// 从 mcp-server.js 提取，行为保持不变。
+
+const { z } = require('zod');
+const { textResult } = require('./util');
+
+function registerCategoryTools(server, { api }) {
+  // --- list_categories ---
+  server.registerTool(
+    'list_categories',
+    {
+      title: 'List Categories',
+      description: '列出所有分类及其文件数量。',
+      inputSchema: {},
+    },
+    async () => {
+      const data = await api.get('/api/categories');
+      return textResult(data.categories);
+    }
+  );
+
+  // --- create_category ---
+  server.registerTool(
+    'create_category',
+    {
+      title: 'Create Category',
+      description: '创建一个新分类（文件夹）。',
+      inputSchema: {
+        name: z.string().min(1).describe('分类名称'),
+      },
+    },
+    async ({ name }) => {
+      const data = await api.post('/api/categories', { name });
+      return textResult(data);
+    }
+  );
+
+  // --- set_file_category ---
+  server.registerTool(
+    'set_file_category',
+    {
+      title: 'Set File Category',
+      description: '设置文件所属分类。传 null 或不传 categoryId 表示移除分类。',
+      inputSchema: {
+        fileId: z.number().int().positive().describe('文件 id'),
+        categoryId: z.number().int().positive().nullable().optional().describe('分类 id，null 表示移除分类'),
+      },
+    },
+    async ({ fileId, categoryId }) => {
+      await api.put(`/api/files/${fileId}/category`, { categoryId: categoryId ?? null });
+      return textResult({ fileId, categoryId: categoryId ?? null });
+    }
+  );
+}
+
+module.exports = { registerCategoryTools };

package/mcp/tools-content-templates.js

@@ -0,0 +1,59 @@
+// MCP 内容模板类工具：list_content_templates / get_content_template。
+// 从 mcp-server.js 提取，行为保持不变。
+
+const { z } = require('zod');
+const { textResult } = require('./util');
+
+function registerContentTemplateTools(server, { api }) {
+  // --- list_content_templates ---
+  server.registerTool(
+    'list_content_templates',
+    {
+      title: 'List Content Templates',
+      description: '列出内容模板市场的模板。返回模板元数据（不含完整内容），供 AI 选择合适的风格参考。支持按场景、文件类型、关键词筛选。',
+      inputSchema: {
+        scene: z.string().optional().describe('按使用场景筛选：dashboard, report, resume, landing, note, presentation, card, email, other'),
+        fileType: z.enum(['html', 'markdown']).optional().describe('按文件类型筛选'),
+        keyword: z.string().optional().describe('按标题或描述搜索'),
+        sort: z.enum(['use_count', 'created_at']).optional().describe('排序方式，默认 use_count（最热门优先）'),
+        limit: z.number().optional().describe('返回数量，默认 10，最大 20'),
+      },
+    },
+    async ({ scene, fileType, keyword, sort, limit }) => {
+      const params = new URLSearchParams();
+      if (scene) params.set('scene', scene);
+      if (fileType) params.set('fileType', fileType);
+      if (keyword) params.set('keyword', keyword);
+      if (sort) params.set('sort', sort);
+      if (limit) params.set('limit', String(Math.min(limit, 20)));
+      const qs = params.toString();
+      const data = await api.get('/api/content-templates' + (qs ? '?' + qs : ''));
+      return textResult(data.templates);
+    }
+  );
+
+  // --- get_content_template ---
+  server.registerTool(
+    'get_content_template',
+    {
+      title: 'Get Content Template',
+      description: '获取指定内容模板的完整样例内容。AI 拿到样例后，应学习其风格、布局和结构，生成风格一致但内容全新的作品。',
+      inputSchema: {
+        id: z.number().int().positive().describe('模板 ID（list_content_templates 返回的 id）'),
+      },
+    },
+    async ({ id }) => {
+      const data = await api.get(`/api/content-templates/${id}/content`);
+      await api.post(`/api/content-templates/${id}/use`).catch(() => {});
+      return textResult({
+        id: data.id,
+        title: data.title,
+        file_type: data.file_type,
+        content: data.content,
+        hint: '请学习此样例的风格和结构，生成风格一致但内容全新的作品。不要复制样例的具体文字内容。',
+      });
+    }
+  );
+}
+
+module.exports = { registerContentTemplateTools };

package/mcp/tools-files.js

@@ -0,0 +1,245 @@
+// MCP 文件类工具：list_files / upload_file / get_file_content / delete_file /
+// rename_file / get_file_url / star_file / unstar_file。
+// 从 mcp-server.js 提取，行为保持不变。
+//
+// 统一接口：导出 register(server, ctx)，ctx = { api, port, mcpIp, protocol }。
+// api 是 lib/dispatch 的进程内客户端（{get,post,put,del}），与 fetch 客户端同形。
+
+const { z } = require('zod');
+const { textResult, applyTagsAndCategory } = require('./util');
+const { ALLOWED_EXTS, MAX_FILE_SIZE } = require('./constants');
+
+function registerFileTools(server, { api, port, mcpIp, protocol }) {
+  // --- list_files ---
+  server.registerTool(
+    'list_files',
+    {
+      title: 'List Files',
+      description: '列出 jpage 中存储的所有 HTML/Markdown 文件元数据。适用于查看已上传文件列表、确认上传结果、或决定后续操作目标。支持分页和排序。',
+      inputSchema: {
+        page: z.number().optional().describe('页码（默认 1）'),
+        limit: z.number().optional().describe('每页数量（默认 20，最大 100）'),
+        sort: z.enum(['updated_at', 'created_at', 'original_name', 'size']).optional().describe('排序字段（默认 updated_at）'),
+        order: z.enum(['asc', 'desc']).optional().describe('排序方向（默认 desc）'),
+        keyword: z.string().optional().describe('按文件名搜索'),
+        category: z.string().optional().describe('按分类 ID 筛选，"uncategorized" 表示未分类'),
+        tag: z.string().optional().describe('按标签 ID 筛选'),
+      },
+    },
+    async ({ page, limit, sort, order, keyword, category, tag }) => {
+      const params = new URLSearchParams();
+      if (page) params.set('page', page);
+      if (limit) params.set('limit', Math.min(limit, 100));
+      if (sort) params.set('sort', sort);
+      if (order) params.set('order', order);
+      if (keyword) params.set('keyword', keyword);
+      if (category) params.set('category', category);
+      if (tag) params.set('tag', tag);
+      const qs = params.toString();
+      const data = await api.get('/api/files' + (qs ? '?' + qs : ''));
+      return textResult({ files: data.files, pagination: data.pagination });
+    }
+  );
+
+  // --- upload_file ---
+  server.registerTool(
+    'upload_file',
+    {
+      title: 'Upload File',
+      description:
+        '上传 HTML、Markdown 或 ZIP 文件到 jpage。ZIP 支持两种模式：网站包（含 index.html + 资源，作为整体预览）和批量上传（多个独立 HTML/MD，各自创建记录）。' +
+        '非 ZIP 文件类型按扩展名自动识别。返回的 url 字段是可公开访问的预览地址。适用于将生成的报告、笔记、可视化页面等内容上传分享。',
+      inputSchema: {
+        name: z.string().describe('文件名，需带扩展名，例如 "report.html" 或 "note.md"'),
+        content: z.string().describe('文件正文，UTF-8 字符串'),
+        isPublic: z
+          .boolean()
+          .optional()
+          .describe('是否公开可访问（无需登录）。默认 true。'),
+        overwriteFileId: z
+          .number()
+          .int()
+          .positive()
+          .optional()
+          .describe('显式指定覆盖目标文件 ID。提供时调用覆盖上传 API（POST /api/files/:id/overwrite-json），不提供时走同名自动覆盖逻辑。'),
+        tags: z
+          .array(z.string())
+          .optional()
+          .describe('标签名列表，上传后自动设置。标签不存在时自动创建。'),
+        categoryId: z
+          .number()
+          .int()
+          .positive()
+          .optional()
+          .describe('分类 id，上传后将文件归入该分类。'),
+      },
+    },
+    async ({ name, content, isPublic, overwriteFileId, tags, categoryId }) => {
+      const ext = (name.match(/\.[^.]+$/) || [''])[0].toLowerCase();
+
+      // ZIP 文件：content 为 base64 编码
+      if (ext === '.zip') {
+        const buf = Buffer.from(content, 'base64');
+        if (buf.length > MAX_FILE_SIZE) {
+          return textResult(`ZIP 文件过大 (${buf.length} 字节)，上限 50MB`, { isError: true });
+        }
+        try {
+          const data = await api.post('/api/files/upload-zip-base64', {
+            name,
+            content,
+            isPublic: isPublic ?? true,
+          });
+          if (data.type === 'batch') {
+            for (const f of data.files) {
+              await applyTagsAndCategory(api, f.id, tags, categoryId);
+            }
+            return textResult({
+              type: 'batch',
+              count: data.count,
+              files: data.files,
+            });
+          }
+          await applyTagsAndCategory(api, data.id, tags, categoryId);
+          return textResult({
+            ...data,
+            url: data.share_key ? `${protocol}://${mcpIp}:${port}/s/${data.share_key}` : `${protocol}://${mcpIp}:${port}/api/files/${data.id}/render`,
+          });
+        } catch (e) {
+          return textResult(`ZIP 上传失败: ${e.message}`, { isError: true });
+        }
+      }
+
+      if (!ALLOWED_EXTS.includes(ext)) {
+        return textResult(
+          `不支持的文件扩展名: ${ext}。仅允许 ${ALLOWED_EXTS.join(', ')}`,
+          { isError: true }
+        );
+      }
+      const size = Buffer.byteLength(content, 'utf-8');
+      if (size > MAX_FILE_SIZE) {
+        return textResult(`文件过大 (${size} 字节)，上限 50MB`, { isError: true });
+      }
+      const uploadPath = overwriteFileId
+        ? `/api/files/${overwriteFileId}/overwrite-json`
+        : '/api/files/upload-json';
+      const data = await api.post(uploadPath, {
+        name,
+        content,
+        isPublic: isPublic ?? true,
+      });
+
+      await applyTagsAndCategory(api, data.id, tags, categoryId);
+
+      return textResult({
+        ...data,
+        url: data.share_key ? `${protocol}://${mcpIp}:${port}/s/${data.share_key}` : `${protocol}://${mcpIp}:${port}/api/files/${data.id}/render`,
+      });
+    }
+  );
+
+  // --- get_file_content ---
+  server.registerTool(
+    'get_file_content',
+    {
+      title: 'Get File Content',
+      description: '读取指定 id 的文件原始内容（UTF-8 文本）。适用于查看或编辑已有文件内容，不限文件大小。不支持网站包（bundle）类型的 ZIP——list_files 中 is_bundle=1 的文件请改用 get_file_url 获取预览链接。',
+      inputSchema: {
+        id: z.number().int().positive().describe('文件 id（list_files 返回的 id 字段）'),
+      },
+    },
+    async ({ id }) => {
+      const data = await api.get(`/api/files/${id}/content`);
+      return textResult({
+        id: data.id,
+        original_name: data.original_name,
+        file_type: data.file_type,
+        size: Buffer.byteLength(data.content, 'utf-8'),
+        content: data.content,
+      });
+    }
+  );
+
+  // --- delete_file ---
+  server.registerTool(
+    'delete_file',
+    {
+      title: 'Delete File',
+      description: '删除指定 id 的文件（同时移除数据库记录与磁盘文件）。适用于清理不需要的页面。此操作不可撤销。',
+      inputSchema: {
+        id: z.number().int().positive().describe('文件 id'),
+      },
+    },
+    async ({ id }) => {
+      const data = await api.del(`/api/files/${id}`);
+      return textResult({ id, ...data });
+    }
+  );
+
+  // --- rename_file ---
+  server.registerTool(
+    'rename_file',
+    {
+      title: 'Rename File',
+      description: '修改指定 id 的文件名（仅 original_name 字段，不影响磁盘存储名）。适用于修正文件名或更改显示标题。',
+      inputSchema: {
+        id: z.number().int().positive().describe('文件 id'),
+        name: z.string().min(1).describe('新文件名，需带扩展名'),
+      },
+    },
+    async ({ id, name }) => {
+      const data = await api.put(`/api/files/${id}`, { name });
+      return textResult({ id, name, ...data });
+    }
+  );
+
+  // --- get_file_url ---
+  server.registerTool(
+    'get_file_url',
+    {
+      title: 'Get File Public URL',
+      description: '返回指定 id 的公开预览短链接（/s/:key）。适用于获取分享链接，无需读取文件内容。',
+      inputSchema: {
+        id: z.number().int().positive().describe('文件 id'),
+      },
+    },
+    async ({ id }) => {
+      const data = await api.get(`/api/files/${id}`);
+      const url = data.share_key ? `${protocol}://${mcpIp}:${port}/s/${data.share_key}` : `${protocol}://${mcpIp}:${port}/api/files/${id}/render`;
+      return textResult({ id, url, share_key: data.share_key || null });
+    }
+  );
+
+  // --- star_file ---
+  server.registerTool(
+    'star_file',
+    {
+      title: 'Star File',
+      description: '收藏指定文件。',
+      inputSchema: {
+        fileId: z.number().int().positive().describe('文件 id'),
+      },
+    },
+    async ({ fileId }) => {
+      await api.post(`/api/files/${fileId}/star`);
+      return textResult({ fileId, starred: true });
+    }
+  );
+
+  // --- unstar_file ---
+  server.registerTool(
+    'unstar_file',
+    {
+      title: 'Unstar File',
+      description: '取消收藏指定文件。',
+      inputSchema: {
+        fileId: z.number().int().positive().describe('文件 id'),
+      },
+    },
+    async ({ fileId }) => {
+      await api.del(`/api/files/${fileId}/star`);
+      return textResult({ fileId, starred: false });
+    }
+  );
+}
+
+module.exports = { registerFileTools };

package/mcp/tools-tags.js

@@ -0,0 +1,41 @@
+// MCP 标签类工具：list_tags / add_tags_to_file。
+// 从 mcp-server.js 提取，行为保持不变。
+
+const { z } = require('zod');
+const { textResult, resolveTagIds } = require('./util');
+
+function registerTagTools(server, { api }) {
+  // --- list_tags ---
+  server.registerTool(
+    'list_tags',
+    {
+      title: 'List Tags',
+      description: '列出所有标签及其关联文件数量。',
+      inputSchema: {},
+    },
+    async () => {
+      const data = await api.get('/api/tags');
+      return textResult(data.tags);
+    }
+  );
+
+  // --- add_tags_to_file ---
+  server.registerTool(
+    'add_tags_to_file',
+    {
+      title: 'Add Tags to File',
+      description: '为指定文件设置标签（替换现有标签）。标签不存在时会自动创建。',
+      inputSchema: {
+        fileId: z.number().int().positive().describe('文件 id'),
+        tags: z.array(z.string()).describe('标签名列表，如 ["报告", "Q3"]'),
+      },
+    },
+    async ({ fileId, tags }) => {
+      const tagIds = await resolveTagIds(api, tags);
+      await api.put(`/api/files/${fileId}/tags`, { tagIds });
+      return textResult({ fileId, tags });
+    }
+  );
+}
+
+module.exports = { registerTagTools };

package/mcp/tools-versions.js

@@ -0,0 +1,57 @@
+// MCP 版本类工具：list_file_versions / restore_file_version。
+// 从 mcp-server.js 提取，行为保持不变。
+
+const { z } = require('zod');
+const { textResult, formatSize, formatTime } = require('./util');
+
+function registerVersionTools(server, { api }) {
+  // --- list_file_versions ---
+  server.registerTool(
+    'list_file_versions',
+    {
+      title: 'List File Versions',
+      description: '列出指定文件的版本历史，包括当前版本信息。适用于查看文件修改历史、确认版本数量、或决定是否恢复到某个历史版本。',
+      inputSchema: {
+        fileId: z.number().positive().describe('文件 ID'),
+      },
+    },
+    async ({ fileId }) => {
+      const data = await api.get(`/api/files/${fileId}/versions`);
+      const current = data.current;
+      const versions = data.versions || [];
+      const currentSize = formatSize(current.size);
+      const updatedAt = formatTime(current.updated_at);
+      const lines = [`文件 #${fileId} 版本历史（共 ${versions.length} 个历史版本）：`];
+      lines.push(`当前版本: ${currentSize}, 更新于 ${updatedAt}`);
+      for (const v of versions) {
+        const vSize = formatSize(v.size);
+        const vTime = formatTime(v.created_at);
+        lines.push(`v${v.version}: ${vSize}, ${vTime}  [查看 | 恢复 | 删除]`);
+      }
+      return textResult(lines.join('\n'));
+    }
+  );
+
+  // --- restore_file_version ---
+  server.registerTool(
+    'restore_file_version',
+    {
+      title: 'Restore File Version',
+      description: '恢复指定文件到某个历史版本。恢复后当前版本会被保存为新的历史版本，目标历史版本的内容成为新的当前版本。适用于撤销误修改或回退到之前的版本。',
+      inputSchema: {
+        fileId: z.number().positive().describe('文件 ID'),
+        version: z.number().positive().describe('要恢复的版本号'),
+      },
+    },
+    async ({ fileId, version }) => {
+      const data = await api.post(`/api/files/${fileId}/versions/${version}/restore`);
+      return textResult({
+        fileId,
+        restoredVersion: version,
+        ...data,
+      });
+    }
+  );
+}
+
+module.exports = { registerVersionTools };