question-workbench-mcp 0.0.0-stage → 0.1.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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 question-workbench-mcp contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,90 @@
1
- # Temporary Holding Version
1
+ # question-workbench-mcp
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ 给**非 DeepSeek Harness** 客户端用的题目工作台插件。它是标准 **MCP(Model Context Protocol)服务器**,不依赖 DSH,可被 Codex、WorkBuddy 以及其他支持 MCP 的代理客户端调用。
4
+
5
+ ## 它提供什么
6
+
7
+ | 工具 | 作用 |
8
+ |---|---|
9
+ | `question_prompt` | 生成题目处理提示:`recognition`(识图三段式)、`analysis`(思路)、`solution`(完整解题)、`summary`(总结)、`full`(全流程) |
10
+ | `build_worksheet` | 生成 A4 讲义 HTML:题目文字、可选解答、可选嵌入原图;返回文件绝对路径,用浏览器 Ctrl+P 预览分页并打印 |
11
+
12
+ 识图仍由客户端自己的多模态模型完成——MCP 服务器不本地 OCR。图片通过客户端附加,或在 `build_worksheet` 里传本地路径嵌入讲义。
13
+
14
+ ## 启动(stdio)
15
+
16
+ ```powershell
17
+ node C:\Users\admin\Documents\deepseek-harness\default-workspace\question-workbench-mcp\server.js
18
+ ```
19
+
20
+ 发布到 npm 后可改用:
21
+
22
+ ```powershell
23
+ npx -y question-workbench-mcp
24
+ ```
25
+
26
+ ## Codex CLI 配置
27
+
28
+ 编辑 `~/.codex/config.toml`,加一段:
29
+
30
+ ```toml
31
+ [mcp_servers.question-workbench]
32
+ command = "node"
33
+ args = ["C:\\Users\\admin\\Documents\\deepseek-harness\\default-workspace\\question-workbench-mcp\\server.js"]
34
+ ```
35
+
36
+ 发布 npm 后更简单:
37
+
38
+ ```toml
39
+ [mcp_servers.question-workbench]
40
+ command = "npx"
41
+ args = ["-y", "question-workbench-mcp"]
42
+ ```
43
+
44
+ 保存后重启 Codex,用 `/mcp`(或对应命令)确认 `question-workbench` 已连接、两个工具可见。
45
+
46
+ ## WorkBuddy / 其他客户端
47
+
48
+ 只要该客户端支持**自定义 MCP 服务器(stdio)**,就填:
49
+
50
+ - 命令:`node`
51
+ - 参数:`<本目录绝对路径>\server.js`
52
+
53
+ 若客户端用 JSON 配置,参考 `mcp-config.example.json`:
54
+
55
+ ```json
56
+ {
57
+ "mcpServers": {
58
+ "question-workbench": {
59
+ "command": "node",
60
+ "args": ["<本目录绝对路径>\\server.js"]
61
+ }
62
+ }
63
+ }
64
+ ```
65
+
66
+ 客户端**不支持 MCP** 的话,无法以插件形式接入;那种情况下只能把提示词作为自定义指令使用。
67
+
68
+ ## 在代理里的推荐流程
69
+
70
+ 1. 用户提供题目照片;
71
+ 2. 调用 `question_prompt`,`mode: "recognition"`,把结果三段式贴在对话里给用户核对;
72
+ 3. 用户改正后,把核对文本传给 `question_prompt`,`mode` 选 `analysis` / `solution` / `summary` / `full`;
73
+ 4. 用 `build_worksheet` 生成讲义:`text` 放题目,`notes` 放解答,`images` 放本地原图路径;
74
+ 5. 打开返回的 `.html` 路径,Ctrl+P 预览并打印。
75
+
76
+ ## 参数说明
77
+
78
+ `question_prompt`:`mode`(必填)、`text`(除 recognition 外必填)、`language`(`zh` 默认 / `en`)。
79
+
80
+ `build_worksheet`:`text`(必填)、`title`、`grade`、`notes`、`images`(png/jpg/jpeg/webp/gif 的本地路径数组)、`outputPath`(默认写到当前工作目录)、`language`。
81
+
82
+ ## 已知限制
83
+
84
+ - 不做本地 OCR,也不做照片增强(去阴影/裁剪属于 DSH 版插件的浏览器端能力);
85
+ - 讲义中 `[待核实:原因]` / `[verify: reason]` 会以红色标出;
86
+ - MCP 服务器不保存状态,草稿由客户端或用户自行保存。
87
+
88
+ ## License
89
+
90
+ MIT
@@ -0,0 +1,10 @@
1
+ # Codex CLI: add to ~/.codex/config.toml
2
+ # Local checkout (no publish needed):
3
+ [mcp_servers.question-workbench]
4
+ command = "node"
5
+ args = ["C:\\Users\\admin\\Documents\\deepseek-harness\\default-workspace\\question-workbench-mcp\\server.js"]
6
+
7
+ # After publishing to npm, use this instead:
8
+ # [mcp_servers.question-workbench]
9
+ # command = "npx"
10
+ # args = ["-y", "question-workbench-mcp"]
@@ -0,0 +1,8 @@
1
+ {
2
+ "mcpServers": {
3
+ "question-workbench": {
4
+ "command": "node",
5
+ "args": ["C:\\Users\\admin\\Documents\\deepseek-harness\\default-workspace\\question-workbench-mcp\\server.js"]
6
+ }
7
+ }
8
+ }
package/package.json CHANGED
@@ -1,6 +1,11 @@
1
1
  {
2
2
  "name": "question-workbench-mcp",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.0",
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
+ "type": "module",
6
+ "license": "MIT",
7
+ "bin": { "question-workbench-mcp": "./server.js" },
8
+ "files": ["server.js", "README.md", "LICENSE", "codex-config.example.toml", "mcp-config.example.json"],
9
+ "keywords": ["mcp", "question", "worksheet", "print", "education"],
10
+ "engines": { "node": ">=18" }
6
11
  }
package/server.js ADDED
@@ -0,0 +1,165 @@
1
+ #!/usr/bin/env node
2
+ // Question workbench MCP server: newline-delimited JSON-RPC over stdio, no dependencies.
3
+ // Provides prompt templates and A4 worksheet HTML generation for any MCP-capable agent.
4
+ import readline from 'node:readline';
5
+ import fs from 'node:fs';
6
+ import path from 'node:path';
7
+
8
+ const VERSION = '0.1.0';
9
+ const PROTOCOLS = ['2024-11-05', '2025-03-26', '2025-06-18'];
10
+
11
+ const PROMPTS = {
12
+ zh: {
13
+ recognition: '只做识别,严格按三段输出,不要解释或额外分节,总字数≤300字:\n【题目】逐字转录印刷文字,保留题号、选项、符号和公式;看不清写[待核实:简短原因],不要猜。\n【图形】每张图一行,≤25字,只写可见关键元素,例如:图1 三角形ABC,P在内部,BM、CN交于P。\n【待确认】最多3条、每条≤15字;没有写“无”。',
14
+ analysis: '以下内容已由用户对照原图人工核对,直接作为已知条件使用;不要重新质疑,也不要补充未确认的关系。\n\n已核对题目:\n{text}\n\n只给思路,不要完整计算:①考点1行 ②关键思路3-5步。≤200字。',
15
+ solution: '以下内容已由用户对照原图人工核对,直接作为已知条件使用;不要重新质疑,也不要补充未确认的关系。\n\n已核对题目:\n{text}\n\n给完整解题过程:分步推导+最终答案,公式简洁。≤400字。',
16
+ summary: '以下内容已由用户对照原图人工核对,直接作为已知条件使用;不要重新质疑,也不要补充未确认的关系。\n\n已核对题目:\n{text}\n\n只总结:3-5条知识点与易错点,每条一行。≤150字。',
17
+ full: '以下内容已由用户对照原图人工核对,直接作为已知条件使用;不要重新质疑,也不要补充未确认的关系。\n\n已核对题目:\n{text}\n\n先给3-5步思路,再给完整解答和最终答案,最后1-2句易错点提醒;不重复题目。≤600字。',
18
+ worksheetTitle: '题目讲义',
19
+ labelDiagram: '图形提示',
20
+ labelSolution: '解答'
21
+ },
22
+ en: {
23
+ recognition: 'Transcribe only. Output exactly three sections, no extra explanation, ≤300 words:\n[Question] literal printed text, keeping numbering, symbols and formulas; write [verify: short reason] instead of guessing.\n[Diagram] one line per figure, ≤25 words, only visible key elements, e.g. Fig.1 triangle ABC, P inside, BM and CN meet at P.\n[Checks] at most 3 items, ≤15 words each; write "none" if none.',
24
+ analysis: 'The user checked the following against the photos; use it as given. Do not re-question it or add unconfirmed relations.\n\nChecked question:\n{text}\n\nReasoning only: 1 line of key concepts, then 3-5 steps. ≤200 words.',
25
+ solution: 'The user checked the following against the photos; use it as given. Do not re-question it or add unconfirmed relations.\n\nChecked question:\n{text}\n\nFull solution: step-by-step work and final answer, concise formulas. ≤400 words.',
26
+ summary: 'The user checked the following against the photos; use it as given. Do not re-question it or add unconfirmed relations.\n\nChecked question:\n{text}\n\nKey points only: 3-5 lines of concepts and common mistakes. ≤150 words.',
27
+ full: 'The user checked the following against the photos; use it as given. Do not re-question it or add unconfirmed relations.\n\nChecked question:\n{text}\n\nGive 3-5 reasoning steps, then the full solution and answer, then 1-2 lines of pitfalls; do not restate the question. ≤600 words.',
28
+ worksheetTitle: 'Question worksheet',
29
+ labelDiagram: 'Diagram notes',
30
+ labelSolution: 'Solution'
31
+ }
32
+ };
33
+
34
+ const MODES = ['recognition', 'analysis', 'solution', 'summary', 'full'];
35
+
36
+ const TOOLS = [
37
+ {
38
+ name: 'question_prompt',
39
+ description: 'Return the workbench prompt for one mode. recognition transcribes an attached question photo into three short sections; analysis/solution/summary/full build a prompt from already-checked text. Use recognition first, then pass the checked result to the other modes.',
40
+ inputSchema: {
41
+ type: 'object',
42
+ properties: {
43
+ mode: { type: 'string', enum: MODES, description: 'Which prompt to build.' },
44
+ text: { type: 'string', description: 'Checked question text; required for analysis, solution, summary and full.' },
45
+ language: { type: 'string', enum: ['zh', 'en'], description: 'Prompt language; defaults to zh.' }
46
+ },
47
+ required: ['mode']
48
+ }
49
+ },
50
+ {
51
+ 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.',
53
+ inputSchema: {
54
+ type: 'object',
55
+ properties: {
56
+ text: { type: 'string', description: 'Question text, including any checked recognition output.' },
57
+ title: { type: 'string', description: 'Worksheet heading; defaults to the workbench title.' },
58
+ grade: { type: 'string', description: 'Optional subject/grade line.' },
59
+ 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.' },
61
+ outputPath: { type: 'string', description: 'Destination .html path; defaults to the current working directory.' },
62
+ language: { type: 'string', enum: ['zh', 'en'], description: 'Worksheet language; defaults to zh.' }
63
+ },
64
+ required: ['text']
65
+ }
66
+ }
67
+ ];
68
+
69
+ const MIME = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif' };
70
+
71
+ const esc = v => String(v).replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
72
+ const marker = /([待核实[^]\n]{0,160}]|\[verify[^\]\n]{0,160}\])/gi;
73
+ const marked = v => esc(v).replace(marker, '<b class="bad">$1</b>');
74
+
75
+ function worksheet(t, state) {
76
+ const lines = v => marked(v).split('\n').map(l => `<div>${l || '&nbsp;'}</div>`).join('');
77
+ const figures = (state.images || []).map((img) => `<figure><img src="${img.data}" alt="${esc(img.name)}"><figcaption>${esc(img.name)}</figcaption></figure>`).join('');
78
+ const notes = state.notes ? `<h2>${esc(t.labelSolution)}</h2><section>${lines(state.notes)}</section>` : '';
79
+ return '<!doctype html><html><head><meta charset="utf-8"><title>' + esc(state.title) + '</title>'
80
+ + '<style>@page{size:A4;margin:16mm}body{font:12pt/1.7 system-ui,sans-serif;color:#161616}h1{font-size:18pt}h2{font-size:13pt;margin-top:16px;border-bottom:1px solid #999}section{white-space:pre-wrap;overflow-wrap:anywhere}figure{break-inside:avoid;margin:14px 0}figure img{max-width:100%;max-height:235mm;object-fit:contain}figcaption{font-size:9pt;color:#666}.bad{color:#b42318;background:#fff0ec}</style></head><body>'
81
+ + '<h1>' + esc(state.title) + '</h1>'
82
+ + (state.grade ? '<p>' + esc(state.grade) + '</p>' : '')
83
+ + '<section>' + lines(state.text || '') + '</section>'
84
+ + figures + notes + '</body></html>';
85
+ }
86
+
87
+ function readImage(file) {
88
+ const ext = path.extname(file).toLowerCase();
89
+ if (!MIME[ext]) throw new Error('unsupported image type: ' + ext);
90
+ const data = fs.readFileSync(file);
91
+ return { name: path.basename(file), data: `data:${MIME[ext]};base64,${data.toString('base64')}` };
92
+ }
93
+
94
+ function callTool(name, args = {}) {
95
+ if (name === 'question_prompt') {
96
+ const mode = args.mode;
97
+ if (!MODES.includes(mode)) throw new Error(`mode must be one of: ${MODES.join(', ')}`);
98
+ const lang = args.language === 'en' ? 'en' : 'zh';
99
+ const text = typeof args.text === 'string' ? args.text.trim() : '';
100
+ if (mode !== 'recognition' && !text) throw new Error('text is required for mode ' + mode);
101
+ return PROMPTS[lang][mode].replace('{text}', text);
102
+ }
103
+ if (name === 'build_worksheet') {
104
+ const lang = args.language === 'en' ? 'en' : 'zh';
105
+ const t = PROMPTS[lang];
106
+ const images = Array.isArray(args.images) ? args.images.map((p) => readImage(path.resolve(p))) : [];
107
+ const title = typeof args.title === 'string' && args.title.trim() ? args.title.trim() : t.worksheetTitle;
108
+ const html = worksheet(t, {
109
+ title,
110
+ grade: typeof args.grade === 'string' ? args.grade : '',
111
+ text: typeof args.text === 'string' ? args.text : '',
112
+ notes: typeof args.notes === 'string' ? args.notes : '',
113
+ images
114
+ });
115
+ const target = args.outputPath
116
+ ? path.resolve(args.outputPath)
117
+ : path.join(process.cwd(), `question-worksheet-${Date.now()}.html`);
118
+ if (path.extname(target).toLowerCase() !== '.html') throw new Error('outputPath must end with .html');
119
+ fs.mkdirSync(path.dirname(target), { recursive: true });
120
+ fs.writeFileSync(target, html, 'utf8');
121
+ return `Worksheet written: ${target} (${Buffer.byteLength(html)} bytes, ${images.length} image(s))`;
122
+ }
123
+ throw new Error('unknown tool: ' + name);
124
+ }
125
+
126
+ function respond(id, result) { send({ jsonrpc: '2.0', id, result }); }
127
+ function fail(id, code, message) { send({ jsonrpc: '2.0', id, error: { code, message } }); }
128
+ function send(obj) { process.stdout.write(JSON.stringify(obj) + '\n'); }
129
+
130
+ function handle(msg) {
131
+ const { id, method, params } = msg;
132
+ if (method === undefined) return; // a response to a server request; none are made
133
+ if (method === 'initialize') {
134
+ const asked = params && params.protocolVersion;
135
+ return respond(id, {
136
+ protocolVersion: PROTOCOLS.includes(asked) ? asked : PROTOCOLS[0],
137
+ capabilities: { tools: {} },
138
+ serverInfo: { name: 'question-workbench-mcp', version: VERSION }
139
+ });
140
+ }
141
+ if (method === 'notifications/initialized' || method === 'initialized') return;
142
+ if (method === 'ping') return respond(id, {});
143
+ if (method === 'tools/list') return respond(id, { tools: TOOLS });
144
+ if (method === 'tools/call') {
145
+ const name = params && params.name;
146
+ const args = (params && params.arguments) || {};
147
+ try {
148
+ const text = callTool(name, args);
149
+ return respond(id, { content: [{ type: 'text', text }], isError: false });
150
+ } catch (e) {
151
+ return respond(id, { content: [{ type: 'text', text: String(e && e.message || e) }], isError: true });
152
+ }
153
+ }
154
+ if (id !== undefined) fail(id, -32601, 'method not found: ' + method);
155
+ }
156
+
157
+ const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
158
+ rl.on('line', (line) => {
159
+ const raw = line.trim();
160
+ if (!raw) return;
161
+ let msg;
162
+ try { msg = JSON.parse(raw); } catch (e) { return fail(null, -32700, 'parse error'); }
163
+ try { handle(msg); } catch (e) { fail(msg && msg.id, -32603, String(e && e.message || e)); }
164
+ });
165
+ process.stderr.write(`question-workbench-mcp ${VERSION} ready (stdio)\n`);