@openbiox/bizard-mcp 0.0.0-stage → 0.1.1

package/dist/http.js

@@ -0,0 +1,109 @@
+import { createServer } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+const RATE_CAPACITY = 60; // requests/min per client IP
+const RATE_INTERVAL_MS = 60_000;
+const BODY_MAX_BYTES = 1_000_000; // JSON-RPC messages are small; reject larger uploads
+/** Trust X-Forwarded-For for client keying (spec §6.2 前置反代). Off by default:
+ *  without a proxy in front, clients could spoof fresh buckets. Read per
+ *  request so a config change takes effect without a restart. */
+function trustProxy() {
+    const v = process.env.BIZARD_TRUST_PROXY;
+    return v === "1" || v === "true";
+}
+/** Client identity for rate limiting: the IP that just handed the request to
+ *  the trusted proxy (rightmost X-Forwarded-For hop) when behind one, else the
+ *  socket address. The leftmost hop is client-controlled and spoofable. */
+function clientIp(req) {
+    if (trustProxy()) {
+        const forwarded = req.headers["x-forwarded-for"];
+        if (typeof forwarded === "string" && forwarded.length > 0) {
+            const hops = forwarded.split(",").map((h) => h.trim()).filter(Boolean);
+            if (hops.length > 0)
+                return hops[hops.length - 1];
+        }
+    }
+    return req.socket.remoteAddress ?? "unknown";
+}
+/**
+ * Stateless Streamable HTTP endpoint (spec §6.2: public anonymous access).
+ * The factory builds one McpServer per POST — the SDK allows a single
+ * transport per server instance, so sharing one across concurrent requests
+ * throws "Already connected to a transport" (and kills the process via an
+ * unhandled rejection). Per-IP token-bucket rate limiting.
+ */
+export function startHttpServer(makeServer, port) {
+    const buckets = new Map();
+    const http = createServer((req, res) => {
+        const ip = clientIp(req);
+        if (!allow(ip, buckets)) {
+            res.writeHead(429, { "Retry-After": "30" });
+            res.end(JSON.stringify({ error: "rate limited" }));
+            return;
+        }
+        if (req.method === "POST" && req.url === "/mcp") {
+            handlePost(makeServer(), req, res).catch((e) => {
+                console.error(`bizard-mcp HTTP: request failed: ${e.message}`);
+                if (res.headersSent)
+                    return;
+                // Oversized uploads are the client's doing — 413, not a server fault.
+                const status = e instanceof BodyTooLargeError ? 413 : 500;
+                res.writeHead(status, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: status === 413 ? "request body too large" : "internal error" }));
+            });
+            return;
+        }
+        res.writeHead(404).end();
+    });
+    http.listen(port, () => {
+        console.error(`bizard-mcp HTTP listening on :${port} (Streamable HTTP, anonymous, rate-limited)`);
+    });
+}
+async function handlePost(server, req, res) {
+    // One stateless transport per request — each POST gets a fresh transport.
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+    res.on("close", () => transport.close());
+    await server.connect(transport);
+    const body = await readBody(req);
+    await transport.handleRequest(req, res, body);
+}
+async function readBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > BODY_MAX_BYTES)
+            throw new BodyTooLargeError();
+        chunks.push(chunk);
+    }
+    const raw = Buffer.concat(chunks).toString("utf-8");
+    try {
+        return JSON.parse(raw || "{}");
+    }
+    catch {
+        return {};
+    }
+}
+class BodyTooLargeError extends Error {
+}
+function allow(ip, buckets) {
+    const now = Date.now();
+    // Opportunistic eviction: a public endpoint sees one-off IPs (spoofed or
+    // scanned); without pruning, the bucket map grows without bound.
+    if (buckets.size >= RATE_CAPACITY) {
+        for (const [key, b] of buckets) {
+            if (now - b.last > RATE_INTERVAL_MS)
+                buckets.delete(key);
+        }
+    }
+    const b = buckets.get(ip) ?? { tokens: RATE_CAPACITY, last: now };
+    const elapsed = now - b.last;
+    b.tokens = Math.min(RATE_CAPACITY, b.tokens + (elapsed / RATE_INTERVAL_MS) * RATE_CAPACITY);
+    b.last = now;
+    if (b.tokens < 1) {
+        buckets.set(ip, b);
+        return false;
+    }
+    b.tokens -= 1;
+    buckets.set(ip, b);
+    return true;
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runCli } from "./entry.js";
+await runCli(process.argv.slice(2));

