@softspark/ai-toolkit 4.2.5 → 4.3.1

package/llms-full.txt

@@ -8186,11 +8186,11 @@ Run `ai-toolkit update --local` to re-resolve and update the lock file.
 title: "Extension API Reference"
 category: reference
 service: ai-toolkit
-tags: [extension-api, inject-rule, inject-hook, mcp-templates, integration, editors]
-version: "1.4.0"
+tags: [extension-api, inject-rule, inject-hook, inject-mcp, mcp-templates, integration, editors]
+version: "1.5.0"
 created: "2026-04-07"
-last_updated: "2026-04-15"
-description: "Reference for ai-toolkit's extension API: inject-rule, inject-hook, remove-rule, remove-hook, and editor-aware MCP template management."
+last_updated: "2026-05-12"
+description: "Reference for ai-toolkit's extension API: inject-rule, inject-hook, inject-mcp, remove-* variants, and editor-aware MCP template management."
 ---
 
 # Extension API Reference
@@ -8209,8 +8209,10 @@ This design is intentional: ai-toolkit is a generic toolkit. Consumers (MCP serv
 | `remove-rule <name>` | `~/.claude/CLAUDE.md` | Strip markers by block name | Yes |
 | `inject-hook <file.json\|url> [name]` | `~/.claude/settings.json` | JSON `_source` tag per entry, URL cached + registered | Yes |
 | `remove-hook <name>` | `~/.claude/settings.json` | Strip all entries with matching `_source`, unregister URL source | Yes |
+| `inject-mcp <file.json\|url> [name] [--force]` | `~/.mcp.json` + every editor with `global_path` | JSON `_source` tag per server, URL cached + registered, full editor propagation | Yes |
+| `remove-mcp <name>` | `~/.mcp.json` + every editor with `global_path` | Strip all servers with matching `_source`, clean editor configs, unregister URL | Yes |
 | `add-rule <file.md\|url>` | `~/.softspark/ai-toolkit/rules/` | File copy + re-inject all rules on next `update` | Yes |
-| `mcp add <name...>` | `.mcp.json` | Merge `mcpServers` block from template | Yes |
+| `mcp add <name...>` | `.mcp.json` | Merge `mcpServers` block from built-in template | Yes |
 | `mcp install --editor <name...>` | Native editor MCP config | Render canonical template into editor format | Yes |
 
 ## inject-rule
@@ -8299,6 +8301,67 @@ npx @softspark/ai-toolkit remove-hook my-tool-hooks
 
 The argument is the source name (file stem used during `inject-hook`). If no entries with that source are present, the command exits 0 silently.
 
+## inject-mcp
+
+Injects an external MCP server template into `~/.mcp.json` (toolkit source-of-truth) and propagates it to every editor that exposes a `global_path` in `EDITOR_SPECS`. Symmetric with `inject-hook` -- accepts both local file paths and HTTPS URLs, with cache + auto-refresh on `ai-toolkit update`.
+
+```bash
+# From local file
+npx @softspark/ai-toolkit inject-mcp ./rag-mcp-template.json
+
+# From URL (cached locally, auto-refreshed on update)
+npx @softspark/ai-toolkit inject-mcp https://example.com/rag-mcp-template.json
+
+# With explicit source name (preferred when filename stem is generic)
+npx @softspark/ai-toolkit inject-mcp ./mcp/mcp-template.json --name rag-mcp
+
+# With explicit target dir
+npx @softspark/ai-toolkit inject-mcp ./template.json /custom/target --name my-rag
+
+# Force overwrite of servers with a different _source (collision resolution)
+npx @softspark/ai-toolkit inject-mcp ./conflict.json --force
+```
+
+**Flags:** `--name <name>` overrides the auto-derived source name (works for both local files and URLs). `--force` overwrites servers tagged with a different `_source`. Positional `template-name` is supported only for URL sources (legacy positional grammar inherited from `inject-hook`); for local files use `--name`.
+
+**Implementation:** `scripts/inject_mcp_cli.py`, `scripts/mcp_sources.py`, `scripts/url_fetch.py`.
+
+**Input format:** Same as built-in templates in `app/mcp-templates/`:
+```json
+{
+  "name": "rag-mcp",
+  "description": "Multi-tenant RAG over knowledge bases",
+  "mcpServers": {
+    "rag-mcp": {
+      "type": "http",
+      "url": "http://localhost:8081/mcp/sse?secret_key=${RAG_MCP_SECRET_KEY}"
+    }
+  }
+}
+```
+
+**Source name derivation:** `rag-mcp-template.json` → `"rag-mcp-template"`. For URLs: `https://example.com/rag-mcp-template.json` → `"rag-mcp-template"`. Every server in the `mcpServers` block is tagged with `"_source": "<source-name>"` inside `~/.mcp.json` only; native editor configs receive the same servers **without** the `_source` field (some clients reject unknown keys).
+
+**URL support:** When an HTTPS URL is provided, the JSON is fetched, validated, cached in `~/.softspark/ai-toolkit/mcp-templates/external/<name>.json`, and registered in `sources.json`. On every `ai-toolkit update`, URL-sourced templates are re-fetched and re-injected automatically. If the fetch fails during update, the cached version is used.
+
+**Editor propagation:** Every editor with a `global_path` in `EDITOR_SPECS` is updated -- Claude (`~/.claude.json`), Cursor (`~/.cursor/mcp.json`), GitHub Copilot (`~/.copilot/mcp-config.json`), Gemini CLI (`~/.gemini/settings.json`), Windsurf (`~/.codeium/windsurf/mcp_config.json`), Cline (`~/.cline/data/settings/cline_mcp_settings.json`), Augment (`~/.augment/settings.json`), Codex CLI (`~/.codex/config.toml`). Per-editor failures are non-fatal -- the command reports a warning and continues.
+
+**Idempotency:** Re-running with the same source overwrites entries for that source cleanly -- no duplicates accumulate.
+
+**Collisions:** If a server name in `~/.mcp.json` already exists under a *different* `_source` tag, the command exits with code 3 unless `--force` is passed. Entries tagged `"_source": "ai-toolkit"` are protected even with `--force` -- the built-in template namespace cannot be hijacked.
+
+**Safety:** Only HTTPS URLs are accepted. The source name `ai-toolkit` is reserved.
+
+## remove-mcp
+
+Strips all server entries from `~/.mcp.json` that carry a given `_source` tag, cleans the same server names from every editor `global_path`, and (if URL-sourced) unregisters from `sources.json` and removes the cached file.
+
+```bash
+npx @softspark/ai-toolkit remove-mcp rag-mcp-template
+```
+
+The argument is the source name (file stem used during `inject-mcp`). If no entries with that source are present, the command exits 0 silently. `ai-toolkit` source is reserved and cannot be removed via this command.
+
 ## mcp add / install
 
 Merges one or more MCP server templates from `app/mcp-templates/` into the project's `.mcp.json`.
@@ -8337,6 +8400,8 @@ When `install` runs with `--scope project`, ai-toolkit also updates `.mcp.json`
 │    remove-rule  <name>        → CLAUDE.md            │
 │    inject-hook  <file|url>    → settings.json        │
 │    remove-hook  <name>        → settings.json        │
+│    inject-mcp   <file|url>    → .mcp.json + editors  │
+│    remove-mcp   <name>        → .mcp.json + editors  │
 │    add-rule     <file|url>    → rules/ registry      │
 │    mcp add      <template>    → .mcp.json            │
 │    mcp install  <template>    → editor-native MCP    │
@@ -8352,7 +8417,7 @@ When `install` runs with `--scope project`, ai-toolkit also updates `.mcp.json`
    (consumer)       (consumer)      (consumer)
 ```
 
-## Example: Registering Rules and Hooks from an External Tool
+## Example: Registering Rules, Hooks, and MCP Servers from an External Tool
 
 An external tool's install script would call:
 
@@ -8360,14 +8425,14 @@ An external tool's install script would call:
 # Register rules into CLAUDE.md
 npx @softspark/ai-toolkit inject-rule ./rules/my-tool-rules.md
 
-# Register hooks into settings.json
+# Register hooks into settings.json (auto-propagates to Codex)
 npx @softspark/ai-toolkit inject-hook ./hooks/my-tool-hooks.json
 
-# Add an MCP server template
-npx @softspark/ai-toolkit mcp add github
+# Register MCP server template into .mcp.json + all editor MCP configs
+npx @softspark/ai-toolkit inject-mcp ./mcp-template.json
 
-# Render the same template into Cursor project config
-npx @softspark/ai-toolkit mcp install --editor cursor --scope project github --target .
+# Alternative: pull MCP template from a URL (auto-refreshed on update)
+npx @softspark/ai-toolkit inject-mcp https://example.com/mcp-template.json
 ```
 
 To uninstall:
@@ -8375,6 +8440,7 @@ To uninstall:
 ```bash
 npx @softspark/ai-toolkit remove-rule my-tool-rules
 npx @softspark/ai-toolkit remove-hook my-tool-hooks
+npx @softspark/ai-toolkit remove-mcp my-tool
 ```
 
 All operations are idempotent — safe to run on every install or update.
@@ -9136,7 +9202,7 @@ First-match-wins per file. Built-in runners: `bats`, `pytest`, `vitest`, `jest`.
 | Script | `~/.softspark/ai-toolkit/hooks/search-tracker.sh` |
 | Fires | After any search-style tool call |
 
-**Action:** Clears `~/.softspark/ai-toolkit/state/search-required.flag`. Pairs with `user-prompt-submit.sh` (sets flag on long technical prompts only when a search provider is detected or strict mode is enabled) and `stop-search-check.sh` (blocks Stop if flag still set). Together they enforce the global CLAUDE.md GOLDEN RULE without breaking offline/no-RAG installs.
+**Action:** Clears `~/.softspark/ai-toolkit/state/search-required-<session_id>.flag` (per-session, keyed by `session_id` from the hook stdin payload, falling back to `transcript_path` basename, then `default`). Pairs with `user-prompt-submit.sh` (sets the flag on long technical prompts only when a search provider is detected or strict mode is enabled) and `stop-search-check.sh` (blocks Stop if the calling session's flag is still set). Together they enforce the global CLAUDE.md GOLDEN RULE without breaking offline/no-RAG installs and without cross-session interference when multiple Claude Code windows run in parallel.
 
 Non-blocking (exit 0). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
@@ -9149,7 +9215,7 @@ Non-blocking (exit 0). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | Script | `~/.softspark/ai-toolkit/hooks/stop-search-check.sh` |
 | Fires | When Claude finishes a response |
 
-**Action:** If `search-required.flag` is still present (no search tool ran during this turn) and a search provider is still detectable, emits `{"decision":"block","reason":"..."}` to continue the conversation with a search-first reminder. If no RAG/Web provider is detected, it clears the stale flag and exits 0, so offline/no-MCP users are not blocked.
+**Action:** If `search-required-<session_id>.flag` for the calling session is still present (no search tool ran during this turn) and a search provider is still detectable, emits `{"decision":"block","reason":"..."}` to continue the conversation with a search-first reminder. If no RAG/Web provider is detected, it clears the stale flag and exits 0, so offline/no-MCP users are not blocked. Flags are scoped by `session_id` from the hook stdin payload so a Stop in session B never consumes session A's flag (and vice versa). Stale per-session flags older than 60 minutes are GC'd on the next `SessionStart`.
 
 **Overrides:** `CLAUDE_SKIP_SEARCH_FIRST=1`, `AI_TOOLKIT_SEARCH_FIRST=off`, or `AI_TOOLKIT_SEARCH_FIRST=strict` to force enforcement. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
@@ -9211,7 +9277,7 @@ Set in `.claude/settings.local.json`:
 ├── rules/          # Registered rules (add-rule.sh)
 ├── state/          # Per-session runtime state (NEW)
 │   ├── session-edits.json         # Append-only edit log per session
-│   ├── search-required.flag       # Set by user-prompt-submit, cleared by search-tracker
+│   ├── search-required-<sid>.flag # Per-session: set by user-prompt-submit, cleared by search-tracker/stop-search-check, GC'd at SessionStart (>60min)
 │   ├── loaded-instructions.log    # Audit trail of which rules entered context
 │   └── test-cohesion-last.log     # Last cohesion test command output
 └── hooks/          # Hook scripts (copied on install)
@@ -9911,11 +9977,11 @@ Global-only clients are configured explicitly via `ai-toolkit mcp install --edit
 title: "MCP Server Templates"
 category: reference
 service: ai-toolkit
-tags: [mcp, templates, servers, configuration, editors]
-version: "1.1.0"
+tags: [mcp, templates, servers, configuration, editors, inject-mcp, external-templates]
+version: "1.2.0"
 created: "2026-04-07"
-last_updated: "2026-04-12"
-description: "Reference for 26 MCP server templates plus native editor MCP installation support."
+last_updated: "2026-05-12"
+description: "Reference for 26 built-in MCP server templates, external template injection via inject-mcp, and native editor MCP installation support."
 ---
 
 # MCP Server Templates
@@ -9924,6 +9990,8 @@ description: "Reference for 26 MCP server templates plus native editor MCP insta
 
 ai-toolkit ships 26 ready-to-use MCP server configuration templates in `app/mcp-templates/`. Each template is a JSON file that defines the canonical `mcpServers` block for a specific service. Templates can be merged into the project's `.mcp.json` and rendered into editor-native MCP config files via the `ai-toolkit mcp` CLI subcommand.
 
+**External templates:** Tools outside the toolkit (MCP servers, plugins, custom integrations) can register their own MCP templates via `ai-toolkit inject-mcp <file|url>` -- the toolkit caches the template, tags every server with a `_source` field, and propagates the config to every editor that exposes a `global_path`. URL-sourced templates are auto-refreshed on every `ai-toolkit update`. See [PATH: kb/reference/extension-api.md] for the inject-mcp / remove-mcp reference.
+
 ## CLI
 
 ```bash

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.2.5",
+  "version": "4.3.1",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "4.2.5",
+  "version": "4.3.1",
   "description": "AI coding toolkit: 107 skills, 44 agents, 12-editor write-through (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity, Codex, opencode), machine-enforced safety constitution, SARIF audit, signed npm provenance.",
   "keywords": [
     "claude",