question-workbench-mcp 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +58 -28
  2. package/package.json +1 -1
  3. package/server.js +46 -7
package/README.md CHANGED
@@ -9,9 +9,36 @@
9
9
  | 工具 | 作用 |
10
10
  |---|---|
11
11
  | `question_prompt` | 生成题目处理提示:`recognition`(识图三段式)、`analysis`(思路)、`solution`(完整解题)、`summary`(总结)、`full`(全流程) |
12
- | `build_worksheet` | 生成 A4 讲义 HTML:题目文字、可选解答、可选嵌入原图;返回文件绝对路径,用浏览器 Ctrl+P 预览分页并打印 |
12
+ | `build_worksheet` | 生成 A4 讲义 HTML:题目、可选解答、**自动嵌入聊天里贴的图片**;默认**跳过【待确认】段**;返回文件路径,浏览器 Ctrl+P 打印 |
13
13
 
14
- 识图仍由客户端自己的多模态模型完成——MCP 服务器不本地 OCR。图片通过客户端附加,或在 `build_worksheet` 里传本地路径嵌入讲义。
14
+ 识图由客户端自己的多模态模型完成——MCP 服务器不本地 OCR。
15
+
16
+ ## 直接贴图(0.2.0 起)
17
+
18
+ 在 WorkBuddy 里直接把题目图片粘贴到聊天框,`build_worksheet` 会自动读取它保存的最近图片,**不需要再提供文件路径**:
19
+
20
+ ```text
21
+ 调用 build_worksheet,text=【题目】核对后的全文,outputPath=D:\讲义.html
22
+ ```
23
+
24
+ 默认规则:取 `~/.workbuddy/clipboard-images/` 中最近 **30 分钟**内的图片,最多 **3 张**。
25
+
26
+ 可用参数调整:
27
+
28
+ | 参数 | 默认 | 说明 |
29
+ |---|---|---|
30
+ | `useClipboard` | `true` | `false` 时不读贴图 |
31
+ | `maxAgeMinutes` | `30` | 超过多久的贴图不再采用;`0` 表示不限 |
32
+ | `imageLimit` | `3` | 最多嵌入几张 |
33
+ | `clipboardDir` | WorkBuddy 目录 | 其他客户端可显式指定贴图目录 |
34
+ | `images` | 无 | 显式传本地路径数组,优先于贴图 |
35
+ | `skipChecks` | `true` | 生成讲义时去掉【待确认】/【待核实】整段;`false` 保留 |
36
+
37
+ 注意:贴图要**先粘进聊天再调用工具**;如果图片是很久以前贴的,把 `maxAgeMinutes` 调大或显式传 `images`。
38
+
39
+ ## 跳过待确认
40
+
41
+ 默认生成讲义时直接跳过【待确认】段,不再要求先人工核对。代价是:如果识别里有错字,讲义也会带着错。需要保留时传 `skipChecks: false`。
15
42
 
16
43
  ## 快速启动(stdio)
17
44
 
@@ -25,56 +52,59 @@ npx -y question-workbench-mcp
25
52
  node <本目录绝对路径>\server.js
26
53
  ```
27
54
 
55
+ ## WorkBuddy 配置
56
+
57
+ 配置文件:`C:\Users\<user>\.workbuddy\.mcp.json`(界面 MCP 管理里显示的路径)。
58
+
59
+ ```json
60
+ {
61
+ "mcpServers": {
62
+ "question-workbench": {
63
+ "type": "stdio",
64
+ "command": "npx",
65
+ "args": ["-y", "question-workbench-mcp@0.2.0"]
66
+ }
67
+ }
68
+ }
69
+ ```
70
+
71
+ **注意**:文件必须是无 BOM 的 UTF-8;带 BOM 时 WorkBuddy 可能解析失败、只显示旧列表。工作区里的 `mcp.json`/`.mcp.json` 示例可直接参考。
72
+
28
73
  ## Codex CLI 配置
29
74
 
30
- 编辑 `~/.codex/config.toml`:
75
+ `~/.codex/config.toml`:
31
76
 
32
77
  ```toml
