fix(scaffold): born-green mcp-servers, escaped output, single pin table

Born green (#102): --type mcp-server now generates a minimal TypeScript
MCP server (src/index.ts, src/server.ts with createServer(), a vitest
test, tsconfig.json) with real tsc/vitest scripts and SDK dependencies.
ci.yml and publish.yml use npm ci plus the npm cache once a lockfile is
committed and npm install before that, so the first push is green. New
born-green clause C7, and the Validate scaffold CI job installs, builds
and tests a generated server. Verified locally, including a stdio
tools/call round trip against the built dist/index.js.

Escaping (#103): JSON and Python templates use json_str / json_inner
filters, HTML templates autoescape, and generate_repo validates input
(no control characters; no quotes, backslashes, angle brackets or
backticks in names; length limits) before writing anything.

Runtimes and docs (#121): --mcp-server with --type mcp-server is rejected
instead of mixing a Python server into a TypeScript package. Deployed
service docs no longer describe publish.yml or npm publishing, and the
mcp-server docs describe the generated layout instead of a nonexistent
src/providers/ProviderManager.

Pins (#122): ACTION_PINS in generator.py is the one source for actions/*
majors (matching the meta-repo); rendered workflows are normalized to it
and a test keeps template literals in sync. Node matrix is [22, 24] and
engines >=22 (Node 20 is end of life).

Papercuts (#123): the registry duplicate check runs before rendering, so
a duplicate leaves no partial repo; negative counts are rejected; the
printed next step uses git commit -s with double quotes; package.json
whitespace fixed.

Docs (#104): every documented scaffold test command passes --no-register,
CLAUDE.md lists the real CLI flags and outputs and warns that
registration is on by default, the --help examples include the required
--description, and the dead index.html.j2 template is removed.

New registry entries default to the developer-tooling category.

Closes #102
Closes #103
Closes #104
Closes #121
Closes #122
Closes #123

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>

Author: TMHSDigital

.github/workflows/README.md

@@ -27,8 +27,8 @@ Third-party actions are pinned by full commit SHA, with the version tag in a com
 First-party GitHub actions (`actions/`, `github/`) may use a major-version tag:
 
 ```yaml
-- uses: actions/checkout@v6
-- uses: actions/setup-python@v5
+- uses: actions/checkout@v7
+- uses: actions/setup-python@v6
 ```
 
 Rationale: tags are mutable and can be retargeted to a malicious commit. SHAs are immutable. GitHub-owned actions are exempt because GitHub's own security model protects them.

.github/workflows/validate.yml

@@ -96,6 +96,27 @@ jobs:
           grep -qv 'gh workflow run publish.yml' /tmp/scaffold-service/ci-deployed-service/.github/workflows/release.yml
           echo "Deployed-service scaffold test passed"
 
+          python3 scaffold/create-tool.py \
+            --name "CI Npm Server" \
+            --description "Automated npm mcp-server test" \
+            --type mcp-server \
+            --no-register \
+            --output /tmp/scaffold-npm
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+
+      # Born-green clause C7: the generated repo's own CI commands pass on
+      # the untouched generated tree.
+      - name: Generated mcp-server builds and tests green
+        working-directory: /tmp/scaffold-npm/ci-npm-server
+        run: |
+          npm install --no-audit --no-fund
+          npm run build
+          npm test
+          test -f dist/index.js
+
       - name: Scaffold YAML well-formed
         run: |
           # Catches Jinja2 trim_blocks bugs that collapse adjacent expression lines.

CLAUDE.md

@@ -59,9 +59,11 @@ Pure-stdlib Python script that regenerates README tables and stats, CLAUDE.md ca
 
 ### scaffold/create-tool.py
 
-CLI args: `--name`, `--slug`, `--description`, `--type`, `--mcp-server`, `--skills N`, `--rules N`, `--license`, `--output`, `--author-name`, `--author-email`.
+Thin CLI over `scaffold/generator.py` (`generate_repo`). CLI args: `--name`, `--slug`, `--description`, `--type` (cursor-plugin | mcp-server), `--mcp-server` (cursor-plugin only: adds a Python MCP server), `--deployed-service` (mcp-server archetype without npm), `--skills N`, `--rules N`, `--license`, `--output`, `--author-name`, `--author-email`, `--no-register`, `--registry-root`. Run `python scaffold/create-tool.py --help` for the authoritative list.
 
-Templates in `scaffold/templates/` produce: plugin.json, GitHub Actions workflows, README.md, AGENTS.md, CLAUDE.md, CONTRIBUTING.md, CHANGELOG.md, CODE_OF_CONDUCT.md, SECURITY.md, ROADMAP.md, LICENSE, .cursorrules, .gitignore, docs/index.html, and optional mcp-server/ scaffold.
+**Registration is on by default:** without `--no-register`, the scaffold appends the new repo to `registry.json` and regenerates README, CLAUDE.md, and the docs site. Always pass `--no-register` for throwaway or test runs.
+
+Templates in `scaffold/templates/` produce: GitHub Actions workflows, README.md, AGENTS.md, CLAUDE.md, CONTRIBUTING.md, CHANGELOG.md, CODE_OF_CONDUCT.md, SECURITY.md, ROADMAP.md, LICENSE, .cursorrules, .gitignore, .gitattributes, site.json, mcp-tools.json, and dependabot.yml. Cursor plugins also get `.cursor-plugin/plugin.json` (plus an optional Python `mcp-server/`); mcp-servers get `package.json`, a buildable TypeScript skeleton (`src/`, `tsconfig.json`, vitest test), and `docs/index.html`. Generated output must meet [`standards/born-green-contract.md`](standards/born-green-contract.md).
 
 ### docs/ (catalog site)
 
@@ -135,9 +137,12 @@ python scaffold/create-tool.py \
   --mcp-server \
   --skills 2 \
   --rules 1 \
+  --no-register \
   --output /tmp/test
 ```
 
+`--no-register` keeps the throwaway repo out of `registry.json`.
+
 ### Testing the docs site locally
 
 Open `docs/index.html` in a browser. The script falls back to embedded registry data when not served from GitHub Pages.

CONTRIBUTING.md

@@ -157,15 +157,17 @@ python scripts/drift_check/cli.py --local /path/to/tool-repo
      --mcp-server \
      --skills 2 \
      --rules 1 \
+     --no-register \
      --output /tmp/scaffold-test
    ```
+   `--no-register` keeps the test repo out of `registry.json`.
 3. Verify the generated files look correct
 4. Commit with `fix:` or `chore:` prefix
 
 ### Adding a new template
 
 1. Create the `.j2` file in `scaffold/templates/`
-2. Update `scaffold/create-tool.py` to render it via `write_file()`
+2. Render it from `_render_repo()` in `scaffold/generator.py` via `write_file()`
 3. Run a test generation and verify the new file appears
 4. Update `README.md` "What it generates" section if visible to users
 5. Commit with `feat: add <template-name> scaffold template`

docs/contributors/adding-a-tool.md

@@ -20,11 +20,11 @@ python scaffold/create-tool.py \
   --mcp-server \
   --skills 6 \
   --rules 4 \
-  --license CC-BY-NC-ND-4.0 \
+  --license cc-by-nc-nd-4.0 \
   --output ../
 ```
 
-This produces `../Cloudflare-Developer-Tools/` with the full standards-compliant layout.
+This produces `../cloudflare-developer-tools/` with the full standards-compliant layout, and (because registration is on by default) adds a schema-valid entry to `registry.json` and regenerates the README, CLAUDE.md, and docs site. Pass `--no-register` only for a throwaway trial run.
 
 ## Step 2: Push the new repo
 

scaffold/create-tool.py

@@ -33,16 +33,26 @@
     )
 
 
+def _non_negative_int(value: str) -> int:
+    try:
+        number = int(value)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"{value!r} is not an integer") from None
+    if number < 0:
+        raise argparse.ArgumentTypeError("must be zero or greater")
+    return number
+
+
 def parse_args():
     parser = argparse.ArgumentParser(
         description="Scaffold a new TMHSDigital developer tool repository",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""
 Examples:
   python create-tool.py --name "Unreal Developer Tools" --description "Cursor plugin for Unreal Engine"
-  python create-tool.py --name "AWS MCP Server" --type mcp-server --mcp-server
-  python create-tool.py --name "Hosted Radar" --type mcp-server --deployed-service
-  python create-tool.py --name "K8s Developer Tools" --mcp-server --skills 5 --rules 3
+  python create-tool.py --name "AWS MCP Server" --description "MCP server for AWS" --type mcp-server
+  python create-tool.py --name "Hosted Radar" --description "Hosted MCP service" --type mcp-server --deployed-service
+  python create-tool.py --name "K8s Developer Tools" --description "Cursor plugin for Kubernetes" --mcp-server --skills 5 --rules 3
   python create-tool.py --name "Throwaway" --description test --no-register
         """,
     )
@@ -55,7 +65,14 @@ def parse_args():
         default="cursor-plugin",
         help="Repository type (default: cursor-plugin)",
     )
-    parser.add_argument("--mcp-server", action="store_true", help="Include MCP server scaffold")
+    parser.add_argument(
+        "--mcp-server",
+        action="store_true",
+        help=(
+            "cursor-plugin only: include a Python MCP server under mcp-server/. "
+            "--type mcp-server already generates a TypeScript server."
+        ),
+    )
     parser.add_argument(
         "--deployed-service",
         action="store_true",
@@ -64,8 +81,8 @@ def parse_args():
             "the registry npm field; writes .drift-check.json. Requires --type mcp-server."
         ),
     )
-    parser.add_argument("--skills", type=int, default=0, help="Number of placeholder skill directories to create")
-    parser.add_argument("--rules", type=int, default=0, help="Number of placeholder rule files to create")
+    parser.add_argument("--skills", type=_non_negative_int, default=0, help="Number of placeholder skill directories to create")
+    parser.add_argument("--rules", type=_non_negative_int, default=0, help="Number of placeholder rule files to create")
     parser.add_argument(
         "--license",
         choices=list(LICENSE_FILES.keys()),
@@ -134,7 +151,7 @@ def main() -> int:
     print(f"\nDone! Repository scaffolded at: {output_dir}")
     print("\nNext steps:")
     print(f"  1. cd {output_dir}")
-    print("  2. git init && git add -A && git commit -m 'feat: initial scaffold'")
+    print('  2. git init && git add -A && git commit -s -m "feat: initial scaffold"')
     print(f"  3. Create GitHub repo: gh repo create TMHSDigital/{slug} --public --source .")
     print("  4. Enable GitHub Pages in Settings > Pages > Source: GitHub Actions")
     if args.no_register: