@ssheleg/make-skill 0.9.1 → 0.11.0

package/plugins/make-skill/skills/make-skill/references/mcp-ship.md

@@ -0,0 +1,275 @@
+# Shipping an MCP server — mount, debug, publish
+
+**Load this when:** the server is written and now has to reach someone —
+mounting it inside an existing web app, fixing a client that cannot connect, or
+publishing it to the official MCP Registry.
+
+`references/mcp.md` is the author's model of the protocol: primitives,
+lifecycle, transports, security. This file starts where that one stops. If you
+are still designing tools and their schemas, Anthropic's `mcp-builder` skill
+covers authoring and evaluation in depth and this file deliberately does not
+repeat it — **it has nothing on the registry, on mounting, or on why a client
+sees 404, which is exactly what is here.**
+
+Registry schema URL and CLI flags move. Read them from
+<https://modelcontextprotocol.io/registry/> and the
+[registry repo](https://github.com/modelcontextprotocol/registry) rather than
+from a copy — the pinned example below was current on **2026-08-06** and the
+schema is dated by design.
+
+## Contents
+
+- Mounting into an existing web app
+- Auth middleware and a health endpoint
+- Client configuration
+- Debugging a client that will not connect
+- Publishing to the MCP Registry
+- Registry name formats and who may claim them
+- Automating publication
+- Versioning
+
+---
+
+## Mounting into an existing web app
+
+The common production shape: you already run a FastAPI/Starlette app, and the
+MCP server should live at `/mcp` on the same host. It is also where the single
+most common bug lives.
+
+**The double-path pitfall.** FastMCP defaults its internal
+`streamable_http_path` to `/mcp/`. Mount that app at `/mcp` and the real
+endpoint becomes `/mcp/mcp` — so every client pointed at `/mcp` gets 404, and
+the SSE fallback 404s too, which reads like the server is down.
+
+```python
+mcp = FastMCP(
+    "my_server",
+    streamable_http_path="/",   # REQUIRED when mounting as a sub-app
+    stateless_http=True,
+    json_response=True,
+)
+
+app.mount("/mcp", mcp.streamable_http_app())
+```
+
+Set `streamable_http_path="/"` whenever the app is mounted rather than served
+standalone. Standalone servers keep the default.
+
+---
+
+## Auth middleware and a health endpoint
+
+Wrap the mounted ASGI app rather than adding auth inside tool handlers — the
+transport handshake happens before any tool runs, so handler-level auth leaves
+the protocol surface open.
+
+```python
+class MCPAuthMiddleware:
+    _PUBLIC_PATHS = {"/health"}
+
+    def __init__(self, app, *, store):
+        self._app, self._store = app, store
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] not in ("http", "websocket"):
+            return await self._app(scope, receive, send)
+        if scope.get("path", "") in self._PUBLIC_PATHS:
+            return await self._app(scope, receive, send)
+
+        headers = dict(scope.get("headers", []))
+        auth = headers.get(b"authorization", b"").decode()
+        if not auth.startswith("Bearer "):
+            return await self._send_401(send, "Missing Bearer token")
+        if not await self._store.validate_api_key(auth[7:]):
+            return await self._send_401(send, "Invalid API key")
+        return await self._app(scope, receive, send)
+
+app.mount("/mcp", MCPAuthMiddleware(mcp.streamable_http_app(), store=key_store))
+```
+
+Keep a health endpoint **outside** the mount and exempt from auth. It is what
+tells you "the app is up, the MCP path is wrong" apart from "the app is down" —
+the two produce identical client errors.
+
+```python
+@app.get("/mcp/health")
+async def mcp_health():
+    return {"status": "ok", "server": "my_server", "transport": "streamable-http"}
+```
+
+---
+
+## Client configuration
+
+Remote (streamable HTTP):
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "url": "https://example.com/mcp",
+      "headers": { "Authorization": "Bearer ${MY_SERVER_KEY}" }
+    }
+  }
+}
+```
+
+Local (stdio):
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "uv",
+      "args": ["--directory", "/path/to/project", "run", "python", "-m", "my_server"],
+      "env": { "API_KEY": "..." }
+    }
+  }
+}
+```
+
+Ship both forms in your README. A user who has to derive the config from prose
+files an issue instead.
+
+---
+
+## Debugging a client that will not connect
+
+**404 — by far the most common.** Symptom: `Error POSTing to endpoint: Not
+Found`, then the SSE fallback 404s as well. Bisect the path directly:
+
+```bash
+curl -X POST https://your-host/mcp/     -H 'Content-Type: application/json' -d '{}'
+curl -X POST https://your-host/mcp      -H 'Content-Type: application/json' -d '{}'
+curl -X POST https://your-host/mcp/mcp  -H 'Content-Type: application/json' -d '{}'
+```
+
+If `/mcp/mcp` answers (even 401) while `/mcp/` 404s, it is the double path.
+A 401 is a **success** for this test: it proves routing reached the server.
+
+**307.** Starlette redirects `/mcp` → `/mcp/`. Most clients follow it on POST;
+some do not, and the failure looks like a hang. Either document the trailing
+slash or add an explicit no-slash route.
+
+**401.** Check the Bearer prefix and the key, then check that the client is
+actually sending headers — several clients drop custom headers on the SSE
+fallback specifically, so the initial POST authenticates and the stream does not.
+
+---
+
+## Publishing to the MCP Registry
+
+The registry stores **metadata pointing at your server**, not the server. You
+publish a `server.json`.
+
+Remote server:
+
+```json
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "com.example/my-mcp",
+  "title": "My MCP Server",
+  "description": "What it does (max 100 chars).",
+  "version": "1.0.0",
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://example.com/mcp",
+      "headers": [
+        { "name": "Authorization", "description": "Bearer API key",
+          "isRequired": true, "isSecret": true }
+      ]
+    }
+  ]
+}
+```
+
+Local package (npm shown; `pypi` takes the same shape with `registryType`
+changed):
+
+```json
+{
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@username/my-mcp-server",
+      "version": "1.0.0",
+      "transport": { "type": "stdio" }
+    }
+  ]
+}
+```
+
+PyPI additionally requires `<!-- mcp-name: your-server-name -->` in the package
+README, as proof the package and the registry entry belong to the same author.
+
+Validate before you publish — `description` is capped at **100 characters** and
+a version may be published only once:
+
+```bash
+mcp-publisher validate
+mcp-publisher publish
+curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=my-mcp"
+```
+
+---
+
+## Registry name formats and who may claim them
+
+The name is not free-form: it encodes how you proved ownership.
+
+| Auth method | Name format | Example |
+|---|---|---|
+| GitHub | `io.github.<user>/*` | `io.github.alice/weather` |
+| DNS | reverse-DNS of the domain | `com.example/my-server` |
+| HTTP | reverse-DNS of the domain | `com.example/my-server` |
+
+**GitHub** is the shortest path — `mcp-publisher login github`, OAuth device
+flow, done. The name must start with your username.
+
+**DNS** and **HTTP** claim a domain with an Ed25519 key. DNS puts the public key
+in a TXT record; HTTP serves it at
+`https://<domain>/.well-known/mcp-registry-auth`. Use HTTP when you control the
+web root but not the zone.
+
+```bash
+openssl genpkey -algorithm Ed25519 -out mcp-registry-key.pem
+PUBLIC_KEY="$(openssl pkey -in mcp-registry-key.pem -pubout -outform DER | tail -c 32 | base64)"
+# DNS:  <domain>. IN TXT "v=MCPv1; k=ed25519; p=${PUBLIC_KEY}"
+# HTTP: echo "v=MCPv1; k=ed25519; p=${PUBLIC_KEY}" > mcp-registry-auth
+```
+
+Treat `mcp-registry-key.pem` as a publishing credential: it is the thing that
+lets someone replace your server entry. It belongs in a secret store, not the
+repository, and the CI job that uses it should be the only consumer.
+
+---
+
+## Automating publication
+
+Same shape as the skill releases in `references/distribution.md`: a `v*` tag
+triggers validate → publish. Two rules carry over unchanged.
+
+- **Gate the publish on the validator**, in the same job. A registry entry
+  pointing at a broken build is worse than no entry, because clients cache it.
+- **Fail on a version already published** rather than skipping quietly. A silent
+  skip is how a tag ends up green while the registry still serves the previous
+  version.
+
+Install the CLI in CI from the released binary:
+
+```bash
+curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+```
+
+---
+
+## Versioning
+
+The registry version is the **server's** version, and it is what clients compare
+against. Keep it equal to the package version — an npm package at 1.2.0 whose
+registry entry says 1.0.0 makes every bug report unactionable.
+
+The `$schema` date and your version are unrelated: the schema is the registry's
+contract and moves on the registry's schedule, so re-read it before each publish
+rather than carrying the pinned URL forward on faith.

