@nyuchi/mzizi-mcp 0.9.1 → 0.10.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,15 +1,19 @@
 # @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.
+> Model Context Protocol server for the Mzizi design system — the registry and skills served from files bundled at build time, the docs joined in from docs.mzizi.dev, and no database behind any of it.
 
-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.
+[![npm](https://img.shields.io/npm/v/%40nyuchi%2Fmzizi-mcp?style=flat-square&logo=npm)](https://www.npmjs.com/package/@nyuchi/mzizi-mcp)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg?style=flat-square)](https://www.apache.org/licenses/LICENSE-2.0)
+
+**Live:** `https://mcp.mzizi.dev/mcp` | **Home:** [mzizi.dev](https://mzizi.dev) | **Docs:** [docs.mzizi.dev](https://docs.mzizi.dev)
+
+Mzizi is an open-architecture project governed by **Mzizi**, operated and
+developed by **Nyuchi**.
+
+---
 
 **Live at** `https://mcp.mzizi.dev/mcp` (Cloudflare Worker `mzizi-mcp`, version
-0.7.0 — `MZIZI_MCP_VERSION` in `src/server.ts` is what `serverInfo.version`
+0.9.1 — `MZIZI_MCP_VERSION` in `src/server.ts` is what `serverInfo.version`
 reports, and it moves in lockstep with `package.json` and `server.json`). A
 **free WorkOS signup gate** fronts the endpoint — a WorkOS
 **Connect OAuth application** (public client, PKCE; no client secret) — so sign up
@@ -17,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)
 
 ---
 
@@ -42,8 +47,9 @@ 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. **It is zero-config** — the public mzizi registry URL + its
-publishable (anon, RLS read-only) key are baked in, so no `env` is needed:
+speaks stdio MCP. **It is zero-config and credential-free**: the registry data and
+skills ship inside the package, so every `mzizi_*` read works offline. The `docs_*`
+tools forward to the public docs MCP and need network.
 
 ```json
 {
@@ -59,78 +65,86 @@ publishable (anon, RLS read-only) key are baked in, so no `env` is needed:
 
 This is the **sanctioned headless path**: the hosted `mcp.mzizi.dev` endpoint
 sits behind an interactive, browser-only WorkOS signup gate that a headless agent
-(Claude Code, CI, an offline client) can't complete, whereas the stdio bin reads
-the same public registry directly with no login.
-
-To point the bin at a fork or a self-hosted mirror, override the defaults with
-`SUPABASE_URL` and `SUPABASE_PUBLISHABLE_KEY` (their `NEXT_PUBLIC_` equivalents
-are also accepted). Neither value is a secret — the publishable key only grants
-the anon role, which RLS restricts to read-only reads of the public registry.
+(Claude Code, CI, an offline client) can't complete. `mzizi_report_issue` needs a
+signed-in user and says so on the stdio bin.
 
 ---
 
-## Registry-driven dispatch
+## Where the data comes from
 
-| Registry `kind` | Dispatch                                  |
-| --------------- | ----------------------------------------- |
-| `sql_function`  | `supabase.rpc(fn, args)`                  |
-| `edge_function` | `supabase.functions.invoke(fn, { body })` |
-| `source_table`  | `supabase.from(table).select()`           |
+Nothing is read from a database, and no registry data is fetched at request time.
 
-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.
+| Data                                                                                                                                                            | Source                                                                                                                                     | How it gets into the Worker                                                                                                                                          |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Components, index, component docs, brand tokens, architecture helix + nodes, Ubuntu pillars/principles, conventions, AI instruction sets, changelog, rename map | [mzizi-dev/mzizi-registry](https://github.com/mzizi-dev/mzizi-registry) at the commit pinned in [`registry.pin.json`](./registry.pin.json) | `scripts/generate-registry.mjs` fetches that exact commit and calls the registry's **own API route handlers** once per resource, writing `src/generated/registry.ts` |
+| Agent skills                                                                                                                                                    | `../mzizi-skills/skills/*/SKILL.md` in this repo                                                                                           | `scripts/generate-skills.mjs` → `src/generated/skills.ts`                                                                                                            |
+| Documentation                                                                                                                                                   | the Mintlify MCP at `https://docs.mzizi.dev/mcp`                                                                                           | federated live — see below                                                                                                                                           |
 
----
+Both generated files are build output: gitignored, never committed, rebuilt by
+`pnpm generate` (which `build`, `build:worker`, `cf:dev`, `cf:deploy`, `test`,
+`typecheck` and `check` all run first), by the Vite config, and by
+`wrangler.toml`'s `[build] command`. They are no-ops when current.
 
-## Core tools (always present, defined in code)
+Because the generator runs the registry's route handlers rather than
+re-deriving their output, a tool here answers with the same payload
+`api.mzizi.dev/v1` would give at the pinned commit. The registry checkout has no
+`node_modules`: every npm package a route imports is replaced with a module that
+throws on use, so a route that still reads a database **fails the build** rather
+than shipping an empty answer.
 
-| 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        |
-| `fundi_status`        | fundi `/admin/whoami` (M2M delegation) | fundi identity + granted scopes (only when `FUNDI_URL` is set) |
+**Moving to newer registry content** is a one-line PR: set `ref` in
+`registry.pin.json` to a newer full commit SHA of mzizi-registry. CI regenerates
+and runs the bundle tests against it.
 
-`fundi_status` is only registered on the server when `FUNDI_URL` is configured. It proxies to
-the fundi worker using a WorkOS M2M token minted from `WORKOS_M2M_CLIENT_ID` /
-`WORKOS_M2M_CLIENT_SECRET`, plus the authenticated user's token in `X-Fundi-User-Token`.
-This makes mzizi-mcp the **sanctioned fundi caller** — the CLI reaches fundi through
-mzizi-mcp, never by holding the M2M secret itself.
+Former `nyuchi-*` component names (renamed to `mzizi-*` on 2026-09-27) resolve
+through the registry's `lib/component-renames.json`, bundled with the rest.
 
----
+### Docs — joined in from docs.mzizi.dev
 
-## 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.
+The documentation site runs its own MCP server (Mintlify; streamable HTTP, public,
+stateless). This server lists its tools under a `docs_` prefix and forwards each
+call, passing the result through untouched:
 
----
+- the upstream tool list is cached for 5 minutes;
+- if a refresh fails the last good list is reused, and with nothing cached a
+  built-in snapshot of the upstream definitions keeps the surface stable;
+- a failed call is a tool error naming the docs server and the reason.
 
-## Resources
+---
 
-| URI                   | Content                                              |
-| --------------------- | ---------------------------------------------------- |
-| `mzizi://collections` | Every collection + document counts + owner breakdown |
-| `mzizi://components`  | Lean index of the `components` collection            |
+## Tools
+
+| Tool                               | Returns                                                                    |
+| ---------------------------------- | -------------------------------------------------------------------------- |
+| `mzizi_search`                     | Word search over components, conventions, AI instruction sets and releases |
+| `mzizi_get_component`              | One component in full, source inline; `include: ["docs", "versions"]`      |
+| `mzizi_list_components`            | The lean, paged index; filter by `node`, `owner`, `collection`, `type`     |
+| `mzizi_get_tokens`                 | Brand system; `family: "colors"` for all 21 colour families                |
+| `mzizi_get_architecture`           | The DNA helix, or one node/rung with `node` (uncapped)                     |
+| `mzizi_get_doctrine`               | `ubuntu-pillars`, `ubuntu-principles`, `ai-instructions`, `conventions`    |
+| `mzizi_get_skills`                 | The agent skills, listed or one in full                                    |
+| `mzizi_check_accessibility`        | Contrast ratio against the Mzizi AAA floor, computed locally               |
+| `mzizi_report_issue`               | Your issue desk (signed-in users on the Worker)                            |
+| `mzizi_fundi`                      | Delegate to fundi (only when the Worker is wired to fundi)                 |
+| `mzizi_mcp_describe`               | This server's tools, what each replaces, and its data sources              |
+| `docs_search_mzizi`                | Search the documentation (forwarded)                                       |
+| `docs_query_docs_filesystem_mzizi` | Read-only `rg`/`cat`/`tree` over the doc pages (forwarded)                 |
+| `docs_submit_feedback`             | Report a documentation problem (forwarded)                                 |
+
+The `docs_*` names mirror whatever docs.mzizi.dev lists; the three above are what
+it lists today. `GET /catalogue.json` and the `mzizi://tools` resource are computed
+from the same registration path.
+
+**Shape notes (changed when the registry moved into the build).**
+
+- `mzizi_get_component` with `include: ["versions"]` is derived from the committed
+  changelog and rename map: rows are `{version, title, change, breaking,
+released_at}` with `meta.previousNames`. The database view it used to read is gone
+  from this path.
+- `mzizi_search` returns `{data: [{kind, name, title?, description?}], meta}`, with
+  `kind` one of `component | convention | ai-instruction | release`. Documentation
+  pages are searched by `docs_search_mzizi`.
+- `mzizi_get_doctrine` gained the `conventions` topic (list, or one by `name`).
 
 ---
 
@@ -140,13 +154,17 @@ catalog.
 
 Secrets (`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                 |
-| `COOKIE_ENCRYPTION_KEY`    | yes      | HMAC key for the consent cookie (random bytes)                 |
-| `WORKOS_AUTHKIT_DOMAIN`    | no       | AuthKit domain for `/oauth2/*` (`https://accounts.mukoko.com`) |
+| Secret                  | Required | Notes                                                          |
+| ----------------------- | -------- | -------------------------------------------------------------- |
+| `COOKIE_ENCRYPTION_KEY` | yes      | HMAC key for the consent cookie (random bytes)                 |
+| `WORKOS_AUTHKIT_DOMAIN` | no       | AuthKit domain for `/oauth2/*` (`https://accounts.mukoko.com`) |
+
+**There is deliberately no `GITHUB_TOKEN` here.** The issue desk used to file GitHub issues
+itself with a PAT that was never set on this Worker, so every report parked at `drafted` and no
+maintainer ever saw one. `mzizi_report_issue` now reproduces, drafts, and **logs** the issue to
+fundi over the `FUNDI_SERVICE` binding; fundi holds the PAT, files the GitHub issue with its
+healing plan in it, and writes that issue's lifecycle back to D1 — which is what lets the desk
+(and the console) say whether yours was picked up or closed.
 
 `WORKOS_AUTHKIT_DOMAIN` is a **secret and not a `[vars]` entry**, even though a hostname is not
 confidential: a var wins on every deploy and silently discards a same-named remote value, so a
@@ -172,12 +190,13 @@ Plain vars (`[vars]` in `wrangler.toml`, not secrets):
 | -------------------------- | ------ | --------------------------------------------------- |
 | `WORKOS_M2M_CLIENT_SECRET` | secret | Fundi M2M app secret (Worker secret; never in code) |
 
-### stdio / local dev (`.dev.vars` or environment)
+### stdio / local dev
+
+The stdio bin takes no environment and holds no credential. (`MZIZI_API_BASE` is
+gone: there is no registry API to point at. Build with a different pin instead.)
 
-| Variable                   | Required | Notes                               |
-| -------------------------- | -------- | ----------------------------------- |
-| `SUPABASE_URL`             | no       | Defaults to canonical mzizi project |
-| `SUPABASE_PUBLISHABLE_KEY` | yes      | Anon key                            |
+At build time only, `MZIZI_REGISTRY_DIR` points the generator at an existing
+mzizi-registry checkout instead of fetching one; its `HEAD` must equal the pin.
 
 ---
 
@@ -191,7 +210,7 @@ Plain vars (`[vars]` in `wrangler.toml`, not secrets):
 
 Source files:
 
-- `src/server.ts` — `createMziziMcpServer(supabase)` factory
+- `src/server.ts` — `createMziziMcpServer()` 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
@@ -201,6 +220,9 @@ Source files:
 ## Build and deploy
 
 ```bash
+# generate src/generated/* (registry bundle at the pin + skills); every script below runs it first
+pnpm --filter @nyuchi/mzizi-mcp generate
+
 # typecheck
 pnpm --filter @nyuchi/mzizi-mcp typecheck
 
@@ -210,16 +232,25 @@ pnpm --filter @nyuchi/mzizi-mcp build
 # local Worker dev
 pnpm --filter @nyuchi/mzizi-mcp cf:dev
 
-# deploy manually (CI handles pushes to main)
+# deploy manually (Workers Builds 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`.
+**Cloudflare Workers Builds** deploys this Worker on every push to `main` — it is connected
+to the repo and surfaces as the `Workers Builds: mzizi-mcp` check. There is no deploy workflow
+in `.github/workflows/`; the one that used to live there was redundant and is gone (#98).
+
+A build fetches the pinned mzizi-registry commit (public, anonymous `git fetch` of one
+commit), so the build environment needs outbound access to github.com. A failed fetch
+fails the build, and a failed build deploys nothing — the running version stays up.
+
+**Rollback:** Cloudflare dashboard → Workers & Pages → `mzizi-mcp` → Deployments → pick
+the previous version → _Rollback_, or `wrangler rollback` from `mzizi-mcp/`. Reverting
+the merge commit on `main` redeploys the previous source through Workers Builds.
 
 ---
 
 ## License
 
-Apache-2.0. Part of the mzizi tooling — an open-architecture project of the
-[Bundu Foundation](https://mzizi.dev), operated by [nyuchi](https://nyuchi.com).
+Apache-2.0. Part of the mzizi tooling — an open-architecture project of
+[Mzizi](https://mzizi.dev), operated by [nyuchi](https://nyuchi.com).

package/dist/access.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Who may call what: the free tier and the Fundi gate, in one place.
+ *
+ * Owner decision, 2026-09-29: the MCP server is free with no gate, except
+ * Fundi. An anonymous session can `initialize`, list the tools and call every
+ * one of them except the tools below, which act as a console user and so need
+ * the WorkOS sign-in:
+ *
+ *   mzizi_fundi         delegates a run to Fundi, forwarding the user's token
+ *   mzizi_report_issue  files into the Fundi issue desk, keyed by the user
+ *
+ * The gated tools are still LISTED to an anonymous caller. A tool that only
+ * appears after sign-in cannot tell an agent that signing in would help; a
+ * listed tool that refuses with "sign in, here is how" can.
+ *
+ * Kept free of Worker imports: the stdio bin, the catalogue and the tests all
+ * read it.
+ */
+/** Where the free tier is served. No token needed. */
+export declare const MCP_URL = "https://mcp.mzizi.dev/mcp";
+/**
+ * The same MCP, behind the sign-in up front.
+ *
+ * `/mcp` answers anonymous requests, so a client connected there is never sent
+ * the 401 that makes most MCP clients start their OAuth flow. This path keeps
+ * the old behaviour: without a token it answers 401 with a `WWW-Authenticate`
+ * pointing at `/.well-known/oauth-protected-resource/mcp/signin`, the client
+ * signs in through WorkOS, and every later request carries the token. It is
+ * the same handler; only the front differs (see `worker.ts`).
+ */
+export declare const SIGN_IN_MCP_URL = "https://mcp.mzizi.dev/mcp/signin";
+/** Bare tool names (without `mzizi_`) that need a signed-in user. */
+export declare const SIGN_IN_TOOLS: readonly string[];
+export type ToolAccess = "free" | "sign-in";
+/** Access for a registered tool name, bare (`fundi`) or federated (`docs_…`). */
+export declare function accessFor(name: string): ToolAccess;
+/**
+ * Anonymous requests per client IP per window, on the Worker.
+ *
+ * Mirrors `[[ratelimits]]` in wrangler.toml, which is what actually enforces
+ * it; this copy is what the catalogue and the 429 body report. Keep the two
+ * equal (test/free-tier.test.ts reads wrangler.toml to check).
+ */
+export declare const ANONYMOUS_RATE_LIMIT: {
+    readonly limit: 120;
+    readonly periodSeconds: 60;
+};
+/** How to get the token, in words an agent can relay to a person. */
+export declare const SIGN_IN_HOW: string;
+/** The in-band refusal a gated tool returns to an anonymous caller. */
+export declare function signInRequired(bareName: string): {
+    isError: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+/** The access model as the catalogue and `mzizi_mcp_describe` state it. */
+export declare function accessSummary(registered: string[]): {
+    model: string;
+    signIn: {
+        tools: string[];
+        how: string;
+        url: string;
+        oauthProtectedResource: string;
+    };
+    rateLimit: string;
+};
+//# sourceMappingURL=access.d.ts.map

package/dist/access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,sDAAsD;AACtD,eAAO,MAAM,OAAO,8BAA8B,CAAC;AAEnD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,qCAAqC,CAAC;AAElE,qEAAqE;AACrE,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAA8B,CAAC;AAE1E,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,CAAC;AAE5C,iFAAiF;AACjF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAElD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB;;;CAA6C,CAAC;AAE/E,qEAAqE;AACrE,eAAO,MAAM,WAAW,QAEkI,CAAC;AAE3J,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM;;;;;;EAQ9C;AAED,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE;;;;;;;;;EAejD"}

package/dist/access.js

@@ -0,0 +1,72 @@
+/**
+ * Who may call what: the free tier and the Fundi gate, in one place.
+ *
+ * Owner decision, 2026-09-29: the MCP server is free with no gate, except
+ * Fundi. An anonymous session can `initialize`, list the tools and call every
+ * one of them except the tools below, which act as a console user and so need
+ * the WorkOS sign-in:
+ *
+ *   mzizi_fundi         delegates a run to Fundi, forwarding the user's token
+ *   mzizi_report_issue  files into the Fundi issue desk, keyed by the user
+ *
+ * The gated tools are still LISTED to an anonymous caller. A tool that only
+ * appears after sign-in cannot tell an agent that signing in would help; a
+ * listed tool that refuses with "sign in, here is how" can.
+ *
+ * Kept free of Worker imports: the stdio bin, the catalogue and the tests all
+ * read it.
+ */
+import { toolError } from "./tool-result.js";
+/** Where the free tier is served. No token needed. */
+export const MCP_URL = "https://mcp.mzizi.dev/mcp";
+/**
+ * The same MCP, behind the sign-in up front.
+ *
+ * `/mcp` answers anonymous requests, so a client connected there is never sent
+ * the 401 that makes most MCP clients start their OAuth flow. This path keeps
+ * the old behaviour: without a token it answers 401 with a `WWW-Authenticate`
+ * pointing at `/.well-known/oauth-protected-resource/mcp/signin`, the client
+ * signs in through WorkOS, and every later request carries the token. It is
+ * the same handler; only the front differs (see `worker.ts`).
+ */
+export const SIGN_IN_MCP_URL = "https://mcp.mzizi.dev/mcp/signin";
+/** Bare tool names (without `mzizi_`) that need a signed-in user. */
+export const SIGN_IN_TOOLS = ["fundi", "report_issue"];
+/** Access for a registered tool name, bare (`fundi`) or federated (`docs_…`). */
+export function accessFor(name) {
+    return SIGN_IN_TOOLS.includes(name) ? "sign-in" : "free";
+}
+/**
+ * Anonymous requests per client IP per window, on the Worker.
+ *
+ * Mirrors `[[ratelimits]]` in wrangler.toml, which is what actually enforces
+ * it; this copy is what the catalogue and the 429 body report. Keep the two
+ * equal (test/free-tier.test.ts reads wrangler.toml to check).
+ */
+export const ANONYMOUS_RATE_LIMIT = { limit: 120, periodSeconds: 60 };
+/** How to get the token, in words an agent can relay to a person. */
+export const SIGN_IN_HOW = `Sign in with a free Mzizi account (WorkOS). If your MCP client offers to sign in or authenticate this server, do that. ` +
+    `Otherwise connect to ${SIGN_IN_MCP_URL} instead of ${MCP_URL}: it asks you to sign in or create an account, then serves every tool, this one included.`;
+/** The in-band refusal a gated tool returns to an anonymous caller. */
+export function signInRequired(bareName) {
+    const why = bareName === "fundi"
+        ? "Fundi runs as your Mzizi console user"
+        : "It files into the Fundi issue desk under your Mzizi console user";
+    return toolError(`Sign-in required: mzizi_${bareName} needs a signed-in user. ${why}, so it is the one part of this server that needs an account; every other tool works without one. ${SIGN_IN_HOW}`);
+}
+/** The access model as the catalogue and `mzizi_mcp_describe` state it. */
+export function accessSummary(registered) {
+    return {
+        model: "Free: every tool works without an account, except the ones marked sign-in. Those are Fundi's: they act as your Mzizi console user.",
+        signIn: {
+            tools: registered
+                .filter((n) => accessFor(n) === "sign-in")
+                .map((n) => `mzizi_${n}`),
+            how: SIGN_IN_HOW,
+            url: SIGN_IN_MCP_URL,
+            oauthProtectedResource: "https://mcp.mzizi.dev/.well-known/oauth-protected-resource",
+        },
+        rateLimit: `Anonymous requests to ${MCP_URL} are limited to ${ANONYMOUS_RATE_LIMIT.limit} per ${ANONYMOUS_RATE_LIMIT.periodSeconds} seconds per IP address. Signed-in requests are not.`,
+    };
+}
+//# sourceMappingURL=access.js.map

package/dist/access.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.js","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE7C,sDAAsD;AACtD,MAAM,CAAC,MAAM,OAAO,GAAG,2BAA2B,CAAC;AAEnD;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,kCAAkC,CAAC;AAElE,qEAAqE;AACrE,MAAM,CAAC,MAAM,aAAa,GAAsB,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;AAI1E,iFAAiF;AACjF,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC;AAC3D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,aAAa,EAAE,EAAE,EAAW,CAAC;AAE/E,qEAAqE;AACrE,MAAM,CAAC,MAAM,WAAW,GACtB,yHAAyH;IACzH,wBAAwB,eAAe,eAAe,OAAO,2FAA2F,CAAC;AAE3J,uEAAuE;AACvE,MAAM,UAAU,cAAc,CAAC,QAAgB;IAC7C,MAAM,GAAG,GACP,QAAQ,KAAK,OAAO;QAClB,CAAC,CAAC,uCAAuC;QACzC,CAAC,CAAC,kEAAkE,CAAC;IACzE,OAAO,SAAS,CACd,2BAA2B,QAAQ,4BAA4B,GAAG,qGAAqG,WAAW,EAAE,CACrL,CAAC;AACJ,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,aAAa,CAAC,UAAoB;IAChD,OAAO;QACL,KAAK,EACH,oIAAoI;QACtI,MAAM,EAAE;YACN,KAAK,EAAE,UAAU;iBACd,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC;iBACzC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC;YAC3B,GAAG,EAAE,WAAW;YAChB,GAAG,EAAE,eAAe;YACpB,sBAAsB,EACpB,4DAA4D;SAC/D;QACD,SAAS,EAAE,yBAAyB,OAAO,mBAAmB,oBAAoB,CAAC,KAAK,QAAQ,oBAAoB,CAAC,aAAa,sDAAsD;KACzL,CAAC;AACJ,CAAC"}