dsh-deeptutor 0.2.1 → 0.3.1

package/lib/index.js

@@ -1,11 +1,9 @@
 import { defineTool } from "@deepseek-ai/dsh-tools";
-import { CAPABILITIES, configGuide, configHint, SSH_HOST, truncate } from "./config.js";
-import { cliNoteLocal, cliNoteRemote, runCli } from "./cli-exec.js";
-import { renderHtml } from "./html-render.js";
-import { cliRunTurn, fmtTurnResult } from "./turn.js";
 import { HTML_DOC_SCRIPT } from "./html-render.js";
+import { TOOLS } from "./tools.js";
 export const name = "dsh-deeptutor";
 export const inject = ["tools"];
+/** Drop undefined values so the canonical JSON value stays lossless-JSON. */
 function json(o) {
     const out = {};
     for (const [k, v] of Object.entries(o))
@@ -13,285 +11,25 @@ function json(o) {
             out[k] = v;
     return out;
 }
+const OUTPUT = {
+    schema: {
+        type: "object",
+        properties: { text: { type: "string" } },
+        additionalProperties: true,
+    },
+    render: (_args, value) => [{ type: "text", text: value.text ?? "" }],
+};
 export function apply(ctx) {
     console.log(`[dsh-deeptutor] plugin loaded (html script: ${HTML_DOC_SCRIPT})`);
-    // ---------- Tool 1: run a DeepTutor learning capability ----------
-    ctx.tools.register(defineTool({
-        name: "deeptutor_run",
-        description: "Execute one learning call on the DeepTutor service: deep_solve (in-depth explanation), deep_question (generate self-test questions), deep_research (deep research), chat (conversation), mastery_path (learning path planning), visualize / math_animator (visualization). Can mount knowledge bases (kbs) and tools (tools like rag / web_search). Returns the final answer plus session_id; pass session_id in later turns to continue the context (inherits chat history, knowledge bases and tools).",
-        parameters: {
-            capability: {
-                type: "string",
-                enum: [...CAPABILITIES],
-                required: true,
-                description: "The learning capability to run",
-            },
-            prompt: {
-                type: "string",
-                required: true,
-                description: "The learning question or instruction for this turn (e.g. explain the async/await state machine)",
-            },
-            kbs: {
-                type: "array",
-                items: { type: "string" },
-                description: "Knowledge base names (check deeptutor_kb list for available ones, e.g. the user's dotnet/sqlserver bases)",
-            },
-            tools: {
-                type: "array",
-                items: { type: "string" },
-                description: "Tools to enable: rag (KB retrieval), web_search, reason, brainstorm, paper_search, code_execution, read_source, etc.",
-            },
-            session_id: {
-                type: "string",
-                description: "Session ID from a previous deeptutor_run call to continue that context",
-            },
-            config: {
-                type: "object",
-                additionalProperties: true,
-                description: "Capability config key-values, e.g. num_questions=5 for deep_question, mode=report / depth=standard for deep_research",
-            },
-            language: {
-                type: "string",
-                description: "Response language code, default en; use zh for Chinese",
-            },
-            timeout: {
-                type: "number",
-                description: "Timeout in seconds, default 600; use 900+ for deep_research",
-            },
-            max_chars: {
-                type: "number",
-                description: "Max characters of the answer returned to the model, default 30000",
-            },
-            html: {
-                type: "string",
-                description: "Optional output path for a self-contained local HTML render of the answer (bundled md-to-html converter; also writes the companion .md source next to it). e.g. data/study/abstract-class/knowledge.html — open the HTML in a browser to read comfortably. Set it when the user wants browsable/printable study material.",
-            },
-            html_title: {
-                type: "string",
-                description: "HTML page title (default: derived from the html output file name)",
-            },
-        },
-        output: {
-            schema: {
-                type: "object",
-                properties: {
-                    mode: { type: "string" },
-                    sessionId: { type: "string" },
-                    answer: { type: "string" },
-                    toolCalls: { type: "array", items: { type: "string" } },
-                    errors: { type: "array", items: { type: "string" } },
-                    text: { type: "string" },
-                },
-                additionalProperties: true,
-            },
-            render: (_args, value) => [{ type: "text", text: value.text ?? "" }],
-        },
-        async execute(args, exec) {
-            const timeoutMs = (args.timeout ?? 600) * 1000;
-            const maxChars = args.max_chars ?? 30000;
-            try {
-                const r = await cliRunTurn(args, timeoutMs, exec.signal);
-                const htmlNote = await renderHtml(args, r.answer);
-                return json({
-                    mode: "cli",
-                    sessionId: r.sessionId,
-                    toolCalls: r.toolCalls,
-                    errors: r.errors,
-                    text: configHint() + fmtTurnResult(args.capability, r, maxChars) + htmlNote,
-                });
-            }
-            catch (err) {
-                if (exec.signal.aborted) {
-                    // user cancelled mid-CLI-run: report it as a cancellation, not a failure
-                    throw new Error("[deeptutor_run cancelled]");
-                }
-                throw new Error(configGuide() +
-                    `[deeptutor_run failed] ${err?.message ?? String(err)}`);
-            }
-        },
-    }));
-    // ---------- Tool 2: knowledge base operations ----------
-    ctx.tools.register(defineTool({
-        name: "deeptutor_kb",
-        description: "Manage/search DeepTutor knowledge bases: list all bases, search inside a base (RAG hit snippets), info for details. Works in both local and remote deployments. Search the user's personal knowledge bases before generating learning content and combine the hits with authoritative sources.",
-        parameters: {
-            action: {
-                type: "string",
-                enum: ["list", "search", "info"],
-                required: true,
-                description: "What to do with the knowledge bases",
-            },
-            kb: {
-                type: "string",
-                description: "Knowledge base name (required for search/info)",
-            },
-            query: {
-                type: "string",
-                description: "Search question (required for search, e.g. C# generics covariance/contravariance)",
-            },
-            mode: {
-                type: "string",
-                enum: ["hybrid", "dense", "sparse"],
-                description: "Retrieval mode, default hybrid",
-            },
-            top_k: {
-                type: "number",
-                description: "Number of hits to return, default 5 (applied locally to the CLI search result; the deeptutor CLI has no --top-k flag)",
-            },
-            max_chars: {
-                type: "number",
-                description: "Max characters of the returned content, default 30000",
-            },
-        },
-        output: {
-            schema: {
-                type: "object",
-                properties: {
-                    action: { type: "string" },
-                    mode: { type: "string" },
-                    kb: { type: "string" },
-                    query: { type: "string" },
-                    text: { type: "string" },
-                },
-                additionalProperties: true,
-            },
-            render: (_args, value) => [{ type: "text", text: value.text ?? "" }],
-        },
-        async execute(args, exec) {
-            const maxChars = args.max_chars ?? 30000;
-            // Local or SSH CLI. NOTE: `kb search` has no --top-k flag
-            // (verified on deeptutor CLI 1.5.x); top_k is applied locally below.
-            let argv;
-            if (args.action === "list") {
-                argv = ["kb", "list", "--format", "json"];
-            }
-            else if (args.action === "info") {
-                argv = ["kb", "info", args.kb ?? ""];
-            }
-            else {
-                argv = [
-                    "kb",
-                    "search",
-                    args.kb ?? "",
-                    args.query ?? "",
-                    "--format",
-                    "json",
-                    "--mode",
-                    args.mode ?? "hybrid",
-                ];
-            }
-            const { stdout, stderr, code, killed } = await runCli(argv, {
-                signal: exec.signal,
-                timeoutMs: 90_000,
-            });
-            if (killed)
-                throw new Error(configGuide() + "[deeptutor_kb timed out]");
-            if (code !== 0) {
-                throw new Error(`[deeptutor_kb failed] exit=${code}\nstderr: ${truncate(stderr || "(none)", 2000)}` +
-                    configGuide());
-            }
-            let body = stdout.trim() || "(empty result)";
-            if (args.action === "search") {
-                try {
-                    const parsed = JSON.parse(stdout);
-                    const fmtHit = (s, i) => {
-                        const text = s.text ?? s.content ?? s.snippet ?? JSON.stringify(s);
-                        const src = s.source ?? s.doc_name ?? s.file ?? "";
-                        const title = s.title ? `  title: ${s.title}` : "";
-                        const score = typeof s.score === "number" ? `  score: ${s.score}` : "";
-                        return `[${i + 1}]${src ? `  source: ${src}` : ""}${title}${score}\n${typeof text === "string" ? text : JSON.stringify(text)}`;
-                    };
-                    // Current deeptutor CLI (1.5.x) returns an object
-                    // { query, answer, content, sources, provider }; older builds
-                    // returned a bare array of hits. Accept both.
-                    if (Array.isArray(parsed)) {
-                        const hits = args.top_k ? parsed.slice(0, args.top_k) : parsed;
-                        body = `${hits.length} hits:\n\n` + hits.map(fmtHit).join("\n\n");
-                    }
-                    else if (parsed && typeof parsed === "object") {
-                        const parts = [];
-                        if (parsed.query)
-                            parts.push(`Query: ${parsed.query}`);
-                        if (typeof parsed.answer === "string" && parsed.answer.trim())
-                            parts.push(`Answer: ${parsed.answer.trim()}`);
-                        const sources = Array.isArray(parsed.sources) ? parsed.sources : [];
-                        const hits = args.top_k ? sources.slice(0, args.top_k) : sources;
-                        parts.push(`${hits.length} hits:`);
-                        parts.push(hits.map(fmtHit).join("\n\n"));
-                        body = parts.join("\n\n");
-                    }
-                }
-                catch {
-                    /* non-JSON output returned as-is */
-                }
-            }
-            return json({
-                action: args.action,
-                mode: "cli",
-                kb: args.kb,
-                query: args.query,
-                text: truncate(body, maxChars),
-            });
-        },
-    }));
-    // ---------- Tool 3: archive learning notes to a server notebook ----------
-    ctx.tools.register(defineTool({
-        name: "deeptutor_note",
-        description: "Archive a Markdown learning note (study plan, deep-solve summary, wrong answers, etc.) to a DeepTutor notebook (auto-creates the notebook if missing). Record type: chat / question / research / solve.",
-        parameters: {
-            notebook: {
-                type: "string",
-                required: true,
-                description: "Notebook name, e.g. dotnet-learning (auto-created if missing)",
-            },
-            title: {
-                type: "string",
-                required: true,
-                description: "Record title, e.g. async/await state machine deep-dive notes",
-            },
-            type: {
-                type: "string",
-                enum: ["chat", "question", "research", "solve"],
-                description: "Record type, default chat",
-            },
-            content: {
-                type: "string",
-                required: true,
-                description: "Learning note content in Markdown",
-            },
-        },
-        output: {
-            schema: {
-                type: "object",
-                properties: {
-                    notebook: { type: "string" },
-                    nbId: { type: "string" },
-                    title: { type: "string" },
-                    mode: { type: "string" },
-                    text: { type: "string" },
-                },
-                additionalProperties: true,
-            },
-            render: (_args, value) => [{ type: "text", text: value.text ?? "" }],
-        },
-        async execute(args, exec) {
-            const recordType = (args.type ?? "chat");
-            const nbName = args.notebook.trim();
-            // Remote deployment runs the PY_NOTE script on the server; local deployment runs locally
-            const { stdout, stderr, code } = SSH_HOST
-                ? await cliNoteRemote(nbName, args.title, recordType, args.content, exec.signal)
-                : await cliNoteLocal(nbName, args.title, recordType, args.content, exec.signal);
-            if (code !== 0) {
-                throw new Error(`[deeptutor_note failed] exit=${code}\n${truncate(stderr || stdout, 2000)}` +
-                    configGuide());
-            }
-            return json({
-                notebook: nbName,
-                title: args.title,
-                mode: "cli",
-                text: configHint() +
-                    `[note archived] notebook=${nbName}, title=${args.title}, type=${recordType}\n${truncate((stdout ?? "").trim(), 2000)}`,
-            });
-        },
-    }));
+    for (const tool of TOOLS) {
+        ctx.tools.register(defineTool({
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.parameters,
+            output: OUTPUT,
+            async execute(args, exec) {
+                return json(await tool.execute(args, exec.signal));
+            },
+        }));
+    }
 }

package/lib/mcp-main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/lib/mcp-main.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * Entry point of the `dsh-deeptutor-mcp` bin: the DeepTutor tools as an MCP
+ * stdio server (Claude Code, Codex and other MCP clients).
+ */
+import { startStdioServer } from "./mcp.js";
+startStdioServer();

package/lib/mcp.d.ts

@@ -0,0 +1,25 @@
+import { type ToolSpec } from "./tools.ts";
+type Id = string | number;
+interface Message {
+    jsonrpc?: string;
+    id?: Id | null;
+    method?: string;
+    params?: any;
+}
+export interface McpServerOptions {
+    tools?: readonly ToolSpec[];
+    /** Writes one serialized message (without the trailing newline). */
+    send: (line: string) => void;
+    log?: (msg: string) => void;
+}
+/**
+ * Transport-free MCP message handler. `handle` takes one parsed message and
+ * resolves once any response has been sent. Exported for tests.
+ */
+export declare function createMcpHandler(opts: McpServerOptions): {
+    handle: (msg: Message) => Promise<void>;
+    inflight: Map<Id, AbortController>;
+};
+/** Run the server on this process's stdin/stdout until stdin closes. */
+export declare function startStdioServer(): void;
+export {};

package/lib/mcp.js

@@ -0,0 +1,133 @@
+/**
+ * DeepTutor bridge: Model Context Protocol server over stdio.
+ *
+ * Serves the same tools as the dsh plugin (src/tools.ts) to MCP clients such as
+ * Claude Code. Hand-rolled on purpose: the protocol surface a tools-only server
+ * needs is small (initialize, ping, tools/list, tools/call, cancellation), and
+ * keeping it in-house preserves the package's zero runtime dependencies.
+ *
+ * Transport: newline-delimited JSON-RPC 2.0 on stdin/stdout. stdout carries
+ * protocol messages only; diagnostics go to stderr.
+ */
+import { readFileSync } from "node:fs";
+import { createInterface } from "node:readline";
+import { TOOLS, toJsonSchema, validateArgs } from "./tools.js";
+const SUPPORTED_PROTOCOLS = ["2024-11-05", "2025-03-26", "2025-06-18"];
+const LATEST_PROTOCOL = SUPPORTED_PROTOCOLS[SUPPORTED_PROTOCOLS.length - 1];
+const INSTRUCTIONS = "DeepTutor learning tools. Explain topics with deeptutor_run (deep_solve, deep_question, …), " +
+    "search the user's knowledge bases with deeptutor_kb before answering from memory, archive notes " +
+    "with deeptutor_note only on request, and reach every other DeepTutor CLI command through " +
+    "deeptutor_cli, discovering commands with args=[\"--help\"] rather than guessing.";
+function packageVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+/**
+ * Transport-free MCP message handler. `handle` takes one parsed message and
+ * resolves once any response has been sent. Exported for tests.
+ */
+export function createMcpHandler(opts) {
+    const tools = opts.tools ?? TOOLS;
+    const byName = new Map(tools.map((t) => [t.name, t]));
+    const inflight = new Map();
+    const log = opts.log ?? (() => { });
+    const reply = (id, result) => opts.send(JSON.stringify({ jsonrpc: "2.0", id, result }));
+    const fail = (id, code, message) => opts.send(JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } }));
+    async function callTool(id, params) {
+        const tool = byName.get(params?.name);
+        if (!tool)
+            return fail(id, -32602, `Unknown tool: ${String(params?.name)}`);
+        const args = params?.arguments && typeof params.arguments === "object" ? params.arguments : {};
+        const problems = validateArgs(tool.parameters, args);
+        if (problems.length) {
+            return reply(id, { content: [{ type: "text", text: `[${tool.name}] ${problems.join("; ")}` }], isError: true });
+        }
+        const ac = new AbortController();
+        inflight.set(id, ac);
+        try {
+            const { text, ...data } = await tool.execute(args, ac.signal);
+            const structured = Object.fromEntries(Object.entries(data).filter(([, v]) => v !== undefined));
+            if (ac.signal.aborted)
+                return; // cancelled: the client no longer expects a response
+            reply(id, { content: [{ type: "text", text }], structuredContent: { text, ...structured } });
+        }
+        catch (err) {
+            if (ac.signal.aborted)
+                return;
+            reply(id, { content: [{ type: "text", text: err?.message ?? String(err) }], isError: true });
+        }
+        finally {
+            inflight.delete(id);
+        }
+    }
+    async function handle(msg) {
+        if (!msg || typeof msg !== "object" || typeof msg.method !== "string") {
+            // Responses to requests we never send, or garbage: ignore.
+            return;
+        }
+        const isRequest = msg.id !== undefined && msg.id !== null;
+        if (!isRequest) {
+            if (msg.method === "notifications/cancelled")
+                inflight.get(msg.params?.requestId)?.abort();
+            return;
+        }
+        const id = msg.id;
+        switch (msg.method) {
+            case "initialize": {
+                const asked = msg.params?.protocolVersion;
+                reply(id, {
+                    protocolVersion: SUPPORTED_PROTOCOLS.includes(asked) ? asked : LATEST_PROTOCOL,
+                    capabilities: { tools: { listChanged: false } },
+                    serverInfo: { name: "dsh-deeptutor", version: packageVersion() },
+                    instructions: INSTRUCTIONS,
+                });
+                return;
+            }
+            case "ping":
+                reply(id, {});
+                return;
+            case "tools/list":
+                reply(id, {
+                    tools: tools.map((t) => ({
+                        name: t.name,
+                        description: t.description,
+                        inputSchema: toJsonSchema(t.parameters),
+                    })),
+                });
+                return;
+            case "tools/call":
+                await callTool(id, msg.params);
+                return;
+            default:
+                log(`unsupported method: ${msg.method}`);
+                fail(id, -32601, `Method not found: ${msg.method}`);
+        }
+    }
+    return { handle, inflight };
+}
+/** Run the server on this process's stdin/stdout until stdin closes. */
+export function startStdioServer() {
+    const log = (m) => process.stderr.write(`[dsh-deeptutor mcp] ${m}\n`);
+    const { handle } = createMcpHandler({ send: (line) => process.stdout.write(line + "\n"), log });
+    const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+    rl.on("line", (line) => {
+        if (!line.trim())
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } }) + "\n");
+            return;
+        }
+        handle(msg).catch((err) => log(`handler error: ${err?.stack ?? err}`));
+    });
+    rl.on("close", () => process.exit(0));
+    log(`ready (v${packageVersion()}, ${process.env.DEEPTUTOR_SSH_HOST ? `remote via ${process.env.DEEPTUTOR_SSH_HOST}` : "local CLI"})`);
+}

