@klosedoc/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KloseDoc contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# KloseDoc MCP
+
+轻量的本地 MCP 适配器，无需获取或安装 KloseDoc 服务端源码。当前版本仅支持网页演示相关功能；尚不支持 Markdown、LaTeX 或 Typst 项目的读写、编译。
+
+## 安装方式
+
+本包通过 npm 独立分发，不需要访问 KloseDoc 闭源仓库。以下命令适用于 npm 上已发布的对应版本；未发布版本可使用维护者提供的 `.tgz` 包。KloseDoc 接入页面会在维护者验证发布后开放配置复制。
+
+## 使用条件
+
+- 本机 Node.js 24 或以上（包含 npm/npx）。
+- 可访问的 KloseDoc 地址，以及在“账户菜单 → Agent 接入”创建的用户级令牌。
+- 各个项目中已存在的演示产物目录（例如 dist），项目可分散放置。
+
+在已开放接入的 KloseDoc 页面选择客户端并复制配置。客户端通过 `npx -y @klosedoc/mcp@0.1.0` 启动适配器；不要使用未固定版本的 `latest`。
+
+配置所需环境变量：
+
+| 变量 | 含义 |
+| --- | --- |
+| `KLOSEDOCPUBLISH_URL` | KloseDoc 的 `/api/agent/slides` 地址；生产环境必须为 HTTPS |
+| `KLOSEDOCPUBLISH_TOKEN` | 用户级令牌；不要提交到仓库或发送给其他人 |
+
+本地 HTTP 地址只能连接本机 KloseDoc，不能用于给其他人分享。
+
+## 本地项目授权
+
+无需在网页填写目录。进入要发布的项目，在终端执行（安装包发布后）：
+
+```sh
+mkdir -p dist
+npx -y @klosedoc/mcp@0.1.0 authorize . dist
+```
+
+内部测试使用已安装的入口替代 npx，例如：
+
+```sh
+node /path/to/installed/@klosedoc/mcp/server.mjs authorize . dist
+```
+
+命令会显示项目的规范绝对路径和产物目录，输入 yes 后授权。每个项目单独执行一次；无需移动项目或修改全局 MCP 配置。授权仅允许读取指定产物目录，以及项目根目录的 klosedoc.json。修改 klosedoc.json 的 output 不会扩大授权。
+
+使用相同入口的 `authorizations` 查看授权，`unauthorize .` 撤销当前项目；之后的上传会立即拒绝，已发布内容不受影响。授权记录保存在本机 `~/.config/klosedoc/authorizations.json`，不发送至服务器。不要把该文件交给 Agent 修改。交互确认不是操作系统沙箱；拥有同一用户任意文件写权限或终端控制权限的程序仍能改变授权记录，需由客户端限制这些权限。
+
+不兼容旧配置：删除 MCP 环境变量中的 KLOSEDOCPUBLISH_ROOT，然后重新按项目授权。上传必须提供授权命令显示的绝对项目路径 configDirectory，path/output 相对于项目；不再默认使用 MCP 进程工作目录。
+
+## 关联项目
+
+首次配置好 MCP 客户端、服务地址和用户令牌后，不需要通过网页创建项目：Agent 可先调用 `klosedoc_presentation_create`，再把返回的项目 ID 传入 `klosedoc_presentation_upload`，最后读取状态并调用 `klosedoc_publication_publish`。上传时显式传入 `projectId`、本地 `path` 和 `entry`，无需预先创建 `klosedoc.json`。发布要求令牌具有发布权限，并且用户明确授权发布。
+
+示例指令：
+
+> 将工作区的 dist/index.html 及其静态资源作为演示发布到 KloseDoc，项目名为“研究汇报”。先创建项目，再上传 dist，然后读取最新状态并发布刚上传的版本，返回演示链接。记录项目 ID，以后更新同一项目。不要修改其他项目。
+
+本地预览和文件检查可以由 Agent 完成；不要求人先打开 KloseDoc 网页。一次指令会编排多个 MCP 操作，并不是一个跨步骤原子事务。网络失败时保留已返回的项目 ID，复用相同操作的幂等键重试，避免重复创建项目。没有发布权限时只能完成草稿上传，不会自动绕过权限。
+
+首次获取令牌目前仍需通过 KloseDoc 的“账户菜单 → Agent 接入”；本版本尚未实现 CLI 登录或设备授权流程。令牌通过 MCP 客户端环境变量配置，不应粘贴进聊天消息。
+
+已有项目也可以使用配置文件：
+
+在演示详情页“来源与同步 → Agent 项目配置”复制 `klosedoc.json`，保存到本地项目根目录。文件包含 `projectId`、相对于配置文件的 `output`（例如 `dist`）和 `entry`（例如 `index.html`），不包含令牌。上传时传入已授权项目的绝对路径 `configDirectory`，该路径仅供本地适配器使用。
+
+让 Agent 调用 `klosedoc_presentation_upload` 上传输出目录，生成草稿。确认预览后再调用 `klosedoc_publication_publish`；默认令牌没有发布权限。也可用 `klosedoc_presentation_create` 创建项目、`klosedoc_publication_status` 读取状态、`klosedoc_publication_rollback` 恢复草稿、`klosedoc_publication_revoke` 下线。
+
+每次发布或回滚前读取最新版本状态，传入 `expectedCurrentVersionId` 和 `expectedDraftVersionId`。同一操作重试时复用 `idempotencyKey`，冲突后重新读取状态并确认。上传、创建和回滚都不会隐式更新线上链接。
+
+## 安全边界
+
+适配器仅打包本地已授权的产物目录，不执行构建脚本，不支持产物符号链接，目录上传要求独立输出目录。目录打包跳过隐藏文件、`node_modules` 和 `klosedoc.json`。单文件最大 10 MB，包解压后最大 50 MB、1000 个文件；账户配额与权限由服务端检查。授权期间不要让不可信进程并发替换目录；本地检查不能替代操作系统级文件隔离。
+
+本包仅含客户端适配器，不包含 KloseDoc 的服务端、数据库、密钥或其他产品源码。
+
+## 许可
+
+`@klosedoc/mcp` 适配器及其随附文档采用 [MIT 许可](LICENSE)。该许可仅适用于此适配器包，不适用于 KloseDoc 服务端或仓库中的其他产品代码，也不改变主项目的许可。第三方依赖遵循各自的许可。

