@pudge-ui/mcp-server 0.1.0 → 0.2.0

package/README.md

@@ -53,6 +53,8 @@ get_composition({ name: "audio-mixer-strip" })
 get_foundation({ extended: true })
 ```
 
+All tools are read-only (annotated with `readOnlyHint`) — the server never writes to your filesystem or makes network calls. Specs are bundled in the package.
+
 ## Development
 
 ```bash
@@ -60,4 +62,12 @@ npm install
 npm run dev        # run with tsx
 npm run build      # compile + copy spec
 npm run typecheck  # type-check only
+npm test           # run the test suite
 ```
+
+## Versioning & stability
+
+This server tracks pudge-ui's versioning and is pre-1.0. The component catalog grows
+between releases, but tool **names and input shapes are stable** — any change to a tool
+signature will come with a minor/major version bump and a CHANGELOG entry. Pin a version
+if you need byte-for-byte reproducibility.

package/dist/tools.d.ts

@@ -8,6 +8,11 @@ export interface ToolContext {
 export declare const toolDefinitions: ({
     name: string;
     description: string;
+    annotations: {
+        readOnlyHint: true;
+        openWorldHint: false;
+        title: string;
+    };
     inputSchema: {
         type: "object";
         properties: {
@@ -26,6 +31,11 @@ export declare const toolDefinitions: ({
 } | {
     name: string;
     description: string;
+    annotations: {
+        readOnlyHint: true;
+        openWorldHint: false;
+        title: string;
+    };
     inputSchema: {
         type: "object";
         properties: {
@@ -47,6 +57,11 @@ export declare const toolDefinitions: ({
 } | {
     name: string;
     description: string;
+    annotations: {
+        readOnlyHint: true;
+        openWorldHint: false;
+        title: string;
+    };
     inputSchema: {
         type: "object";
         properties: {
@@ -65,6 +80,11 @@ export declare const toolDefinitions: ({
 } | {
     name: string;
     description: string;
+    annotations: {
+        readOnlyHint: true;
+        openWorldHint: false;
+        title: string;
+    };
     inputSchema: {
         type: "object";
         properties: {
@@ -83,6 +103,11 @@ export declare const toolDefinitions: ({
 } | {
     name: string;
     description: string;
+    annotations: {
+        readOnlyHint: true;
+        openWorldHint: false;
+        title: string;
+    };
     inputSchema: {
         type: "object";
         properties: {

package/dist/tools.js

@@ -1,53 +1,61 @@
 import { searchComponents } from "./search.js";
 import { loadFoundation, assembleComponent, assembleComponents, assembleComposition, } from "./assembler.js";
+const readOnly = { readOnlyHint: true, openWorldHint: false };
 export const toolDefinitions = [
     {
         name: "list_components",
-        description: "List all pudge-ui components, optionally filtered by category.",
+        description: "List pudge-ui components — 93 skeuomorphic UI specs across 11 categories (buttons, toggles, dials, sliders, readouts, meters, navigation, forms, overlays, indicators, data). Returns each component's id, name, category, and one-line description. Optionally filter by category id. Use this first to discover what exists, then call get_component for full specs.",
+        annotations: { title: "List components", ...readOnly },
         inputSchema: {
             type: "object",
             properties: {
                 category: {
                     type: "string",
-                    description: "Filter by category id (e.g. 'buttons', 'toggles')",
+                    description: "Optional category id to filter by, e.g. 'buttons', 'toggles', 'dials', 'sliders', 'readouts', 'meters', 'navigation', 'forms', 'overlays', 'indicators', 'data'. Omit to list all 93 components.",
                 },
             },
         },
     },
     {
         name: "search_components",
-        description: "Fuzzy search pudge-ui components by name, description, or tags.",
+        description: "Fuzzy-search pudge-ui components by name, description, or tag (e.g. 'volume', 'knob', 'LCD', 'walkman'). Returns ranked matches with id, name, category, and description. Use this when you know what the user wants but not the exact component id; then call get_component with the best match.",
+        annotations: { title: "Search components", ...readOnly },
         inputSchema: {
             type: "object",
             properties: {
-                query: { type: "string", description: "Search query" },
-                limit: { type: "number", description: "Max results (default 10)" },
+                query: {
+                    type: "string",
+                    description: "Free-text search query (matched against name, description, and tags)",
+                },
+                limit: { type: "number", description: "Max results, 1–50 (default 10)" },
             },
             required: ["query"],
         },
     },
     {
         name: "get_foundation",
-        description: "Get pudge-ui foundation spec (philosophy, tokens, materials, depth, naming). Set extended=true for all 9 docs.",
+        description: "Get the pudge-ui foundation: the design-system rules every component depends on. Core (default) returns 5 docs — philosophy, tokens, materials, depth-model, naming. Set extended=true for all 9 (adds theme, accessibility, layout, canvas). Load this once at the start of a build so the agent applies the depth model, material recipes, and warm-neutral palette correctly.",
+        annotations: { title: "Get foundation spec", ...readOnly },
         inputSchema: {
             type: "object",
             properties: {
                 extended: {
                     type: "boolean",
-                    description: "Include all 9 foundation docs (default: core 5)",
+                    description: "Include all 9 foundation docs (default: false → core 5 docs)",
                 },
             },
         },
     },
     {
         name: "get_component",
-        description: "Get full spec for a single pudge-ui component (foundation + component spec).",
+        description: "Get the full spec for one pudge-ui component: its physical analog (the real 2000s hardware it imitates), mechanism, exact CSS recipe, and constraints — with the foundation prepended so the result is self-contained. This is the spec you hand to a coding agent to build the component in any stack (CSS, React Native, SwiftUI, Compose, Flutter). Accepts a component id or display name (e.g. 'push-button' or 'Push Button').",
+        annotations: { title: "Get component spec", ...readOnly },
         inputSchema: {
             type: "object",
             properties: {
                 name: {
                     type: "string",
-                    description: "Component id or name (e.g. 'push-button' or 'Push Button')",
+                    description: "Component id or name, e.g. 'push-button' or 'Push Button'",
                 },
             },
             required: ["name"],
@@ -55,14 +63,15 @@ export const toolDefinitions = [
     },
     {
         name: "get_components",
-        description: "Get full specs for multiple pudge-ui components (foundation included once).",
+        description: "Get full specs for several pudge-ui components at once, with the shared foundation included a single time (deduplicated) to save context. Use when building a screen that needs multiple components — pass an array of component ids or names.",
+        annotations: { title: "Get multiple component specs", ...readOnly },
         inputSchema: {
             type: "object",
             properties: {
                 names: {
                     type: "array",
                     items: { type: "string" },
-                    description: "Array of component ids or names",
+                    description: "Array of component ids or names, e.g. ['volume-slider', 'vu-meter', 'lcd']",
                 },
             },
             required: ["names"],
@@ -70,11 +79,12 @@ export const toolDefinitions = [
     },
     {
         name: "get_composition",
-        description: "Get a pudge-ui composition spec with all referenced component specs.",
+        description: "Get a pudge-ui composition — a pre-assembled multi-component layout (e.g. 'audio-mixer-strip') — with every referenced component spec inlined and the foundation included once. Use to build a complete, cohesive interface in one shot rather than wiring components together yourself.",
+        annotations: { title: "Get composition spec", ...readOnly },
         inputSchema: {
             type: "object",
             properties: {
-                name: { type: "string", description: "Composition name (e.g. 'audio-mixer-strip')" },
+                name: { type: "string", description: "Composition name, e.g. 'audio-mixer-strip'" },
             },
             required: ["name"],
         },

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@pudge-ui/mcp-server",
-  "version": "0.1.0",
+  "version": "0.2.0",
+  "mcpName": "io.github.pudge-studio/pudge-ui",
   "description": "MCP server for pudge-ui design system — query component specs for LLM context",
   "type": "module",
   "bin": {
@@ -14,7 +15,7 @@
   ],
   "scripts": {
     "build": "tsc && npm run copy-spec",
-    "copy-spec": "cp -r ../../spec ./spec",
+    "copy-spec": "rm -rf ./spec && cp -r ../../spec ./spec",
     "dev": "tsx src/index.ts",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
@@ -32,11 +33,11 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/pudgestudio/pudge-ui",
+    "url": "git+https://github.com/pudge-studio/pudge-ui.git",
     "directory": "packages/mcp-server"
   },
   "homepage": "https://ui.pudgestudio.com",
-  "bugs": "https://github.com/pudgestudio/pudge-ui/issues",
+  "bugs": "https://github.com/pudge-studio/pudge-ui/issues",
   "keywords": [
     "mcp",
     "design-system",

package/spec/components/.gstack/browse.json.lock

@@ -0,0 +1 @@
+11722