package/plugins/make-skill/skills/make-skill/references/retrofit.md

@@ -14,18 +14,33 @@ standard — including the no-argument `/make-skill` path, where a `SKILL.md`,
 
 ## Run the script first
 
-The mechanical half is deterministic — do not reason your way through it:
+The mechanical half is deterministic — do not reason your way through it. In
+Claude Code the plugin's `bin/` is on the Bash tool's PATH, so the auditor is
+reachable by name:
 
 ```bash
-python3 "${CLAUDE_PLUGIN_ROOT}/skills/make-skill/scripts/audit_skill.py" <skill-dir> --house
+make-skill-audit <skill-dir> --house
 ```
 
-`${CLAUDE_PLUGIN_ROOT}` is Claude Code's. On any other host the script sits at
-`scripts/audit_skill.py` inside the make-skill directory you are reading this
-from (`~/.agents/skills/make-skill/`, `~/.claude/skills/make-skill/`). No
-`python3` at all? Check items 1 and 9 below by hand against
-`references/agent-skills-spec.md` — the script implements that checklist and
-nothing more. Either way, the judgement items are yours.
+On any other host, run the script it wraps — `scripts/audit_skill.py` inside the
+make-skill directory you are reading this from (`~/.agents/skills/make-skill/`,
+`~/.claude/skills/make-skill/`):
+
+```bash
+python3 <make-skill dir>/scripts/audit_skill.py <skill-dir> --house
+```
+
+**Do not build the command out of `${CLAUDE_PLUGIN_ROOT}`.** That variable is
+substituted into skill, command and agent *text*, but it is **not exported to
+the Bash tool's environment** — a command written around it expands to
+`/skills/...` and dies with "No such file or directory" (measured, Claude Code
+2.1.220). That failure is how a mechanical check turns into a reasoned-about
+PASS, which is the one outcome this file exists to prevent.
+
+No `python3` at all? Record items 1 and 9 as **NOT-RUN** with that reason and
+check them by hand against `references/agent-skills-spec.md` — the script
+implements that checklist and nothing more. Either way, the judgement items are
+yours.
 
 ## How to report
 