package/authorization.mjs

@@ -0,0 +1,70 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { createInterface } from 'node:readline/promises';
+
+const registry = process.env.KLOSEDOC_AUTH_FILE || path.join(os.homedir(), '.config', 'klosedoc', 'authorizations.json');
+export function within(parent, target) {
+  const relative = path.relative(parent, target);
+  return relative === '' || (!relative.startsWith('..' + path.sep) && relative !== '..' && !path.isAbsolute(relative));
+}
+export async function checkedPath(value) {
+  if (!value || !path.isAbsolute(value)) throw new Error('An absolute project path is required');
+  const resolved = path.resolve(value);
+  let current = path.parse(resolved).root;
+  for (const part of resolved.slice(current.length).split(path.sep).filter(Boolean)) {
+    current = path.join(current, part);
+    if ((await fs.lstat(current)).isSymbolicLink()) throw new Error('Symlinks are not supported');
+  }
+  return resolved;
+}
+async function load() {
+  try {
+    await checkedPath(registry);
+    const data = JSON.parse(await fs.readFile(registry, 'utf8'));
+    if (data.version !== 1 || !Array.isArray(data.projects)) throw new Error('Invalid local authorization registry');
+    return data;
+  } catch (error) { if (error.code === 'ENOENT') return { version: 1, projects: [] }; throw error; }
+}
+export async function authorization(projectDirectory) {
+  const project = await checkedPath(projectDirectory);
+  const grant = (await load()).projects.find(item => item.project === project);
+  if (!grant) throw new Error('Project is not authorized. Run klosedoc-mcp authorize in your terminal.');
+  const output = await checkedPath(grant.output);
+  if (output === project || !within(project, output)) throw new Error('Invalid authorized output directory');
+  return { project, output };
+}
+export async function authorizationCommand(command, args) {
+  if (command === 'authorizations') { console.log(JSON.stringify((await load()).projects, null, 2)); return; }
+  if (!process.stdin.isTTY || !process.stdout.isTTY) throw new Error('Authorization changes require an interactive terminal; no unattended approval is supported.');
+  const requested = path.resolve(args[0] || '.');
+  const project = await fs.realpath(requested).catch(error => {
+    if (command === 'unauthorize' && error.code === 'ENOENT') return requested;
+    throw error;
+  });
+  if (project === path.parse(project).root || project === os.homedir()) throw new Error('Choose an individual project, not a home directory or filesystem root');
+  const data = await load();
+  let output;
+  if (command === 'authorize') {
+    await checkedPath(project);
+    if (!(await fs.stat(project)).isDirectory()) throw new Error('Choose a project directory');
+    const relative = args[1] || 'dist';
+    if (path.isAbsolute(relative)) throw new Error('Output must be relative to the project');
+    output = await checkedPath(path.resolve(project, relative));
+    if (output === project || !within(project, output) || !(await fs.stat(output)).isDirectory()) throw new Error('Choose an existing dedicated output directory inside the project');
+  }
+  console.log(`${command === 'authorize' ? 'Allow uploads from' : 'Revoke access to'} project: ${project}`);
+  if (output) console.log(`Output: ${output}\nAlso allows reading only klosedoc.json at the project root. Paths remain local.`);
+  const prompt = createInterface({ input: process.stdin, output: process.stdout });
+  let answer;
+  try { answer = await prompt.question('Type yes to confirm: '); } finally { prompt.close(); }
+  if (answer.trim() !== 'yes') throw new Error('Cancelled; authorization unchanged');
+  data.projects = data.projects.filter(item => item.project !== project);
+  if (output) data.projects.push({ project, output });
+  await fs.mkdir(path.dirname(registry), { recursive: true, mode: 0o700 });
+  await checkedPath(path.dirname(registry));
+  const temporary = registry + '.' + process.pid + '.tmp';
+  await fs.writeFile(temporary, JSON.stringify(data, null, 2), { mode: 0o600, flag: 'wx' });
+  await fs.rename(temporary, registry);
+  console.log('Local authorization updated.');
+}

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@klosedoc/mcp",
+  "version": "0.1.0",
+  "description": "MCP adapter for KloseDoc. Currently supports presentation workflows only.",
+  "license": "MIT",
+  "files": ["server.mjs", "authorization.mjs", "README.md", "LICENSE"],
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "type": "module",
+  "bin": { "klosedoc-mcp": "server.mjs" },
+  "scripts": { "start": "node server.mjs" },
+  "engines": { "node": ">=24" },
+  "dependencies": { "@modelcontextprotocol/sdk": "^1.26.0", "fflate": "^0.8.3", "zod": "^3.25.0" }
+}