package/lib/tools.d.ts

@@ -0,0 +1,52 @@
+interface Base {
+    description: string;
+    required?: true;
+}
+export type ParamSpec = (Base & {
+    type: "string";
+    enum?: readonly string[];
+}) | (Base & {
+    type: "number";
+}) | (Base & {
+    type: "boolean";
+}) | (Base & {
+    type: "array";
+    items: {
+        type: "string";
+    };
+}) | (Base & {
+    type: "object";
+    additionalProperties: true;
+});
+export type ParamsSpec = Record<string, ParamSpec>;
+export interface ToolResultData {
+    /** Text shown to the model. */
+    text: string;
+    /** Structured extras (session id, tool calls…); undefined values are dropped. */
+    [key: string]: unknown;
+}
+export interface ToolSpec {
+    name: string;
+    description: string;
+    parameters: ParamsSpec;
+    /** Throws an Error whose message is shown to the model on failure. */
+    execute(args: Record<string, any>, signal: AbortSignal): Promise<ToolResultData>;
+}
+/** Plain JSON Schema (object) for one tool's parameters. Pure. */
+export declare function toJsonSchema(params: ParamsSpec): {
+    type: "object";
+    properties: Record<string, unknown>;
+    required: string[];
+    additionalProperties: false;
+};
+/** Required-parameter and basic type check (MCP clients may skip schema validation). Pure. */
+export declare function validateArgs(params: ParamsSpec, args: Record<string, unknown>): string[];
+/** Format `kb search --format json` output; undefined when it is not JSON. Exported for tests. */
+export declare function formatSearch(stdout: string, topK?: number): string | undefined;
+/**
+ * Rich pads every line to the terminal width; drop that padding and blank-line
+ * runs so wide output does not waste the model's context. Pure; exported for tests.
+ */
+export declare function tidyOutput(s: string): string;
+export declare const TOOLS: readonly ToolSpec[];
+export {};