package/dist/prompts.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerPrompts(server: McpServer): void;

package/dist/prompts.js

@@ -0,0 +1,74 @@
+import { z } from "zod";
+export function registerPrompts(server) {
+    server.registerPrompt("recommend", {
+        title: "Recommend a chart",
+        description: "Clarify the user's visualization goal and recommend Bizard charts.",
+        argsSchema: { goal: z.string().describe("What the user wants to visualize") },
+    }, async ({ goal }) => ({
+        messages: [{
+                role: "user", content: {
+                    type: "text", text: `The user wants to visualize: "${goal}".
+
+1. If the goal is ambiguous, ask at most 2 clarifying questions (data shape, message to convey).
+2. Call bizard_search with 2-3 keyword variants (EN and zh).
+3. Compare the top hits on: data types required, message emphasis, aesthetics.
+4. Recommend ONE chart plus 2 alternatives, with tutorial URLs from the results.
+5. Remind the user that code should be adapted to their data (offer the adapt prompt).`,
+                },
+            }],
+    }));
+    server.registerPrompt("adapt", {
+        title: "Adapt tutorial code",
+        description: "Drive data-aware adaptation of a Bizard tutorial to the user's dataset.",
+        argsSchema: {
+            chartId: z.string().describe("Chart id from bizard_search"),
+            language: z.enum(["r", "python", "julia"]).default("r"),
+        },
+    }, async ({ chartId, language }) => ({
+        messages: [{
+                role: "user", content: {
+                    type: "text", text: `Adapt Bizard chart "${chartId}" to my data using ${language}.
+
+1. Call bizard_adapt_guidance for "${chartId}" (${language}) and follow its five sections in order.
+2. FIRST inspect my data (str/df.info/head) — do not assume column names.
+3. Rewrite the tutorial code from bizard_get_code minimally: only parameter and column changes.
+4. Run the adapted code, show the plot, and self-check against the guidance's failure modes.
+5. If a step fails, switch to the troubleshoot flow before improvising.`,
+                },
+            }],
+    }));
+    server.registerPrompt("troubleshoot", {
+        title: "Troubleshoot reproduction",
+        description: "Classify and fix a chart reproduction failure.",
+        argsSchema: {
+            chartId: z.string().describe("Chart id whose reproduction failed"),
+            error: z.string().max(4000).describe("The error output"),
+        },
+    }, async ({ chartId, error }) => ({
+        messages: [{
+                role: "user", content: {
+                    type: "text", text: `Reproducing Bizard chart "${chartId}" failed with:
+
+${error}
+
+Classify the failure: (a) data shape/content, (b) package/dependency, (c) code/syntax.
+Then: for (a) call bizard_adapt_guidance and fix the data prep; for (b) check the tutorial's Setup list; for (c) diff against bizard_get_code output. Re-run after each fix; report what changed.`,
+                },
+            }],
+    }));
+    server.registerPrompt("contribute", {
+        title: "Contribute back",
+        description: "Turn the current finding into a validated Bizard contribution.",
+    }, async () => ({
+        messages: [{
+                role: "user", content: {
+                    type: "text", text: `Help me contribute to Bizard.
+
+1. Ask which contribution type: new-tutorial (+10), fix (+3), translation (+2), gallery-image (+3).
+2. Draft the content following Template/contribution_0323.md conventions (YAML author, ## Setup, executable code blocks).
+3. Run bizard_contribute_check on the draft; fix all issues.
+4. Call bizard_contribute_submit. If it returns a draft + deep-link (no credentials here), open the link and confirm submission.`,
+                },
+            }],
+    }));
+}

