@handamade/psi-mcp 0.4.0

package/README.md

@@ -0,0 +1,21 @@
+# @handamade/psi-mcp
+
+MCP server and agent-context generator for the Psi (Ψ) design system. Documents the system — the 11 React 19 components, every semantic token with its OKLCH derivation formula resolved across all four themes, and the usage guidance — through two read-only tools. It does not write code.
+
+## Connect
+
+- **Hosted (no install):** Streamable HTTP at `https://psi.kurkin.de/mcp`
+- **Local (stdio):** `npx @handamade/psi-mcp`
+
+Tools: `search(query)` → compact briefs with ids · `get(id)` → full detail (`component:Button`, `token:bgPrimary`, `topic:variants`, or a bare name).
+
+## Generate agent context (D44)
+
+    npx @handamade/psi-mcp init            # writes/updates AGENTS.md
+    npx @handamade/psi-mcp init --claude   # also CLAUDE.md
+
+Content is generated from the same baked index as the MCP tools, inside `<!-- psi:agents:start/end -->` markers — re-run after upgrades; edits outside the markers are preserved.
+
+## How it stays honest
+
+The index is baked at publish time from the sibling packages' generated artifacts (`manifest.json`, `guidance.json`, `resolved/<theme>.json`, per-component docs) and versioned in lockstep with them — the server never answers from prose.

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadIndex } from "./index.js";
+import { createStore } from "./store.js";
+import { createPsiServer } from "./server.js";
+const [command] = process.argv.slice(2);
+if (command === "init") {
+    const { runInit } = await import("./init.js");
+    await runInit({ cwd: process.cwd(), claude: process.argv.includes("--claude") });
+}
+else {
+    const index = await loadIndex();
+    const server = createPsiServer(createStore(index), index.version);
+    await server.connect(new StdioServerTransport());
+}

package/dist/http.d.ts

@@ -0,0 +1,10 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { PsiIndex } from "./types.js";
+/**
+ * Stateless Streamable HTTP handler: a fresh server + transport per request,
+ * no sessions, JSON responses. Suitable for a Vercel function (req.body may
+ * already be parsed) and for plain node:http (body read from the stream).
+ */
+export declare function createMcpHandler(index: PsiIndex): (req: IncomingMessage & {
+    body?: unknown;
+}, res: ServerResponse) => Promise<void>;

package/dist/http.js

@@ -0,0 +1,24 @@
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createStore } from "./store.js";
+import { createPsiServer } from "./server.js";
+/**
+ * Stateless Streamable HTTP handler: a fresh server + transport per request,
+ * no sessions, JSON responses. Suitable for a Vercel function (req.body may
+ * already be parsed) and for plain node:http (body read from the stream).
+ */
+export function createMcpHandler(index) {
+    const store = createStore(index);
+    return async function handleMcpRequest(req, res) {
+        const server = createPsiServer(store, index.version);
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+            enableJsonResponse: true,
+        });
+        res.on("close", () => {
+            void transport.close();
+            void server.close();
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+    };
+}

package/dist/index-builder.d.ts

@@ -0,0 +1,15 @@
+import type { PsiIndex } from "./types.js";
+export interface BuildInputs {
+    tokensDist: string;
+    reactDist: string;
+    reactDocs: string;
+    version: string;
+}
+/** Release-versioned onboarding facts; travels with the index (spec: topics). */
+export declare const GETTING_STARTED: {
+    install: string;
+    cssImports: string[];
+    themeAttribute: string;
+    rules: string;
+};
+export declare function buildIndex(inputs: BuildInputs): Promise<PsiIndex>;

package/dist/index-builder.js

