@handamade/psi-mcp 0.4.0

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Store } from "./store.js";
+export declare function createPsiServer(store: Store, version: string): McpServer;

package/dist/server.js

@@ -0,0 +1,30 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+export function createPsiServer(store, version) {
+    const server = new McpServer({ name: "psi", version });
+    server.registerTool("search", {
+        title: "Search the Psi design system",
+        description: "Keyword search over Psi components, semantic tokens, and guidance topics. " +
+            "Returns compact briefs with ids for the get tool. Empty query returns an overview.",
+        inputSchema: { query: z.string().describe("Keywords, e.g. 'button variants' or 'bg token'") },
+    }, async ({ query }) => ({
+        content: [{ type: "text", text: JSON.stringify(store.search(query), null, 1) }],
+    }));
+    server.registerTool("get", {
+        title: "Get full Psi detail by id",
+        description: "Full detail for one id from search: component (props, defaults, a11y doc), " +
+            "token (formula + resolved OKLCH/hex in all four themes), or topic (guidance). " +
+            "Accepts 'component:Button', 'token:bgPrimary', 'topic:variants', or a bare name.",
+        inputSchema: { id: z.string().describe("An id from search results, or a bare name") },
+    }, async ({ id }) => {
+        const detail = store.get(id);
+        if (!detail) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Unknown id "${id}". Use the search tool to discover ids.` }],
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(detail, null, 1) }] };
+    });
+    return server;
+}

package/dist/store.d.ts

@@ -0,0 +1,21 @@
+import type { ComponentEntry, PsiIndex, TokenEntry } from "./types.js";
+export interface Brief {
+    id: string;
+    kind: "component" | "token" | "topic";
+    title: string;
+    summary: string;
+}
+export type Detail = ({
+    kind: "component";
+} & ComponentEntry) | ({
+    kind: "token";
+} & TokenEntry) | {
+    kind: "topic";
+    name: string;
+    content: unknown;
+};
+export interface Store {
+    search(query: string): Brief[];
+    get(id: string): Detail | null;
+}
+export declare function createStore(index: PsiIndex): Store;

package/dist/store.js

@@ -0,0 +1,99 @@
+const MAX_RESULTS = 20;
+const TOPIC_SUMMARIES = {
+    variants: "Variant intent and typical use for all 8 flat variants",
+    rules: "House rules: accent budget, sizing, color binding",
+    states: "hover/active/disabled/focus derivation formulas",
+    typographyDefaults: "Default type combos per role",
+    fonts: "Font roles and brand font stacks",
+    motion: "Durations, easings, reduced-motion behavior, recipes",
+    layout: "Breakpoints, container, z-index",
+    recipes: "Composition recipes (mediaTint, sectionHeader)",
+    tags: "Tag/badge rules incl. the accent exemption (D40)",
+    "getting-started": "Install, the four required CSS imports, theme attribute, core rules",
+};
+function componentSummary(c) {
+    const axis = (name) => c.props.find((p) => p.name === name)?.type;
+    const parts = [];
+    if (c.description)
+        parts.push(c.description);
+    const variants = axis("variant");
+    const sizes = axis("size");
+    if (variants)
+        parts.push(`variants: ${variants.replaceAll('"', "")}`);
+    if (sizes)
+        parts.push(`sizes: ${sizes}`);
+    if (!variants && !sizes)
+        parts.push(`props: ${c.props.map((p) => p.name).slice(0, 6).join(", ")}`);
+    return parts.join(" — ").slice(0, 220);
+}
+export function createStore(index) {
+    const briefs = [
+        ...index.components.map((c) => ({
+            id: `component:${c.name}`,
+            kind: "component",
+            title: c.name,
+            summary: componentSummary(c),
+        })),
+        ...Object.keys(index.topics).map((name) => ({
+            id: `topic:${name}`,
+            kind: "topic",
+            title: name,
+            summary: TOPIC_SUMMARIES[name] ?? "Guidance topic",
+        })),
+        ...index.tokens.map((t) => ({
+            id: `token:${t.name}`,
+            kind: "token",
+            title: t.name,
+            summary: t.formula,
+        })),
+    ];
+    function score(brief, terms) {
+        let s = 0;
+        const title = brief.title.toLowerCase();
+        const summary = brief.summary.toLowerCase();
+        for (const term of terms) {
+            if (title === term)
+                s += 10;
+            else if (title.includes(term))
+                s += 5;
+            if (summary.includes(term))
+                s += 1;
+        }
+        return s;
+    }
+    function search(query) {
+        const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+        if (terms.length === 0) {
+            // Overview: all components + all topics (tokens are discoverable via query).
+            return briefs.filter((b) => b.kind !== "token").slice(0, MAX_RESULTS + 10);
+        }
+        return briefs
+            .map((b) => ({ b, s: score(b, terms) }))
+            .filter((x) => x.s > 0)
+            .sort((a, z) => z.s - a.s)
+            .slice(0, MAX_RESULTS)
+            .map((x) => x.b);
+    }
+    function get(id) {
+        const [prefix, rest] = id.includes(":") ? id.split(/:(.*)/s) : [null, id];
+        const name = (rest ?? id).toLowerCase();
+        const want = (kind) => prefix === null || prefix === kind;
+        if (want("component")) {
+            const c = index.components.find((c) => c.name.toLowerCase() === name);
+            if (c)
+                return { kind: "component", ...c };
+        }
+        if (want("token")) {
+            const t = index.tokens.find((t) => t.name.toLowerCase() === name);
+            if (t)
+                return { kind: "token", ...t };
+        }
+        if (want("topic")) {
+            const key = Object.keys(index.topics).find((k) => k.toLowerCase() === name);
+            if (key)
+                return { kind: "topic", name: key, content: index.topics[key] };
+        }
+        return null;
+    }
+    return { search, get };
+}

package/dist/types.d.ts

@@ -0,0 +1,36 @@
+export interface PropDoc {
+    name: string;
+    type: string;
+    required: boolean;
+    default: unknown;
+    description: string;
+}
+export interface ComponentEntry {
+    name: string;
+    description: string;
+    props: PropDoc[];
+    /** Full generated markdown doc (includes the a11y/keyboard table). */
+    doc: string;
+}
+export interface Oklch {
+    l: number;
+    c: number;
+    h: number;
+    alpha?: number;
+}
+export interface TokenEntry {
+    name: string;
+    formula: string;
+    values: Record<string, {
+        oklch: Oklch;
+        hex: string;
+    }>;
+}
+export interface PsiIndex {
+    version: string;
+    themes: string[];
+    components: ComponentEntry[];
+    tokens: TokenEntry[];
+    scales: Record<string, unknown>;
+    topics: Record<string, unknown>;
+}

package/dist/types.js

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

package/llms.txt

@@ -0,0 +1,10 @@
+# @handamade/psi-mcp — MCP access to Psi (Ψ)
+
+Two read-only tools over a baked index of the generated artifacts:
+- search(query): briefs {id, kind, title, summary}; empty query = overview
+- get(id): component (props/defaults/a11y doc) | token (formula + OKLCH/hex per theme) | topic (guidance)
+Ids: component:<Name>, token:<name>, topic:<key>; bare names resolve case-insensitively.
+
+Connect: https://psi.kurkin.de/mcp (Streamable HTTP) or `npx @handamade/psi-mcp` (stdio).
+Agent context: `npx @handamade/psi-mcp init [--claude]` writes a marker-delimited block into AGENTS.md/CLAUDE.md (D44).
+The index bakes packages/react/dist/manifest.json + packages/tokens/dist/{guidance.json,resolved/*.json} at publish; lockstep versioning keeps it truthful (D43).

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@handamade/psi-mcp",
+  "version": "0.4.0",
+  "description": "MCP server and agent-context generator for the Psi (Ψ) design system",
+  "type": "module",
+  "bin": {
+    "psi-mcp": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./http": {
+      "types": "./dist/http.d.ts",
+      "import": "./dist/http.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "llms.txt"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.16.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.22.4",
+    "typescript": "^5.7.0",
+    "vitest": "^3.2.6",
+    "@handamade/psi-react": "0.4.0",
+    "@handamade/psi-tokens": "0.4.0"
+  },
+  "scripts": {
+    "build": "tsx scripts/build-index.ts && tsc -p tsconfig.build.json"
+  }
+}