package/dist/resources.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Bundle } from "./types.js";
+export declare function registerResources(server: McpServer, getBundle: () => Bundle | null): void;

package/dist/resources.js

@@ -0,0 +1,36 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { tutorialPayload } from "./tutorial.js";
+import { NO_BUNDLE_ERROR } from "./server.js";
+const LLMS_TXT_PATH = join(dirname(fileURLToPath(import.meta.url)), "snapshot", "llms.txt");
+function textResult(text) {
+    return { contents: [{ uri: "", text }] };
+}
+export function registerResources(server, getBundle) {
+    server.registerResource("catalog", "bizard://catalog", { title: "Chart catalog", description: "Compact JSON of all Bizard charts (id, name, category, URLs).", mimeType: "application/json" }, () => {
+        const bundle = getBundle();
+        if (!bundle)
+            throw new Error(NO_BUNDLE_ERROR);
+        const compact = bundle.charts.map((c) => ({
+            id: c.id, name: c.name, level1: c.level1, level2: c.level2, tutorialUrl: c.tutorialUrl,
+        }));
+        return textResult(JSON.stringify(compact, null, 2));
+    });
+    server.registerResource("tutorial", new ResourceTemplate("bizard://tutorial/{chartId}", { list: undefined }), { title: "Tutorial payload", description: "Full tutorial payload for one chart.", mimeType: "application/json" }, (uri, variables) => {
+        const bundle = getBundle();
+        if (!bundle)
+            throw new Error(NO_BUNDLE_ERROR);
+        const payload = tutorialPayload(bundle, String(variables.chartId));
+        return { contents: [{ uri: uri.href, text: JSON.stringify(payload, null, 2), mimeType: "application/json" }] };
+    });
+    server.registerResource("llms-txt", "bizard://llms-txt", { title: "llms.txt", description: "Bizard llms.txt overview (present only in built snapshots).", mimeType: "text/plain" }, () => {
+        try {
+            return textResult(readFileSync(LLMS_TXT_PATH, "utf-8"));
+        }
+        catch {
+            throw new Error("bizard-mcp: llms.txt not found — run `npm run build:bundle` to generate the snapshot, then rebuild.");
+        }
+    });
+}

package/dist/results.d.ts

