@nyuchi/mzizi-mcp

Registry-driven Model Context Protocol server for the mzizi design system — the drop-in replacement for the legacy design.nyuchi.com MCP.

The tool catalog is loaded at startup from the Supabase mcp_tool_registry table (RLS public-read, anon role) and dispatched dynamically. Adding, renaming, or retiring a tool is a registry edit, not a code change. The server is read-only on the anonymous surface — write-kind tools are excluded.

Live at https://mcp.mzizi.dev/mcp (Cloudflare Worker mzizi-mcp, version 0.3.0). A free WorkOS-AuthKit signup gate fronts the endpoint; sign up 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

Using it — MCP client config

Point any MCP client at the live HTTP endpoint:

{
  "mcpServers": {
    "mzizi": {
      "type": "http",
      "url": "https://mcp.mzizi.dev/mcp"
    }
  }
}

The client will be redirected through the WorkOS-AuthKit OAuth flow on first connect. After that, reads are free and unlimited.

stdio (local / offline)

Run the stdio bin via npx — useful for Claude Code, Cursor, or any assistant that speaks stdio MCP:

{
  "mcpServers": {
    "mzizi": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@nyuchi/mzizi-mcp"],
      "env": {
        "SUPABASE_URL": "https://grjsboqkaywpwatvrzmy.supabase.co",
        "SUPABASE_PUBLISHABLE_KEY": "<anon-key>"
      }
    }
  }
}

SUPABASE_URL defaults to the canonical mzizi project if omitted. Only SUPABASE_PUBLISHABLE_KEY is required for the stdio path.

Registry-driven dispatch

| Registry kind | Dispatch | | --------------- | ----------------------------------------- | | sql_function | supabase.rpc(fn, args) | | edge_function | supabase.functions.invoke(fn, { body }) | | source_table | supabase.from(table).select() |

The registry currently holds 62 rows (60 enabled). After filtering out write-kind and first-party tools, ~55 tools are exposed on the anonymous public surface, spread across 17 categories.

Core tools (always present, defined in code)

| Tool | Backed by | Returns | | --------------------- | ------------------------------- | -------------------------------------------------------- | | list_collections | component_documents aggregate | Every collection + document counts + per-owner breakdown | | get_database_status | component_documents count | Provider health + document-store row count + tool count |

Tool categories (registry-driven)

| Category | Example tools | | --------------- | --------------------------------------------------------------------------------- | | component | get_component, list_components, search_components, get_component_links | | architecture | get_node_documents | | brand | get_brand_tokens, list_ecosystem_brands | | skills | get_skill, list_skills | | doctrine | doctrine-read tools | | documents | read_documents, read_versions | | release | list_changelog, get_changelog_entry, compute_release_diff | | resolver | resolve_primitive, list_framework_descriptors | | a11y | calculate_contrast_ratio, simulate_color_blindness, run_accessibility_audit | | observability | list_observability_events, is_domain_allowed | | fundi | get_healing_log, list_recent_fundi_issues | | chaos | list_chaos_events | | system | system-read tools | | ai | get_ai_instructions, list_ai_instructions | | governance | get_bundu_convention | | meta | mcp_describe |

Call mcp_describe (with optional p_category filter) to enumerate the full live catalog.

Resources

| URI | Content | | --------------------- | ---------------------------------------------------- | | mzizi://collections | Every collection + document counts + owner breakdown | | mzizi://components | Lean index of the components collection |

Environment / secrets

HTTP Worker (Cloudflare — set via wrangler secret put)

| Secret | Required | Notes | | -------------------------- | -------- | ---------------------------------------------- | | SUPABASE_URL | yes | Public Supabase project URL | | SUPABASE_PUBLISHABLE_KEY | yes | Anon (RLS public-read) key | | SUPABASE_SECRET_KEY | no | Service-role key; placeholder is used if unset | | WORKOS_CLIENT_ID | yes | mzizi-mcp WorkOS AuthKit app client ID | | WORKOS_CLIENT_SECRET | yes | mzizi-mcp WorkOS AuthKit app secret | | COOKIE_ENCRYPTION_KEY | yes | HMAC key for the consent cookie (random bytes) |

stdio / local dev (.dev.vars or environment)

| Variable | Required | Notes | | -------------------------- | -------- | ----------------------------------- | | SUPABASE_URL | no | Defaults to canonical mzizi project | | SUPABASE_PUBLISHABLE_KEY | yes | Anon key |

Entrypoints

| Surface | Entry | Use | | ------------- | ------------------- | ----------------------------------------------- | | stdio | bin: mzizi-mcp | Local AI assistants (Claude Code, Cursor, etc.) | | HTTP / Worker | mzizi-mcp/http | Cloudflare Workers + any fetch runtime | | Library | @nyuchi/mzizi-mcp | Embed the server factory in your own host |

Source files:

• src/server.ts — createMziziMcpServer(supabase) factory
• src/http.ts — createMziziHttpHandler() for any fetch runtime
• src/worker.ts — Cloudflare Worker bound to env (the gated deployment)
• src/stdio.ts — bin: mzizi-mcp for the MCP registry / local Claude Code

Build and deploy

# typecheck
pnpm --filter @nyuchi/mzizi-mcp typecheck

# build (tsc → dist/)
pnpm --filter @nyuchi/mzizi-mcp build

# local Worker dev
pnpm --filter @nyuchi/mzizi-mcp cf:dev

# deploy manually (CI handles pushes to main)
pnpm --filter @nyuchi/mzizi-mcp cf:deploy

CI deploys automatically on push to main touching mzizi-mcp/** via .github/workflows/deploy-mzizi-mcp.yml.

License

Apache-2.0. Part of the mzizi tooling — an open-architecture project of the Bundu Foundation, operated by nyuchi.