Skip to content

docs: users-guide TOC + AI/Human split; plan + architecture add Phase 6 registry-listing #43

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rafael5 merged 3 commits into from
May 11, 2026
Merged

docs: users-guide TOC + AI/Human split; plan + architecture add Phase 6 registry-listing #43

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
66e709c
docs(dev-practices): prioritize the five rules front-and-center in RE…
rafael5 May 11, 2026
d87c2b7
docs: users-guide TOC + AI/Human split; plan + architecture add Phase…
rafael5 May 11, 2026
e0732a2
docs: reverse §5.3 PyPI deferral; PyPI is the Phase-6 registry channel
rafael5 May 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 57 additions & 6 deletions docs/ai-discoverability/AI-discoverability-architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,11 +89,12 @@ transport. For us to be MCP-native, we need:
ID malformed, tool not found, …), the failure carries a stable
string code the agent can switch on. No free-form exception text.
- **A frictionless install path** that doesn't require the agent's
operator to babysit. We use `uvx --from git+…@<tag>` (pin to a
release tag, install on demand) and `pip install <release-wheel-url>`
as the two supported paths. No PyPI registration — see
[`AI-discoverability-plan.md` §5.3](AI-discoverability-plan.md#53-mcp-server-m-dev-tools-mcp)
for the rationale.
operator to babysit. We support `pip install m-dev-tools-mcp`
(PyPI), `pip install <release-wheel-url>` (GitHub Release wheel),
and `uvx --from git+…@<tag>` (pin to a release tag, install on
demand) — three channels with overlapping reach. PyPI is the
channel of choice for the official MCP registry listing (per
[`AI-discoverability-plan.md` §5.3 + Phase 6](AI-discoverability-plan.md#53-mcp-server-m-dev-tools-mcp)).
- **Pointer-blob responses.** The MCP tools never inline catalog
payloads. `describe("module:m-stdlib#STDJSON")` returns a dict of
URLs to fetch next — same "pointers, not facts" invariant as the
Expand Down Expand Up @@ -384,6 +385,49 @@ repo root, the generator resolves it against the raw-content prefix.
the M toolchain isn't installed in CI; full executable
verification is a maintainer task when bumping `verified_on`).

### 4.6 Ship the MCP server through a new distribution channel

The MCP server (`m-dev-tools-mcp`) is currently distributed through
four channels:

1. **PyPI** — `pip install m-dev-tools-mcp`. Primary channel; what
the MCP registry's `server.json` declares.
2. **GitHub Release wheel** — `pip install <release-url>`. Backup
for environments that can't reach PyPI.
3. **`uvx --from git+...@<tag>`** — source-build pinned to a tag or
commit. Useful for pre-release testing.
4. **Public MCP registry** at
[`registry.modelcontextprotocol.io`](https://registry.modelcontextprotocol.io/)
under the namespace `io.github.m-dev-tools/m-dev-tools-mcp`.
Registry-aware clients (Codex, Continue, Goose, …) discover the
server without a hand-written `.mcp.json`.

To add a new channel (a VS Code extension bundling the server, a
Homebrew tap, …):

1. Decide whether the channel is worth the recurring maintenance.
The MCP registry is one PR per release tag via the
`mcp-publisher` CLI; a VS Code extension carries the maintenance
cost of the entire marketplace surface.
2. Add the install path to the
[`docs/ai-discoverability/ai-users-guide.md`](ai-users-guide.md)
"For humans" section under §A.1.
3. If the channel exposes a new pointer URL (e.g. a Marketplace
listing), add it as an `exposes` field on
`m-dev-tools-mcp/dist/repo.meta.json` — the catalog's
`build-catalog.py` will surface it as a `<kind>_url` on the
`tools.m-dev-tools-mcp` entry on the next `make catalog`.
4. If the channel needs versioned releases, wire the publish step
into `m-dev-tools-mcp/.github/workflows/release.yml` so every
`v*` tag fires it.

The registry-listing step uses `mcp-publisher login github`
(browser OAuth) and `mcp-publisher publish` — these require a real
human at a browser, so document the steps for the maintainer rather
than expecting CI to do it (GitHub OIDC auth in
`mcp-publisher login github-oidc` mode is the CI-friendly path for
later automation).

---

## 5. Operational invariants
Expand Down Expand Up @@ -484,7 +528,14 @@ same Phase-0 contract, applied to six more repos.
recipes.
- [`m-dev-tools-mcp`](https://github.com/m-dev-tools/m-dev-tools-mcp)
— the MCP server repo. v0.1.0 wheel attached to the
[v0.1.0 release](https://github.com/m-dev-tools/m-dev-tools-mcp/releases/tag/v0.1.0).
[v0.1.0 release](https://github.com/m-dev-tools/m-dev-tools-mcp/releases/tag/v0.1.0);
also published to the
[official MCP registry](https://registry.modelcontextprotocol.io/)
as `io.github.m-dev-tools/m-dev-tools-mcp` (Phase 6).
- [`docs/ai-discoverability/ai-users-guide.md`](ai-users-guide.md)
— the consumer-facing front door (Part A for human developers,
Part B for AI agents). Read this if you're using the framework
rather than extending it.

### Phase 5 — closed 2026-05-11

Expand Down
98 changes: 71 additions & 27 deletions docs/ai-discoverability/AI-discoverability-plan.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -298,30 +298,33 @@ protocol. Three tools:
One Python file (~150 LOC). Turns the catalog into a first-class protocol
surface instead of "go read these files."

**Distribution:** GitHub-first, not PyPI. Ships as a pre-built wheel attached
to a GitHub Release — same pattern `tree-sitter-m` uses for its Python
binding (see CONTRIBUTING.md § "Parser repo"). PyPI publishing is **deferred
until external usage validates the API + name** — a published PyPI name +
version is permanent (yank-only, not delete), and Phase 4 is the first time
the `route_intent` / `describe` / `verify` surface gets real-agent use. The
cost of a regretted PyPI publish is much higher than the cost of waiting.

Users install via either form:

```bash
# Pre-built wheel from a tagged GitHub Release (fast, no Python build):
pip install https://github.com/m-dev-tools/m-dev-tools-mcp/releases/download/v<X.Y>/m_dev_tools_mcp-<X.Y>-py3-none-any.whl

# Or uvx, source-build pinned to a tag or commit:
uvx --from git+https://github.com/m-dev-tools/m-dev-tools-mcp@v<X.Y> m-dev-tools-mcp
```

The MCP-client config (Claude Desktop / Codex / Continue / etc.) points at
the `m-dev-tools-mcp` binary that either install path provides.

PyPI publishing is in scope as a **follow-up after Phase 5** if external
adoption demonstrates the name + API surface are worth the irreversible
commitment. Until then, the GitHub-Release wheel is the canonical artifact.
**Distribution.** Originally GitHub-Release-wheel-only (Phase 4 v0.1.0
shipped that way); the **PyPI deferral was reversed at Phase 6
planning** because publishing to the official MCP registry
(`registry.modelcontextprotocol.io`) requires the server be reachable
through a registry-supported channel — and PyPI is the natural fit for
a Python package. The original concern (permanent PyPI namespace +
yank-only versions) is now mitigated by Phase 4 having already
shipped a real-agent-tested v0.1.0 via the GitHub Release path; the
API surface (`route_intent` / `describe` / `verify`) is no longer
speculative.

Channels, in order of recommended use:

1. **PyPI** — `pip install m-dev-tools-mcp` or
`uvx m-dev-tools-mcp`. This is the primary channel and what the
MCP registry's `server.json` declares.
2. **GitHub Release wheel** — `pip install
https://github.com/m-dev-tools/m-dev-tools-mcp/releases/download/v<X.Y>/m_dev_tools_mcp-<X.Y>-py3-none-any.whl`.
Stays available for environments that can't reach PyPI.
3. **Source via `uvx` + git tag** —
`uvx --from git+https://github.com/m-dev-tools/m-dev-tools-mcp@v<X.Y> m-dev-tools-mcp`.
Still works; useful for testing pre-release commits.

The MCP-client config (Claude Desktop / Codex / Continue / etc.)
points at the `m-dev-tools-mcp` binary any install path provides.
See Phase 6 below for the registry listing that makes config-less
discovery possible.

---

Expand Down Expand Up @@ -419,8 +422,10 @@ new-app-TDD-CI recipe top-to-bottom against a fresh clone, with green CI.
### Phase 4 — Tier-3 repos + MCP server

Goal: VS Code extensions and `m-cli-extras` ship `repo.meta.json`. Ship
`m-dev-tools-mcp` as a GitHub-Release wheel (not PyPI — see §5.3 for the
deferral rationale).
`m-dev-tools-mcp` as a GitHub-Release wheel — PyPI follows in Phase 6
once registry-listing requires it (Phase 4 closed pre-PyPI per the
original §5.3 deferral; §5.3 was updated at Phase 6 planning to
reverse the deferral).

**Exit:** Claude/Codex/Continue can be pointed at the MCP server (installed
via `pip install https://github.com/m-dev-tools/m-dev-tools-mcp/releases/download/v<X.Y>/...whl`
Expand All @@ -433,6 +438,45 @@ Goal: freshness, link-check, license-reconcile gates running weekly in CI.

**Exit:** a stale catalog or broken link is caught within 7 days.

### Phase 6 — Distribution surface (broaden client reach)

Goal: ship `m-dev-tools-mcp` through every distribution channel an
MCP client is likely to consult, so a user doesn't have to
hand-roll a `.mcp.json` to use it.

Required ships:

1. **PyPI publication.** `m-dev-tools-mcp` ships as a regular Python
package via `uv publish`. Reverses the §5.3 deferral — see that
section's updated rationale. PyPI is the official MCP registry's
accepted Python package channel; the registry-listing step
below references the PyPI entry.
2. **Official MCP registry listing.** Publish
`io.github.m-dev-tools/m-dev-tools-mcp` to
[`registry.modelcontextprotocol.io`](https://registry.modelcontextprotocol.io/)
via the `mcp-publisher` CLI. Adds a `server.json` to the
`m-dev-tools-mcp` repo root with `registryType: pypi`;
`mcp-publisher publish` lands it in the registry. Once listed,
any registry-aware client (Codex, Continue, Goose, …)
auto-discovers without `.mcp.json` config.
3. **Maintenance:** every release tag (`v0.1.1`, `v0.2.0`, …)
triggers `uv publish` to PyPI **and** `mcp-publisher publish` to
the registry from a GitHub-Actions workflow in `m-dev-tools-mcp`.
PyPI auth via Trusted Publisher (OIDC, no stored tokens);
`mcp-publisher` auth via GitHub OIDC mode for the same reason.

Optional (deferred until external adoption demand):

- **VS Code extension** bundling the MCP server for the
VS Code / Cursor audience specifically. Sibling to the existing
`tree-sitter-m-vscode` and `m-stdlib-vscode` Tier-3 repos.

**Exit:** a fresh-install MCP-capable client points at the registry
and resolves `route_intent("parse JSON in M")` without any
hand-written client-side config. The catalog's `tools.json` entry
for `m-dev-tools-mcp` carries a `registry_url` field pointing at
the live registry record.

---

## 8. Explicit Non-Goals
Expand Down Expand Up @@ -484,7 +528,7 @@ that requires careful agent prompting — encoded in `AGENTS.md` and
| Each repo | `AGENTS.md`, `dist/repo.meta.json`, `dist/<kind>.json`, `make check-manifest` | yes (small, repo-local) |
| Meta-repo | `llms.txt`, `README.md`, `task_index.json`, schemas, build scripts, CI, recipes | yes (routing only) |
| Meta-repo (generated) | `tools.json` | **no** |
| External | `m-dev-tools-mcp` (GitHub-Release wheel; PyPI deferred — see §5.3) | yes |
| External | `m-dev-tools-mcp` (Python package — PyPI + GitHub-Release wheel + official MCP registry listing per §5.3 + Phase 6) | yes |

That is the entire surface area. Everything else lives in the repo that owns
the facts.
Loading
Loading