@@ -0,0 +1,13 @@
+export declare function jsonResult(payload: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function errorResult(message: string): {
+    isError: true;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};

package/dist/results.js

@@ -0,0 +1,6 @@
+export function jsonResult(payload) {
+    return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+}
+export function errorResult(message) {
+    return { isError: true, content: [{ type: "text", text: message }] };
+}

package/dist/search.d.ts

@@ -0,0 +1,21 @@
+import type { Bundle, Chart } from "./types.js";
+export interface SearchHit {
+    chart: Chart;
+    score: number;
+}
+/** Tokenize a query into lowercase terms; CJK chars become individual terms. */
+export declare function tokenize(query: string): string[];
+/**
+ * Expand query terms via the bundle's synonym table (both directions:
+ * canonical → synonyms and synonyms → canonical) for cross-language reach.
+ */
+export declare function expandTerms(query: string, synonyms: Record<string, string[]>): string[];
+/**
+ * Score charts against expanded terms: name matches weigh most, then type,
+ * then description/levels. Deterministic; no LLM.
+ */
+export declare function searchCharts(bundle: Bundle, query: string, opts?: {
+    category?: string;
+}): SearchHit[];
+/** Zero-hit fallback: top-3 charts from the same Level1 category as best type guess. */
+export declare function adjacentSuggestions(bundle: Bundle, query: string, limit?: number): Chart[];

package/dist/search.js

@@ -0,0 +1,64 @@
+/** Tokenize a query into lowercase terms; CJK chars become individual terms. */
+export function tokenize(query) {
+    return query
+        .toLowerCase()
+        .split(/[\s,，。;；:、!！?？()（）]+/)
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0);
+}
+/**
+ * Expand query terms via the bundle's synonym table (both directions:
+ * canonical → synonyms and synonyms → canonical) for cross-language reach.
+ */
+export function expandTerms(query, synonyms) {
+    const terms = new Set();
+    for (const raw of tokenize(query)) {
+        terms.add(raw);
+        for (const [canon, syns] of Object.entries(synonyms)) {
+            const all = [canon, ...syns].map((s) => s.toLowerCase());
+            if (all.includes(raw)) {
+                for (const s of all)
+                    terms.add(s);
+            }
+        }
+    }
+    return [...terms];
+}
+/** Null-safe lowercase-includes: a chart field lost to a malformed CSV row never crashes scoring. */
+const contains = (field, term) => typeof field === "string" && field.toLowerCase().includes(term);
+/**
+ * Score charts against expanded terms: name matches weigh most, then type,
+ * then description/levels. Deterministic; no LLM.
+ */
+export function searchCharts(bundle, query, opts) {
+    const terms = expandTerms(query, bundle.keywords?.synonyms ?? {});
+    const hits = [];
+    for (const chart of bundle.charts) {
+        if (opts?.category && opts.category !== chart.level2)
+            continue;
+        let score = 0;
+        for (const term of terms) {
+            if (contains(chart.name, term))
+                score += 5;
+            if (contains(chart.nameZh, term))
+                score += 5;
+            if (contains(chart.type, term))
+                score += 3;
+            if (contains(chart.description, term))
+                score += 2;
+            if (contains(chart.level2, term))
+                score += 3;
+        }
+        if (score > 0)
+            hits.push({ chart, score });
+    }
+    return hits.sort((a, b) => b.score - a.score || a.chart.id.localeCompare(b.chart.id));
+}
+/** Zero-hit fallback: top-3 charts from the same Level1 category as best type guess. */
+export function adjacentSuggestions(bundle, query, limit = 3) {
+    const terms = expandTerms(query, bundle.keywords?.synonyms ?? {});
+    const level1 = bundle.charts.find((c) => terms.some((t) => contains(c.level2, t) || contains(c.type, t)))?.level1;
+    if (!level1)
+        return bundle.charts.slice(0, limit);
+    return bundle.charts.filter((c) => c.level1 === level1).slice(0, limit);
+}

package/dist/server.d.ts

@@ -0,0 +1,18 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Bundle } from "./types.js";
+import type { CredentialEnv } from "./contribute.js";
+import type { NoticeQueue } from "./update-check.js";
+export declare const NO_BUNDLE_ERROR: string;
+/** Anything that can hand back a Bundle or null (snapshot today, ETag re-check later). */
+export interface BundleHolder {
+    get(): Bundle | null;
+}
+export declare function createBizardServer(source: Bundle | BundleHolder | null, notices?: NoticeQueue, opts?: {
+    credentialEnv?: CredentialEnv;
+}): McpServer;
+export declare function searchTool(bundle: Bundle, query: string, language: "en" | "zh", category?: string, limit?: number, note?: string | null): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};

package/dist/server.js