@@ -0,0 +1,55 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+const THEMES = ["light", "dark", "acme", "ember"];
+/** Release-versioned onboarding facts; travels with the index (spec: topics). */
+export const GETTING_STARTED = {
+    install: "npm install @handamade/psi-tokens @handamade/psi-react",
+    cssImports: [
+        "@handamade/psi-tokens/base.css",
+        "@handamade/psi-tokens/<theme>.css — one per theme you use (light|dark|acme|ember)",
+        "@handamade/psi-tokens/components.css",
+        "@handamade/psi-tokens/utilities.css — REQUIRED: .psi-container + reduced-motion zeroing",
+    ],
+    themeAttribute: 'Set data-psi-theme="light|dark|acme|ember" on <html> or a subtree root.',
+    rules: "Sizes are px numbers (24 | 32 | 40 | 48), never S/M/L. Variants are flat " +
+        "(accent, accent-subtle, neutral, neutral-subtle, ghost, danger, danger-subtle, outline); " +
+        "one accent per visual group (Tags exempt, D40); danger only for destructive actions. " +
+        "Never hardcode colors — bind var(--psi-*).",
+};
+async function readJson(path) {
+    return JSON.parse(await readFile(path, "utf8"));
+}
+export async function buildIndex(inputs) {
+    const manifest = (await readJson(join(inputs.reactDist, "manifest.json")));
+    const guidance = (await readJson(join(inputs.tokensDist, "guidance.json")));
+    const resolved = {};
+    for (const theme of THEMES) {
+        resolved[theme] = (await readJson(join(inputs.tokensDist, "resolved", `${theme}.json`)));
+    }
+    const components = [];
+    for (const c of manifest.components) {
+        components.push({
+            name: c.name,
+            description: c.description,
+            props: c.props,
+            doc: await readFile(join(inputs.reactDocs, `${c.name}.md`), "utf8"),
+        });
+    }
+    const light = resolved.light;
+    const tokens = Object.keys(light.tokens).map((name) => ({
+        name,
+        formula: light.tokens[name].formula,
+        values: Object.fromEntries(THEMES.map((t) => [
+            t,
+            { oklch: resolved[t].tokens[name].oklch, hex: resolved[t].tokens[name].hex },
+        ])),
+    }));
+    return {
+        version: inputs.version,
+        themes: [...THEMES],
+        components,
+        tokens,
+        scales: light.scales,
+        topics: { ...guidance, "getting-started": GETTING_STARTED },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import type { PsiIndex } from "./types.js";
+export type { PsiIndex, ComponentEntry, TokenEntry, PropDoc } from "./types.js";
+export { buildIndex, GETTING_STARTED } from "./index-builder.js";
+export { createStore } from "./store.js";
+export type { Store, Brief, Detail } from "./store.js";
+export { createPsiServer } from "./server.js";
+/** Loads the index baked next to the compiled module at publish time. */
+export declare function loadIndex(): Promise<PsiIndex>;

package/dist/index.js

@@ -0,0 +1,9 @@
+import { readFile } from "node:fs/promises";
+export { buildIndex, GETTING_STARTED } from "./index-builder.js";
+export { createStore } from "./store.js";
+export { createPsiServer } from "./server.js";
+/** Loads the index baked next to the compiled module at publish time. */
+export async function loadIndex() {
+    const url = new URL("./psi-index.json", import.meta.url);
+    return JSON.parse(await readFile(url, "utf8"));
+}

package/dist/init.d.ts

@@ -0,0 +1,9 @@
+import type { PsiIndex } from "./types.js";
+export declare const START_MARKER = "<!-- psi:agents:start -->";
+export declare const END_MARKER = "<!-- psi:agents:end -->";
+export declare function renderAgentsBlock(index: PsiIndex): string;
+export declare function applyBlock(existing: string | null, block: string): string;
+export declare function runInit(opts: {
+    cwd: string;
+    claude: boolean;
+}): Promise<void>;

package/dist/init.js

@@ -0,0 +1,60 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { loadIndex } from "./index.js";
+export const START_MARKER = "<!-- psi:agents:start -->";
+export const END_MARKER = "<!-- psi:agents:end -->";
+function axes(c) {
+    const type = (n) => c.props.find((p) => p.name === n)?.type;
+    const parts = [];
+    const variants = type("variant");
+    const sizes = type("size");
+    if (variants)
+        parts.push(`variants: ${variants.replaceAll('"', "")}`);
+    if (sizes)
+        parts.push(`sizes: ${sizes}`);
+    return parts.length ? ` — ${parts.join("; ")}` : "";
+}
+export function renderAgentsBlock(index) {
+    return [
+        START_MARKER,
+        `# Psi (Ψ) design system — agent guide`,
+        "",
+        `Generated by \`npx @handamade/psi-mcp init\` for Psi v${index.version}. Re-run after upgrades; do not edit inside the markers (D44).`,
+        "",
+        "## House rules",
+        "- Sizes are px numbers (24 | 32 | 40 | 48), never S/M/L.",
+        "- Variants are flat: accent | accent-subtle | neutral | neutral-subtle | ghost | danger | danger-subtle | outline. One accent per visual group (Tags exempt, D40); danger only for destructive actions.",
+        "- Never hardcode colors — bind var(--psi-*) custom properties.",
+        "- Import all four token CSS files: base.css, one theme css, components.css, utilities.css (utilities is REQUIRED — .psi-container + reduced-motion zeroing).",
+        `- Themes: ${index.themes.join(" | ")} — set data-psi-theme on <html> or a subtree root.`,
+        "",
+        `## Components (${index.components.length})`,
+        ...index.components.map((c) => `- ${c.name}${axes(c)}`),
+        "",
+        "## Live documentation (MCP, tools: search/get)",
+        "- Hosted: https://psi.kurkin.de/mcp (Streamable HTTP)",
+        "- Local: `npx @handamade/psi-mcp` (stdio)",
+        END_MARKER,
+    ].join("\n");
+}
+export function applyBlock(existing, block) {
+    if (existing === null || existing.trim() === "")
+        return block + "\n";
+    if (existing.includes(START_MARKER) && existing.includes(END_MARKER)) {
+        const re = new RegExp(`${START_MARKER}[\\s\\S]*?${END_MARKER}`);
+        return existing.replace(re, () => block);
+    }
+    return existing.trimEnd() + "\n\n" + block + "\n";
+}
+export async function runInit(opts) {
+    const index = await loadIndex();
+    const block = renderAgentsBlock(index);
+    const files = ["AGENTS.md", ...(opts.claude ? ["CLAUDE.md"] : [])];
+    for (const name of files) {
+        const path = join(opts.cwd, name);
+        const existing = existsSync(path) ? await readFile(path, "utf8") : null;
+        await writeFile(path, applyBlock(existing, block));
+        console.log(`${existing === null ? "created" : "updated"} ${name}`);
+    }
+}