@softspark/ai-toolkit 4.2.5 → 4.3.1

package/CHANGELOG.md

@@ -7,6 +7,62 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.3.1 - per-session search-first flag (2026-05-19)
+
+Patch release. Fixes a cross-session race condition in the search-first enforcement trio (`user-prompt-submit.sh` + `search-tracker.sh` + `stop-search-check.sh`): the single global flag file `~/.softspark/ai-toolkit/state/search-required.flag` was shared by every parallel Claude Code window, so a Stop in session B could consume session A's flag (or vice versa), blocking unrelated turns with someone else's prompt. Also unblocks `bats 1.13` regression in the test-cohesion runner default.
+
+### Fixed
+
+- **Search-first flag is now per-session** - `user-prompt-submit.sh`, `search-tracker.sh`, and `stop-search-check.sh` key the flag by `session_id` from the hook stdin payload (`search-required-<session_id>.flag`), falling back to `transcript_path` basename, then `default`. Parallel sessions no longer interfere with each other. Each Stop check reads only its own session's flag.
+- **`bats 1.13` regression in test-cohesion runner** - `scripts/test_cohesion.py` no longer passes `--no-parallelize-within-files` (now requires `--jobs 2` in bats 1.13). Default sequential mode is used, which is what the hook expected anyway.
+
+### Added
+
+- **`hook_session_id()` helper in `_hook-io.sh`** - Resolves and sanitizes the per-session key for any hook that needs to scope state to a single Claude Code window.
+- **`session-start.sh` GC** - Stale per-session search-required flags older than 60 minutes are deleted on every `SessionStart`, so crashed sessions do not leave residue.
+- **Two new bats tests** in `tests/test_search_first_flow.bats` verifying per-session isolation and that `search-tracker` only clears its own session's flag.
+
+### Changed
+
+- **`kb/reference/hooks-catalog.md`** - Documents the new per-session flag layout, GC behavior, and isolation guarantee.
+- **`README.md`** - Test count badge 1131 → 1133.
+
+---
+
+## v4.3.0 - inject-mcp extension API (2026-05-12)
+
+Minor release. Closes the asymmetry between `inject-rule` / `inject-hook` and MCP servers by adding `inject-mcp` and `remove-mcp` as first-class members of the extension API. External tools (rag-mcp, jira-mcp, custom integrations) can now register their MCP templates the same way they register rules and hooks -- from a local file or HTTPS URL, with full editor propagation and auto-refresh on `ai-toolkit update`.
+
+### Added
+
+- **`ai-toolkit inject-mcp <file|url> [--name <name>] [--force]`** - Inject an external MCP server template into `~/.mcp.json` (toolkit source-of-truth) and propagate it to every editor with a `global_path` (Claude, Cursor, Codex, Gemini, Windsurf, Cline, Augment, Copilot). Servers in `~/.mcp.json` are tagged with `_source` for idempotent re-injection; native editor configs receive the same servers without `_source`.
+- **`ai-toolkit remove-mcp <name>`** - Strip all servers tagged with the given source from `~/.mcp.json` and every editor config, unregister URL sources, and remove cached template files.
+- **`--name <name>` flag** - Override the auto-derived source name for both local files and URLs. Required when filename stem is generic (e.g., `mcp-template.json` → `--name rag-mcp`).
+- **`--force` flag** - Overwrite servers tagged with a different `_source`. Without `--force`, collisions exit with code 3. Entries tagged `"_source": "ai-toolkit"` are protected even with `--force`.
+- **URL fetch + cache + auto-refresh** - HTTPS templates are cached in `~/.softspark/ai-toolkit/mcp-templates/external/<name>.json` and registered in `sources.json` with sha256 pin. On every `ai-toolkit update`, URL-sourced templates are re-fetched and re-injected; cached version is used on fetch failure.
+- **`scripts/mcp_sources.py`** - Source registry for external MCP templates, mirroring `hook_sources.py`.
+- **`scripts/inject_mcp_cli.py`** - CLI entry point implementing both inject and remove modes.
+- **`refresh_url_mcp()` in `install_steps/markers.py`** - Update flow integration, called from `install.py` alongside `refresh_url_hooks()`.
+
+### Changed
+
+- **`paths.py`** - Added `MCP_TEMPLATES_DIR` and `EXTERNAL_MCP_DIR` constants.
+- **`bin/ai-toolkit.js`** - Registered `inject-mcp` / `remove-mcp` handlers and help text.
+- **`kb/reference/extension-api.md`** - Documented inject-mcp / remove-mcp + flags. Version bumped to 1.5.0.
+- **`kb/reference/mcp-templates.md`** - Added External Templates section pointing to inject-mcp. Version bumped to 1.2.0.
+
+### Tests
+
+- **`tests/test_inject_mcp.bats`** - 15 bats cases covering local-file inject, URL fetch via fixture, `--name` override, `--force` collision override, ai-toolkit source protection, idempotent re-inject, editor propagation to Cursor (JSON) and Codex (TOML), `_source` strip from native configs, sources.json registry, `--remove` cleanup, HTTPS-only enforcement.
+
+### Verification
+
+- 15/15 bats cases passing in `test_inject_mcp.bats`.
+- E2E smoke test: injecting an external `mcp-template.json` writes 9 files (`~/.mcp.json` + 8 editor configs) with `_source` only in source-of-truth and stripped from native configs.
+- No regressions in `test_inject_hook.bats` or `test_mcp_manager.bats`.
+
+---
+
 ## v4.2.5 - Hook safety and no-RAG compatibility (2026-05-12)
 
 Patch release. Hardens Claude Code hook enforcement while keeping the toolkit safe for users who do not have RAG/MCP search providers installed.

