@openbiox/bizard-mcp 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,92 @@
-# Temporary Holding Version
+# @openbiox/bizard-mcp
 
-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.
+A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for
+the [Bizard](https://bizard.app) biomedical visualization atlas. It serves the
+full chart lifecycle over MCP: **query** (bilingual search across 800+ chart
+tutorials), **use** (runnable code, dependencies, data URLs, and structured
+adaptation guidance the host AI executes), **cite** (BibTeX/DOI metadata with
+license notice), and **contribute** (template-checked issue/PR submission that
+degrades gracefully by environment). Content comes from a bundle generated by
+CI from the same sources as the website and `SKILL.md`, so all three never
+drift. The server never executes plotting code — the host AI does.
+
+## Quickstart (local, stdio)
+
+```bash
+npx @openbiox/bizard-mcp
+```
+
+Register it with Claude Code:
+
+```bash
+claude mcp add bizard -- npx @openbiox/bizard-mcp
+```
+
+Works offline: an npm-shipped content snapshot backs everything up.
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `bizard_search` | Bilingual weighted search over the chart gallery; adjacent-category suggestions on zero hits |
+| `bizard_list_categories` | Category tree (12 Level-1 categories with Chinese/English aliases and counts) |
+| `bizard_get_tutorial` | Structured tutorial content: sections, setup dependencies, data description, key parameters |
+| `bizard_get_code` | Runnable tutorial code with package list, install guard, and example-data URLs |
+| `bizard_adapt_guidance` | Data-shape checks, dependency prep, parameter mapping, failure modes, alternatives |
+| `bizard_cite` | Bizard paper + tutorial citation (bibtex/text/json) with CC-BY-NC-4.0 license notice |
+| `bizard_contribute_check` | Validate a draft against the contribution template; preview points (issue #4) |
+| `bizard_contribute_submit` | Submit as issue/PR via user credentials, or degrade to draft + deep-link |
+
+Prompts: `recommend`, `adapt`, `troubleshoot`, `contribute`.
+Resources: `bizard://catalog`, `bizard://tutorial/{chartId}`, `bizard://llms-txt`.
+
+## Deployment
+
+One package, two transports:
+
+- **Local (stdio, default)**: `npx @openbiox/bizard-mcp`. Full capability; contribution runs at level 1/2 when local credentials exist.
+- **Hosted (Streamable HTTP)**: `npx @openbiox/bizard-mcp --http`. Port via `BIZARD_HTTP_PORT` (default 3000). Anonymous, stateless — each POST to `/mcp` gets a fresh transport. Per-IP token-bucket rate limit (60 req/min; 429 with `Retry-After`). Contribution runs at level 3 (no credentials on the server).
+
+## Contribution credential degradation
+
+`bizard_contribute_submit` probes the environment on every call and states
+which level it used — never silently failing:
+
+| Level | Condition | Behavior |
+|-------|-----------|----------|
+| 1 | `gh` CLI installed and logged in | Creates issue (or PR when `asPR`) as the user |
+| 2 | No `gh`, but `GITHUB_TOKEN` set | GitHub API submission, limited by token scope |
+| 3 | Neither (typical for hosted) | Returns formatted draft + pre-filled `issues/new?title=&body=` deep-link |
+
+The server itself holds zero credentials. User free text is truncated
+(single field ≤ 4000 chars) before being assembled into issue bodies.
+
+## Privacy
+
+Usage feedback is local-only, anonymous, and never networked:
+
+- Appended to `~/.cache/bizard-mcp/usage-log.jsonl` as
+  `{ ts, event, chartId, language, queryHash }` — `queryHash` is the first
+  8 hex chars of the query's SHA-256 (irreversible).
+- Set `BIZARD_USAGE_LOG=off` to disable entirely; set it to a path to relocate
+  the log.
+- No server-side telemetry, ever.
+
+## Development
+
+```bash
+npm install
+npm run build:bundle   # regenerate src/snapshot/ (works from mcp/ — defaults are repo-root-relative)
+npm test               # vitest suite
+npm run coverage       # gate: statements ≥ 80%
+npm run build          # tsc + copy snapshot into dist/
+```
+
+`npm run build:bundle` shells out to `../.github/scripts/build-bundle.py`,
+whose CLI defaults resolve against the repository root regardless of the
+current working directory. Run it from `mcp/` via the npm script, or run the
+Python script from anywhere with an explicit `--out`. CI:
+`.github/workflows/mcp-ci.yml` (Python bundle tests, node tests + coverage
+gate, stdio smoke) and `.github/workflows/mcp-bundle.yml` (rebuilds
+`files/mcp/bundle.json` + `llms.txt` on content pushes, which the site ships
+via `_quarto.yml` resources).

package/dist/adapt-tools.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { LazyBundle, UsageTracker } from "./tutorial-tools.js";
+export declare function registerAdaptTools(server: McpServer, bundle: LazyBundle, track: UsageTracker): void;

package/dist/adapt-tools.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import { adaptGuidance } from "./adapt.js";
+import { citationPayload } from "./citation.js";
+import { jsonResult, errorResult } from "./results.js";
+export function registerAdaptTools(server, bundle, track) {
+    server.registerTool("bizard_adapt_guidance", {
+        title: "Get chart adaptation guidance",
+        description: "Category-aware checklist for adapting a Bizard chart tutorial to the user's own data: data shape, dependencies, parameter mapping, failure modes, alternatives.",
+        inputSchema: {
+            chartId: z.string().describe("Chart id from bizard_search"),
+            language: z.enum(["r", "python", "julia"]).describe("Target language for the adaptation"),
+            userDataContext: z.string().max(2000).optional()
+                .describe("Optional description of the user's data/task; echoed into the checklist"),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ chartId, language, userDataContext }) => {
+        try {
+            const payload = adaptGuidance(bundle.get(), chartId, language, userDataContext);
+            track({ event: "adapt", chartId, language });
+            return jsonResult(payload);
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+    server.registerTool("bizard_cite", {
+        title: "Cite Bizard",
+        description: "Citation for the Bizard paper and optionally one chart tutorial: BibTeX, paste-ready methods text, or structured JSON.",
+        inputSchema: {
+            chartId: z.string().optional().describe("Chart id to cite a specific tutorial (omitted = paper only)"),
+            paperOnly: z.boolean().default(false).describe("Cite only the Bizard paper, ignore chartId"),
+            format: z.enum(["bibtex", "text", "json"]).default("bibtex").describe("Citation format"),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ chartId = null, paperOnly, format }) => {
+        try {
+            const result = citationPayload(bundle.get(), chartId, paperOnly, format);
+            track({ event: "cite", chartId: chartId ?? undefined });
+            return jsonResult(format === "json" ? result.json : result.text);
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+}

package/dist/adapt.d.ts

@@ -0,0 +1,12 @@
+import type { Bundle } from "./types.js";
+export interface GuidanceSection {
+    title: string;
+    items: string[];
+}
+export interface AdaptGuidance {
+    chartId: string;
+    language: string;
+    userDataContext: string | null;
+    sections: GuidanceSection[];
+}
+export declare function adaptGuidance(bundle: Bundle, chartId: string, language: "r" | "python" | "julia", userDataContext?: string): AdaptGuidance;

package/dist/adapt.js

@@ -0,0 +1,77 @@
+import { findChart } from "./tutorial.js";
+const FAILURE_MODES = {
+    Distribution: [
+        "Too few data points: violin/box plots need >= 5 values per group; check with nrow()/len() before plotting.",
+        "Factor levels missing: a group absent from the data drops silently — verify levels(factor_col) / unique(df.group).",
+        "Distribution summary checks: confirm the plotted variable's range and spread make sense for a distribution chart.",
+    ],
+    Correlation: [
+        "Non-numeric columns passed to correlation: coerce or drop them first (types(df) / str(df)).",
+        "Perfect collinearity produces NaN coefficients — inspect the variance of each variable.",
+    ],
+    default: [
+        "Wrong data shape (long vs wide): reshape (pivot_longer / melt / pd.melt) before plotting.",
+        "Package version drift: reinstall with the pinned versions from the Setup section.",
+    ],
+};
+const PARAM_HINTS = {
+    r: [
+        "Map user columns onto aes(): replace example column names (e.g. aes(x = wt) → aes(x = your_col)).",
+        "Adjust scale_/theme_ options only after the base plot renders — change one layer at a time.",
+    ],
+    python: [
+        "Replace example column names in the plotting call with your DataFrame columns.",
+        "Keep seaborn/matplotlib layer order: data → axes → styling.",
+    ],
+    julia: [
+        "Replace example column symbols in the plotting macro with your table columns.",
+        "Keep Makie/Gadfly attribute names consistent with the loaded backend.",
+    ],
+};
+const MAX_ALTERNATIVES = 3;
+const DESCRIPTION_PREVIEW_CHARS = 80;
+export function adaptGuidance(bundle, chartId, language, userDataContext) {
+    const chart = findChart(bundle, chartId);
+    if (!chart)
+        throw new Error(`Unknown chartId: ${chartId}`);
+    const failureModes = FAILURE_MODES[chart.level2] ?? FAILURE_MODES.default;
+    const alternatives = bundle.charts
+        .filter((c) => c.level1 === chart.level1 && c.id !== chart.id)
+        .slice(0, MAX_ALTERNATIVES)
+        .map((c) => `${c.name} (${c.tutorialUrl}) — ${c.description.slice(0, DESCRIPTION_PREVIEW_CHARS)}`);
+    return {
+        chartId: chart.id,
+        language,
+        userDataContext: userDataContext ?? null,
+        sections: [
+            {
+                title: "Data shape check",
+                items: [
+                    `Before plotting, verify your data has the columns this ${chart.type} expects (long format unless stated otherwise).`,
+                    "Run a structural self-check first: str(df) / df.info() / show(schema).",
+                ],
+            },
+            {
+                title: "Dependency preparation",
+                items: [
+                    `Install exactly the packages listed in the tutorial Setup (${chart.codeRefs.join(", ") || "see tutorial"}).`,
+                    "Use the tutorial's install-guard pattern: check-installed → install → library(), never bare install.packages at top level.",
+                ],
+            },
+            {
+                title: "Parameter mapping",
+                items: PARAM_HINTS[language],
+            },
+            {
+                title: "Common failure modes",
+                items: failureModes,
+            },
+            {
+                title: "Alternatives",
+                items: alternatives.length > 0
+                    ? alternatives
+                    : ["No same-category alternatives in the bundle; browse bizard_list_categories."],
+            },
+        ],
+    };
+}

package/dist/bundle.d.ts

@@ -0,0 +1,4 @@
+import type { Bundle } from "./types.js";
+export declare function loadBundle(inline: unknown): Bundle;
+/** Read the npm-shipped snapshot; null when absent (fresh checkout without a build). */
+export declare function loadSnapshot(): Bundle | null;

package/dist/bundle.js

@@ -0,0 +1,35 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+const SNAPSHOT_PATH = join(dirname(fileURLToPath(import.meta.url)), "snapshot", "bundle.json");
+/**
+ * Validate and load a bundle. Throws a descriptive error when the input
+ * is not a bundle-shaped object — the server falls back to the snapshot
+ * (or a startup failure) rather than serving garbage.
+ */
+/** Chart fields a row lost to a malformed CSV cell; null here crashes search. */
+const REQUIRED_CHART_FIELDS = [
+    "name", "type", "level1", "level2", "tutorialUrl", "imageUrl", "description",
+];
+export function loadBundle(inline) {
+    const b = inline;
+    if (!b || typeof b !== "object" ||
+        !Array.isArray(b.charts) || b.charts.length === 0 ||
+        !b.charts.every((c) => typeof c?.id === "string" && c.id.length > 0 &&
+            REQUIRED_CHART_FIELDS.every((f) => typeof c[f] === "string" && c[f].length > 0)) ||
+        !Array.isArray(b.categories) ||
+        !b.meta || typeof b.meta !== "object" ||
+        !b.citation || typeof b.citation !== "object") {
+        throw new Error("Bundle missing or invalid: expected object with non-empty charts[], categories[], meta, citation");
+    }
+    return b;
+}
+/** Read the npm-shipped snapshot; null when absent (fresh checkout without a build). */
+export function loadSnapshot() {
+    try {
+        return loadBundle(JSON.parse(readFileSync(SNAPSHOT_PATH, "utf-8")));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/citation.d.ts

@@ -0,0 +1,6 @@
+import type { Bundle } from "./types.js";
+export interface CitationResult {
+    text: string;
+    json: unknown;
+}
+export declare function citationPayload(bundle: Bundle, chartId: string | null, paperOnly: boolean, format: "bibtex" | "text" | "json"): CitationResult;

package/dist/citation.js

@@ -0,0 +1,34 @@
+import { findChart } from "./tutorial.js";
+const LICENSE_NOTE = "CC-BY-NC-4.0";
+const METHODS_SENTENCE_EN = 'The figure was generated following the Bizard tutorial "{name}" ({url}); Bizard is licensed CC-BY-NC-4.0.';
+const METHODS_SENTENCE_ZH = "该图参考 Bizard 教程「{name}」({url}) 复现；Bizard 采用 CC-BY-NC-4.0 许可。";
+export function citationPayload(bundle, chartId, paperOnly, format) {
+    const cite = bundle.citation;
+    const wantsChart = chartId !== null && !paperOnly;
+    const chart = wantsChart ? findChart(bundle, chartId) : undefined;
+    if (wantsChart && !chart)
+        throw new Error(`Unknown chartId: ${chartId}`);
+    if (format === "json") {
+        return {
+            text: "",
+            json: {
+                paper: { doi: cite.paperDoi, url: cite.paperUrl, license: cite.license },
+                chart: chart ? { id: chart.id, name: chart.name, url: chart.tutorialUrl } : null,
+            },
+        };
+    }
+    if (format === "bibtex") {
+        const text = chart
+            ? `${cite.bibtex}\n% Chart: ${chart.name} — ${chart.tutorialUrl}\n% License: ${cite.license}`
+            : cite.bibtex;
+        return { text, json: null };
+    }
+    const text = chart
+        ? fillMethods(METHODS_SENTENCE_EN, chart.name, chart.tutorialUrl)
+            + "\n" + fillMethods(METHODS_SENTENCE_ZH, chart.name, chart.tutorialUrl)
+        : `Biomedical charts adapted from Bizard (${cite.paperUrl}), DOI ${cite.paperDoi}, license ${cite.license}.`;
+    return { text, json: null };
+}
+function fillMethods(template, name, url) {
+    return template.replaceAll("{name}", name).replaceAll("{url}", url);
+}

package/dist/contribute-tools.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CredentialEnv } from "./contribute.js";
+export declare function registerContributeTools(server: McpServer, credentialEnv?: CredentialEnv): void;

package/dist/contribute-tools.js

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { checkContribution, submitContribution } from "./contribute.js";
+import { jsonResult, errorResult } from "./results.js";
+const USER_CONTEXT_MAX_CHARS = 2000;
+export function registerContributeTools(server, credentialEnv) {
+    server.registerTool("bizard_contribute_check", {
+        title: "Check a contribution draft",
+        description: "Static checks on a draft tutorial/fix before submitting to Bizard: front matter, Setup section, executable code blocks; previews contribution points.",
+        inputSchema: {
+            contributionType: z.enum(["new-tutorial", "fix", "translation", "gallery-image"]),
+            content: z.string().max(200_000).describe("Full draft content (markdown/QMD) to check"),
+            language: z.enum(["en", "zh"]),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ contributionType, content, language }) => {
+        try {
+            return jsonResult(checkContribution({ contributionType, content, language }));
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+    server.registerTool("bizard_contribute_submit", {
+        title: "Submit a contribution to Bizard",
+        description: "Submit a contribution as a GitHub issue. Degradation chain: gh CLI → GITHUB_TOKEN API → draft + deep-link for manual browser submission.",
+        inputSchema: {
+            contributionType: z.enum(["new-tutorial", "fix", "translation", "gallery-image"]),
+            title: z.string().max(200).describe("Issue title"),
+            body: z.string().max(100_000).describe("Issue body (markdown); over-long bodies are truncated"),
+            asPR: z.boolean().default(false).describe("Kept for future PR submission; issues only today"),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: true },
+    }, async ({ contributionType, title, body, asPR }) => {
+        try {
+            return jsonResult(await submitContribution({ contributionType, title, body, asPR }, credentialEnv ?? {}));
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+}

package/dist/contribute.d.ts

@@ -0,0 +1,44 @@
+export declare const BODY_MAX_CHARS = 4000;
+export interface ExecResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export type ExecFn = (cmd: string, args: string[]) => Promise<ExecResult>;
+export interface CredentialEnv {
+    exec?: ExecFn;
+    githubToken?: string;
+    /** Overridable fetch for tests; defaults to globalThis.fetch. */
+    fetch?: typeof fetch;
+    ghOwner?: string;
+    ghRepo?: string;
+}
+export interface CheckInput {
+    contributionType: "new-tutorial" | "fix" | "translation" | "gallery-image";
+    content: string;
+    language: "en" | "zh";
+}
+export interface CheckResult {
+    pass: boolean;
+    issues: string[];
+    checklist: string[];
+    pointsPreview: string;
+}
+export interface SubmitInput {
+    contributionType: CheckInput["contributionType"];
+    title: string;
+    body: string;
+    asPR: boolean;
+}
+export interface SubmitResult {
+    level: 1 | 2 | 3;
+    submitted: boolean;
+    url: string | null;
+    draft: string | null;
+    deepLink: string | null;
+    bodyTruncated: boolean;
+    note: string;
+}
+export declare function checkContribution(input: CheckInput): CheckResult;
+export declare function detectCredentialLevel(env: CredentialEnv): Promise<1 | 2 | 3>;
+export declare function submitContribution(input: SubmitInput, env: CredentialEnv): Promise<SubmitResult>;

package/dist/contribute.js

@@ -0,0 +1,136 @@
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+const execFile = promisify(execFileCb);
+export const BODY_MAX_CHARS = 4000;
+const TITLE_MAX_CHARS = 120;
+const ERROR_SNIPPET_CHARS = 200;
+const MAX_BUFFER_BYTES = 10 * 1024 * 1024;
+const POINTS = {
+    "new-tutorial": "+10",
+    "fix": "+3",
+    "translation": "+2",
+    "gallery-image": "+3",
+};
+/** Only labels that exist in openbiox/Bizard; other types submit unlabeled for maintainer triage. */
+const ISSUE_LABELS = {
+    "new-tutorial": "新增图表-新教程",
+};
+export function checkContribution(input) {
+    const issues = [];
+    const c = input.content;
+    if (!/^---\n[\s\S]*?\n---/.test(c))
+        issues.push("Missing YAML front matter (--- … ---).");
+    if (!/^author:/m.test(c))
+        issues.push("YAML front matter lacks author field.");
+    if (input.contributionType === "new-tutorial" && !/^## Setup/m.test(c)) {
+        issues.push("New tutorials must include the fixed '## Setup' section (see Template/).");
+    }
+    if (input.contributionType === "new-tutorial" && !/```\{(r|python|julia)/.test(c)) {
+        issues.push("New tutorials must contain at least one executable code block.");
+    }
+    return {
+        pass: issues.length === 0,
+        issues,
+        checklist: [
+            "Followed Template/contribution_0323.md structure",
+            "Figures carry fig-alt text",
+            `Contribution points reference: ${POINTS[input.contributionType]} (issue #4 rules)`,
+        ],
+        pointsPreview: POINTS[input.contributionType],
+    };
+}
+export async function detectCredentialLevel(env) {
+    const exec = execOf(env);
+    const gh = await exec("gh", ["auth", "status"]);
+    if (gh.code === 0)
+        return 1;
+    if (env.githubToken)
+        return 2;
+    return 3;
+}
+export async function submitContribution(input, env) {
+    const owner = env.ghOwner ?? "openbiox";
+    const repo = env.ghRepo ?? "Bizard";
+    const truncated = input.body.length > BODY_MAX_CHARS;
+    const body = truncated ? input.body.slice(0, BODY_MAX_CHARS) + "\n\n[Truncated]" : input.body;
+    const level = await detectCredentialLevel(env);
+    if (level === 1)
+        return submitViaGh(input, env, owner, repo, body, truncated);
+    if (env.githubToken)
+        return submitViaApi(input, env, owner, repo, body, truncated);
+    return draftResult(owner, repo, input.title, body, truncated, level);
+}
+async function submitViaGh(input, env, owner, repo, body, truncated) {
+    const label = ISSUE_LABELS[input.contributionType];
+    const args = ["issue", "create",
+        "--repo", `${owner}/${repo}`,
+        "--title", truncateTitle(input.title),
+        "--body", body];
+    if (label)
+        args.push("--label", label);
+    const res = await execOf(env)("gh", args);
+    if (res.code === 0) {
+        const url = res.stdout.trim().split("\n").pop() ?? null;
+        return { level: 1, submitted: true, url, draft: null, deepLink: null, bodyTruncated: truncated,
+            note: "Submitted via gh CLI as your GitHub user (level 1)." };
+    }
+    return { level: 1, submitted: false, url: null, draft: body, deepLink: deepLink(owner, repo, input.title, body),
+        bodyTruncated: truncated, note: `gh CLI submission failed (exit ${res.code}): ${res.stderr.slice(0, ERROR_SNIPPET_CHARS)}` };
+}
+async function submitViaApi(input, env, owner, repo, body, truncated) {
+    const token = env.githubToken;
+    const doFetch = env.fetch ?? globalThis.fetch;
+    const res = await doFetch(`https://api.github.com/repos/${owner}/${repo}/issues`, {
+        method: "POST",
+        headers: {
+            "Authorization": `Bearer ${token}`,
+            "Accept": "application/vnd.github+json",
+            "Content-Type": "application/json",
+            "User-Agent": "bizard-mcp",
+        },
+        body: JSON.stringify({
+            title: truncateTitle(input.title),
+            body,
+            ...(ISSUE_LABELS[input.contributionType] ? { labels: [ISSUE_LABELS[input.contributionType]] } : {}),
+        }),
+    });
+    if (res.ok) {
+        const data = (await res.json());
+        return { level: 2, submitted: true, url: data.html_url, draft: null, deepLink: null, bodyTruncated: truncated,
+            note: "Submitted via GitHub API with your GITHUB_TOKEN (level 2)." };
+    }
+    const errText = await res.text();
+    return { level: 2, submitted: false, url: null, draft: body, deepLink: deepLink(owner, repo, input.title, body),
+        bodyTruncated: truncated, note: `GitHub API error ${res.status}: ${errText.slice(0, ERROR_SNIPPET_CHARS)} — draft retained.` };
+}
+/** Promisified execFile wrapper; non-zero exits resolve (code carries the status), missing binaries resolve with code 127. */
+function execOf(env) {
+    if (env.exec)
+        return env.exec;
+    return async (cmd, args) => {
+        try {
+            const { stdout, stderr } = await execFile(cmd, args, { maxBuffer: MAX_BUFFER_BYTES });
+            return { code: 0, stdout, stderr };
+        }
+        catch (e) {
+            const err = e;
+            const code = typeof err.code === "number" ? err.code : 1;
+            return { code, stdout: err.stdout ?? "", stderr: err.stderr ?? err.message ?? "" };
+        }
+    };
+}
+function truncateTitle(t) {
+    return t.length > TITLE_MAX_CHARS ? t.slice(0, TITLE_MAX_CHARS - 3) + "..." : t;
+}
+function deepLink(owner, repo, title, body) {
+    return `https://github.com/${owner}/${repo}/issues/new?title=${encodeURIComponent(truncateTitle(title))}&body=${encodeURIComponent(body)}`;
+}
+function draftResult(owner, repo, title, body, truncated, level) {
+    return {
+        level, submitted: false, url: null,
+        draft: `Title: ${truncateTitle(title)}\n\n${body}`,
+        deepLink: deepLink(owner, repo, title, body),
+        bodyTruncated: truncated,
+        note: "No GitHub credentials in this environment (level 3). Open the deep-link to submit the pre-filled issue in your browser.",
+    };
+}

package/dist/entry.d.ts

@@ -0,0 +1,17 @@
+import { createBizardServer } from "./server.js";
+import type { Bundle } from "./types.js";
+import type { MutableHolder, NoticeQueue } from "./update-check.js";
+export interface CliDeps {
+    loadSnapshotFn?: () => Bundle | null;
+    connect?: (server: ReturnType<typeof createBizardServer>) => Promise<void>;
+    startHttp?: (makeServer: () => ReturnType<typeof createBizardServer>, port: number) => void;
+    env?: Record<string, string | undefined>;
+    stderr?: (line: string) => void;
+    startUpdateCheck?: (holder: MutableHolder, notices: NoticeQueue) => void;
+}
+/**
+ * CLI entry logic, testable in isolation: degraded start (stderr note, server still
+ * connects) when the snapshot is missing, `--http` for the streamable-HTTP transport,
+ * and a fire-and-forget spec §3.4 update check.
+ */
+export declare function runCli(argv: string[], deps?: CliDeps): Promise<void>;

package/dist/entry.js

@@ -0,0 +1,48 @@
+import { loadSnapshot } from "./bundle.js";
+import { createBizardServer } from "./server.js";
+import { startHttpServer } from "./http.js";
+import { checkForUpdate, createNoticeQueue } from "./update-check.js";
+const DEFAULT_HTTP_PORT = 3000;
+const DEGRADED_NOTE = "bizard-mcp: no bundled snapshot found. Tools will return a build hint until `npm run build:bundle` runs.";
+/**
+ * CLI entry logic, testable in isolation: degraded start (stderr note, server still
+ * connects) when the snapshot is missing, `--http` for the streamable-HTTP transport,
+ * and a fire-and-forget spec §3.4 update check.
+ */
+export async function runCli(argv, deps = {}) {
+    const load = deps.loadSnapshotFn ?? loadSnapshot;
+    const log = deps.stderr ?? ((line) => console.error(line));
+    const env = deps.env ?? process.env;
+    const holder = { bundle: load(), etag: null };
+    if (!holder.bundle) {
+        log(DEGRADED_NOTE);
+    }
+    const notices = createNoticeQueue();
+    const server = createBizardServer({ get: () => holder.bundle }, notices);
+    const startCheck = deps.startUpdateCheck
+        ?? ((h, ns) => {
+            void checkForUpdate(h, { notices: ns });
+        });
+    startCheck(holder, notices);
+    if (argv.includes("--http")) {
+        const port = Number(env.BIZARD_HTTP_PORT ?? DEFAULT_HTTP_PORT);
+        // The HTTP path builds a fresh server per request (one transport per
+        // McpServer — a shared instance crashes on concurrent POSTs).
+        const makeServer = () => createBizardServer({ get: () => holder.bundle }, notices);
+        if (deps.startHttp) {
+            deps.startHttp(makeServer, port);
+        }
+        else {
+            startHttpServer(makeServer, port);
+        }
+    }
+    else {
+        const connect = deps.connect
+            ? () => deps.connect(server)
+            : async () => {
+                const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+                await server.connect(new StdioServerTransport());
+            };
+        await connect();
+    }
+}

package/dist/http.d.ts

@@ -0,0 +1,9 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * 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 declare function startHttpServer(makeServer: () => McpServer, port: number): void;