package/server.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import { constants } from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { zipSync } from 'fflate';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { authorization, authorizationCommand, checkedPath, within } from './authorization.mjs';
+import metadata from './package.json' with { type: 'json' };
+
+if (process.argv.includes('--version')) { console.log(metadata.version); process.exit(0); }
+if (process.argv.includes('--help')) {
+  console.log('KloseDoc MCP (stdio) — currently supports presentations only.\nRequires Node.js 24+.\nSet KLOSEDOCPUBLISH_URL, KLOSEDOCPUBLISH_TOKEN in your MCP client.\nLocal access: authorize [project-directory] [output-directory=dist], authorizations, unauthorize [project-directory].\nSee the package README for setup and safety boundaries.');
+  process.exit(0);
+}
+if (['authorize', 'unauthorize', 'authorizations'].includes(process.argv[2])) {
+  await authorizationCommand(process.argv[2], process.argv.slice(3));
+  process.exit(0);
+}
+if (process.env.KLOSEDOCPUBLISH_ROOT) throw new Error('KLOSEDOCPUBLISH_ROOT is no longer supported. Use local project authorization.');
+const server = new McpServer({ name: 'klosedoc-mcp', version: metadata.version });
+const base = new URL(process.env.KLOSEDOCPUBLISH_URL || 'http://127.0.0.1:3000/api/agent/slides');
+if ((base.protocol !== 'https:' && !(base.protocol === 'http:' && ['localhost','127.0.0.1','[::1]'].includes(base.hostname)))
+    || base.username || base.password || base.search || base.hash || base.pathname.replace(/\/$/, '') !== '/api/agent/slides') throw new Error('Use an HTTPS KloseDoc URL, or HTTP on localhost');
+const token = process.env.KLOSEDOCPUBLISH_TOKEN;
+if (!token) throw new Error('KLOSEDOCPUBLISH_TOKEN is required');
+const maxBytes = 50 * 1024 * 1024;
+const extensions = new Set(['.html','.htm','.css','.js','.mjs','.json','.png','.jpg','.jpeg','.gif','.webp','.avif','.svg','.ico','.woff','.woff2','.ttf','.otf','.mp4','.webm','.mp3','.ogg','.wav','.txt','.pdf']);
+async function readFile(file, limit) {
+  await checkedPath(file);
+  const handle = await fs.open(file,constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stat = await handle.stat();
+    if (stat.nlink !== 1) throw new Error('Hard links are not supported');
+    if (!stat.isFile() || stat.size > limit) throw new Error('File exceeds the size limit');
+    const bytes = await handle.readFile();
+    await checkedPath(file);
+    if (bytes.length > limit) throw new Error('File exceeds the size limit');
+    return bytes;
+  } finally { await handle.close(); }
+}
+async function configFor(directory) {
+  const filename = path.join(directory,'klosedoc.json');
+  try {
+    const value = JSON.parse((await readFile(filename,64*1024)).toString('utf8'));
+    if (value.type && value.type !== 'web_slides') throw new Error('type must be web_slides');
+    return value;
+  } catch (error) { if (error.code === 'ENOENT') return {}; throw new Error('Invalid klosedoc.json: ' + error.message); }
+}
+async function bundle(value, configPath) {
+  const grant = await authorization(configPath);
+  const config = await configFor(grant.project);
+  const selected = value || config.output || path.relative(grant.project, grant.output);
+  if (path.isAbsolute(selected)) throw new Error('Output path must be relative to the project');
+  const target = path.resolve(grant.project, selected);
+  async function localPath(filename) {
+    if (!within(grant.output, filename)) throw new Error('Path is outside the authorized output directory');
+    return checkedPath(filename);
+  }
+  await localPath(target);
+  const stat = await fs.lstat(target);
+  if (stat.isFile()) {
+    if (!/\.(html?|zip)$/i.test(target)) throw new Error('Expected an HTML or ZIP file');
+    return { bytes: await readFile(target, /\.zip$/i.test(target) ? maxBytes : 10*1024*1024), filename: path.basename(target), config };
+  }
+  if (!stat.isDirectory()) throw new Error('Select a dedicated output directory, inside the authorized project');
+  const files = Object.create(null);
+  let total = 0, count = 0;
+  async function walk(directory) {
+    for (const entry of (await fs.readdir(directory,{withFileTypes:true})).sort((a,b)=>a.name.localeCompare(b.name))) {
+      if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.name === 'klosedoc.json') continue;
+      const filename = await localPath(path.join(directory,entry.name));
+      if (entry.isSymbolicLink()) throw new Error('Symlinks are not supported');
+      if (entry.isDirectory()) { await walk(filename); continue; }
+      if (!entry.isFile() || !extensions.has(path.extname(filename).toLowerCase())) throw new Error('Unsupported output file: ' + entry.name);
+      if (++count > 1000) throw new Error('Maximum 1000 files');
+      const bytes = await readFile(filename,10*1024*1024);
+      total += bytes.length;
+      if (total > maxBytes) throw new Error('Output exceeds 50 MB');
+      const relative = path.relative(target,filename).split(path.sep).join('/');
+      files[relative] = [bytes,{mtime:new Date('2020-01-01T00:00:00Z')}];
+    }
+  }
+  await walk(target);
+  if (!count) throw new Error('Output directory is empty');
+  return { bytes: zipSync(files,{level:6}), filename:'slides.zip', config };
+}
+async function request(route = '', input, key, bytes) {
+  const options = { method: input === undefined && !bytes ? 'GET' : 'POST', redirect:'error',
+    headers:{Authorization:'Bearer ' + token}, signal:AbortSignal.timeout(120000) };
+  if (key) options.headers['Idempotency-Key'] = key;
+  if (bytes) { options.headers['Content-Type']='application/octet-stream'; options.body=bytes; }
+  else if (input !== undefined) { options.headers['Content-Type']='application/json'; options.body=JSON.stringify(input); }
+  const response = await fetch(base.toString().replace(/\/$/,'') + route,options);
+  const payload = await response.json();
+  if (!response.ok) throw new Error(payload.error?.message || 'KloseDoc request failed (' + response.status + ')');
+  return payload.data;
+}
+function register(name, description, schema, action, readOnly = false) {
+  server.registerTool(name,{ description, inputSchema:schema,
+    annotations:{readOnlyHint:readOnly,destructiveHint:!readOnly,idempotentHint:true,openWorldHint:true} },async input => {
+    try {
+      const result = await action(input);
+      return { content:[{type:'text',text:JSON.stringify(result)}], structuredContent:result };
+    } catch (error) { return { isError:true,content:[{type:'text',text:error.message.replaceAll(token,'[redacted]')}] }; }
+  });
+}
+const project = z.string().uuid();
+const idempotencyKey = z.string().regex(/^[A-Za-z0-9_.:-]{8,160}$/).describe('Reuse the same key when retrying the same operation.');
+register('klosedoc_presentation_create','Create a Web Slides project. Never publishes content.',{
+  title:z.string().min(1).max(160),folderId:project.optional(),idempotencyKey,
+},input=>request('',{title:input.title,...(input.folderId?{folderId:input.folderId}:{})},input.idempotencyKey));
+register('klosedoc_publication_status','Read status and version IDs, or list presentations. Preview links require the owner to sign in.',{
+  projectId:project.optional(),query:z.string().optional(),page:z.number().int().min(1).optional(),
+},input=>request(input.projectId ? '/' + input.projectId : '?' + new URLSearchParams({query:input.query||'',page:String(input.page||1)})),true);
+register('klosedoc_presentation_upload','Upload a local HTML, ZIP or dedicated output directory inside a locally authorized project output directory as a draft. Reads klosedoc.json; never auto-publishes or creates a project implicitly.',{
+  projectId:project.optional(),path:z.string().optional(),configDirectory:z.string().describe('Absolute local project directory previously authorized by the user in a terminal. Never sent to the server.'),entry:z.string().optional(),idempotencyKey,
+},async input=>{
+  const packed=await bundle(input.path,input.configDirectory);
+  const id=project.parse(input.projectId || packed.config.projectId);
+  const query=new URLSearchParams({filename:packed.filename,entry:input.entry||packed.config.entry||''});
+  const output=await request('/'+id+'/upload?'+query,undefined,input.idempotencyKey,packed.bytes);
+  return {...output,checksum:crypto.createHash('sha256').update(packed.bytes).digest('hex')};
+});
+for (const operation of ['publish','rollback']) register('klosedoc_publication_'+operation,
+  operation==='publish'?'Publish the specified version. Requires user authorization and a publish-enabled token; preserves audience and expiry.':'Restore a historical version as the draft. The live link stays unchanged until a separate publish operation.',{
+    projectId:project,versionId:project,expectedCurrentVersionId:project.nullable(),expectedDraftVersionId:project.nullable(),idempotencyKey,
+  },input=>request('/'+input.projectId+'/'+operation,{versionId:input.versionId,expectedCurrentVersionId:input.expectedCurrentVersionId,expectedDraftVersionId:input.expectedDraftVersionId},input.idempotencyKey));
+register('klosedoc_publication_revoke','Take the presentation offline without deleting versions. Requires publish permission.',{
+  projectId:project,idempotencyKey,
+},input=>request('/'+input.projectId+'/revoke',{},input.idempotencyKey));
+await server.connect(new StdioServerTransport());