33
78
  # Windows
34
79
  [mcp_servers.question-workbench]
35
80
  command = "cmd"
36
- args = ["/c", "npx", "-y", "question-workbench-mcp"]
81
+ args = ["/c", "npx", "-y", "question-workbench-mcp@0.2.0"]
37
82
 
38
83
  # macOS / Linux
39
84
  # [mcp_servers.question-workbench]
40
85
  # command = "npx"
41
- # args = ["-y", "question-workbench-mcp"]
86
+ # args = ["-y", "question-workbench-mcp@0.2.0"]
42
87
  ```
43
88
 
44
- 保存后重启 Codex,用 `/mcp` 或对应命令确认 `question-workbench` 已连接、两个工具可见。
45
-
46
- **Windows 注意**:MCP 客户端直接 spawn `npx` 常因 `.cmd` shim 报 ENOENT,所以要 `cmd /c npx ...` 包装;若客户端允许填写 argv 数组,也可用 `cmd.exe` + `/c`。
47
-
48
- ## WorkBuddy / 其他客户端
49
-
50
- 只要支持**自定义 MCP 服务器(stdio)**,填:
51
-
52
- - 命令:`cmd`
53
- - 参数:`/c`、`npx`、`-y`、`question-workbench-mcp`(Windows)
54
- - macOS / Linux:命令 `npx`,参数 `-y`、`question-workbench-mcp`
55
-
56
- JSON 写法参考 [mcp-config.example.json](mcp-config.example.json)。
57
-
58
- 客户端**不支持 MCP** 的话,无法以插件形式接入,只能把提示词当自定义指令使用。
59
-
60
89
  ## 在代理里的推荐流程
61
90
 
62
- 1. 用户提供题目照片;
63
- 2. 调用 `question_prompt`,`mode: "recognition"`,把结果给用户核对;
64
- 3. 用户改正后,把核对文本传给 `question_prompt`,`mode` 选 `analysis` / `solution` / `summary` / `full`;
65
- 4. 用 `build_worksheet` 生成讲义:`text` 放题目,`notes` 放解答,`images` 放本地原图路径;
66
- 5. 打开返回的 `.html` 路径,Ctrl+P 预览并打印。
91
+ 1. 用户在聊天里**贴题目图片**;
92
+ 2. 调用 `question_prompt(mode="recognition")`,把三段结果给用户;
93
+ 3. 用户确认/改正后,把文本传给 `question_prompt` 的 `analysis` / `solution` / `summary` / `full`;
94
+ 4. 调用 `build_worksheet(text=题目, notes=解答)` —— 贴图自动带入、待确认段自动去掉;
95
+ 5. 打开返回的 `.html`,Ctrl+P 预览并打印。
67
96
 
68
97
  ## 参数说明
69
98
 
70
99
  `question_prompt`:`mode`(必填)、`text`(除 recognition 外必填)、`language`(`zh` 默认 / `en`)。
71
100
 
72
- `build_worksheet`:`text`(必填)、`title`、`grade`、`notes`、`images`(png/jpg/jpeg/webp/gif 的本地路径数组)、`outputPath`(默认写到当前工作目录)、`language`。
101
+ `build_worksheet`:`text`(必填)、`title`、`grade`、`notes`、`images`、`useClipboard`、`maxAgeMinutes`、`imageLimit`、`clipboardDir`、`skipChecks`、`outputPath`(默认写到当前工作目录)、`language`。
73
102
 
74
103
  ## 已知限制
75
104
 
76
105
  - 不做本地 OCR,也不做照片增强(去阴影/裁剪属于 DSH 版插件的浏览器端能力);
77
- - 讲义中 `[待核实:原因]` / `[verify: reason]` 会以红色标出;
106
+ - 贴图自动读取目前面向 WorkBuddy 的目录约定;其他客户端请显式传 `images` 或 `clipboardDir`;
107
+ - 讲义中 `[待核实:原因]` / `[verify: reason]` 会以红色标出(`skipChecks` 只删除整段,不处理行内标记);
78
108
  - MCP 服务器不保存状态,草稿由客户端或用户自行保存。
79
109
 
80
110
  ## License
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "question-workbench-mcp",
3
- "version": "0.1.1",
3
+ "version": "0.2.0",
4
4
  "description": "MCP server for the question-workbench flow: structured recognition/solution prompts and A4 worksheet HTML generation, usable from Codex, WorkBuddy and any MCP-capable agent.",
5
5
  "type": "module",
6
6
  "license": "MIT",
package/server.js CHANGED
@@ -4,8 +4,11 @@
4
4
  import readline from 'node:readline';
5
5
  import fs from 'node:fs';
6
6
  import path from 'node:path';
7
+ import os from 'node:os';
7
8
 
8
- const VERSION = '0.1.0';
9
+ const VERSION = (() => {
10
+ try { return JSON.parse(fs.readFileSync(new URL('./package.json', import.meta.url), 'utf8')).version; } catch { return '0.0.0'; }
11
+ })();
9
12
  const PROTOCOLS = ['2024-11-05', '2025-03-26', '2025-06-18'];
10
13
 
11
14
  const PROMPTS = {
@@ -49,7 +52,7 @@ const TOOLS = [
49
52
  },
50
53
  {
51
54
  name: 'build_worksheet',
52
- description: 'Write an A4 worksheet HTML file (question text, optional diagram notes, optional solution, optional embedded photos) and return its absolute path. Open it in a browser and print with Ctrl+P for a paginated preview.',
55
+ description: 'Write an A4 worksheet HTML file and return its absolute path. By default it embeds the most recent images the user pasted into WorkBuddy (no path needed) and skips the 【待确认】 section.',
53
56
  inputSchema: {
54
57
  type: 'object',
55
58
  properties: {
@@ -57,7 +60,12 @@ const TOOLS = [
57
60
  title: { type: 'string', description: 'Worksheet heading; defaults to the workbench title.' },
58
61
  grade: { type: 'string', description: 'Optional subject/grade line.' },
59
62
  notes: { type: 'string', description: 'Optional reasoning, solution or summary printed after the question.' },
60
- images: { type: 'array', items: { type: 'string' }, description: 'Optional local image paths (png/jpg/webp/gif) embedded in the worksheet.' },
63
+ images: { type: 'array', items: { type: 'string' }, description: 'Optional explicit local image paths; when given, clipboard images are ignored.' },
64
+ useClipboard: { type: 'boolean', description: 'Embed the newest pasted images from the WorkBuddy clipboard folder when images is omitted. Defaults to true.' },
65
+ maxAgeMinutes: { type: 'number', description: 'How recent a pasted image must be, in minutes; 0 disables the age filter. Defaults to 30.' },
66
+ imageLimit: { type: 'number', description: 'Maximum clipboard images to embed. Defaults to 3.' },
67
+ clipboardDir: { type: 'string', description: 'Advanced: pasted-image folder; defaults to <home>/.workbuddy/clipboard-images or QUESTION_WORKBENCH_CLIPBOARD_DIR.' },
68
+ skipChecks: { type: 'boolean', description: 'Remove a 【待确认】/【待核实】 section from the text. Defaults to true.' },
61
69
  outputPath: { type: 'string', description: 'Destination .html path; defaults to the current working directory.' },
62
70
  language: { type: 'string', enum: ['zh', 'en'], description: 'Worksheet language; defaults to zh.' }
63
71
  },
@@ -67,6 +75,31 @@ const TOOLS = [
67
75
  ];
68
76
 
69
77
  const MIME = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif' };
78
+ const CLIP_DIR = process.env.QUESTION_WORKBENCH_CLIPBOARD_DIR || path.join(os.homedir(), '.workbuddy', 'clipboard-images');
79
+
80
+ // WorkBuddy writes pasted images as clipboard-<ISO>-<hash>.(png|jpg) in its home.
81
+ function clipboardImages(maxAgeMinutes = 30, limit = 3, dir) {
82
+ const base = dir ? path.resolve(dir) : CLIP_DIR;
83
+ let files;
84
+ try { files = fs.readdirSync(base); } catch { return []; }
85
+ const cutoff = maxAgeMinutes > 0 ? Date.now() - maxAgeMinutes * 60000 : 0;
86
+ return files
87
+ .filter((n) => MIME[path.extname(n).toLowerCase()])
88
+ .map((n) => { const p = path.join(base, n); let s; try { s = fs.statSync(p); } catch { return null; } return { p, t: s.mtimeMs }; })
89
+ .filter((x) => x && x.t >= cutoff)
90
+ .sort((a, b) => b.t - a.t)
91
+ .slice(0, limit)
92
+ .map((x) => x.p);
93
+ }
94
+
95
+ // Drop the verification section so a worksheet can be generated without it.
96
+ function stripChecks(text) {
97
+ return String(text)
98
+ .replace(/(?:^|\n)\s*【(?:待确认|待核实)】[\s\S]*?(?=\n\s*【|$)/g, '')
99
+ .replace(/(?:^|\n)\s*\[(?:Checks|Items to verify)\][\s\S]*?(?=\n\s*\[|$)/gi, '')
100
+ .replace(/\n{3,}/g, '\n\n')
101
+ .trim();
102
+ }
70
103
 
71
104
  const esc = v => String(v).replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
72
105
  const marker = /([待核实[^]\n]{0,160}]|\[verify[^\]\n]{0,160}\])/gi;
@@ -103,12 +136,17 @@ function callTool(name, args = {}) {
103
136
  if (name === 'build_worksheet') {
104
137
  const lang = args.language === 'en' ? 'en' : 'zh';
105
138
  const t = PROMPTS[lang];
106
- const images = Array.isArray(args.images) ? args.images.map((p) => readImage(path.resolve(p))) : [];
139
+ const explicit = Array.isArray(args.images) ? args.images.filter(Boolean) : [];
140
+ const picked = explicit.length
141
+ ? explicit.map((p) => path.resolve(p))
142
+ : (args.useClipboard === false ? [] : clipboardImages(Number(args.maxAgeMinutes ?? 30), Number(args.imageLimit ?? 3), args.clipboardDir));
143
+ const images = picked.map((p) => readImage(p));
144
+ const text = args.skipChecks === false ? String(args.text || '') : stripChecks(args.text || '');
107
145
  const title = typeof args.title === 'string' && args.title.trim() ? args.title.trim() : t.worksheetTitle;
108
146
  const html = worksheet(t, {
109
147
  title,
110
148
  grade: typeof args.grade === 'string' ? args.grade : '',
111
- text: typeof args.text === 'string' ? args.text : '',
149
+ text,
112
150
  notes: typeof args.notes === 'string' ? args.notes : '',
113
151
  images
114
152
  });
@@ -118,7 +156,8 @@ function callTool(name, args = {}) {
118
156
  if (path.extname(target).toLowerCase() !== '.html') throw new Error('outputPath must end with .html');
119
157
  fs.mkdirSync(path.dirname(target), { recursive: true });
120
158
  fs.writeFileSync(target, html, 'utf8');
121
- return `Worksheet written: ${target} (${Buffer.byteLength(html)} bytes, ${images.length} image(s))`;
159
+ const names = images.map((i) => i.name).join(', ');
160
+ return `Worksheet written: ${target} (${Buffer.byteLength(html)} bytes, ${images.length} image(s)${names ? ': ' + names : ''}${args.skipChecks === false ? '' : ', 待确认 section skipped'})`;
122
161
  }
123
162
  throw new Error('unknown tool: ' + name);
124
163
  }
@@ -156,7 +195,7 @@ function handle(msg) {
156
195
 
157
196
  const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
158
197
  rl.on('line', (line) => {
159
- const raw = line.trim();
198
+ const raw = line.replace(/^\uFEFF/, '').trim();
160
199
  if (!raw) return;
161
200
  let msg;
162
201
  try { msg = JSON.parse(raw); } catch (e) { return fail(null, -32700, 'parse error'); }