@rhize/skill-forge 0.4.0 → 0.5.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,69 @@ 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.
+
+**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.
+
+**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 |