@@ -0,0 +1,115 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { adjacentSuggestions, searchCharts } from "./search.js";
+import { registerTutorialTools } from "./tutorial-tools.js";
+import { registerAdaptTools } from "./adapt-tools.js";
+import { registerContributeTools } from "./contribute-tools.js";
+import { registerPrompts } from "./prompts.js";
+import { registerResources } from "./resources.js";
+import { updateNotice } from "./update-check.js";
+import { recordUsage } from "./usage.js";
+const SEARCH_LIMIT_MAX = 20;
+const QUERY_MAX_CHARS = 4000;
+export const NO_BUNDLE_ERROR = "bizard-mcp: bundle snapshot unavailable. The maintainer must run " +
+    "`npm run build:bundle` (or CI) to generate src/snapshot/bundle.json, then rebuild.";
+function json(value, note) {
+    const payload = note === null || note === undefined
+        ? { ...value }
+        : { note, ...value };
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify(payload, null, 2),
+            }],
+    };
+}
+function bundleError() {
+    return {
+        isError: true,
+        content: [{ type: "text", text: NO_BUNDLE_ERROR }],
+    };
+}
+/** Constant server identity — never derives from bundle state. */
+const SERVER_IDENTITY = { name: "bizard-mcp", version: "0.1.1" };
+export function createBizardServer(source, notices, opts) {
+    const getBundle = () => {
+        if (source === null)
+            return null;
+        if ("get" in source && typeof source.get === "function")
+            return source.get();
+        return source;
+    };
+    // One-time SFL notice (spec §3.4): consumed by the first tool result after an update swap.
+    const drainNotice = () => (notices ? updateNotice(notices) : null);
+    // Local-only, anonymous usage feedback (README Privacy): fire-and-forget — a
+    // logging failure must never fail the tool call it observes. Each handler
+    // passes its event only after the payload was built successfully.
+    const track = (ev) => {
+        void recordUsage(ev).catch(() => { });
+    };
+    const server = new McpServer(SERVER_IDENTITY);
+    server.registerTool("bizard_search", {
+        title: "Search Bizard chart tutorials",
+        description: "Search the Bizard atlas (800+ biomedical chart tutorials, EN/zh) by keyword. Returns chart cards with tutorial URLs and image previews.",
+        inputSchema: {
+            query: z.string().max(QUERY_MAX_CHARS).describe("Search keywords, English or Chinese"),
+            language: z.enum(["en", "zh"]).default("en").describe("Preferred result language"),
+            category: z.string().optional().describe("Filter by category (from bizard_list_categories)"),
+            limit: z.number().int().min(1).max(SEARCH_LIMIT_MAX).default(5),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ query, language, category, limit }) => {
+        const bundle = getBundle();
+        if (!bundle)
+            return bundleError();
+        track({ event: "search", language, query });
+        return searchTool(bundle, query, language, category, limit, drainNotice());
+    });
+    server.registerTool("bizard_list_categories", {
+        title: "List Bizard categories",
+        description: "List all Bizard chart categories (bilingual) with per-category chart counts.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async () => {
+        const bundle = getBundle();
+        if (!bundle)
+            return bundleError();
+        return categoriesTool(bundle, drainNotice());
+    });
+    const lazyBundle = {
+        get: () => {
+            const bundle = getBundle();
+            if (!bundle)
+                throw new Error(NO_BUNDLE_ERROR);
+            return bundle;
+        },
+    };
+    registerTutorialTools(server, lazyBundle, track);
+    registerAdaptTools(server, lazyBundle, track);
+    registerContributeTools(server, opts?.credentialEnv);
+    registerPrompts(server);
+    registerResources(server, getBundle);
+    return server;
+}
+export function searchTool(bundle, query, language, category, limit = 5, note = null) {
+    const hits = searchCharts(bundle, query, { category });
+    const nameOf = (c) => (language === "zh" ? c.nameZh ?? c.name : c.name);
+    const urlOf = (c) => (language === "zh" ? c.tutorialUrlZh ?? c.tutorialUrl : c.tutorialUrl);
+    const cards = hits.slice(0, limit).map(({ chart }) => ({
+        id: chart.id,
+        name: nameOf(chart),
+        type: chart.type,
+        imageUrl: chart.imageUrl,
+        tutorialUrl: urlOf(chart),
+        description: chart.description,
+    }));
+    if (cards.length > 0)
+        return json({ results: cards }, note);
+    const near = adjacentSuggestions(bundle, query).map((c) => ({
+        id: c.id, name: nameOf(c), tutorialUrl: urlOf(c),
+    }));
+    return json({ results: [], suggestions: near, note: note ?? "No exact matches. Nearby charts in the closest category:" });
+}
+function categoriesTool(bundle, note = null) {
+    return json(bundle.categories, note);
+}