@nyuchi/mzizi-mcp 0.10.0 → 0.10.1

package/README.md

@@ -21,7 +21,8 @@ once and read the whole registry at no cost. The worker advertises
 `/.well-known/oauth-protected-resource` so MCP clients can run the OAuth discovery
 dance automatically.
 
-**MCP Registry name:** `io.github.nyuchi/mzizi-mcp`
+**MCP Registry name:** `io.github.mzizi-dev/mzizi-mcp` (from 0.10.1; the older
+`io.github.nyuchi/mzizi-mcp` entry is stale and no longer updated)
 
 ---
 

package/dist/generated/skills.js

@@ -58,7 +58,7 @@ export const BUNDLED_SKILLS = [
     {
         "name": "mcp-server-cloudflare",
         "description": "Add or change an MCP server running as a Cloudflare Worker in the Mzizi ecosystem: the live endpoint map, one-factory/many-entrypoints layout, Streamable HTTP transport, registry-driven tool catalogues with drift gates, tool naming and annotations, the auth-by-audience gate (Connect OAuth PKCE vs M2M), and publishing to the MCP registry.",
-        "body_mdx": "# MCP server on Cloudflare Workers — the ecosystem pattern\n\n## The live endpoint map\n\nRead this before inventing a hostname — each MCP has its own host, and the umbrella\n`mcp.nyuchi.dev/{service}` path scheme is **not** how these are deployed:\n\n| Endpoint              | Worker            | Serves                                                          |\n| --------------------- | ----------------- | --------------------------------------------------------------- |\n| `mcp.mzizi.dev/mcp`   | `mzizi-mcp`       | The Mzizi registry — components, tokens, architecture, doctrine |\n| `docs.nyuchi.com/mcp` | `nyuchi-docs-mcp` | The docs corpus — search / ask / read / feedback                |\n| (Worker)              | `bushtrade-mcp`   | Agentic commerce — task-driven UCP/AP2 verbs                    |\n\n`design.nyuchi.com` is a 308 permanent redirect to `mzizi.dev`. Never reference it in new code\nor docs.\n\n**One MCP per surface.** Mzizi previously ran a second, unauthenticated MCP at\n`mzizi.dev/mcp` inside the portal, serving a subset of the same registry. Two\nendpoints over one corpus is two tool catalogues to keep in step, two auth\nstories to explain, and a silent choice for every client author. `mzizi.dev/mcp`\nnow 308-redirects to `mcp.mzizi.dev/mcp` — method and body preserved, so an\nin-flight `POST` survives the hop. Point new clients at `mcp.mzizi.dev/mcp`\ndirectly; the gate there is a free WorkOS signup, not a paywall.\n\n## Transport\n\nMCP over HTTP is **Streamable HTTP**, JSON-RPC 2.0:\n\n- `POST /mcp` — JSON-RPC requests\n- `GET /mcp` — SSE stream\n- `DELETE /mcp` — session cleanup\n- `OPTIONS /mcp` — CORS preflight\n\nA server exposes `tools/list` + `tools/call`, and optionally `resources/list` and\n`prompts/list`.\n\nUse `@modelcontextprotocol/sdk` — TypeScript is the right choice here, because the SDK, `hono`,\nand `agents` are all TS-first. Pin the SDK version deliberately: `agents` hard-pins\n`@modelcontextprotocol/sdk`, and letting your own declaration drift produces two incompatible\n`McpServer` classes in the type graph and a private-field mismatch at typecheck.\n\n## One factory, many entrypoints\n\nKeep the server definition free of any runtime binding, then wrap it per surface. This is what\nlets the same catalogue ship as a Worker, a generic fetch handler, and a local stdio bin:\n\n```\nsrc/\n├── server.ts   # createXMcpServer(deps) → McpServer   ← the only place tools are defined\n├── http.ts     # createXHttpHandler()   — any fetch runtime\n├── worker.ts   # Cloudflare Worker entry, bound to env\n└── stdio.ts    # bin for local clients / the MCP registry\n```\n\n## Prefer a registry-driven tool catalogue\n\nHardcoding a tool list means every new tool is a code change and a deploy. Build the catalogue\nat startup from a table instead, and dispatch by the row's `kind`:\n\n- `sql_function` → `supabase.rpc(...)`\n- `edge_function` → `supabase.functions.invoke(...)`\n- `source_table` → `supabase.from(...).select(...)`\n\nKeep only genuinely code-shaped tools (health, collection listing) in source.\n\n**Registry-driven surfaces need two gates**, because a table edit changes what the server\nexposes with no code change:\n\n1. An **offline suite** that connects a real MCP `Client` to the factory over an in-memory\n   transport and asserts the contract — the tool prefix, annotations, filtering, output schemas,\n   and dispatch routing.\n2. A **live drift gate** that reconstructs the public surface from the live registry and diffs\n   it against a committed manifest, failing when a tool was added, edited, or removed without\n   updating it. Run it before deploy.\n\n## Tool naming and annotations\n\nTools are `snake_case` and named for the action: `list_components`, `get_component`,\n`search_components`, `get_node_documents`, `get_brand_tokens`, `get_skill`.\n\nEvery tool carries a `title`, an `outputSchema`, and honest behaviour hints:\n\n- `readOnlyHint` — true only if the tool cannot mutate anything. An action-kind tool that runs\n  an audit is **not** read-only.\n- `destructiveHint` / `idempotentHint` / `openWorldHint` — set them deliberately; clients use\n  them to decide what to auto-approve.\n\nReturn `structuredContent` matching the declared `outputSchema` (array results wrapped under\n`rows`, scalars under `result`).\n\nNote the RPC parameter convention: registry functions take `p_`-prefixed params. Call\n`get_component` with `{ p_name }`, `search_components` with `{ p_query, p_limit }`. Getting the\nprefix wrong surfaces as \"Could not find function public.get_component(name)\".\n\n## Auth — decide by audience\n\n- **Public / customer MCPs** (`mzizi-mcp`, `bushtrade-mcp`) → **WorkOS Connect OAuth PKCE**,\n  a public client with no secret, each MCP with its own Connect app. Entitlement for paid\n  surfaces is a commerce subscription, never a per-user tag.\n- **Internal staff / machine surfaces** → **WorkOS M2M** (client-credentials). Only the Worker\n  holds the secret. A Worker that fronts an internal service mints the M2M token itself and\n  proxies the call, so a CLI never has to hold it.\n\nWrite-kind tools stay off the anonymous surface. If a public write is genuinely needed, keep it\nto an append-only sink on an explicit allow-list, running `SECURITY DEFINER` or self-gating —\nand enumerate those exceptions in one place in the source.\n\nAuth happens **inline in the client**, never by punting the user to a browser tab.\n\n## Static assets\n\nIf the Worker also needs to serve `llms.txt` or `robots.txt`, put them behind an `[assets]`\nblock so they resolve ahead of the OAuth handler; everything else falls through to the server.\n\n## Instrumentation\n\nWrap tool dispatch and emit an observability event on any tool error, fire-and-forget via\n`ctx.waitUntil` so it never blocks the response. Errors feed the fundi self-healing loop;\ndeliberately injected faults go to the chaos stream instead.\n\n## Publishing to the MCP registry\n\n`server.json` next to `package.json` is the source of truth, and\n`package.json#mcpName` **must** equal `server.json#name` or the registry refuses the publish.\nRegistry names look like `io.github.nyuchi/<server>`.\n\nRelease checklist:\n\n1. Bump the version everywhere it is stated — the version constant the server reports in\n   `serverInfo`, `package.json#version`, `server.json#version`, and\n   `server.json#packages[0].version`. A mismatch here is the most common failed publish.\n2. Tag and push. CI publishes to npm with provenance, then runs\n   `mcp-publisher login github-oidc` followed by `mcp-publisher publish` to reach the registry.\n   The login uses OIDC, so no registry secret is needed.\n\n## Deploy\n\n```bash\nwrangler dev\nwrangler deploy\nwrangler secret put SUPABASE_URL\nwrangler secret put SUPABASE_PUBLISHABLE_KEY\n```\n\nWire the deploy to CI on push to `main` so what is live matches what is merged, and run the\ndrift gate + a live smoke pass of every read tool before `wrangler deploy`.",
+        "body_mdx": "# MCP server on Cloudflare Workers — the ecosystem pattern\n\n## The live endpoint map\n\nRead this before inventing a hostname — each MCP has its own host, and the umbrella\n`mcp.nyuchi.dev/{service}` path scheme is **not** how these are deployed:\n\n| Endpoint              | Worker            | Serves                                                          |\n| --------------------- | ----------------- | --------------------------------------------------------------- |\n| `mcp.mzizi.dev/mcp`   | `mzizi-mcp`       | The Mzizi registry — components, tokens, architecture, doctrine |\n| `docs.nyuchi.com/mcp` | `nyuchi-docs-mcp` | The docs corpus — search / ask / read / feedback                |\n| (Worker)              | `bushtrade-mcp`   | Agentic commerce — task-driven UCP/AP2 verbs                    |\n\n`design.nyuchi.com` is a 308 permanent redirect to `mzizi.dev`. Never reference it in new code\nor docs.\n\n**One MCP per surface.** Mzizi previously ran a second, unauthenticated MCP at\n`mzizi.dev/mcp` inside the portal, serving a subset of the same registry. Two\nendpoints over one corpus is two tool catalogues to keep in step, two auth\nstories to explain, and a silent choice for every client author. `mzizi.dev/mcp`\nnow 308-redirects to `mcp.mzizi.dev/mcp` — method and body preserved, so an\nin-flight `POST` survives the hop. Point new clients at `mcp.mzizi.dev/mcp`\ndirectly; the gate there is a free WorkOS signup, not a paywall.\n\n## Transport\n\nMCP over HTTP is **Streamable HTTP**, JSON-RPC 2.0:\n\n- `POST /mcp` — JSON-RPC requests\n- `GET /mcp` — SSE stream\n- `DELETE /mcp` — session cleanup\n- `OPTIONS /mcp` — CORS preflight\n\nA server exposes `tools/list` + `tools/call`, and optionally `resources/list` and\n`prompts/list`.\n\nUse `@modelcontextprotocol/sdk` — TypeScript is the right choice here, because the SDK, `hono`,\nand `agents` are all TS-first. Pin the SDK version deliberately: `agents` hard-pins\n`@modelcontextprotocol/sdk`, and letting your own declaration drift produces two incompatible\n`McpServer` classes in the type graph and a private-field mismatch at typecheck.\n\n## One factory, many entrypoints\n\nKeep the server definition free of any runtime binding, then wrap it per surface. This is what\nlets the same catalogue ship as a Worker, a generic fetch handler, and a local stdio bin:\n\n```\nsrc/\n├── server.ts   # createXMcpServer(deps) → McpServer   ← the only place tools are defined\n├── http.ts     # createXHttpHandler()   — any fetch runtime\n├── worker.ts   # Cloudflare Worker entry, bound to env\n└── stdio.ts    # bin for local clients / the MCP registry\n```\n\n## Prefer a registry-driven tool catalogue\n\nHardcoding a tool list means every new tool is a code change and a deploy. Build the catalogue\nat startup from a table instead, and dispatch by the row's `kind`:\n\n- `sql_function` → `supabase.rpc(...)`\n- `edge_function` → `supabase.functions.invoke(...)`\n- `source_table` → `supabase.from(...).select(...)`\n\nKeep only genuinely code-shaped tools (health, collection listing) in source.\n\n**Registry-driven surfaces need two gates**, because a table edit changes what the server\nexposes with no code change:\n\n1. An **offline suite** that connects a real MCP `Client` to the factory over an in-memory\n   transport and asserts the contract — the tool prefix, annotations, filtering, output schemas,\n   and dispatch routing.\n2. A **live drift gate** that reconstructs the public surface from the live registry and diffs\n   it against a committed manifest, failing when a tool was added, edited, or removed without\n   updating it. Run it before deploy.\n\n## Tool naming and annotations\n\nTools are `snake_case` and named for the action: `list_components`, `get_component`,\n`search_components`, `get_node_documents`, `get_brand_tokens`, `get_skill`.\n\nEvery tool carries a `title`, an `outputSchema`, and honest behaviour hints:\n\n- `readOnlyHint` — true only if the tool cannot mutate anything. An action-kind tool that runs\n  an audit is **not** read-only.\n- `destructiveHint` / `idempotentHint` / `openWorldHint` — set them deliberately; clients use\n  them to decide what to auto-approve.\n\nReturn `structuredContent` matching the declared `outputSchema` (array results wrapped under\n`rows`, scalars under `result`).\n\nNote the RPC parameter convention: registry functions take `p_`-prefixed params. Call\n`get_component` with `{ p_name }`, `search_components` with `{ p_query, p_limit }`. Getting the\nprefix wrong surfaces as \"Could not find function public.get_component(name)\".\n\n## Auth — decide by audience\n\n- **Public / customer MCPs** (`mzizi-mcp`, `bushtrade-mcp`) → **WorkOS Connect OAuth PKCE**,\n  a public client with no secret, each MCP with its own Connect app. Entitlement for paid\n  surfaces is a commerce subscription, never a per-user tag.\n- **Internal staff / machine surfaces** → **WorkOS M2M** (client-credentials). Only the Worker\n  holds the secret. A Worker that fronts an internal service mints the M2M token itself and\n  proxies the call, so a CLI never has to hold it.\n\nWrite-kind tools stay off the anonymous surface. If a public write is genuinely needed, keep it\nto an append-only sink on an explicit allow-list, running `SECURITY DEFINER` or self-gating —\nand enumerate those exceptions in one place in the source.\n\nAuth happens **inline in the client**, never by punting the user to a browser tab.\n\n## Static assets\n\nIf the Worker also needs to serve `llms.txt` or `robots.txt`, put them behind an `[assets]`\nblock so they resolve ahead of the OAuth handler; everything else falls through to the server.\n\n## Instrumentation\n\nWrap tool dispatch and emit an observability event on any tool error, fire-and-forget via\n`ctx.waitUntil` so it never blocks the response. Errors feed the fundi self-healing loop;\ndeliberately injected faults go to the chaos stream instead.\n\n## Publishing to the MCP registry\n\n`server.json` next to `package.json` is the source of truth, and\n`package.json#mcpName` **must** equal `server.json#name` or the registry refuses the publish.\nRegistry names look like `io.github.mzizi-dev/<server>`: the namespace is the GitHub owner of the\nrepository the publish runs from, because `mcp-publisher login github-oidc` only authorises\n`io.github.<owner>/*`. (`io.github.nyuchi/*` stopped working when the repos moved to mzizi-dev.)\n\nRelease checklist:\n\n1. Bump the version everywhere it is stated — the version constant the server reports in\n   `serverInfo`, `package.json#version`, `server.json#version`, and\n   `server.json#packages[0].version`. A mismatch here is the most common failed publish.\n2. Tag and push. CI publishes to npm with provenance, then runs\n   `mcp-publisher login github-oidc` followed by `mcp-publisher publish` to reach the registry.\n   The login uses OIDC, so no registry secret is needed.\n\n## Deploy\n\n```bash\nwrangler dev\nwrangler deploy\nwrangler secret put SUPABASE_URL\nwrangler secret put SUPABASE_PUBLISHABLE_KEY\n```\n\nWire the deploy to CI on push to `main` so what is live matches what is merged, and run the\ndrift gate + a live smoke pass of every read tool before `wrangler deploy`.",
         "source": "mzizi-tools/mzizi-skills/skills/mcp-server-cloudflare"
     }
 ];

