Mzizi tools overview

Caution

Partly a stub. Agent skills below is a reference and current. The mzizi-mcp and mzizi-cli sections under What needs to land here are still a TODO list — don’t read them as documentation.

The Mzizi tooling — @nyuchi/mzizi-mcp, @nyuchi/mzizi-cli (the fundi agent SDK + CLI, in the monorepo’s mzizi-cli/ directory), and @nyuchi/mzizi-skills — is governed by the Bundu Foundation and operated by Nyuchi as part of the open Mzizi project, and consumed by every Nyuchi codebase. This section documents how Nyuchi uses them; the upstream reference lives in bundu-docs.

Quick start — connecting to the MCP

Two live MCP surfaces read the same Mzizi document store:

• https://mzizi.dev/mcp — the portal’s canonical document-route MCP (components, collections, database status).
• https://mcp.mzizi.dev/mcp — the standalone mzizi-mcp Cloudflare Worker; registry-driven (~60 tools from mcp_tool_registry) behind a free Connect OAuth signup gate.

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

The component registry

Mzizi ships UI through a shadcn-compatible registry at mzizi.dev, consumed under the @mzizi namespace — mzizi.dev/api/v1/ui/{name}. The mzizi add CLI (@nyuchi/mzizi-cli, aka fundi) and the Mzizi MCP resolver both resolve the same source, so a component pulled by the CLI, an agent, or a raw shadcn add all come from one place.

Component naming is a deliberate mix: plain shadcn names for framework-standard primitives (button, dialog, card, …) alongside custom components prefixed by brand — nyuchi-, bundu-, or mzizi-. The prefix signals a brand-specific composite; an unprefixed name is a stock shadcn primitive re-served through the registry.

Note

@mzizi is not @bundu/ui. The @mzizi registry is for React app consumers (shadcn-style add). @bundu/ui is a separate Astro/marketing kit — Hero/Section/MineralStrip components plus the shared token CSS and Tailwind preset. This docs site is Astro and legitimately uses @bundu/ui for its tokens and theming; it does not consume the @mzizi component registry.

Agent skills — @nyuchi/mzizi-skills

The design-system and engineering doctrine ships as a public npm package of agent skills. Install it into any repo so Claude Code (or Cursor, Copilot, Cline, Windsurf) has the doctrine on hand instead of guessing:

npx skills add @nyuchi/mzizi-skills

Or take the whole toolchain as a Claude Code plugin — the skills, the fundi agent, the registry MCP, and the /mzizi:* commands in one step:

/plugin marketplace add nyuchi/mzizi-tools
/plugin install mzizi@mzizi-tools

Nine skills ship in the bundle:

Skill	Reach for it when
nyuchi-design	Generating any branded interface — minerals, radius, type
bundu-design	Cross-brand materials and brand-voice decisions
mukoko-design	Producing or exporting mukoko visual identity
simplify	Before adding a component or style, and during any refactor
discoverability	A shared link shows no preview, or you’re adding a route/site
scaffold-component	Authoring a new component into the Mzizi registry
ecosystem-app-setup	Bootstrapping a new ecosystem app against the registry
cloudflare-worker-rust	Building a Worker in Rust with workers-rs
mcp-server-cloudflare	Adding or changing an MCP Worker

The live list is served from the portal, so read it rather than trusting this table to stay current:

curl -s https://mzizi.dev/api/v1/skills | jq '.skills[].name'

Git is the source of truth

Skills are authored in nyuchi/mzizi-tools as mzizi-skills/skills/<name>/SKILL.md — YAML frontmatter carrying name and description, then the body. That bundle is the single home for skill content: mzizi-tools projects it into the Supabase skills collection (pnpm skills:sync, disk → DB), and the portal serves what it finds there via /api/v1/skills* and MCP get_skill.

Caution

Never edit a skill anywhere but the bundle. Not a copy vendored into a consumer repo, not a .claude/skills/*.md file, and not the Supabase row directly — the next skills:sync overwrites all three. This reverses the older “authored once in Supabase” model, which broke down precisely because two syncs wrote to the same collection in opposite directions.

Changing a skill

1. Open a PR against nyuchi/mzizi-tools editing mzizi-skills/skills/<name>/SKILL.md.
2. Adding a skill? Also add an index.json entry (name, file, description) — consumers read the index, so an unlisted skill is invisible.
3. Bump the version in both mzizi-skills/package.json and index.json; they move in lockstep.
4. Run pnpm skills:validate from the repo root. It is offline and needs no credentials, and it catches the whole class of packaging mistakes: version drift between the two files, an index entry pointing at a missing file, frontmatter name disagreeing with the index, an unlisted skill directory, or an exports map that would make consumers silently fall back to built-in defaults.
5. Merge to main. publish-mzizi-skills.yml validates and publishes to npm with provenance. The workflow checks the registry first, so a merge without a version bump publishes nothing — bump the version or nothing ships.
6. An operator runs pnpm skills:sync (needs the Supabase service-role key) to project the change into the registry surface.

What needs to land here

mzizi-mcp

• The MCP server we run locally and in CI, the tools it exposes, and how to configure Claude Code / other MCP clients to talk to it.
• Token handling, registry lookups, and the offline cache.
• Common workflows: scaffolding a new mini-app, validating component back-links, running the registry health check.

mzizi-cli (mzizi-cli/ directory)

• Install + minimum-viable usage from a Nyuchi project.
• The auth helpers (Nyuchi JWT verification, org-scoped clients).
• The data helpers (typed resource clients, pagination, error envelopes).
• The UI helpers (Mzizi-aware fetch hooks, error-boundary glue).
• Versioning policy — when we pin, when we float.

mzizi-skills

Covered above — install, the nine skills, and the authoring flow. Still open:

• Whether Nyuchi-specific skills (ones no external consumer would want) belong in the shared bundle or in a per-repo .claude/skills/.
• How to exercise a skill locally before publishing, beyond pnpm skills:validate’s structural checks.

Cross-links

• nyuchi/mzizi-tools — the monorepo.
• @nyuchi/mzizi-skills — the published skills bundle; source under mzizi-skills/skills/.
• bundu-docs › Mzizi architecture — the upstream architecture reference.
• bundu-docs › Mzizi registry — the self-healing component registry the tools talk to.