@rhize/skill-forge 0.4.0 → 0.6.0

package/LICENSE

@@ -15,6 +15,7 @@ Pro Modules
 
 - src/license.ts
 - src/gate/overlap.ts
+- src/gate/mcpOverlap.ts
 - src/provenance.ts
 - src/queue.ts
 

package/README.md

@@ -117,6 +117,9 @@ nothing is left behind to record. These are Pro features that run free during th
 [docs/pro.md](docs/pro.md#beta-pricing-0x)): with no valid license, `add` still writes them, and
 prints a one-line notice above the report instead of skipping them.
 
+`add`/`scan` also accept `--artifact mcp` (plus `add`-only `--mcp-target <file>`/`--force`) to gate
+an MCP server instead of a skill — see [MCP gating](#mcp-gating-v05) below.
+
 ### `scan`
 
 ```bash
@@ -135,6 +138,90 @@ nonzero when the safety verdict is `block`. `--json` prints the same gate-result
 promoted or rejected). `status` shows the resolved configuration (skills roots, quarantine dir,
 strictness) plus a count of held entries.
 
+## MCP gating (v0.5)
+
+`add` and `scan` can also gate an **MCP server** instead of a skill — the same quarantine →
+profile → safety scan → overlap analysis → report → promote/hold/reject pipeline, applied to an
+MCP server candidate rather than a skill:
+
+```bash
+skill-forge scan ./my-mcp-server --artifact mcp
+skill-forge add @scope/some-mcp-server --artifact mcp --mcp-target ~/.claude.json
+skill-forge add https://github.com/owner/mcp-server.git --artifact mcp --yes
+```
+
+Pass `--artifact mcp` explicitly — skill-forge never guesses. In particular, an npm package name
+(`@scope/name`, or a bare `some-mcp-server` name) is only treated as an npm source with this flag;
+without it, the same string resolves as a skills.sh `owner/name` slug instead (no ambiguity
+guessing between the two).
+
+**Source forms**
+
+| Form | Example | How it's fetched |
+|---|---|---|
+| Local directory | `./my-mcp-server` | Copied into quarantine, same as a local skill source. |
+| Git URL | `https://github.com/owner/mcp-server.git` | Shallow-cloned into quarantine, same as a git skill source. |
+| npm package | `@scope/name` or `some-mcp-server` | `npm pack <name> --pack-destination <quarantine>`, then tarball **extraction only** — never `npm install`, never lifecycle scripts. |
+
+**What's gated**
+
+Safety runs the same built-in deny-pattern ruleset used for skills (curl\|bash, credential-file
+access, etc.) plus MCP-specific rules: inline credential values in config/env, unpinned `npx -y`
+launch commands, `--dangerously-*`/`--no-sandbox` flags, and filesystem-root launch args — see the
+[MCP safety ruleset table](docs/gate-policy.md#mcp-safety-ruleset). Overlap analysis (Pro, free
+during the 0.x beta) ranks the candidate against the server entries already present in your
+configured `mcpTargets` files, instead of against a skills root.
+
+**Capability profile (v0.6).** The report also includes a **static** capability summary — tool,
+resource, and prompt counts, plus a `declaredConfidence` (`high`/`partial`/`none`) — parsed from
+the candidate's `package.json`, any shipped `.mcp.json`/manifest, and MCP SDK source-text patterns
+(`server.tool(...)`, `setRequestHandler(ListToolsRequestSchema, ...)`, etc.):
+
+```
+Artifact type       : mcp
+Capabilities        : 2 tools, 1 resource, 0 prompts (declaredConfidence: high)
+```
+
+This is free (it's profiling, not a Pro feature) and **never derived by running the candidate
+server** — anything that can't be determined from source text is reported as undetermined rather
+than discovered by executing it. `--json` includes the full `tools`/`resources`/`prompts` name
+lists under `profile.capabilities`.
+
+**Promote semantics**
+
+Promoting an MCP candidate writes ONE server entry into a target MCP config file's `mcpServers`
+map — it never touches a skills root:
+
+```json
+{ "mcpServers": { "<name>": { "command": "...", "args": ["..."], "env": { "SOME_KEY": "" } } } }
+```
+
+- **Env values are never copied** from the candidate — every declared env var is written as an
+  empty string, and skill-forge prints the var names you need to fill in yourself.
+- **Target resolution:** `--mcp-target <file>`, else `config.mcpTargets[0]`, else `<cwd>/.mcp.json`.
+- **Existing target file:** backed up first to `<file>.bak-<timestamp>`.
+- **Existing same-name server entry:** refused unless `--force` is passed.
+- **Missing target file/parent dirs:** created.
+- A candidate config listing more than one server gates/promotes the first (same "N found — using
+  the first" convention `add`/`scan` already use for a multi-skill source), noted on stderr.
+
+There's no MCP equivalent of the skill provenance ledger (`SOURCES.md`) — the pending-ingestion
+queue (Pro) and `--ingest` handoff both apply the same way, keyed on the written config file path
+instead of an installed skill directory. The queued entry carries the candidate's static capability
+profile (`capabilities`, v0.6, above), so a `--ingest` handoff run on an MCP promote has real
+material to work with: `assets/ingest-prompt.md` branches on `artifactType: "mcp"` and walks the
+same five-verb decide (DEFER/ABSORB/FORK/REJECT/WATCH) applied to a server instead of a skill —
+compare declared capabilities against what's already configured, then keep/tighten/remove the
+promoted config entry accordingly. Same static-only rule as the CLI's own profiling: the deep pass
+never runs or installs the candidate server to inspect it.
+
+**TOML-format agents: detect-only.** `skill-forge init` detects MCP config files for every known
+agent, including TOML-format ones (Codex CLI's `config.toml`) — they show up in `init`'s MCP-target
+list and can be selected into `config.mcpTargets` for **overlap ranking**. But **promote only
+writes JSON-shaped targets** (`{ "mcpServers": { ... } }`); pointing `--mcp-target` at (or letting
+`config.mcpTargets[0]` resolve to) a TOML file fails when the promote step tries to parse it as
+JSON. Detection/overlap is agent-format-agnostic; writing is JSON-only.
+
 ## Free vs. Pro
 
 | Capability | Free | Pro |
@@ -196,7 +283,10 @@ that deeper judgment (which patterns to keep, whether to absorb into an existing
 new one, verifying the result beats baseline) is a job for a coding agent, not the gate. `--ingest`
 hands a promoted skill off to one, running the bundled, agent-neutral prompt at
 `assets/ingest-prompt.md` (Claude Code users get a deeper experience via the companion
-`rhize-skill-forge` plugin skill, but the bundled prompt works with any agent).
+`rhize-skill-forge` plugin skill, but the bundled prompt works with any agent). The same flag works
+on an MCP server promote (`--artifact mcp --ingest`, v0.6): the bundled prompt branches on the
+queue entry's `artifactType` and runs the matching decide pass — see
+[MCP gating](#mcp-gating-v05) above.
 
 ```bash
 skill-forge add owner/name --yes --ingest