@@ -35,11 +50,21 @@ Audit first, fix second, in the same session. One verdict per item:
 |---|---|
 | **PASS** | the check was actually run — a command's output or a `file:line` |
 | **GAP** | what is wrong, the evidence, and the fix that closes it |
+| **NOT-RUN** | the tool the check needs is absent — name the tool and the reason |
 
 "Looks fine" is not a verdict. Neither is a PASS on a check that was reasoned
 about rather than executed: `python3 test/validate.py`, `claude plugin validate
 … --strict`, `npx skills add <repo> --list` all produce output, and the output is
-the evidence. Report the gap table before changing anything, then fix.
+the evidence.
+
+**NOT-RUN exists so that "I could not run this" has somewhere to go.** A
+checklist with only PASS and GAP forces an unrunnable check into one of them,
+and the cheaper lie is PASS. Item 1's `skills-ref validate` is the standing
+example: it installs from source only, so on most machines it is NOT-RUN, and
+saying so is the honest result. A NOT-RUN you did not try to resolve is still a
+gap in the audit — say what would make it runnable.
+
+Report the table before changing anything, then fix.
 
 ## The 14-item audit checklist
 
@@ -84,15 +109,17 @@ the evidence. Report the gap table before changing anything, then fix.
     skills add <repo> --list` lists ONLY real skills; `npx <name>` works from a
     non-repo cwd if it is published; `.mdc` rules valid and free of relative
     links.
-11. **Repo meta**: homepage, description and topics set on the forge; LICENSE
+11. **Repo meta**: homepage, description and topics set on the forge (any
+    consistent homepage convention — do not "fix" a deliberate one); LICENSE
     present and declared in the front matter and the marketplace entry;
     CHANGELOG current; public repos also carry CONTRIBUTING.md and SECURITY.md.
 12. **Gotcha compliance**: the list in `SKILL.md`, plus the installer traps in
     `references/distribution.md` when the repo ships a CLI or a validator.
 13. **Protocol dependencies** if it touches MCP or A2A (`references/mcp.md`,
-    `references/a2a.md`): dependency and protocol version in `compatibility`,
-    discovery instead of hardcoded tool names, the untrusted-output rule stated,
-    interactive auth handled as a human step rather than a retry loop.
+    `references/mcp-ship.md` once a server is being shipped, `references/a2a.md`):
+    dependency and protocol version in `compatibility`, discovery instead of
+    hardcoded tool names, the untrusted-output rule stated, interactive auth
+    handled as a human step rather than a retry loop.
 14. **Host capabilities and their fallbacks**
     (`references/host-capabilities.md`) if it ships a hook, subagent, command or
     MCP server: the degradation contract written in the body for all three axes

package/plugins/make-skill/skills/make-skill/scripts/audit_skill.py

@@ -171,7 +171,10 @@ def _check_name(a, fm, lines, dir_name, rel):
         a.gap("NAME_CHARSET", "name %r must be lowercase a-z0-9 with single internal "
               "hyphens — no uppercase, no leading/trailing or doubled hyphen" % name, rel, ln)
     else:
-        a.ok("NAME_CHARSET", "name %r is spec-legal" % name, rel, ln)
+        # Charset only. Saying "spec-legal" here would contradict NAME_RESERVED
+        # and NAME_XML below, and a PASS line quoted out of context is exactly
+        # how a wrong verdict acquires real command output as its evidence.
+        a.ok("NAME_CHARSET", "name %r uses a legal charset" % name, rel, ln)
     if name != dir_name:
         a.gap("NAME_DIR", "name %r != directory %r — the spec requires them to match, "
               "and the Skills API matches the uploaded top-level directory against it"
@@ -211,10 +214,16 @@ def _check_description(a, fm, lines, rel, house):
     else:
         a.ok("DESC_PERSON", "description is third person", rel, ln)
     if house:
+        # Both report either way: "the house rules were checked" has to be
+        # provable from the output the canon tells the agent to cite.
         if not desc.lower().startswith("use when"):
             a.gap("DESC_USEWHEN", "description must start with 'Use when …' (house rule)", rel, ln)
+        else:
+            a.ok("DESC_USEWHEN", "description opens with 'Use when …' (house rule)", rel, ln)
         if not re.search(r"[а-яё]", desc, re.I):
             a.gap("DESC_RU", "description carries no Russian trigger phrases (house rule)", rel, ln)
+        else:
+            a.ok("DESC_RU", "description carries Russian trigger phrases (house rule)", rel, ln)
 
 
 def _check_optional_fields(a, fm, lines, rel):
@@ -253,13 +262,18 @@ def _check_keys(a, fm, lines, rel):
 def _check_body_budget(a, body, rel):
     n_lines = body.count("\n") + 1
     est = int(len(body) / CHARS_PER_TOKEN)
+    # Both, not either: a body over the line budget still has to report its
+    # token count, or the second fix arrives only after the first one ships.
+    over = False
     if n_lines >= BODY_MAX_LINES:
         a.gap("BODY_LINES", "body is %d lines, the budget is < %d — move detail into "
               "references/" % (n_lines, BODY_MAX_LINES), rel)
-    elif est >= BODY_MAX_TOKENS:
+        over = True
+    if est >= BODY_MAX_TOKENS:
         a.gap("BODY_TOKENS", "body is ~%d tokens (%d chars / %s), the budget is < %d"
               % (est, len(body), CHARS_PER_TOKEN, BODY_MAX_TOKENS), rel)
-    else:
+        over = True
+    if not over:
         a.ok("BODY_BUDGET", "body is %d lines / ~%d tokens (budget %d / %d)"
              % (n_lines, est, BODY_MAX_LINES, BODY_MAX_TOKENS), rel)
 
@@ -295,21 +309,27 @@ def _check_bundle(a, skill_dir, skill_text, dir_name):
 
 
 def _check_links(a, skill_dir, skill_text, rel):
-    """A relative link that escapes the skill directory arrives broken everywhere."""
-    escaped = broken = False
-    for target in LINK_RE.findall(skill_text):
-        if target.startswith(("http://", "https://", "mailto:", "#")):
-            continue
-        if target.startswith("../") or "/../" in target:
-            a.gap("LINK_ESCAPE", "link %r escapes the skill directory — packagers ship "
-                  "that directory alone, so it arrives broken on every agent" % target, rel)
-            escaped = True
-            continue
-        path = os.path.normpath(os.path.join(skill_dir, target.split("#")[0]))
-        if not os.path.exists(path):
-            a.gap("LINK_BROKEN", "link %r does not resolve" % target, rel)
-            broken = True
-    if not escaped and not broken:
+    """A relative link that escapes the skill directory arrives broken everywhere.
+
+    Reported per line: the canon defines evidence as a `file:line`, so a finding
+    without one forces the agent to either drop the evidence or invent it.
+    """
+    bad = False
+    for i, line in enumerate(skill_text.split("\n"), start=1):
+        for target in LINK_RE.findall(line):
+            if target.startswith(("http://", "https://", "mailto:", "#")):
+                continue
+            if target.startswith("../") or "/../" in target:
+                a.gap("LINK_ESCAPE", "link %r escapes the skill directory — packagers "
+                      "ship that directory alone, so it arrives broken on every agent"
+                      % target, rel, i)
+                bad = True
+                continue
+            path = os.path.normpath(os.path.join(skill_dir, target.split("#")[0]))
+            if not os.path.exists(path):
+                a.gap("LINK_BROKEN", "link %r does not resolve" % target, rel, i)
+                bad = True
+    if not bad:
         a.ok("LINK_INTEGRITY", "every relative link resolves and stays inside the skill", rel)
 
 
@@ -335,8 +355,11 @@ def _check_prose(a, body, rel):
             a.gap("TIME_BRANCH", "time-branching instruction (%r) — it is wrong the day "
                   "it ships; put superseded material under '## Old patterns'"
                   % raw.strip()[:60], rel, i)
-    # a pointer at a directory rather than a file with a load condition
-    for i, line in enumerate(body.split("\n"), start=1):
+    # A pointer at a directory rather than a file with a load condition. Quoted
+    # spans are blanked here too: a canon that forbids "see references/" has to
+    # be able to quote the phrase it forbids.
+    for i, raw in enumerate(body.split("\n"), start=1):
+        line = _strip_quoted(raw)
         if re.search(r"\b(?:see|read)\s+`?(?:references|scripts|assets)/`?(?![\w.-])", line, re.I):
             a.gap("REF_NO_TRIGGER", "points at a directory instead of a file with a "
                   "stated load condition — 'read X when Y' beats 'see references/'", rel, i)