package/README.md

@@ -6,16 +6,16 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-107-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-1116%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-1133%20passing-success)](tests/)
 
-## What's New in v4.2.5
+## What's New in v4.3.1
 
-Patch release hardening Claude Code hooks while keeping installs safe for users without RAG/MCP.
+Patch release. Fixes a cross-session race in the search-first enforcement trio: the single global `search-required.flag` was shared by every parallel Claude Code window, so a Stop in one session could block another with someone else's prompt. Also unblocks the `bats 1.13` regression in the test-cohesion runner.
 
-- **Capability-aware search hooks**: search-first enforcement now degrades to guidance when no RAG/MCP provider is installed.
-- **Revert safety**: destructive `git checkout`/`git restore` flows are blocked when they would discard unrelated user work.
-- **Test cohesion**: source edits can trigger only their mapped Bats tests, with project-level override support.
-- **Cross-editor hook payloads**: shared hook I/O helpers normalize Claude, Gemini, Augment, Codex, Cursor, and Windsurf payloads.
+- **Per-session search-first flag**: `user-prompt-submit.sh`, `search-tracker.sh`, and `stop-search-check.sh` now key the flag by `session_id` (`search-required-<session_id>.flag`), so parallel Claude Code windows no longer interfere with each other.
+- **Stale-flag GC**: `session-start.sh` deletes per-session flags older than 60 minutes, so crashed sessions leave no residue.
+- **`bats 1.13` compatibility**: `scripts/test_cohesion.py` no longer passes `--no-parallelize-within-files` (it now requires `--jobs 2` in bats 1.13 and was redundant in sequential mode anyway).
+- **Two new isolation tests**: `tests/test_search_first_flow.bats` verifies per-session flag scoping for both Stop and PostToolUse paths.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -148,7 +148,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (1116 tests)
+├── tests/               # Bats test suite (1133 tests)
 └── CHANGELOG.md
 ```
 

package/app/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
   "description": "Professional-grade Claude Code toolkit with persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "4.2.5",
+  "version": "4.3.1",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/hooks/_hook-io.sh

@@ -19,6 +19,20 @@ hook_prompt() {
     hook_json '.prompt // .tool_info.user_prompt // .user_prompt // .input // empty'
 }
 
+hook_session_id() {
+    local sid
+    sid=$(hook_json '.session_id // empty')
+    if [ -z "$sid" ] || [ "$sid" = "null" ]; then
+        local tp
+        tp=$(hook_json '.transcript_path // empty')
+        if [ -n "$tp" ] && [ "$tp" != "null" ]; then
+            sid=$(basename "$tp" .jsonl)
+        fi
+    fi
+    [ -z "$sid" ] && sid="default"
+    printf '%s' "$sid" | LC_ALL=C tr -c 'a-zA-Z0-9_-' '_'
+}
+
 hook_command() {
     hook_json '.tool_input.command // .tool_input.command_line // .tool_info.command // .tool_info.command_line // .command // empty'
 }

package/app/hooks/commit-quality.sh

@@ -4,6 +4,7 @@
 # Fires on: PreToolUse (Bash)
 # Non-blocking: always exits 0 (warnings only).
 
+# shellcheck disable=SC2034  # INPUT is consumed via sourced _hook-io.sh
 INPUT=$(cat)
 # shellcheck source=_hook-io.sh
 source "$(dirname "$0")/_hook-io.sh"

package/app/hooks/governance-capture.sh

@@ -13,6 +13,7 @@ LOG_FILE="$LOG_DIR/governance.log"
 TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 SESSION="${CLAUDE_SESSION_ID:-unknown}"
 
+# shellcheck disable=SC2034  # INPUT is consumed via sourced _hook-io.sh
 INPUT=$(cat)
 # shellcheck source=_hook-io.sh
 source "$(dirname "$0")/_hook-io.sh"

package/app/hooks/guard-config.sh

@@ -4,6 +4,7 @@
 # Fires on: PreToolUse (Edit|Write|MultiEdit)
 # Exit 2 = block the tool call. Stderr message goes to Claude as feedback.
 
+# shellcheck disable=SC2034  # INPUT is consumed via sourced _hook-io.sh
 INPUT=$(cat)
 # shellcheck source=_hook-io.sh
 source "$(dirname "$0")/_hook-io.sh"

package/app/hooks/guard-destructive.sh

@@ -4,6 +4,7 @@
 # Fires on: PreToolUse (Bash)
 # Exit 2 = block the command. Stderr message goes to Claude as feedback.
 
+# shellcheck disable=SC2034  # INPUT is consumed via sourced _hook-io.sh
 INPUT=$(cat)
 # shellcheck source=_hook-io.sh
 source "$(dirname "$0")/_hook-io.sh"

package/app/hooks/revert-guard.sh

@@ -22,6 +22,7 @@ source "$(dirname "$0")/_locate-toolkit.sh"
 # shellcheck source=_hook-io.sh
 source "$(dirname "$0")/_hook-io.sh"
 
+# shellcheck disable=SC2034  # INPUT is consumed via sourced _hook-io.sh
 INPUT=$(cat)
 COMMAND=$(hook_command)
 

package/app/hooks/search-tracker.sh

@@ -12,7 +12,11 @@
 
 # shellcheck source=_profile-check.sh
 source "$(dirname "$0")/_profile-check.sh"
+# shellcheck source=_hook-io.sh
+source "$(dirname "$0")/_hook-io.sh"
 
-FLAG="$HOME/.softspark/ai-toolkit/state/search-required.flag"
+# shellcheck disable=SC2034  # INPUT is consumed via sourced _hook-io.sh
+INPUT=$(cat 2>/dev/null || true)
+FLAG="$HOME/.softspark/ai-toolkit/state/search-required-$(hook_session_id).flag"
 rm -f "$FLAG" 2>/dev/null
 exit 0

package/app/hooks/session-start.sh

@@ -22,6 +22,10 @@ if [ -n "$TOOLKIT_DIR" ] && command -v python3 >/dev/null 2>&1; then
         ${SESSION_ID_INPUT:+--session-id "$SESSION_ID_INPUT"} >/dev/null 2>&1 || true
 fi
 
+# 1b. GC stale per-session search-required flags (older than 60 min)
+find "$HOME/.softspark/ai-toolkit/state" -maxdepth 1 -name 'search-required-*.flag' \
+    -type f -mmin +60 -delete 2>/dev/null || true
+
 # 2. Check for updates (cached, max once per 24h, non-blocking)
 VERSION_MSG=$(python3 "$TOOLKIT_DIR/scripts/version_check.py" 2>/dev/null)
 if [ -n "$VERSION_MSG" ]; then

package/app/hooks/stop-search-check.sh

@@ -21,7 +21,9 @@ source "$(dirname "$0")/_search-capability.sh"
 
 [ "${CLAUDE_SKIP_SEARCH_FIRST:-0}" = "1" ] && exit 0
 
-FLAG="$HOME/.softspark/ai-toolkit/state/search-required.flag"
+# shellcheck disable=SC2034  # INPUT is consumed via sourced _hook-io.sh
+INPUT=$(cat 2>/dev/null || true)
+FLAG="$HOME/.softspark/ai-toolkit/state/search-required-$(hook_session_id).flag"
 [ -f "$FLAG" ] || exit 0
 
 if ! ai_toolkit_has_search_provider; then

package/app/hooks/test-cohesion.sh

@@ -32,6 +32,7 @@ source "$(dirname "$0")/_hook-io.sh"
 [ "${CLAUDE_HOOK_BOOTSTRAP:-0}" = "1" ] && exit 0
 [ "${CLAUDE_SKIP_COHESION:-0}" = "1" ] && exit 0
 
+# shellcheck disable=SC2034  # INPUT is consumed via sourced _hook-io.sh
 INPUT=$(cat)
 FILE_PATH=$(hook_file_path)
 

package/app/hooks/track-usage.sh

@@ -10,6 +10,7 @@
 STATS_FILE="${HOME}/.softspark/ai-toolkit/stats.json"
 
 # Read prompt from stdin (Claude Code passes JSON with .prompt field)
+# shellcheck disable=SC2034  # INPUT is consumed via sourced _hook-io.sh
 INPUT=$(cat)
 # shellcheck source=_hook-io.sh
 source "$(dirname "$0")/_hook-io.sh"

package/app/hooks/user-prompt-submit.sh

@@ -13,6 +13,7 @@ source "$(dirname "$0")/_hook-io.sh"
 source "$(dirname "$0")/_search-capability.sh"
 
 # Read prompt from stdin (Claude Code passes JSON with .prompt field)
+# shellcheck disable=SC2034  # INPUT is consumed via sourced _hook-io.sh
 INPUT=$(cat)
 PROMPT_TEXT=$(hook_prompt)
 LOWERED="$(printf '%s' "$PROMPT_TEXT" | tr '[:upper:]' '[:lower:]')"
@@ -22,7 +23,7 @@ LOWERED="$(printf '%s' "$PROMPT_TEXT" | tr '[:upper:]' '[:lower:]')"
 # Cleared by search-tracker.sh after smart_query / hybrid_search_kb / web runs.
 PROMPT_LEN=${#PROMPT_TEXT}
 STATE_DIR="$HOME/.softspark/ai-toolkit/state"
-FLAG="$STATE_DIR/search-required.flag"
+FLAG="$STATE_DIR/search-required-$(hook_session_id).flag"
 mkdir -p "$STATE_DIR" 2>/dev/null
 if [ "$PROMPT_LEN" -gt 30 ] && \
    [ "${CLAUDE_SKIP_SEARCH_FIRST:-0}" != "1" ] && \

package/bin/ai-toolkit.js

@@ -69,6 +69,8 @@ const COMMANDS = {
   'remove-rule': 'Unregister a rule from ~/.softspark/ai-toolkit/rules/ and remove its block from CLAUDE.md',
   'inject-hook': 'Inject external hooks (file or URL) into ~/.claude/settings.json (URL hooks auto-refresh on update)',
   'remove-hook': 'Remove injected hooks by source name from ~/.claude/settings.json (also unregisters URL source)',
+  'inject-mcp': 'Inject external MCP template (file or URL) into ~/.mcp.json + all editor MCP configs (URL templates auto-refresh on update)',
+  'remove-mcp': 'Remove injected MCP servers by source name from ~/.mcp.json and all editor configs',
   validate: 'Verify toolkit integrity',
   doctor: 'Check install health, hooks, and artifact drift',
   eject: 'Export standalone config (no symlinks, no toolkit dependency)',
@@ -257,6 +259,14 @@ function showHelp() {
   console.log('\nOptions for remove-hook:');
   console.log('  <source-name>   Source tag to remove (also unregisters URL source if present)');
   console.log('  [target-dir]    Target dir containing .claude/settings.json (default: $HOME)');
+  console.log('\nOptions for inject-mcp:');
+  console.log('  <template-file-or-url>  Path to JSON file or HTTPS URL with {"mcpServers": {...}}');
+  console.log('  [target-dir]            Target dir for .mcp.json + editor configs (default: $HOME)');
+  console.log('  --name <name>           Override source name (default: filename/URL stem)');
+  console.log('  --force                 Overwrite servers tagged with a different _source');
+  console.log('\nOptions for remove-mcp:');
+  console.log('  <source-name>   Source tag to remove (also unregisters URL source and cleans editor configs)');
+  console.log('  [target-dir]    Target dir containing .mcp.json (default: $HOME)');
   console.log('\nOptions for add-rule:');
   console.log('  <rule-file>     Path to .md rule file or HTTPS URL to register globally');
   console.log('  [rule-name]     Override rule name (default: filename/URL stem without .md)');
@@ -417,6 +427,37 @@ function handleRemoveHook(args) {
   run(scriptPath('inject_hook_cli.py'), ['--remove', sourceName, targetDir]);
 }
 
+/**
+ * Handle `ai-toolkit inject-mcp` -- injects external MCP template (file or URL) into .mcp.json
+ * and propagates to all editor MCP configs.
+ * @param {string[]} args
+ */
+function handleInjectMcp(args) {
+  const source = args[0];
+  if (!source) {
+    console.error('Usage: ai-toolkit inject-mcp <template-file-or-url> [target-dir] [--name <name>] [--force]');
+    process.exit(1);
+  }
+  const isUrl = source.startsWith('https://') || source.startsWith('http://');
+  const resolvedSource = isUrl ? source : path.resolve(CWD, source);
+  const remaining = args.slice(1);
+  run(scriptPath('inject_mcp_cli.py'), [resolvedSource, ...remaining]);
+}
+
+/**
+ * Handle `ai-toolkit remove-mcp` -- removes injected MCP servers by source name.
+ * @param {string[]} args
+ */
+function handleRemoveMcp(args) {
+  const sourceName = args[0];
+  if (!sourceName) {
+    console.error('Usage: ai-toolkit remove-mcp <template-source-name> [target-dir]');
+    process.exit(1);
+  }
+  const targetDir = args[1] || process.env.HOME;
+  run(scriptPath('inject_mcp_cli.py'), ['--remove', sourceName, targetDir]);
+}
+
 /**
  * Handle `ai-toolkit mcp` -- delegates to mcp_manager.py with subcommand.
  * @param {string[]} args
@@ -566,6 +607,8 @@ const SPECIAL_HANDLERS = {
   'add-rule':     handleAddRule,
   'inject-hook':  handleInjectHook,
   'remove-hook':  handleRemoveHook,
+  'inject-mcp':   handleInjectMcp,
+  'remove-mcp':   handleRemoveMcp,
   'llms-txt':     (_args) => generateLlmsTxt(),
   'antigravity-rules': (_args) => run(scriptPath('generate_antigravity.py'), [CWD]),
   'cursor-mdc':   (_args) => run(scriptPath('generate_cursor_mdc.py'), [CWD]),

package/kb/reference/extension-api.md

@@ -2,11 +2,11 @@
 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
@@ -25,8 +25,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
@@ -115,6 +117,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`.
@@ -153,6 +216,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    │
@@ -168,7 +233,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:
 
@@ -176,14 +241,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:
@@ -191,6 +256,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.

package/kb/reference/hooks-catalog.md

@@ -381,7 +381,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`.
 
@@ -394,7 +394,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`.
 
@@ -456,7 +456,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)

package/kb/reference/mcp-templates.md

@@ -2,11 +2,11 @@
 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
@@ -15,6 +15,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