@openbiox/bizard-mcp 0.0.0-stage → 0.1.1

package/dist/tutorial-tools.d.ts

@@ -0,0 +1,10 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Bundle } from "./types.js";
+import type { UsageEvent } from "./usage.js";
+/** Lazy bundle access so degraded mode (null snapshot) surfaces as a tool error, not a crash. */
+export interface LazyBundle {
+    get(): Bundle;
+}
+/** Fire-and-forget usage tracker (local anonymous JSONL, README Privacy). */
+export type UsageTracker = (ev: UsageEvent) => void;
+export declare function registerTutorialTools(server: McpServer, bundle: LazyBundle, track: UsageTracker): void;

package/dist/tutorial-tools.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { tutorialPayload, codePayload } from "./tutorial.js";
+import { jsonResult, errorResult } from "./results.js";
+export function registerTutorialTools(server, bundle, track) {
+    server.registerTool("bizard_get_tutorial", {
+        title: "Get tutorial structure",
+        description: "Structured tutorial content: dependencies, example data URLs, languages available, and tutorial link.",
+        inputSchema: { chartId: z.string() },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ chartId }) => {
+        try {
+            const payload = tutorialPayload(bundle.get(), chartId);
+            track({ event: "view", chartId });
+            return jsonResult(payload);
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+    server.registerTool("bizard_get_code", {
+        title: "Get runnable chart code",
+        description: "Runnable code for one chart in R, Python, or Julia with package list and example-data URLs.",
+        inputSchema: {
+            chartId: z.string(),
+            language: z.enum(["r", "python", "julia"]),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ chartId, language }) => {
+        try {
+            const payload = codePayload(bundle.get(), chartId, language);
+            track({ event: "view", chartId, language });
+            return jsonResult(payload);
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+}

package/dist/tutorial.d.ts

@@ -0,0 +1,31 @@
+import type { Bundle, Chart, CodeSnippet } from "./types.js";
+export declare function findChart(bundle: Bundle, id: string): Chart | undefined;
+export declare function snippetsFor(bundle: Bundle, chartId: string): CodeSnippet[];
+export declare function tutorialPayload(bundle: Bundle, chartId: string): {
+    id: string;
+    name: string;
+    nameZh: string | null;
+    description: string;
+    tutorialUrl: string;
+    tutorialUrlZh: string | null;
+    imageUrl: string;
+    packages: string[];
+    dataUrls: string[];
+    languages: string[];
+    snippetCount: number;
+};
+export declare function codePayload(bundle: Bundle, chartId: string, language: "r" | "python" | "julia"): {
+    code: null;
+    packages: never[];
+    dataUrls: never[];
+    license: string;
+    message: string;
+    tutorialUrl: string;
+} | {
+    code: string;
+    packages: string[];
+    dataUrls: string[];
+    license: string;
+    message: null;
+    tutorialUrl?: undefined;
+};

package/dist/tutorial.js

@@ -0,0 +1,53 @@
+const LICENSE_NOTE = "CC-BY-NC-4.0: non-commercial use with attribution. Cite Bizard (see bizard_cite).";
+export function findChart(bundle, id) {
+    const lower = id.toLowerCase();
+    return bundle.charts.find((c) => c.id.toLowerCase() === lower);
+}
+export function snippetsFor(bundle, chartId) {
+    return bundle.codeSnippets.filter((s) => s.chartId === chartId);
+}
+export function tutorialPayload(bundle, chartId) {
+    const chart = findChart(bundle, chartId);
+    if (!chart)
+        throw new Error(`Unknown chartId: ${chartId}`);
+    const snips = snippetsFor(bundle, chart.id);
+    return {
+        id: chart.id,
+        name: chart.name,
+        nameZh: chart.nameZh,
+        description: chart.description,
+        tutorialUrl: chart.tutorialUrl,
+        tutorialUrlZh: chart.tutorialUrlZh,
+        imageUrl: chart.imageUrl,
+        packages: [...new Set(snips.flatMap((s) => s.packages))],
+        dataUrls: [...new Set(snips.flatMap((s) => s.dataUrls))],
+        languages: chart.codeRefs,
+        snippetCount: snips.length,
+    };
+}
+export function codePayload(bundle, chartId, language) {
+    const chart = findChart(bundle, chartId);
+    if (!chart)
+        throw new Error(`Unknown chartId: ${chartId}`);
+    const snips = snippetsFor(bundle, chart.id).filter((s) => s.lang === language);
+    if (chart.codeRefs.length === 0) {
+        return {
+            code: null,
+            packages: [],
+            dataUrls: [],
+            license: LICENSE_NOTE,
+            message: `This tutorial has no structured code. Full tutorial: ${chart.tutorialUrl}`,
+            tutorialUrl: chart.tutorialUrl,
+        };
+    }
+    if (snips.length === 0) {
+        throw new Error(`No ${language} code for ${chartId}. Available languages: ${chart.codeRefs.join(", ")}.`);
+    }
+    return {
+        code: snips.map((s) => s.code).join("\n\n"),
+        packages: [...new Set(snips.flatMap((s) => s.packages))],
+        dataUrls: [...new Set(snips.flatMap((s) => s.dataUrls))],
+        license: LICENSE_NOTE,
+        message: null,
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,49 @@
+export interface BundleMeta {
+    siteVersion: string;
+    bundleVersion: number;
+    generatedAt: string;
+    license: string;
+}
+export interface Category {
+    name: string;
+    nameZh: string | null;
+    count: number;
+}
+export interface Chart {
+    id: string;
+    name: string;
+    nameZh: string | null;
+    type: string;
+    level1: string;
+    level2: string;
+    tutorialUrl: string;
+    tutorialUrlZh: string | null;
+    imageUrl: string;
+    description: string;
+    codeRefs: string[];
+}
+export interface CodeSnippet {
+    chartId: string;
+    lang: "r" | "python" | "julia";
+    code: string;
+    packages: string[];
+    dataUrls: string[];
+    sourceAnchor: string;
+}
+export interface Citation {
+    paperDoi: string;
+    paperUrl: string;
+    bibtex: string;
+    license: string;
+}
+export interface Bundle {
+    meta: BundleMeta;
+    categories: Category[];
+    charts: Chart[];
+    codeSnippets: CodeSnippet[];
+    keywords: {
+        synonyms: Record<string, string[]>;
+        intentKeywords: Record<string, string[]>;
+    } | null;
+    citation: Citation;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/update-check.d.ts

@@ -0,0 +1,24 @@
+import type { Bundle } from "./types.js";
+/** CI publishes the bundle here (mcp-bundle.yml → files/mcp/bundle.json on main). */
+export declare const REMOTE_BUNDLE_URL = "https://openbiox.github.io/Bizard/files/mcp/bundle.json";
+/** Mutable cell the server reads per-call; the update check hot-swaps its contents. */
+export interface MutableHolder {
+    bundle: Bundle | null;
+    etag: string | null;
+}
+export type NoticeQueue = string[];
+export interface UpdateCheckDeps {
+    fetch?: typeof fetch;
+    onSwap?: (bundle: Bundle, etag: string) => void;
+    notices: NoticeQueue;
+    stderr?: (line: string) => void;
+}
+export declare function createNoticeQueue(): NoticeQueue;
+export declare function updateNotice(notices: NoticeQueue): string | null;
+/**
+ * Spec §3.4: background HEAD of the remote bundle comparing ETag; on change, GET +
+ * validate + hot-swap, queueing a ONE-TIME notice for the session's next tool result.
+ * Offline / network / validation failure: silent fallback to the in-memory snapshot,
+ * one stderr line, never throws.
+ */
+export declare function checkForUpdate(holder: MutableHolder, deps: UpdateCheckDeps): Promise<boolean>;

package/dist/update-check.js

@@ -0,0 +1,49 @@
+import { loadBundle } from "./bundle.js";
+/** CI publishes the bundle here (mcp-bundle.yml → files/mcp/bundle.json on main). */
+export const REMOTE_BUNDLE_URL = "https://openbiox.github.io/Bizard/files/mcp/bundle.json";
+function diffCounts(oldB, newB) {
+    if (!oldB)
+        return { added: newB.charts.length, updated: 0 };
+    const oldIds = new Set(oldB.charts.map((c) => c.id));
+    let shared = 0;
+    for (const c of newB.charts)
+        if (oldIds.has(c.id))
+            shared += 1;
+    return { added: newB.charts.length - shared, updated: shared };
+}
+export function createNoticeQueue() {
+    return [];
+}
+export function updateNotice(notices) {
+    return notices.shift() ?? null;
+}
+/**
+ * Spec §3.4: background HEAD of the remote bundle comparing ETag; on change, GET +
+ * validate + hot-swap, queueing a ONE-TIME notice for the session's next tool result.
+ * Offline / network / validation failure: silent fallback to the in-memory snapshot,
+ * one stderr line, never throws.
+ */
+export async function checkForUpdate(holder, deps) {
+    const doFetch = deps.fetch ?? globalThis.fetch;
+    const stderr = deps.stderr ?? ((line) => console.error(line));
+    try {
+        const head = await doFetch(REMOTE_BUNDLE_URL, { method: "HEAD" });
+        const etag = head.headers.get("ETag");
+        if (!etag || etag === holder.etag)
+            return false;
+        const res = await doFetch(REMOTE_BUNDLE_URL);
+        if (!res.ok)
+            return false;
+        const remote = loadBundle(await res.json());
+        const { added, updated } = diffCounts(holder.bundle, remote);
+        holder.bundle = remote;
+        holder.etag = etag;
+        deps.onSwap?.(remote, etag);
+        deps.notices.push(`[Bizard 内容包已更新至 v${remote.meta.bundleVersion}:新增 ${added} 图、更新 ${updated} 图]`);
+        return true;
+    }
+    catch (e) {
+        stderr(`bizard-mcp: update check failed, using built-in snapshot (${e.message})`);
+        return false;
+    }
+}

package/dist/usage.d.ts

@@ -0,0 +1,10 @@
+export interface UsageEvent {
+    event: "search" | "view" | "adapt" | "cite";
+    chartId?: string;
+    language?: string;
+    query?: string;
+}
+/** Append one anonymized usage row (query hashed, never stored verbatim). Returns false when logging is off. */
+export declare function recordUsage(ev: UsageEvent, overridePath?: string): Promise<boolean>;
+/** Read the last `limit` usage rows; a missing file yields []. */
+export declare function readUsage(limit?: number, overridePath?: string): Promise<Array<Record<string, unknown>>>;

package/dist/usage.js

@@ -0,0 +1,44 @@
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+const DEFAULT_LOG = join(homedir(), ".cache", "bizard-mcp", "usage-log.jsonl");
+/** Resolve the active log path: BIZARD_USAGE_LOG wins ("off" disables), else the explicit override, else the default. */
+function logPath(override) {
+    const env = process.env.BIZARD_USAGE_LOG;
+    if (env !== undefined && env !== "off")
+        return env;
+    return override ?? DEFAULT_LOG;
+}
+function sha256_8(s) {
+    return createHash("sha256").update(s).digest("hex").slice(0, 8);
+}
+/** Append one anonymized usage row (query hashed, never stored verbatim). Returns false when logging is off. */
+export async function recordUsage(ev, overridePath) {
+    if (process.env.BIZARD_USAGE_LOG === "off")
+        return false;
+    const target = logPath(overridePath);
+    const row = {
+        ts: new Date().toISOString(),
+        event: ev.event,
+        chartId: ev.chartId ?? null,
+        language: ev.language ?? null,
+        queryHash: ev.query ? sha256_8(ev.query) : null,
+    };
+    await mkdir(dirname(target), { recursive: true });
+    await appendFile(target, JSON.stringify(row) + "\n", "utf-8");
+    return true;
+}
+/** Read the last `limit` usage rows; a missing file yields []. */
+export async function readUsage(limit = 100, overridePath) {
+    if (process.env.BIZARD_USAGE_LOG === "off")
+        return [];
+    try {
+        const txt = await readFile(logPath(overridePath), "utf-8");
+        return txt.trim().split("\n").filter(Boolean).slice(-limit)
+            .map((l) => JSON.parse(l));
+    }
+    catch {
+        return [];
+    }
+}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@openbiox/bizard-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "MCP server for the Bizard biomedical visualization atlas: search, adapt, cite, and contribute chart tutorials",
+  "type": "module",
+  "engines": { "node": ">=20" },
+  "bin": { "bizard-mcp": "dist/index.js" },
+  "main": "dist/index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openbiox/Bizard.git",
+    "directory": "mcp"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && cp -r src/snapshot dist/snapshot",
+    "build:bundle": "python3 ../.github/scripts/build-bundle.py --out src/snapshot",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@vitest/coverage-v8": "^2.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}