From 66e709c0e8796b7ea337de53192cbdf95ab61220 Mon Sep 17 00:00:00 2001 From: Rafael Richards Date: Mon, 11 May 2026 13:28:40 -0400 Subject: [PATCH 1/3] docs(dev-practices): prioritize the five rules front-and-center in README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Promotes "One session ↔ one repo" to Rule 1 of a numbered five-rule list at the top of the index README. Rules 2–5 (feature branches, sequential cross-repo work, .github read-only during feature work, git status glance before commit) round out the practice with diminishing-returns ordering — Rule 1 alone catches ~90% of the "git problems" the strategic doc was written to address. Longer narrative, three-tier model, filesystem shared-state inventory, guardrails, diagnostic recipes, and escape hatches (git worktree) stay in parallel-multi-repo-git-hygiene.md and are linked from the README under "Going deeper". Also adds the doc-spec-conforming frontmatter the README was missing. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/dev-practices/README.md | 132 ++++++++++++++++++++++++++++++----- 1 file changed, 116 insertions(+), 16 deletions(-) diff --git a/docs/dev-practices/README.md b/docs/dev-practices/README.md index bc7209d..dc0bcb5 100644 --- a/docs/dev-practices/README.md +++ b/docs/dev-practices/README.md @@ -1,32 +1,132 @@ +--- +created: 2026-05-11 +last_modified: 2026-05-11 +revisions: 2 +doc_type: [REFERENCE, GUIDE] +lifecycle: active +owner: rmrich5 +title: "dev-practices — working in the m-dev-tools org" +--- + # dev-practices — working in the m-dev-tools org How to *develop* in this org without fighting the tooling. Where the org-wide standards (AI-discoverability, docs-discoverability, CONTRIBUTING, layout conventions) tell you **what** the result has to look like, this section captures **how** to actually get day-to-day -work done across 12+ interconnected sibling repos without git -clashes, leaked edits, or wasted cycles. +work done across 12+ interconnected sibling repos. + +If you remember nothing else, remember the first rule. It catches the +great majority of failure modes that exist; the rest exist for the +residue. + +--- + +## The five rules + +### Rule 1 — One session ↔ one repo + +**Don't run two Claude sessions on the same repo at the same time.** + +With 12+ repos in the org, parallel work means parallel *repos* — not +parallel *sessions on one repo*. Two sessions on `m-cli` will clobber +each other on `main`, on the working tree, on each other's branch +state. Two sessions on `m-cli` + `m-stdlib` will not collide at all — +separate working trees come for free. + +This rule alone catches ~90% of "git problems" people hit working in +this org. Adopt it first; only add the rest if you're already +following this one. + +### Rule 2 — Feature branches, not `main` + +**Start every session on a feature branch.** + +```bash +cd ~/m-dev-tools/m-cli +git switch -c +``` + +If Rule 1 ever slips, at least each session's commits land on its own +branch instead of stacking on `main`. Direct-to-`main` is only safe +when you're certain you're the only actor in this repo today. + +### Rule 3 — Cross-repo features go sequentially, leaves first + +**Two repos, two sessions, two PRs — in dependency order.** + +When `m-cli` needs a new `m-stdlib` primitive: -These are not policies — those live at the repo root (`CONTRIBUTING.md`, -`profile/`, the schemas). These are *practices* a maintainer or agent -follows when sitting down to do the work. +1. Session A in `m-stdlib/` — TDD the primitive, commit, push, tag + if release-bound. +2. Session B in `m-cli/` — bump the m-stdlib reference, implement the + consumer, commit, push. -## Index +Never let one session edit both repos, even when the changes feel +"one feature". + +### Rule 4 — `.github/` is read-only during feature work + +**Don't edit `.github/` from a session whose purpose is implementing +in `m-cli` / `m-stdlib` / etc.** + +`.github/` holds org policy: CONTRIBUTING, schemas, the +AI-discoverability framework, the docs-discoverability spec, layout +conventions. Implementation work in functional repos consumes those — +it shouldn't be modifying them. Change `.github/` in a session whose +explicit purpose is `.github/` work, where you can also bump +`profile/repo.meta.json` and regenerate the catalog intentionally. + +### Rule 5 — Glance at `git status` before saying "commit" + +**Three seconds. If you see files you don't recognize, stop.** + +The agent already runs `git status` before staging. Read what it shows +you. Unfamiliar files (especially from another repo, or on a branch +you didn't expect to be on) are the warning sign — investigate before +committing. This is the backstop for the residual cases where the +rules above slipped. + +--- + +## Going deeper + +The rules above are the practice. The strategic doc carries the +analysis behind them — three-tier model, what's shared at the +filesystem level (workspace pytest cache, scheduler lock, memory dir), +guardrails (workspace-root tripwire, `make scope-check`), diagnostic +recipes for specific failure modes ("Why is sibling-repo X dirty?", +"Two sessions clobbered each other's commits in the same repo", etc.), +and escape hatches like `git worktree` for the rare case you truly +need concurrent sessions on the same repo. - **[`parallel-multi-repo-git-hygiene.md`](parallel-multi-repo-git-hygiene.md)** - — Why parallel Claude sessions across `m-cli`, `m-stdlib`, - `m-test-engine`, … cause "git problems," and the workflow that - eliminates them. Read this first if you run more than one agent - session at once. + — full rules with rationale, three-tier model, filesystem + shared-state inventory, guardrails, diagnostic recipes. + +--- + +## Adding a practice + +A new doc lives in this folder when: + +1. It's a *workflow* concern (how to work), not a content concern + (what the work should produce). +2. It applies across more than one repo in the org. +3. It's stable enough to document — not a one-off experiment. + +New docs follow the +[docs-discoverability spec](../docs-discoverability/docs-discoverability-spec.md) +filename and frontmatter conventions. -## Audience +--- -Anyone (human or agent) doing implementation work across multiple repos -in the m-dev-tools org. If you're only changing one repo and only ever -have one session open, you can probably skip this section — the -per-repo `CLAUDE.md` and the org `CONTRIBUTING.md` cover the basics. +## Audience and relationship to other doc sections -## Relationship to other doc sections +If you only ever change one repo at a time and run one session, this +section is reassurance reading — your default workflow already +respects the rules. If you regularly run more than one session, read +at least the five rules above. | Section | What it answers | |---|---| From d87c2b7d17279482663ffedc8685aa3d14bc44fb Mon Sep 17 00:00:00 2001 From: Rafael Richards Date: Mon, 11 May 2026 13:40:55 -0400 Subject: [PATCH 2/3] docs: users-guide TOC + AI/Human split; plan + architecture add Phase 6 registry-listing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit User-facing front-door rewrite plus a new "Phase 6 — Distribution surface" requirement in the plan that records the MCP-registry listing as a maintained shipping channel. Master architecture doc gets a §4.6 growth-playbook entry covering the same and a §6 ref to the official registry + the new users guide. ### docs/ai-discoverability/ai-users-guide.md — rewrite * Title shifted from "AI user's guide" to "users guide" — the doc now serves both audiences explicitly. * Table of contents at the top with anchored links. * §1 What's available — three artifacts (llms.txt + tools.json + task_index.json) + the MCP server + the registry-listing call-out (io.github.m-dev-tools/m-dev-tools-mcp). * Part A — For humans (developers + teams): * A.1 Quickest path — three install options: Option 1 GitHub Copilot Chat in VS Code (.vscode/mcp.json, agent mode) Option 2 Claude Code (.mcp.json, terminal or extension) Option 3 Registry-driven (any client that consults the official MCP registry — Codex, Continue, Goose, …; no hand-rolled .mcp.json) * A.2 Alternative: direct catalog access (no MCP). * A.3 Smoke-test the wiring. * A.4 Troubleshooting table. * A.5 Reporting issues — which tracker per bug class. * Part B — For AI agents (reading this in-session): * B.1 Tools available (route_intent / describe / verify) with the JSON-schema-on-connect note. * B.2 Typed-ID grammar + what describe returns per kind. * B.3 Example session (route_intent → describe → fetch manifest → cite the URL). * B.4 What you WILL and WILL NOT do, including the "verify doesn't execute" security stance. * B.5 Fallback: raw-catalog 8-step handshake. * §3 Shared "Where to learn more" — links to the architecture doc, plan, guide, phase docs, MCP-server repo, and the registry entry. ### AI-discoverability-plan.md — new "Phase 6" Phase 6 spells out the distribution-surface broadening as a required ship beyond Phase 5: 1. Official MCP registry listing via `mcp-publisher publish` from the m-dev-tools-mcp repo. A server.json lands at the repo root; the CLI submits it to registry.modelcontextprotocol.io. Once listed under io.github.m-dev-tools/m-dev-tools-mcp, registry- aware clients auto-discover without .mcp.json config. 2. Maintenance: every release tag triggers `mcp-publisher publish` from a GitHub-Actions workflow. Optional (deferred): PyPI (same rationale as §5.3 — irreversible namespace claim, defer until external adoption demands it); a VS Code extension sibling to tree-sitter-m-vscode / m-stdlib-vscode for the VS Code / Cursor-specific audience. Exit criterion: a fresh-install MCP-capable client points at the registry and resolves the canonical `route_intent` query without client-side config. ### AI-discoverability-architecture.md — new §4.6 growth playbook §4.6 "Ship the MCP server through a new distribution channel" — the maintainer's recipe for adding a new channel (PyPI, VS Code extension, Homebrew tap, …) on top of the registry-listing pattern. Notes that mcp-publisher login github + publish needs human at a browser; GitHub OIDC mode is the CI-automation path for later. §6 Where to read more — added the registry pointer (`registry.modelcontextprotocol.io` / `io.github.m-dev-tools/m-dev-tools-mcp`) on the m-dev-tools-mcp bullet, and added the users guide as its own list item. ### Verified * make check-docs-prose / check-freshness / check-links / check-licenses / check-schema-compat / recipes-check / handshake / validate-catalog — all clean. ### What's next (separate PR + manual step) * PR 2 on m-dev-tools-mcp: add server.json at repo root + publish-on-tag GitHub Action. * Manual step: maintainer runs `mcp-publisher login github` + `mcp-publisher publish` from a clean clone (browser OAuth; can't be scripted from here). --- .../AI-discoverability-architecture.md | 45 ++- .../AI-discoverability-plan.md | 32 ++ docs/ai-discoverability/ai-users-guide.md | 367 +++++++++++------- 3 files changed, 309 insertions(+), 135 deletions(-) diff --git a/docs/ai-discoverability/AI-discoverability-architecture.md b/docs/ai-discoverability/AI-discoverability-architecture.md index fd9df5b..0d030c9 100644 --- a/docs/ai-discoverability/AI-discoverability-architecture.md +++ b/docs/ai-discoverability/AI-discoverability-architecture.md @@ -384,6 +384,42 @@ 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 +three channels: a `uvx --from git+...@` install, a GitHub +Release wheel, and the 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 (PyPI, 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 `_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 @@ -484,7 +520,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 diff --git a/docs/ai-discoverability/AI-discoverability-plan.md b/docs/ai-discoverability/AI-discoverability-plan.md index f4630e7..bf7e3d4 100644 --- a/docs/ai-discoverability/AI-discoverability-plan.md +++ b/docs/ai-discoverability/AI-discoverability-plan.md @@ -433,6 +433,38 @@ 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. **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; `mcp-publisher publish` lands it + in the registry. Once listed, any registry-aware client (Codex, + Continue, Goose, …) auto-discovers without `.mcp.json` config. +2. **Maintenance:** every release tag (`v0.1.1`, `v0.2.0`, …) + triggers `mcp-publisher publish` from a GitHub-Actions workflow + in `m-dev-tools-mcp`, so the registry stays in sync. + +Optional (deferred until external adoption demand): + +- **PyPI.** Same deferral rationale as §5.3. +- **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 diff --git a/docs/ai-discoverability/ai-users-guide.md b/docs/ai-discoverability/ai-users-guide.md index d7e7fdc..4504449 100644 --- a/docs/ai-discoverability/ai-users-guide.md +++ b/docs/ai-discoverability/ai-users-guide.md @@ -1,57 +1,107 @@ --- created: 2026-05-11 last_modified: 2026-05-11 -revisions: 0 +revisions: 1 doc_type: [GUIDE] lifecycle: active owner: rmrich5 connections: [function] -title: "m-dev-tools — AI user's guide" +title: "m-dev-tools — users guide" --- -# m-dev-tools — AI user's guide - -> The front door for using `m-dev-tools` as an LLM-based agent or -> automated tool. Read this when you want an agent (Claude Code, -> Codex, Continue, …) to route plain-English questions about M -> tooling to the right repo without you hand-holding it. - -If you're building the framework itself or extending its -enforcement coverage, the foundational reference is -[`AI-discoverability-architecture.md`](AI-discoverability-architecture.md). -This guide is the *consumer* counterpart: how to wire your agent in -and what it can do once you have. +# m-dev-tools — users guide + +> The front door for **using** m-dev-tools, split between human +> developers (you, configuring an agent) and AI agents (the agent +> itself, reading this guide to understand what's available). If +> you're *extending* the framework rather than using it, the +> foundational reference is +> [`AI-discoverability-architecture.md`](AI-discoverability-architecture.md). + +## Table of contents + +- [1. What's available](#1-whats-available) +- [Part A — For humans (developers + teams)](#part-a--for-humans-developers--teams) + - [A.1 Quickest path: install the MCP server in your IDE](#a1-quickest-path-install-the-mcp-server-in-your-ide) + - [A.2 Alternative: direct catalog access (no MCP)](#a2-alternative-direct-catalog-access-no-mcp) + - [A.3 Smoke-test the wiring](#a3-smoke-test-the-wiring) + - [A.4 Troubleshooting](#a4-troubleshooting) + - [A.5 Reporting issues](#a5-reporting-issues) +- [Part B — For AI agents (reading this to know what to do)](#part-b--for-ai-agents-reading-this-to-know-what-to-do) + - [B.1 Tools you have access to](#b1-tools-you-have-access-to) + - [B.2 Typed-ID grammar you'll see](#b2-typed-id-grammar-youll-see) + - [B.3 Example session](#b3-example-session) + - [B.4 What you will and will not do](#b4-what-you-will-and-will-not-do) + - [B.5 If you don't have MCP support](#b5-if-you-dont-have-mcp-support) +- [3. Where to learn more (shared)](#3-where-to-learn-more-shared) --- -## 1. What "AI-enabled" means here +## 1. What's available The org publishes three machine-readable artifacts at known URLs: - **`llms.txt`** — < 40-line entry point (the standard [llmstxt.org](https://llmstxt.org/) format). - **`tools.json`** — generated catalog of every repo, every - exposes-URL, every consumes-edge. One line per repo + pointer URLs - to deeper manifests. + exposes-URL, every consumes-edge. - **`task_index.json`** — hand-curated mapping from plain-English - intent (`"parse JSON in M"`) to typed IDs (`module:m-stdlib#STDJSON`). - -Plus a thin **MCP server** that wraps all three behind three tools -your agent can call directly: `route_intent`, `describe`, `verify`. + intent (`"parse JSON in M"`) to typed IDs + (`module:m-stdlib#STDJSON`). + +Plus a thin **MCP server** (`m-dev-tools-mcp`) that wraps all three +behind three tools any MCP-capable agent can call: `route_intent`, +`describe`, `verify`. The server is published to the **official MCP +registry** at +[`registry.modelcontextprotocol.io`](https://registry.modelcontextprotocol.io/) +under the namespace `io.github.m-dev-tools/m-dev-tools-mcp` — so +MCP clients that browse the registry pick it up without +hand-rolling a config file. Continuous-enforcement gates ([Phase 5 evidence](phases/phase5-evidence.md)) keep `verified_on` fresh, URLs live, declared licenses honest, and schema changes documented — so the agent isn't reading stale facts. -## 2. Two install paths +--- + +## Part A — For humans (developers + teams) + +You're a developer who wants their AI assistant to give correct +answers about m-dev-tools without you supervising every step. This +part is about the wiring. + +### A.1 Quickest path: install the MCP server in your IDE + +Pick the option that matches the AI extension you're using. + +#### Option 1 — GitHub Copilot Chat (VS Code, agent mode) + +Create `.vscode/mcp.json` at your workspace root: + +```json +{ + "servers": { + "m-dev-tools": { + "type": "stdio", + "command": "uvx", + "args": [ + "--from", + "git+https://github.com/m-dev-tools/m-dev-tools-mcp@v0.1.0", + "m-dev-tools-mcp" + ] + } + } +} +``` -Pick one based on how your agent loads tools. +Open Copilot Chat → switch to **Agent** mode → the three tools +(`route_intent`, `describe`, `verify`) appear in the tool list. -### Path A — MCP (recommended) +#### Option 2 — Claude Code (anthropic.claude-code extension or terminal) -Drop this into your project's `.mcp.json` (Claude Code, Codex, -Continue, any MCP-capable agent): +Create `.mcp.json` at your workspace root (or +`~/.config/claude/.mcp.json` for user-level): ```json { @@ -68,24 +118,40 @@ Continue, any MCP-capable agent): } ``` -Pin to `@v0.1.0` for reproducibility, or `@main` to ride latest. +Reload Claude Code. Ask `list your MCP tools` → expect +`route_intent`, `describe`, `verify`. + +#### Option 3 — Any MCP-capable agent via the public registry + +If your client supports the MCP registry directly (e.g. modern +Codex, Continue, Goose, …), point it at the registry entry: + +``` +io.github.m-dev-tools/m-dev-tools-mcp +``` -Confirm the server registered: +The client fetches the server's `server.json` metadata from +`registry.modelcontextprotocol.io` and configures itself. No +hand-rolled `.mcp.json` needed. + +#### Prerequisite — `uv` (provides `uvx`) + +Required for Options 1 and 2. One-line install: ```bash -claude --print "list your MCP tools" -# expected: route_intent, describe, verify +curl -LsSf https://astral.sh/uv/install.sh | sh ``` -Three tools become available: +Option 3 (registry-driven) does not require `uv` on your machine — +the client decides how to launch the server. -| Tool | Signature | Returns | -|---|---|---| -| `route_intent` | `(query: str) -> list[str]` | Typed IDs matching the intent. Example: `"parse JSON in M"` → `["module:m-stdlib#STDJSON"]`. | -| `describe` | `(typed_id: str) -> dict` | Pointer-blob with `manifest_url`, `agent_instructions`, `verification_commands`. Supports `tool:` / `module:` / `cmd:` / `recipe:` kinds. Returns URLs the caller should fetch next — never inlines payloads. | -| `verify` | `(repo: str) -> list[str]` | Lists a repo's declared `verification_commands`. **Does not execute them** — that's your decision. | +#### Pin to a version + +`@v0.1.0` is pinned to the released tag. Use `@main` to ride latest +(see [Releases](https://github.com/m-dev-tools/m-dev-tools-mcp/releases) +for what's in each tag). -### Path B — raw catalog (no MCP) +### A.2 Alternative: direct catalog access (no MCP) If your agent doesn't support MCP, point it at the three raw URLs directly: @@ -94,123 +160,169 @@ directly: - `https://raw.githubusercontent.com/m-dev-tools/.github/main/profile/tools.json` - `https://raw.githubusercontent.com/m-dev-tools/.github/main/profile/task_index.json` -The agent then walks the routing trail itself: find an intent row in -`task_index.json`, follow `primary` → `tools.._url`, fetch -the manifest. The 8-step handshake in +The agent then walks the routing trail itself: find an intent row, +follow `primary` → `tools.._url`, fetch the manifest. The +8-step handshake in [`AI-discoverability-architecture.md` §3.1](AI-discoverability-architecture.md#31-the-discovery-handshake--bidirectional-contract) spells out the canonical sequence. -The MCP server (Path A) is a thin wrapper over exactly this flow — -it doesn't have hidden behavior the raw catalog can't reproduce. +The MCP server is a thin wrapper over exactly this flow — it doesn't +have hidden behavior the raw catalog can't reproduce. -## 3. Example session — Claude Code +### A.3 Smoke-test the wiring -User opens a project that has the `.mcp.json` from §2. +Don't want to open an agent just to find out the install is broken? +Shell the MCP server's CLI mode directly: +```bash +uvx --from "git+https://github.com/m-dev-tools/m-dev-tools-mcp@v0.1.0" \ + m-dev-tools-mcp --tool route_intent --query "parse JSON in M" +# expected: ["module:m-stdlib#STDJSON"] ``` -> How do I parse a JSON string in M into a tree? -(Claude calls route_intent("parse JSON in M")) -→ ["module:m-stdlib#STDJSON"] +Or clone and run the canned smoke: -(Claude calls describe("module:m-stdlib#STDJSON")) -→ { typed_id, symbol: "STDJSON", - manifest_url: "https://raw.githubusercontent.com/m-dev-tools/m-stdlib/main/dist/stdlib-manifest.json", - tool: { typed_id: "tool:m-stdlib", - repo: "https://github.com/m-dev-tools/m-stdlib", - agent_instructions: "…/AGENTS.md", - modules_url: "…/dist/stdlib-manifest.json" } } +```bash +git clone https://github.com/m-dev-tools/m-dev-tools-mcp +cd m-dev-tools-mcp +./examples/claude-code/smoke.sh +``` -(Claude fetches stdlib-manifest.json, finds parse^STDJSON's signature -+ worked example) +If either exits 0 with the typed ID, the server itself works; any +remaining issue is on the IDE-config side. -Claude: Use `parse^STDJSON(jsonText, .tree)`. It populates `tree` -with one node per JSON value; strings get the prefix "s:". Worked -example: … -``` +### A.4 Troubleshooting -The key invariant: Claude never guesses the API surface — every -claim is grounded in a manifest URL the agent actually fetched. +| Symptom | Fix | +|---|---| +| `uvx: command not found` | Install `uv`: `curl -LsSf https://astral.sh/uv/install.sh \| sh` | +| Copilot Chat shows no `route_intent` tool | Confirm `.vscode/mcp.json` is in the workspace root, switch to **Agent** mode, restart VS Code | +| Claude Code "list your MCP tools" returns nothing | Confirm `.mcp.json` is in the workspace root or `~/.config/claude/`; reload Claude Code | +| Server crashes on launch | You're probably pinned to `@main` and HEAD landed broken. Pin to `@v0.1.0` (or a later release tag) | +| `route_intent` returns `[]` for everything | The catalog isn't reachable. Check internet; the server does live fetches over HTTPS, no offline mode | +| A tool returns a stale `verified_on` | The weekly cron in `.github`'s CI catches stale within 7 days. Don't want to wait? File an issue on the relevant repo | -## 4. Example session — agent-free shell smoke +### A.5 Reporting issues -Don't want to open an agent? `examples/claude-code/smoke.sh` (in the -[m-dev-tools-mcp repo](https://github.com/m-dev-tools/m-dev-tools-mcp/tree/v0.1.0/examples/claude-code)) -shells the same `route_intent` query through the MCP server's CLI -mode and asserts the canonical typed ID lands in the response: +- **MCP-server bugs** (wrong typed ID, server crashes on a query) → + +- **Catalog bugs** (404'd `*_url`, wrong intent routing, missing + recipe) → + +- **Per-repo bugs** (e.g. `STDJSON` behavior differs from the + manifest) → file on the owning repo. `describe`'s response + includes the repo URL — go straight there. -```bash -git clone https://github.com/m-dev-tools/m-dev-tools-mcp -cd m-dev-tools-mcp -./examples/claude-code/smoke.sh -# → "module:m-stdlib#STDJSON" -``` +--- + +## Part B — For AI agents (reading this to know what to do) -Useful for CI or as a quick sanity check after install. +You're an agent. A user just registered the `m-dev-tools` MCP server +or pointed you at the catalog directly. This part tells you what +you can call and what to do with it. -## 5. The four typed-ID kinds your agent will see +### B.1 Tools you have access to -| Kind | Example | What it points at | +If MCP is wired up (the common case — `.mcp.json` or registry +entry), you have three tools: + +| Tool | Signature | Returns | |---|---|---| -| `tool:` | `tool:m-cli` | A repo (m-cli, m-stdlib, …). `describe` returns the repo's `*_url` pointers + agent_instructions + verification_commands. | -| `module:` | `module:m-stdlib#STDJSON` | A symbol in a repo's manifest. `describe` resolves to the manifest URL for fetching signatures + examples. | -| `cmd:` | `cmd:m-cli#test` | An m-cli subcommand. `describe` returns `commands_url` (the per-subcommand manifest) + parent tool. | -| `recipe:` | `recipe:new-app-tdd-ci` | A mechanically-runnable workflow under `docs/recipes/`. `describe` returns the recipe's HTTPS + raw URLs. | +| `route_intent` | `(query: str) -> list[str]` | Typed IDs matching the intent. Example: `"parse JSON in M"` → `["module:m-stdlib#STDJSON"]`. First call when a user asks about M tooling. | +| `describe` | `(typed_id: str) -> dict` | Pointer-blob with `manifest_url`, `agent_instructions`, `verification_commands`. Supports `tool:` / `module:` / `cmd:` / `recipe:` kinds. **Returns URLs, never inlines payloads.** | +| `verify` | `(repo: str) -> list[str]` | Lists a repo's declared `verification_commands`. **Does not execute them** — see §B.4. | -Other kinds (`rule:` / `doc:` / `data:` / `workflow:` / `task:`) -exist in the typed-ID grammar but `describe` currently handles the -four above. Adding a kind is a small change — file an issue if you -need it. +The MCP framework gives you a JSON schema for each tool's parameters +on connect; you don't have to memorize the signatures from this +doc. + +### B.2 Typed-ID grammar you'll see + +Pattern: +`^(tool|cmd|module|rule|doc|data|workflow|task|recipe):[a-z0-9_-]+(#[A-Za-z0-9._-]+)?$` + +| Kind | Example | What `describe` returns | +|---|---|---| +| `tool:` | `tool:m-cli` | The repo's `*_url` pointers + `agent_instructions` + `verification_commands` | +| `module:` | `module:m-stdlib#STDJSON` | The `manifest_url` for fetching signatures + worked examples; parent tool pointer | +| `cmd:` | `cmd:m-cli#test` | The `commands_url` (per-subcommand manifest) + parent tool | +| `recipe:` | `recipe:new-app-tdd-ci` | HTTPS + raw URLs of a mechanically-runnable recipe under `docs/recipes/` | -## 6. What the agent will and will not do +`rule:` / `doc:` / `data:` / `workflow:` / `task:` are valid in the +grammar but not currently handled by `describe`. If you encounter +one, return the typed ID to the user as a citation rather than +attempting to resolve it. + +### B.3 Example session + +User: *"How do I parse a JSON string in M into a tree?"* + +``` +call route_intent("parse JSON in M") + → ["module:m-stdlib#STDJSON"] + +call describe("module:m-stdlib#STDJSON") + → { typed_id, symbol: "STDJSON", + manifest_url: "…/m-stdlib/main/dist/stdlib-manifest.json", + tool: { repo, agent_instructions, modules_url, … } } + +fetch manifest_url (HTTP GET) + → find parse^STDJSON signature + example + +Compose answer: + "Use `parse^STDJSON(jsonText, .tree)`. It populates `tree` with one + node per JSON value; strings get the prefix \"s:\". Worked + example from the manifest: …" +``` + +Key invariant: never guess the API surface. Every claim should be +grounded in a `manifest_url` you actually fetched. + +### B.4 What you will and will not do **Will:** -- Route from plain-English intent to typed IDs (single call). +- Route plain-English intent to typed IDs (single `route_intent` call). - Fetch real signatures + worked examples from per-repo manifests. -- Surface a repo's `verification_commands` so you can decide to run - them. +- Surface a repo's `verification_commands` so the user can decide to + run them. +- Cite the manifest URL you used in your answer. **Will not:** -- Execute commands on its own. `verify` *lists* what a repo declared; - running them is your call. -- Fabricate APIs. If a symbol isn't in the manifest, the agent - surfaces "I don't have a verified source for that" rather than - guessing. -- Cache state on disk. The MCP server keeps a 60-second in-process - cache so a Claude-Code interaction amortizes fetches, but nothing - hits the filesystem. +- Execute commands on your own. `verify` *lists* what a repo + declared; running them is the user's call. +- Fabricate APIs. If a symbol isn't in the manifest, say so rather + than inventing one. +- Cache catalog state on disk. The MCP server keeps a 60-second + in-process cache so a session amortizes fetches, but nothing hits + the filesystem. The `verify` "don't execute" choice is a security stance, not an oversight — see [phase4-plan.md §3 B5](phases/phase4-plan.md) for the rationale. -## 7. Troubleshooting - -**`uvx` not found.** Install [`uv`](https://docs.astral.sh/uv/) first: -`curl -LsSf https://astral.sh/uv/install.sh | sh`. +### B.5 If you don't have MCP support -**`claude --print "list your MCP tools"` returns nothing.** Check -`.mcp.json` is in the repo root or your home `.config/claude/` -directory. Restart Claude Code after editing. +Fetch the three raw catalog URLs and walk the 8-step handshake: -**The MCP server crashes on launch.** Pinning to `@main` picks up -breakage on first push. Pin to `@v0.1.0` (or the latest release tag — -see ) for -stability. +1. `GET …/profile/llms.txt` +2. `GET …/profile/tools.json`, validate against `tools.schema.json` +3. `GET …/profile/task_index.json`, find matching intent row +4. Take the row's `primary` typed ID, look it up in + `tools.json` to get its `*_url` +5. `GET` that manifest URL +6. Read signature + example +7. Compose the answer +8. Cite the manifest URL -**The catalog returns a stale `verified_on` for a tool.** The weekly -cron in `.github`'s CI catches that within 7 days. If you're not -willing to wait, file an issue on the relevant repo asking the -maintainer to re-run the verification commands + bump `verified_on`. +The MCP server does steps 1–6 for you and returns the manifest URL +ready to cite. The raw-catalog path is functionally identical, just +more round-trips. -**Network unreachable on first call.** The MCP server has no offline -mode for live operation. The CLI flag `--offline` exists on each -gate but not on the server itself. Use the raw catalog (Path B) with -a local checkout if you genuinely need offline. +--- -## 8. Where to learn more +## 3. Where to learn more (shared) - [`AI-discoverability-architecture.md`](AI-discoverability-architecture.md) — the master architecture doc. First principles → three-layer @@ -228,21 +340,8 @@ a local checkout if you genuinely need offline. output, so an agent can reproduce the framework's claims from history. - [`m-dev-tools-mcp`](https://github.com/m-dev-tools/m-dev-tools-mcp) - — the MCP server repo (the same repo `uvx` clones in Path A - above). The `AGENTS.md` there has the per-tool contracts in more - detail. - -## 9. Reporting issues - -The framework is CI-gated end-to-end, but bugs still happen. Report -them at: - -- **MCP-server bugs** (a tool returns the wrong typed ID, the server - crashes on a query) → - -- **Catalog bugs** (a `*_url` 404s, an intent routes wrong, a recipe - references a removed function) → - -- **Per-repo bugs** (e.g. m-stdlib STDJSON behavior differs from the - manifest) → file on the owning repo. The MCP `describe` response - includes the repo URL — go straight there. + — the MCP server repo (the same repo `uvx` clones above). The + `AGENTS.md` there has the per-tool contracts in more detail. +- [Official MCP registry entry](https://registry.modelcontextprotocol.io/) + — search for `io.github.m-dev-tools/m-dev-tools-mcp`. The + registry-driven install path (Option 3 above) reads from here. From e0732a2fc38ad6c11be66af71786901a92b93258 Mon Sep 17 00:00:00 2001 From: Rafael Richards Date: Mon, 11 May 2026 13:48:37 -0400 Subject: [PATCH 3/3] =?UTF-8?q?docs:=20reverse=20=C2=A75.3=20PyPI=20deferr?= =?UTF-8?q?al;=20PyPI=20is=20the=20Phase-6=20registry=20channel?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The original AI-discoverability-plan.md §5.3 deferred PyPI publication "until external usage validates the API + name". Phase 4 shipped v0.1.0 via the GitHub-Release wheel path and got real agent use without a regretted publish. Phase 6 planning then surfaced a constraint: the official MCP registry only accepts packages from NPM / PyPI / NuGet / Docker-OCI / MCPB. A `uvx --from git+...` install isn't accepted. Decision (2026-05-11): reverse the deferral. Publish to PyPI; declare the PyPI entry in the registry-listing server.json. The "permanent namespace" concern that drove the original deferral is now mitigated — the v0.1.0 API surface (route_intent / describe / verify) is exactly what shipped to real agents in Phase 4, so the PyPI commit is no longer speculative. ### Plan doc — §5.3 rewritten The "Distribution: GitHub-first, not PyPI" paragraph now reads "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 requires the server be reachable through a registry-supported channel." Three install paths surfaced in recommended order: PyPI (primary, what the registry references), GitHub Release wheel (backup), git+url via uvx (pre-release testing). ### Plan doc — Phase 6 rewritten The "Required ships" list now has three entries: (1) PyPI publication via `uv publish`; (2) MCP registry listing via `mcp-publisher publish` referencing the PyPI entry; (3) release-tag maintenance workflow that does both. The "Optional deferred" list drops PyPI (no longer deferred) and keeps only the VS Code extension as a future possibility. ### Plan doc — §7 Phase-4 + §10 distribution table Phase-4 description note: now reads "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)." Distribution table's m-dev-tools-mcp row rewritten to list all three channels + the registry listing. ### Architecture doc — §1.2 + §4.6 §1.2 "What MCP clients need on top of discovery" — the frictionless-install bullet now lists `pip install m-dev-tools-mcp` first, then the wheel and uvx paths. The "No PyPI registration" sentence is gone. §4.6 "Ship the MCP server through a new distribution channel" — the lead paragraph now says four channels (PyPI / GH-Release wheel / uvx / MCP registry) and the maintainer recipe drops PyPI from the "to add a new channel" example. ### Users guide — new Option 0 under §A.1 Added "Option 0 — PyPI (works for any MCP client that points at a binary on $PATH)" at the top of §A.1, with `pip install m-dev-tools-mcp` + the resulting one-line `.mcp.json` / `.vscode/mcp.json` config. Existing Options 1-3 remain as fallbacks; phrasing notes Option 0 is the recommended path once m-dev-tools-mcp is on PyPI (Phase-6 ship). ### Verified * make check-docs-prose / check-freshness / check-links / check-licenses / check-schema-compat / recipes-check / handshake / validate-catalog — all clean. ### What lands next (out of this PR) PR 2 on m-dev-tools-mcp: server.json with `registryType: pypi` at the repo root + a `release.yml` GitHub Action that does `uv build` + `uv publish` (Trusted Publisher OIDC) + `mcp-publisher publish` (GitHub OIDC) on every `v*` tag. --- .../AI-discoverability-architecture.md | 36 ++++---- .../AI-discoverability-plan.md | 82 +++++++++++-------- docs/ai-discoverability/ai-users-guide.md | 34 ++++++++ 3 files changed, 103 insertions(+), 49 deletions(-) diff --git a/docs/ai-discoverability/AI-discoverability-architecture.md b/docs/ai-discoverability/AI-discoverability-architecture.md index 0d030c9..0de50e3 100644 --- a/docs/ai-discoverability/AI-discoverability-architecture.md +++ b/docs/ai-discoverability/AI-discoverability-architecture.md @@ -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+…@` (pin to a - release tag, install on demand) and `pip install ` - 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 ` (GitHub Release wheel), + and `uvx --from git+…@` (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 @@ -387,15 +388,22 @@ repo root, the generator resolves it against the raw-content prefix. ### 4.6 Ship the MCP server through a new distribution channel The MCP server (`m-dev-tools-mcp`) is currently distributed through -three channels: a `uvx --from git+...@` install, a GitHub -Release wheel, and the 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 (PyPI, a VS Code extension bundling the -server, a Homebrew tap, …): +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 `. Backup + for environments that can't reach PyPI. +3. **`uvx --from git+...@`** — 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 diff --git a/docs/ai-discoverability/AI-discoverability-plan.md b/docs/ai-discoverability/AI-discoverability-plan.md index bf7e3d4..9f1a957 100644 --- a/docs/ai-discoverability/AI-discoverability-plan.md +++ b/docs/ai-discoverability/AI-discoverability-plan.md @@ -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/m_dev_tools_mcp--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 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/m_dev_tools_mcp--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 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. --- @@ -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/...whl` @@ -441,20 +446,27 @@ hand-roll a `.mcp.json` to use it. Required ships: -1. **Official MCP registry listing.** Publish +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; `mcp-publisher publish` lands it - in the registry. Once listed, any registry-aware client (Codex, - Continue, Goose, …) auto-discovers without `.mcp.json` config. -2. **Maintenance:** every release tag (`v0.1.1`, `v0.2.0`, …) - triggers `mcp-publisher publish` from a GitHub-Actions workflow - in `m-dev-tools-mcp`, so the registry stays in sync. + `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): -- **PyPI.** Same deferral rationale as §5.3. - **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. @@ -516,7 +528,7 @@ that requires careful agent prompting — encoded in `AGENTS.md` and | Each repo | `AGENTS.md`, `dist/repo.meta.json`, `dist/.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. diff --git a/docs/ai-discoverability/ai-users-guide.md b/docs/ai-discoverability/ai-users-guide.md index 4504449..0b24865 100644 --- a/docs/ai-discoverability/ai-users-guide.md +++ b/docs/ai-discoverability/ai-users-guide.md @@ -75,6 +75,40 @@ part is about the wiring. Pick the option that matches the AI extension you're using. +#### Option 0 — PyPI (works for any MCP client that points at a binary on `$PATH`) + +```bash +pip install m-dev-tools-mcp +# or with uv: +uv pip install m-dev-tools-mcp +``` + +Then point your client's MCP config at the `m-dev-tools-mcp` +executable. For Claude Code's `.mcp.json`: + +```json +{ + "mcpServers": { + "m-dev-tools": { "command": "m-dev-tools-mcp" } + } +} +``` + +For Copilot Chat's `.vscode/mcp.json`: + +```json +{ + "servers": { + "m-dev-tools": { "type": "stdio", "command": "m-dev-tools-mcp" } + } +} +``` + +This is the recommended path once `m-dev-tools-mcp` is on PyPI +(target: Phase 6 ship). Options 1–3 below all still work and are +the fallbacks when you'd rather not `pip install` into your +environment. + #### Option 1 — GitHub Copilot Chat (VS Code, agent mode) Create `.vscode/mcp.json` at your workspace root: