@softspark/ai-toolkit 4.2.5 → 4.3.0

package/CHANGELOG.md

@@ -7,6 +7,40 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## 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-1131%20passing-success)](tests/)
 
-## What's New in v4.2.5
+## What's New in v4.3.0
 
-Patch release hardening Claude Code hooks while keeping installs safe for users without RAG/MCP.
+Minor release. Closes the asymmetry between `inject-rule` / `inject-hook` and MCP servers -- external tools (rag-mcp, jira-mcp, custom integrations) can now register MCP templates the same way they register rules and hooks.
 
-- **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.
+- **`ai-toolkit inject-mcp <file|url>`**: register an external MCP template into `~/.mcp.json` + every editor with a `global_path` (Claude, Cursor, Codex, Gemini, Windsurf, Cline, Augment, Copilot) in one command.
+- **`ai-toolkit remove-mcp <name>`**: strip injected servers from `~/.mcp.json` and every editor config in one command.
+- **URL templates + auto-refresh**: HTTPS-sourced templates are cached and re-fetched on every `ai-toolkit update`, just like URL rules and hooks.
+- **`--name` and `--force` flags**: explicit source naming for both files and URLs, plus collision-safe overwrites that still protect `ai-toolkit` built-in entries.
 
 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 (1131 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.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

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/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

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.2.5",
+  "version": "4.3.0",
   "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.0",
   "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",

package/scripts/inject_mcp_cli.py

@@ -0,0 +1,514 @@
+#!/usr/bin/env python3
+"""Inject external MCP server templates into .mcp.json and all editor configs.
+
+Allows external tools (MCP servers, plugins) to register their own MCP server
+templates alongside ai-toolkit's built-in templates. Each injected template is
+tagged with ``_source`` derived from the filename stem (or URL last segment)
+so that re-running is idempotent and removal is safe.
+
+Usage:
+    inject_mcp_cli.py <template-file-or-url> [target-dir] [--name <name>] [--force]
+    inject_mcp_cli.py <url> [template-name] [target-dir] [--force]   # URL-only legacy form
+    inject_mcp_cli.py --remove <template-source-name> [target-dir]
+
+Arguments:
+    template-file-or-url  Path to a JSON file or HTTPS URL with
+                          ``{"mcpServers": {...}}`` block (toolkit template format).
+    target-dir            Directory containing ``.mcp.json``
+                          (default: $HOME -- writes to ~/.mcp.json and propagates
+                          to ~/.claude.json, ~/.cursor/mcp.json, ~/.codex/config.toml, ...).
+
+Flags:
+    --name <name>  Explicit source name. Default: filename stem or URL last segment.
+                   Works for both local files and URLs. Preferred over positional
+                   template-name (which only works for URL sources for backward
+                   compatibility with the inject-hook positional grammar).
+    --force        Overwrite servers that already exist under a different
+                   ``_source`` tag. Without --force, collisions are rejected.
+    --remove       Remove all server entries tagged with the given source name
+                   (also unregisters URL source and removes cached template file).
+
+The source name is derived from the filename stem (e.g.,
+``rag-mcp-template.json`` becomes ``"rag-mcp-template"``). Every server in the
+template is tagged with ``"_source": "<source-name>"`` inside ``.mcp.json``
+(toolkit source-of-truth). Native editor configs receive the same servers
+without ``_source`` (some editors reject unknown fields).
+
+Servers tagged with ``_source: "ai-toolkit"`` are **never** modified -- those
+are managed exclusively by the toolkit itself.
+
+Propagation: every supported editor with a `global_path` in EDITOR_SPECS is
+updated. Project-scoped editors are skipped (use ``ai-toolkit mcp install`` for
+project scope).
+
+Exit codes:
+    0  success
+    1  usage / argument error
+    2  JSON parse error
+    3  collision rejected (use --force)
+"""
+from __future__ import annotations
+
+import copy
+import json
+import os
+import re
+import sys
+import urllib.parse
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+PROTECTED_SOURCE = "ai-toolkit"
+
+
+def load_json(path: str) -> dict:
+    """Load and parse a JSON file."""
+    with open(path) as f:
+        return json.load(f)
+
+
+def save_json(path: str, data: dict, indent: int = 2) -> None:
+    """Write a dictionary to a JSON file with trailing newline."""
+    Path(path).parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w") as f:
+        json.dump(data, f, indent=indent, ensure_ascii=False)
+        f.write("\n")
+
+
+def _is_url(source: str) -> bool:
+    """Check if source looks like an HTTP(S) URL."""
+    return source.startswith("https://") or source.startswith("http://")
+
+
+def _name_from_url(url: str) -> str:
+    """Derive a template source name from a URL's last path segment."""
+    parsed = urllib.parse.urlparse(url)
+    filename = parsed.path.rstrip("/").split("/")[-1]
+    stem = filename.rsplit(".", 1)[0] if "." in filename else filename
+    return re.sub(r"[^a-zA-Z0-9_-]", "", stem)
+
+
+def _server_source(server: dict) -> str | None:
+    """Return the ``_source`` tag of a server entry, or None if untagged."""
+    if isinstance(server, dict):
+        return server.get("_source")
+    return None
+
+
+def _strip_source_tag(server: dict) -> dict:
+    """Return a copy of *server* with ``_source`` removed (for native editors)."""
+    clean = copy.deepcopy(server)
+    clean.pop("_source", None)
+    return clean
+
+
+def _tag_servers(servers: dict, source: str) -> dict:
+    """Return a copy of *servers* with every entry tagged ``_source: <source>``."""
+    result: dict = {}
+    for name, server in servers.items():
+        if not isinstance(server, dict):
+            result[name] = server
+            continue
+        tagged = copy.deepcopy(server)
+        tagged["_source"] = source
+        result[name] = tagged
+    return result
+
+
+def _strip_servers_by_source(servers: dict, source: str) -> dict:
+    """Return a copy of *servers* with entries matching ``_source`` removed."""
+    return {
+        name: server for name, server in servers.items()
+        if _server_source(server) != source
+    }
+
+
+def _server_names_for_source(servers: dict, source: str) -> list[str]:
+    """Return server names tagged with the given ``_source``."""
+    return [name for name, server in servers.items()
+            if _server_source(server) == source]
+
+
+def _check_collisions(
+    existing: dict, new_servers: dict, source: str, force: bool
+) -> None:
+    """Reject when an existing server has a different ``_source``.
+
+    Same-source overwrite is always allowed (idempotent re-inject).
+    PROTECTED_SOURCE entries are protected even with --force.
+    """
+    collisions = []
+    for name in new_servers:
+        if name not in existing:
+            continue
+        existing_source = _server_source(existing[name])
+        if existing_source == source:
+            continue
+        if existing_source == PROTECTED_SOURCE:
+            print(
+                f"Error: server '{name}' is managed by '{PROTECTED_SOURCE}' "
+                "and cannot be overwritten.",
+                file=sys.stderr,
+            )
+            sys.exit(3)
+        collisions.append((name, existing_source))
+
+    if not collisions:
+        return
+
+    if not force:
+        print(
+            f"Error: server name collision(s) in .mcp.json (re-run with --force):",
+            file=sys.stderr,
+        )
+        for name, other_source in collisions:
+            src_label = other_source or "(untagged)"
+            print(f"  - {name} already exists under _source={src_label}", file=sys.stderr)
+        sys.exit(3)
+
+    for name, other_source in collisions:
+        src_label = other_source or "(untagged)"
+        print(f"  Overwriting '{name}' (was _source={src_label})")
+
+
+def _fetch_and_cache(url: str, source: str) -> str:
+    """Fetch template JSON from URL, cache locally, register source.
+
+    Returns:
+        Path to the cached template JSON file.
+    """
+    from url_fetch import fetch_url
+    from mcp_sources import register_url_source
+    from paths import EXTERNAL_MCP_DIR
+
+    EXTERNAL_MCP_DIR.mkdir(parents=True, exist_ok=True)
+
+    try:
+        data = fetch_url(url)
+    except Exception as exc:
+        print(f"Error fetching URL: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        parsed = json.loads(data)
+    except json.JSONDecodeError as exc:
+        print(f"Error: URL returned invalid JSON: {exc}", file=sys.stderr)
+        sys.exit(2)
+
+    if "mcpServers" not in parsed:
+        print("Warning: no 'mcpServers' key found in URL response", file=sys.stderr)
+
+    cached_path = EXTERNAL_MCP_DIR / f"{source}.json"
+    cached_path.write_bytes(data)
+    register_url_source(None, source, url, content=data)
+
+    return str(cached_path)
+
+
+def _propagate_to_editors(
+    servers_clean: dict, source: str, target_dir: str, force: bool
+) -> None:
+    """Mirror servers to every editor that has a global_path in EDITOR_SPECS.
+
+    Servers are written without the ``_source`` tag (native editor configs do
+    not need it). Per-editor failures are non-fatal -- we report and continue.
+    """
+    from mcp_editors import EDITOR_SPECS, install_servers
+
+    home = Path(target_dir)
+    editors_with_global = [
+        name for name, spec in EDITOR_SPECS.items()
+        if spec.get("global_path")
+    ]
+
+    for editor in sorted(editors_with_global):
+        try:
+            updated = install_servers(
+                [editor], servers_clean, scope="global", home=home,
+            )
+            for path in updated:
+                print(f"  Propagated to {editor}: {path}")
+        except Exception as exc:
+            print(
+                f"  Warning: {editor} propagation failed: {exc}",
+                file=sys.stderr,
+            )
+
+
+def _remove_from_editors(server_names: list[str], target_dir: str) -> None:
+    """Remove servers from every editor with a global_path."""
+    from mcp_editors import EDITOR_SPECS, remove_servers
+
+    home = Path(target_dir)
+    editors_with_global = [
+        name for name, spec in EDITOR_SPECS.items()
+        if spec.get("global_path")
+    ]
+
+    for editor in sorted(editors_with_global):
+        try:
+            updated = remove_servers(
+                [editor], server_names, scope="global", home=home,
+            )
+            for path in updated:
+                print(f"  Cleaned {editor}: {path}")
+        except Exception as exc:
+            print(
+                f"  Warning: {editor} cleanup failed: {exc}",
+                file=sys.stderr,
+            )
+
+
+def inject(
+    template_file: str,
+    target_dir: str,
+    source_override: str = "",
+    force: bool = False,
+) -> None:
+    """Inject an MCP template into .mcp.json + propagate to all editors.
+
+    Args:
+        template_file: Path to the template JSON file, or an HTTPS URL.
+        target_dir: Directory used as $HOME for editor config resolution.
+            ``.mcp.json`` is written to ``<target_dir>/.mcp.json``.
+        source_override: Explicit source name (overrides filename-derived).
+        force: Overwrite servers tagged with a different ``_source``.
+    """
+    is_url = _is_url(template_file)
+
+    if is_url:
+        if template_file.startswith("http://"):
+            print(
+                "Error: only HTTPS URLs are supported. Use https:// for security.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+        source = source_override or _name_from_url(template_file)
+        source = re.sub(r"[^a-zA-Z0-9_-]", "", source)
+        if not source:
+            print(
+                "Error: could not derive template name from URL. "
+                "Provide one explicitly.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+        if source == PROTECTED_SOURCE:
+            print(
+                f"Error: source name '{PROTECTED_SOURCE}' is reserved.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+        template_file = _fetch_and_cache(template_file, source)
+        print(f"Fetched template from URL (source: '{source}')")
+    else:
+        source = source_override or Path(template_file).stem
+        if source == PROTECTED_SOURCE:
+            print(
+                f"Error: source name '{PROTECTED_SOURCE}' is reserved. "
+                "Rename your template file.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+    try:
+        template_data = load_json(template_file)
+    except json.JSONDecodeError as exc:
+        print(f"Error: malformed JSON in {template_file}: {exc}", file=sys.stderr)
+        sys.exit(2)
+    except OSError as exc:
+        print(f"Error reading template file: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    new_servers = template_data.get("mcpServers", {})
+    if not new_servers:
+        print(f"Warning: no 'mcpServers' key found in {template_file}", file=sys.stderr)
+        return
+
+    mcp_path = Path(target_dir) / ".mcp.json"
+    config: dict = {"mcpServers": {}}
+    if mcp_path.is_file():
+        try:
+            config = load_json(str(mcp_path))
+        except json.JSONDecodeError as exc:
+            print(f"Error: malformed JSON in {mcp_path}: {exc}", file=sys.stderr)
+            sys.exit(2)
+
+    if "mcpServers" not in config or not isinstance(config["mcpServers"], dict):
+        config["mcpServers"] = {}
+
+    _check_collisions(config["mcpServers"], new_servers, source, force)
+
+    tagged = _tag_servers(new_servers, source)
+    stripped = _strip_servers_by_source(config["mcpServers"], source)
+    stripped.update(tagged)
+    config["mcpServers"] = stripped
+
+    save_json(str(mcp_path), config)
+    print(f"Injected MCP template '{source}' into {mcp_path}")
+    print(f"  Servers: {', '.join(sorted(new_servers.keys()))}")
+
+    if not is_url:
+        try:
+            from mcp_sources import register_path_source
+            register_path_source(
+                None, source, Path(template_file),
+                content=Path(template_file).read_bytes(),
+            )
+        except Exception as exc:
+            print(f"Warning: could not register local source: {exc}", file=sys.stderr)
+
+    servers_clean = {name: _strip_source_tag(s) for name, s in new_servers.items()}
+    _propagate_to_editors(servers_clean, source, target_dir, force)
+
+
+def remove(source_name: str, target_dir: str) -> None:
+    """Remove all server entries tagged with *source_name*.
+
+    Also unregisters the URL source if it was URL-sourced, removes cached file,
+    and cleans matching server names from every global editor config.
+    """
+    if source_name == PROTECTED_SOURCE:
+        print(
+            f"Error: cannot remove '{PROTECTED_SOURCE}' entries. "
+            "Use 'ai-toolkit uninstall' instead.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    mcp_path = Path(target_dir) / ".mcp.json"
+
+    server_names: list[str] = []
+    if mcp_path.is_file():
+        try:
+            config = load_json(str(mcp_path))
+        except json.JSONDecodeError as exc:
+            print(f"Error: malformed JSON in {mcp_path}: {exc}", file=sys.stderr)
+            sys.exit(2)
+
+        servers = config.get("mcpServers", {})
+        if isinstance(servers, dict):
+            server_names = _server_names_for_source(servers, source_name)
+            config["mcpServers"] = _strip_servers_by_source(servers, source_name)
+            save_json(str(mcp_path), config)
+            if server_names:
+                print(
+                    f"Removed source '{source_name}' from {mcp_path} "
+                    f"(servers: {', '.join(server_names)})"
+                )
+
+    if server_names:
+        _remove_from_editors(server_names, target_dir)
+
+    try:
+        from mcp_sources import unregister_source
+        from paths import EXTERNAL_MCP_DIR
+
+        if unregister_source(None, source_name):
+            print(f"Unregistered MCP source '{source_name}'")
+
+        cached = EXTERNAL_MCP_DIR / f"{source_name}.json"
+        if cached.is_file():
+            cached.unlink()
+    except ImportError:
+        pass
+
+    if not server_names:
+        print(f"No entries with source '{source_name}' found.")
+
+
+def _parse_args(argv: list[str]) -> dict:
+    """Parse CLI arguments."""
+    result: dict = {
+        "remove_mode": False,
+        "remove_name": "",
+        "source_file": "",
+        "template_name": "",
+        "target_dir": str(Path.home()),
+        "force": False,
+    }
+
+    i = 0
+    positional = 0
+    while i < len(argv):
+        arg = argv[i]
+        if arg == "--remove":
+            result["remove_mode"] = True
+            i += 1
+            if i >= len(argv):
+                print("--remove requires a template source name", file=sys.stderr)
+                sys.exit(1)
+            result["remove_name"] = argv[i]
+        elif arg == "--name":
+            i += 1
+            if i >= len(argv):
+                print("--name requires a template source name", file=sys.stderr)
+                sys.exit(1)
+            result["template_name"] = argv[i]
+        elif arg == "--force":
+            result["force"] = True
+        elif arg.startswith("-"):
+            print(f"Unknown option: {arg}", file=sys.stderr)
+            sys.exit(1)
+        else:
+            if positional == 0:
+                if not result["remove_mode"]:
+                    result["source_file"] = arg
+                else:
+                    result["target_dir"] = arg
+            elif positional == 1:
+                if _is_url(result["source_file"]):
+                    if arg.startswith(("/", "~", ".")):
+                        result["target_dir"] = arg
+                    else:
+                        result["template_name"] = arg
+                else:
+                    result["target_dir"] = arg
+            elif positional == 2:
+                result["target_dir"] = arg
+            positional += 1
+        i += 1
+
+    return result
+
+
+def main() -> None:
+    """Inject or remove external MCP templates."""
+    args = _parse_args(sys.argv[1:])
+
+    if args["remove_mode"]:
+        remove(args["remove_name"], args["target_dir"])
+        return
+
+    source_file = args["source_file"]
+    if not source_file:
+        print(
+            "Usage: inject_mcp_cli.py <template-file-or-url> [template-name] "
+            "[target-dir] [--force]",
+            file=sys.stderr,
+        )
+        print(
+            "       inject_mcp_cli.py --remove <template-source-name> [target-dir]",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    if not _is_url(source_file):
+        source_path = Path(source_file)
+        if not source_path.is_file():
+            print(f"Template file not found: {source_path}", file=sys.stderr)
+            sys.exit(1)
+
+    inject(
+        source_file,
+        args["target_dir"],
+        source_override=args["template_name"],
+        force=args["force"],
+    )
+
+
+if __name__ == "__main__":
+    main()

package/scripts/install.py

@@ -52,7 +52,7 @@ from emission import agent_count as count_agents, skill_count as count_skills
 # Step modules
 from install_steps.symlinks import install_agents, install_skills, clean_legacy_commands
 from install_steps.hooks import install_hooks
-from install_steps.markers import install_marker_files, inject_rules, refresh_url_hooks
+from install_steps.markers import install_marker_files, inject_rules, refresh_url_hooks, refresh_url_mcp
 from install_steps.ai_tools import install_ai_tools, install_local_project, run_script
 from install_steps.install_state import (
     load_state,
@@ -449,6 +449,7 @@ def install_claude_code(target_dir: Path, hooks_scripts_dir: Path,
 
     if not dry_run:
         refresh_url_hooks(str(target_dir))
+        refresh_url_mcp(str(target_dir))
 
     _sync_mcp_templates(dry_run)
 

package/scripts/install_steps/markers.py

@@ -141,6 +141,46 @@ def refresh_url_hooks(target_dir: str | None = None) -> None:
             inject(str(cached_file), target, source_override=hook_name)
 
 
+def refresh_url_mcp(target_dir: str | None = None) -> None:
+    """Re-fetch all URL-sourced MCP templates and re-inject them.
+
+    Called during ``ai-toolkit update`` to keep URL-sourced MCP templates
+    current. On fetch failure, warns and keeps the cached version.
+    """
+    from mcp_sources import get_url_templates, register_url_source
+    from paths import EXTERNAL_MCP_DIR
+    from url_fetch import fetch_url
+    import json
+
+    url_templates = get_url_templates()
+    if not url_templates:
+        return
+
+    print("  Refreshing URL-sourced MCP templates...")
+    target = target_dir or str(Path.home())
+
+    for template_name, url in url_templates.items():
+        cached_file = EXTERNAL_MCP_DIR / f"{template_name}.json"
+        try:
+            data = fetch_url(url)
+            json.loads(data)
+            cached_file.write_bytes(data)
+            register_url_source(None, template_name, url, content=data)
+            print(f"  Refreshed: {template_name} (from {url})")
+        except Exception as exc:
+            if cached_file.is_file():
+                print(f"  Warning: could not refresh '{template_name}' from {url}: {exc}")
+                print(f"           Using cached version.")
+            else:
+                print(f"  Warning: could not fetch '{template_name}' from {url}: {exc}")
+                print(f"           No cached version — template will be skipped.")
+                continue
+
+        if cached_file.is_file():
+            from inject_mcp_cli import inject
+            inject(str(cached_file), target, source_override=template_name, force=True)
+
+
 def _inject_rules_dry_run(rules_dir: Path) -> None:
     rules_src = app_dir / "rules"
     rule_names = " ".join(

package/scripts/mcp_sources.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""URL source registry for externally-injected MCP templates.
+
+Tracks which MCP templates were registered from a URL or local file so that
+`ai-toolkit update` can re-fetch the latest version and re-inject. Mirrors
+the design of hook_sources.py for parity between inject-hook and inject-mcp.
+
+Metadata stored in ~/.softspark/ai-toolkit/mcp-templates/external/sources.json.
+
+Stdlib-only -- no external dependencies.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import sys
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from paths import EXTERNAL_MCP_DIR
+
+_SOURCES_FILENAME = "sources.json"
+
+
+def _sources_path(mcp_dir: Path | None = None) -> Path:
+    return (mcp_dir or EXTERNAL_MCP_DIR) / _SOURCES_FILENAME
+
+
+def load_sources(mcp_dir: Path | None = None) -> dict[str, dict[str, Any]]:
+    """Load sources.json. Returns {} if missing or corrupt."""
+    path = _sources_path(mcp_dir)
+    if not path.is_file():
+        return {}
+    try:
+        with open(path, encoding="utf-8") as f:
+            data = json.load(f)
+        if isinstance(data, dict):
+            return data.get("templates", {})
+        return {}
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def save_sources(mcp_dir: Path | None = None,
+                 sources: dict[str, dict[str, Any]] | None = None) -> None:
+    """Write sources.json atomically."""
+    mcp_dir = mcp_dir or EXTERNAL_MCP_DIR
+    path = _sources_path(mcp_dir)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    payload = json.dumps(
+        {"schema_version": 1, "templates": sources or {}}, indent=2
+    )
+
+    fd, tmp_path = tempfile.mkstemp(
+        dir=str(path.parent), prefix=".sources_", suffix=".tmp"
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(payload)
+            f.write("\n")
+            f.flush()
+            os.fsync(f.fileno())
+        os.rename(tmp_path, str(path))
+    except BaseException:
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        raise
+
+
+def register_url_source(
+    mcp_dir: Path | None,
+    template_name: str,
+    url: str,
+    content: bytes | None = None,
+) -> None:
+    """Add or update a URL source entry for an MCP template.
+
+    When ``content`` is supplied, its sha256 is persisted. If a previous
+    sha256 exists and differs from the new one, a warning is printed
+    (and the process fails with exit 2 when ``AI_TOOLKIT_STRICT_PIN=1``).
+    """
+    if not template_name or not re.fullmatch(r"[a-zA-Z0-9_-]+", template_name):
+        raise ValueError(f"Invalid MCP template name: {template_name!r}")
+    mcp_dir = mcp_dir or EXTERNAL_MCP_DIR
+    sources = load_sources(mcp_dir)
+    entry: dict[str, Any] = {
+        "url": url,
+        "fetched_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    }
+    if content is not None:
+        new_hash = hashlib.sha256(content).hexdigest()
+        prev = sources.get(template_name) or {}
+        prev_hash = prev.get("sha256")
+        if prev_hash and prev_hash != new_hash:
+            msg = (
+                f"  CHECKSUM CHANGED: mcp '{template_name}' sha256 "
+                f"{prev_hash[:12]}... -> {new_hash[:12]}..."
+            )
+            print(msg)
+            if os.environ.get("AI_TOOLKIT_STRICT_PIN") == "1":
+                raise SystemExit(
+                    f"Refusing to update '{template_name}' under AI_TOOLKIT_STRICT_PIN=1."
+                )
+        entry["sha256"] = new_hash
+    sources[template_name] = entry
+    save_sources(mcp_dir, sources)
+
+
+def register_path_source(
+    mcp_dir: Path | None,
+    template_name: str,
+    path: Path,
+    content: bytes | None = None,
+) -> None:
+    """Add or update a local-file source entry for an MCP template.
+
+    Stores the absolute origin path so subsequent ``ai-toolkit update`` runs
+    can detect drift, plus a sha256 of the injected content.
+    """
+    if not template_name or not re.fullmatch(r"[a-zA-Z0-9_-]+", template_name):
+        raise ValueError(f"Invalid MCP template name: {template_name!r}")
+    mcp_dir = mcp_dir or EXTERNAL_MCP_DIR
+    sources = load_sources(mcp_dir)
+    existing = sources.get(template_name) or {}
+    # Never demote a URL-tracked entry to a local-path entry. update() flows
+    # call inject() with the cached file path after URL fetch, which would
+    # otherwise overwrite the URL.
+    if "url" in existing:
+        return
+    entry: dict[str, Any] = {
+        "path": str(Path(path).resolve()),
+        "fetched_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    }
+    if content is not None:
+        entry["sha256"] = hashlib.sha256(content).hexdigest()
+    sources[template_name] = entry
+    save_sources(mcp_dir, sources)
+
+
+def unregister_source(mcp_dir: Path | None, template_name: str) -> bool:
+    """Remove a source entry. Returns True if found and removed."""
+    mcp_dir = mcp_dir or EXTERNAL_MCP_DIR
+    sources = load_sources(mcp_dir)
+    if template_name in sources:
+        del sources[template_name]
+        save_sources(mcp_dir, sources)
+        return True
+    return False
+
+
+def get_url_templates(mcp_dir: Path | None = None) -> dict[str, str]:
+    """Return {template_name: url} for all URL-sourced MCP templates."""
+    sources = load_sources(mcp_dir)
+    return {name: entry["url"] for name, entry in sources.items() if "url" in entry}

package/scripts/paths.py

@@ -26,6 +26,8 @@ LEGACY_DATA_DIR = Path.home() / ".ai-toolkit"
 # Sub-directories under TOOLKIT_DATA_DIR
 HOOKS_DIR = TOOLKIT_DATA_DIR / "hooks"
 EXTERNAL_HOOKS_DIR = HOOKS_DIR / "external"
+MCP_TEMPLATES_DIR = TOOLKIT_DATA_DIR / "mcp-templates"
+EXTERNAL_MCP_DIR = MCP_TEMPLATES_DIR / "external"
 RULES_DIR = TOOLKIT_DATA_DIR / "rules"
 SESSIONS_DIR = TOOLKIT_DATA_DIR / "sessions"
 COMPACTIONS_DIR = TOOLKIT_DATA_DIR / "compactions"