package/dist/generated/skills.js.map

@@ -1 +1 @@
-{"version":3,"file":"skills.js","sourceRoot":"","sources":["../../src/generated/skills.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,MAAM,CAAC,MAAM,cAAc,GAA4B;IACrD;QACE,MAAM,EAAE,UAAU;QAClB,aAAa,EAAE,4YAA4Y;QAC3Z,UAAU,EAAE,w3FAAw3F;QACp4F,QAAQ,EAAE,0CAA0C;KACrD;IACD;QACE,MAAM,EAAE,iBAAiB;QACzB,aAAa,EAAE,kfAAkf;QACjgB,UAAU,EAAE,+kOAA+kO;QAC3lO,QAAQ,EAAE,iDAAiD;KAC5D;IACD;QACE,MAAM,EAAE,cAAc;QACtB,aAAa,EAAE,mPAAmP;QAClQ,UAAU,EAAE,omQAAomQ;QAChnQ,QAAQ,EAAE,8CAA8C;KACzD;IACD;QACE,MAAM,EAAE,eAAe;QACvB,aAAa,EAAE,iVAAiV;QAChW,UAAU,EAAE,07SAA07S;QACt8S,QAAQ,EAAE,+CAA+C;KAC1D;IACD;QACE,MAAM,EAAE,eAAe;QACvB,aAAa,EAAE,gYAAgY;QAC/Y,UAAU,EAAE,yqMAAyqM;QACrrM,QAAQ,EAAE,+CAA+C;KAC1D;IACD;QACE,MAAM,EAAE,oBAAoB;QAC5B,aAAa,EAAE,skBAAskB;QACrlB,UAAU,EAAE,8lXAA8lX;QAC1mX,QAAQ,EAAE,oDAAoD;KAC/D;IACD;QACE,MAAM,EAAE,qBAAqB;QAC7B,aAAa,EAAE,0QAA0Q;QACzR,UAAU,EAAE,mhPAAmhP;QAC/hP,QAAQ,EAAE,qDAAqD;KAChE;IACD;QACE,MAAM,EAAE,wBAAwB;QAChC,aAAa,EAAE,2SAA2S;QAC1T,UAAU,EAAE,q6MAAq6M;QACj7M,QAAQ,EAAE,wDAAwD;KACnE;IACD;QACE,MAAM,EAAE,uBAAuB;QAC/B,aAAa,EAAE,qVAAqV;QACpW,UAAU,EAAE,21NAA21N;QACv2N,QAAQ,EAAE,uDAAuD;KAClE;CACO,CAAA;AAEV,oDAAoD;AACpD,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAA"}
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../../src/generated/skills.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,MAAM,CAAC,MAAM,cAAc,GAA4B;IACrD;QACE,MAAM,EAAE,UAAU;QAClB,aAAa,EAAE,4YAA4Y;QAC3Z,UAAU,EAAE,w3FAAw3F;QACp4F,QAAQ,EAAE,0CAA0C;KACrD;IACD;QACE,MAAM,EAAE,iBAAiB;QACzB,aAAa,EAAE,kfAAkf;QACjgB,UAAU,EAAE,+kOAA+kO;QAC3lO,QAAQ,EAAE,iDAAiD;KAC5D;IACD;QACE,MAAM,EAAE,cAAc;QACtB,aAAa,EAAE,mPAAmP;QAClQ,UAAU,EAAE,omQAAomQ;QAChnQ,QAAQ,EAAE,8CAA8C;KACzD;IACD;QACE,MAAM,EAAE,eAAe;QACvB,aAAa,EAAE,iVAAiV;QAChW,UAAU,EAAE,07SAA07S;QACt8S,QAAQ,EAAE,+CAA+C;KAC1D;IACD;QACE,MAAM,EAAE,eAAe;QACvB,aAAa,EAAE,gYAAgY;QAC/Y,UAAU,EAAE,yqMAAyqM;QACrrM,QAAQ,EAAE,+CAA+C;KAC1D;IACD;QACE,MAAM,EAAE,oBAAoB;QAC5B,aAAa,EAAE,skBAAskB;QACrlB,UAAU,EAAE,8lXAA8lX;QAC1mX,QAAQ,EAAE,oDAAoD;KAC/D;IACD;QACE,MAAM,EAAE,qBAAqB;QAC7B,aAAa,EAAE,0QAA0Q;QACzR,UAAU,EAAE,mhPAAmhP;QAC/hP,QAAQ,EAAE,qDAAqD;KAChE;IACD;QACE,MAAM,EAAE,wBAAwB;QAChC,aAAa,EAAE,2SAA2S;QAC1T,UAAU,EAAE,q6MAAq6M;QACj7M,QAAQ,EAAE,wDAAwD;KACnE;IACD;QACE,MAAM,EAAE,uBAAuB;QAC/B,aAAa,EAAE,qVAAqV;QACpW,UAAU,EAAE,skOAAskO;QACllO,QAAQ,EAAE,uDAAuD;KAClE;CACO,CAAA;AAEV,oDAAoD;AACpD,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAA"}

package/dist/server.d.ts

@@ -16,7 +16,7 @@ import type { Registry } from "./registry.js";
 import { type DocsFederationOptions } from "./docs-federation.js";
 import type { FundiToolContext } from "./fundi-client.js";
 import { type IssueDeskContext } from "./tools.js";
-export declare const MZIZI_MCP_VERSION = "0.10.0";
+export declare const MZIZI_MCP_VERSION = "0.10.1";
 export type CreateServerOptions = {
     fundi?: FundiToolContext;
     /** The signed-in user's issue desk. See `tools.ts` — absent off the Worker. */

package/dist/server.js

@@ -17,7 +17,7 @@ import { registerDocsTools, DOCS_MCP_URL } from "./docs-federation.js";
 import { registerMziziTools, TOOL_COVERAGE, TOOL_PREFIX } from "./tools.js";
 import { jsonContent } from "./tool-result.js";
 import { accessFor, accessSummary } from "./access.js";
-export const MZIZI_MCP_VERSION = "0.10.0";
+export const MZIZI_MCP_VERSION = "0.10.1";
 /**
  * What this server exposes, computed from what was actually registered.
  *

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@nyuchi/mzizi-mcp",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "publishConfig": {
     "access": "public"
   },
-  "mcpName": "io.github.nyuchi/mzizi-mcp",
+  "mcpName": "io.github.mzizi-dev/mzizi-mcp",
   "description": "Mzizi MCP — Model Context Protocol server for the Mzizi design system: registry, design tokens, doctrine, agent skills and the docs.mzizi.dev docs. Free with no account; sign-in only for the Fundi tools. Registry data and skills are bundled at build time from a pinned registry commit; holds no database credential.",
   "license": "Apache-2.0",
   "homepage": "https://mzizi.dev",