boost-skill-cli 1.0.51__tar.gz → 1.0.53__tar.gz

{boost_skill_cli-1.0.51 → boost_skill_cli-1.0.53}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.51
+Version: 1.0.53
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE

{boost_skill_cli-1.0.51 → boost_skill_cli-1.0.53}/boost_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.0.51'
-__version_tuple__ = version_tuple = (1, 0, 51)
+__version__ = version = '1.0.53'
+__version_tuple__ = version_tuple = (1, 0, 53)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.0.51 → boost_skill_cli-1.0.53}/boost_cli/commands/configuration.py

@@ -20,7 +20,7 @@ from pathlib import Path
 from .. import cliparse
 from .. import __version__
 from ..core import agents, catalog, config, frontmatter, gitutil, journal
-from ..core import lockfile, paths, policy, rag, registry, store, util
+from ..core import lockfile, mcp, paths, policy, rag, registry, store, util
 from ..core import output as out
 from ..errors import BoostError
 
@@ -864,105 +864,167 @@ def cmd_serve(argv) -> int:
 
 # ---------------------------------------------------------------- mcp
 
-_MCP_TOOLS = [
-    {"name": "boost_search",
-     "description": "Search AI coding skills across the configured tap registries",
-     "inputSchema": {"type": "object",
-                     "properties": {"query": {"type": "string",
-                                              "description": "search terms"}},
-                     "required": ["query"]}},
-    {"name": "boost_list",
-     "description": "List the skills currently installed by boost",
-     "inputSchema": {"type": "object", "properties": {}}},
-    {"name": "boost_info",
-     "description": "Show detailed information about one skill",
-     "inputSchema": {"type": "object",
-                     "properties": {"name": {"type": "string",
-                                             "description": "skill name"}},
-                     "required": ["name"]}},
-    {"name": "boost_install",
-     "description": "Install a skill from a configured tap registry",
-     "inputSchema": {"type": "object",
-                     "properties": {"name": {"type": "string",
-                                             "description": "skill name"}},
-                     "required": ["name"]}},
-    {"name": "boost_doctor",
-     "description": "Health summary of the boost skill environment",
-     "inputSchema": {"type": "object", "properties": {}}},
-]
+# The MCP tool surface is an extensible registry (core/mcp.py): each handler is
+# a small `fn(args) -> (text, is_error)` that self-registers its JSON spec, so a
+# new capability is one REGISTRY.register(...) call — no dispatcher edits. This
+# is the Phase-3 "MCP as a hub" seam (docs/rag-architecture.md §8).
+
+REGISTRY = mcp.Registry()
+
+
+def _tool_search(args: dict):
+    query = str(args.get("query", ""))
+    rag_result = rag.search(query, limit=10)
+    if rag_result is not None:  # full-content index is built
+        hits, _ranker = rag_result
+        if not hits:
+            return "no skills match %r" % query, False
+        return "\n".join(
+            "%s — %s (%s)" % (h["entry"]["name"],
+                              h["entry"].get("description", ""),
+                              h["entry"]["tap"])
+            for h in hits), False
+    # no index yet -> keep today's frontmatter search so nothing regresses
+    scored = catalog.search(query)[:10]
+    if not scored:
+        return "no skills match %r" % query, False
+    return "\n".join("%s — %s (%s)" % (e["name"], e["description"], e["tap"])
+                     for e, _score in scored), False
+
+
+def _tool_list(args: dict):
+    skills = lockfile.installed()
+    if not skills:
+        return "no skills installed", False
+    return "\n".join("%s v%s (%s)%s"
+                     % (n, e.get("version", "?"), e.get("tap", "?"),
+                        " [pinned]" if e.get("pinned") else "")
+                     for n, e in sorted(skills.items())), False
+
+
+def _tool_info(args: dict):
+    name = str(args.get("name", ""))
+    entry = lockfile.get_skill(name)
+    matches = catalog.find(name)
+    if not entry and not matches:
+        return "no skill named %r (installed or in any tap)" % name, True
+    src = matches[0] if matches else {}
+    lines = ["name: " + name,
+             "version: %s" % (entry or src).get("version", "?"),
+             "tap: %s" % (entry or src).get("tap", "?")]
+    if src.get("description"):
+        lines.append("description: %s" % src["description"])
+    if entry:
+        lines.append("installed: yes (%s)" % entry.get("installed_at", "?"))
+        lines.append("agents: %s" % (", ".join(entry.get("agents") or []) or "none"))
+        if entry.get("pinned"):
+            lines.append("pinned: yes")
+    else:
+        lines.append("installed: no")
+    return "\n".join(lines), False
+
+
+def _tool_install(args: dict):
+    entry = catalog.resolve_one(str(args.get("name", "")))
+    res = store.install(entry)
+    lines = ["installed %s v%s from %s → %s"
+             % (res.name, entry.get("version", "?"), entry["tap"], res.dest),
+             "linked agents: %s" % (", ".join(res.linked) or "none"),
+             "quality score: %d/100" % res.score]
+    if res.conflicts:
+        lines.append("conflicts (left in place): %s" % ", ".join(res.conflicts))
+    return "\n".join(lines), False
+
+
+def _tool_doctor(args: dict):
+    plan = store.sync_plan()
+    issues = sum(len(v) for v in plan.values())
+    taps = registry.list_taps()
+    lines = ["installed skills: %d" % len(lockfile.installed()),
+             "taps: %d (%d skills available)" % (len(taps), len(catalog.all_entries()))]
+    for key, vals in plan.items():
+        if vals:
+            lines.append("%s: %s" % (key, ", ".join(str(v) for v in vals)))
+    lines.append("healthy — no issues found" if issues == 0
+                 else "%d issue(s) — run `boost sync` to fix" % issues)
+    return "\n".join(lines), issues > 0
+
+
+def _tool_discover_github(args: dict):
+    """Grow the corpus: GitHub code-search for SKILL.md repos (needs `gh`).
+
+    A Phase-3 reach-out tool. Degrades the ``core/ai.py`` way — if `gh` is absent
+    or the search fails, it returns a short helpful message instead of raising,
+    so the MCP server never dies on a missing external dependency.
+    """
+    from . import discovery
+    if not shutil.which("gh"):
+        return ("GitHub discovery needs the `gh` CLI — install it with "
+                "`brew install gh && gh auth login`, then retry."), True
+    query = str(args.get("query", ""))
+    raw = args.get("limit")
+    limit = int(raw) if isinstance(raw, (int, float)) and int(raw) > 0 else 20
+    limit = min(limit, 100)
+    hits = discovery.github_skill_search(query, limit)
+    if hits is None:
+        return ("GitHub code search failed — check `gh auth status` and retry."), True
+    if not hits:
+        return ("no SKILL.md repositories found on GitHub for %r"
+                % (query.strip() or "any query")), False
+    return "\n".join("%s — %s" % (h["repo"], h.get("description") or h.get("path", ""))
+                     for h in hits), False
+
+
+REGISTRY.register(
+    "boost_search",
+    "Search AI coding skills across the configured tap registries",
+    {"type": "object",
+     "properties": {"query": {"type": "string", "description": "search terms"}},
+     "required": ["query"]},
+    _tool_search)
+REGISTRY.register(
+    "boost_list",
+    "List the skills currently installed by boost",
+    {"type": "object", "properties": {}},
+    _tool_list)
+REGISTRY.register(
+    "boost_info",
+    "Show detailed information about one skill",
+    {"type": "object",
+     "properties": {"name": {"type": "string", "description": "skill name"}},
+     "required": ["name"]},
+    _tool_info)
+REGISTRY.register(
+    "boost_install",
+    "Install a skill from a configured tap registry",
+    {"type": "object",
+     "properties": {"name": {"type": "string", "description": "skill name"}},
+     "required": ["name"]},
+    _tool_install)
+REGISTRY.register(
+    "boost_doctor",
+    "Health summary of the boost skill environment",
+    {"type": "object", "properties": {}},
+    _tool_doctor)
+REGISTRY.register(
+    "boost_discover_github",
+    "Discover new SKILL.md repositories on GitHub to grow the corpus (needs the "
+    "`gh` CLI; degrades to a hint when unavailable)",
+    {"type": "object",
+     "properties": {
+         "query": {"type": "string",
+                   "description": "optional extra search terms (topic, language)"},
+         "limit": {"type": "integer",
+                   "description": "max repositories to return (default 20)"}}},
+    _tool_discover_github)
+
+# Back-compat shims: the JSON-RPC server and tests reference these names.
+_MCP_TOOLS = REGISTRY.specs()
 
 
 def _mcp_tool(tool: str, args: dict):
     """Run one MCP tool -> (text, is_error). (None, _) for unknown tools."""
-    if tool == "boost_search":
-        query = str(args.get("query", ""))
-        rag_result = rag.search(query, limit=10)
-        if rag_result is not None:  # full-content index is built
-            hits, _ranker = rag_result
-            if not hits:
-                return "no skills match %r" % query, False
-            return "\n".join(
-                "%s — %s (%s)" % (h["entry"]["name"],
-                                  h["entry"].get("description", ""),
-                                  h["entry"]["tap"])
-                for h in hits), False
-        # no index yet -> keep today's frontmatter search so nothing regresses
-        scored = catalog.search(query)[:10]
-        if not scored:
-            return "no skills match %r" % query, False
-        return "\n".join("%s — %s (%s)" % (e["name"], e["description"], e["tap"])
-                         for e, _score in scored), False
-    if tool == "boost_list":
-        skills = lockfile.installed()
-        if not skills:
-            return "no skills installed", False
-        return "\n".join("%s v%s (%s)%s"
-                         % (n, e.get("version", "?"), e.get("tap", "?"),
-                            " [pinned]" if e.get("pinned") else "")
-                         for n, e in sorted(skills.items())), False
-    if tool == "boost_info":
-        name = str(args.get("name", ""))
-        entry = lockfile.get_skill(name)
-        matches = catalog.find(name)
-        if not entry and not matches:
-            return "no skill named %r (installed or in any tap)" % name, True
-        src = matches[0] if matches else {}
-        lines = ["name: " + name,
-                 "version: %s" % (entry or src).get("version", "?"),
-                 "tap: %s" % (entry or src).get("tap", "?")]
-        if src.get("description"):
-            lines.append("description: %s" % src["description"])
-        if entry:
-            lines.append("installed: yes (%s)" % entry.get("installed_at", "?"))
-            lines.append("agents: %s" % (", ".join(entry.get("agents") or []) or "none"))
-            if entry.get("pinned"):
-                lines.append("pinned: yes")
-        else:
-            lines.append("installed: no")
-        return "\n".join(lines), False
-    if tool == "boost_install":
-        entry = catalog.resolve_one(str(args.get("name", "")))
-        res = store.install(entry)
-        lines = ["installed %s v%s from %s → %s"
-                 % (res.name, entry.get("version", "?"), entry["tap"], res.dest),
-                 "linked agents: %s" % (", ".join(res.linked) or "none"),
-                 "quality score: %d/100" % res.score]
-        if res.conflicts:
-            lines.append("conflicts (left in place): %s" % ", ".join(res.conflicts))
-        return "\n".join(lines), False
-    if tool == "boost_doctor":
-        plan = store.sync_plan()
-        issues = sum(len(v) for v in plan.values())
-        taps = registry.list_taps()
-        lines = ["installed skills: %d" % len(lockfile.installed()),
-                 "taps: %d (%d skills available)" % (len(taps), len(catalog.all_entries()))]
-        for key, vals in plan.items():
-            if vals:
-                lines.append("%s: %s" % (key, ", ".join(str(v) for v in vals)))
-        lines.append("healthy — no issues found" if issues == 0
-                     else "%d issue(s) — run `boost sync` to fix" % issues)
-        return "\n".join(lines), issues > 0
-    return None, False
+    return REGISTRY.call(tool, args)
 
 
 def _mcp_send(msg: dict) -> bool:

{boost_skill_cli-1.0.51 → boost_skill_cli-1.0.53}/boost_cli/commands/discovery.py

@@ -13,6 +13,7 @@ import shutil
 import subprocess
 import sys
 import time
+import urllib.parse
 from pathlib import Path
 
 from .. import cliparse, spin
@@ -350,6 +351,47 @@ def cmd_index(argv):
     return 0
 
 
+def github_skill_search(query="", limit=20):
+    """One-shot GitHub code search for SKILL.md repos (Phase-3 MCP reach-out).
+
+    Returns a list of ``{repo, path, url, description}`` dicts, or ``None`` when
+    the `gh` CLI is unavailable or the search fails — so callers degrade
+    gracefully instead of raising. Unlike :func:`cmd_index` this fetches a single
+    page and writes no cache: it is sized for an interactive MCP call, not a full
+    corpus build.
+    """
+    if not shutil.which("gh"):
+        return None
+    q = "filename:SKILL.md"
+    if query and query.strip():
+        q += " " + query.strip()
+    per_page = max(1, min(int(limit), 100))
+    try:
+        proc = subprocess.run(
+            ["gh", "api", "-H", "Accept: application/vnd.github+json",
+             "search/code?q=%s&per_page=%d&page=1"
+             % (urllib.parse.quote(q, safe=":"), per_page)],
+            capture_output=True, text=True, timeout=120)
+    except (subprocess.TimeoutExpired, OSError):
+        return None
+    if proc.returncode != 0:
+        return None
+    try:
+        data = json.loads(proc.stdout)
+    except json.JSONDecodeError:
+        return None
+    items = []
+    for it in (data.get("items") or [])[:per_page]:
+        repo = it.get("repository") or {}
+        items.append({
+            "repo": repo.get("full_name", "?"),
+            "path": it.get("path", ""),
+            "url": it.get("html_url", ""),
+            "description": repo.get("description") or "",
+        })
+    return items
+
+
 def cmd_discover(argv):
     """Browse/filter the GitHub-wide index built by `boost index`."""
     p = cliparse.parser(

{boost_skill_cli-1.0.51 → boost_skill_cli-1.0.53}/boost_cli/core/config.py

@@ -5,7 +5,7 @@ import json
 from copy import deepcopy
 from typing import Any
 
-from . import paths
+from . import paths, util
 
 DEFAULTS = {
     "agents": {
@@ -90,7 +90,8 @@ def load() -> dict:
 
 def save(cfg: dict) -> None:
     paths.ensure_dirs()
-    paths.config_path().write_text(json.dumps(cfg, indent=2, sort_keys=False) + "\n")
+    util.atomic_write_text(
+        paths.config_path(), json.dumps(cfg, indent=2, sort_keys=False) + "\n")
 
 
 def get(dotted: str, default=None):

{boost_skill_cli-1.0.51 → boost_skill_cli-1.0.53}/boost_cli/core/journal.py

@@ -67,4 +67,6 @@ def _maybe_rotate() -> None:
     except OSError:
         return
     if len(lines) > ROTATE_AT:
-        p.write_text("\n".join(lines[-ROTATE_KEEP:]) + "\n")
+        # Atomic swap: a bare write_text here races concurrent log() appends and
+        # can truncate the feed mid-line if interrupted.
+        util.atomic_write_text(p, "\n".join(lines[-ROTATE_KEEP:]) + "\n")

{boost_skill_cli-1.0.51 → boost_skill_cli-1.0.53}/boost_cli/core/lockfile.py

@@ -26,16 +26,41 @@ def _skeleton() -> dict:
 def read() -> dict:
     p = paths.lockfile_path()
     if not p.exists():
-        return _skeleton()
+        return _skeleton()          # empty: never installed anything yet
     try:
         lock = json.loads(p.read_text())
     except (json.JSONDecodeError, OSError):
+        # Corrupt (present but unparseable) is NOT the same as empty: returning
+        # a bare skeleton here would let the next write() overwrite the only
+        # record of every prior install. Preserve the bytes for recovery and
+        # surface it loudly before falling back to the skeleton.
+        _preserve_corrupt(p)
         return _skeleton()
     lock.setdefault("version", SCHEMA_VERSION)
     lock.setdefault("skills", {})
     return lock
 
 
+def _preserve_corrupt(p) -> None:
+    """Copy an unparseable lock file aside as ``<lock>.corrupt`` and warn.
+
+    Best effort: a read must still succeed (returning the skeleton) even if the
+    sidecar cannot be written, so failures here are swallowed after logging.
+    """
+    try:
+        backup = p.with_name(p.name + ".corrupt")
+        shutil.copy(p, backup)
+    except OSError:
+        backup = None
+    try:
+        from . import logs
+        logs.get_logger().warning(
+            "lock file %s is corrupt; preserved %s and continuing with an "
+            "empty lock", p, backup or "(backup failed)")
+    except Exception:
+        pass
+
+
 def write(lock: dict) -> None:
     paths.ensure_dirs()
     p = paths.lockfile_path()
@@ -52,7 +77,7 @@ def write(lock: dict) -> None:
         _prune_history()
     lock["version"] = SCHEMA_VERSION
     lock["updated"] = util.now_iso()
-    p.write_text(json.dumps(lock, indent=2, sort_keys=True) + "\n")
+    util.atomic_write_text(p, json.dumps(lock, indent=2, sort_keys=True) + "\n")
 
 
 def _history_files() -> List:

boost_skill_cli-1.0.53/boost_cli/core/mcp.py

@@ -0,0 +1,70 @@
+"""Extensible MCP tool registry — the Phase-3 "MCP as a hub" seam.
+
+An MCP tool is a *handler* — ``fn(args: dict) -> (text, is_error)`` — paired with
+its JSON spec (``name`` / ``description`` / ``inputSchema``). Instead of a flat
+``if/elif`` dispatcher, tools self-register on a :class:`Registry`; the JSON-RPC
+server iterates it for both ``tools/list`` and ``tools/call``. Adding a
+capability (a GitHub reach-out, a database query, some future dependency) is one
+``register()`` call — no dispatcher edits, no server changes.
+
+Handlers return ``(text, is_error)``. A handler that returns ``text is None``
+signals "I did not produce a result"; :meth:`Registry.call` also returns
+``(None, False)`` for an unknown tool, so the server can answer with a JSON-RPC
+``unknown tool`` error in exactly one place. Reach-out handlers degrade the way
+``core/ai.py`` does: probe for the dependency, and when it is absent return a
+short helpful message rather than raising.
+"""
+from __future__ import annotations
+
+from typing import Callable, Dict, List, Optional, Tuple
+
+# A handler maps parsed arguments to (text, is_error). ``text is None`` means the
+# handler produced no result (treated by the server as an unknown/aborted tool).
+Handler = Callable[[dict], Tuple[Optional[str], bool]]
+
+
+class Registry:
+    """An ordered name -> (spec, handler) map for MCP tools."""
+
+    def __init__(self) -> None:
+        self._order: List[str] = []
+        self._specs: Dict[str, dict] = {}
+        self._handlers: Dict[str, Handler] = {}
+
+    def register(self, name: str, description: str, input_schema: dict,
+                 handler: Handler) -> None:
+        """Register one tool. Raises on an empty or duplicate name."""
+        if not name:
+            raise ValueError("MCP tool name must be non-empty")
+        if name in self._handlers:
+            raise ValueError("duplicate MCP tool %r" % name)
+        self._order.append(name)
+        self._specs[name] = {"name": name, "description": description,
+                             "inputSchema": input_schema}
+        self._handlers[name] = handler
+
+    def tool(self, name: str, description: str,
+             input_schema: dict) -> Callable[[Handler], Handler]:
+        """Decorator form of :meth:`register`; returns the handler unchanged."""
+        def deco(fn: Handler) -> Handler:
+            self.register(name, description, input_schema, fn)
+            return fn
+        return deco
+
+    def specs(self) -> List[dict]:
+        """The ``tools/list`` payload — specs in registration order."""
+        return [self._specs[name] for name in self._order]
+
+    def names(self) -> List[str]:
+        """Registered tool names, in registration order."""
+        return list(self._order)
+
+    def has(self, name: str) -> bool:
+        return name in self._handlers
+
+    def call(self, name: str, args: dict) -> Tuple[Optional[str], bool]:
+        """Dispatch to a handler. ``(None, False)`` for an unknown tool."""
+        handler = self._handlers.get(name)
+        if handler is None:
+            return None, False
+        return handler(args)

{boost_skill_cli-1.0.51 → boost_skill_cli-1.0.53}/boost_cli/core/util.py

@@ -2,7 +2,9 @@
 from __future__ import annotations
 
 import hashlib
+import os
 import re
+import tempfile
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import List, Tuple
@@ -10,6 +12,36 @@ from typing import List, Tuple
 IGNORED = {".git", "__pycache__", ".DS_Store"}
 
 
+def atomic_write_text(path: Path, text: str, encoding: str = "utf-8") -> None:
+    """Write ``text`` to ``path`` so a reader never sees a partial file.
+
+    The bytes go to a temp file in the *same* directory (so the rename stays on
+    one filesystem and is atomic), get flushed and fsynced to disk, then swap
+    into place with ``os.replace``. An interrupted or concurrent write can no
+    longer truncate the target: the previous file survives intact until the
+    complete new one atomically replaces it. This is the corruption-safe
+    substitute for a bare ``Path.write_text`` on any file boost must not lose —
+    the lock file, the config, the pulse journal.
+    """
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent),
+                               prefix="." + path.name + ".", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding=encoding) as f:
+            f.write(text)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp, str(path))
+    except BaseException:
+        # Never leave a temp turd behind, and never mask the original error.
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
 def now_iso() -> str:
     return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
 

{boost_skill_cli-1.0.51 → boost_skill_cli-1.0.53}/boost_skill_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.51
+Version: 1.0.53
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE

{boost_skill_cli-1.0.51 → boost_skill_cli-1.0.53}/boost_skill_cli.egg-info/SOURCES.txt

@@ -41,6 +41,7 @@ boost_cli/core/gitutil.py
 boost_cli/core/journal.py
 boost_cli/core/lockfile.py
 boost_cli/core/logs.py
+boost_cli/core/mcp.py
 boost_cli/core/output.py
 boost_cli/core/paths.py
 boost_cli/core/policy.py
@@ -97,6 +98,7 @@ tests/unit/test_gitutil.py
 tests/unit/test_journal.py
 tests/unit/test_lockfile.py
 tests/unit/test_logs.py
+tests/unit/test_mcp.py
 tests/unit/test_mutation_hardening.py
 tests/unit/test_output.py
 tests/unit/test_paths.py

{boost_skill_cli-1.0.51 → boost_skill_cli-1.0.53}/docs/rag-architecture.md

@@ -194,23 +194,41 @@ dense retrieval.
 
 ---
 
-## 8. Phase 3 — MCP as a hub (GitHub, database, other deps)
+## 8. Phase 3 — MCP as a hub (GitHub, database, other deps) — ✅ shipped
+
+The flat `if/elif` dispatcher is now an **extensible registry** (`boost_cli/core/mcp.py`):
+
+1. **Registry refactor (done).** `core/mcp.py` defines a `Registry` — an ordered `name -> (spec, handler)`
+   map. Each handler is `fn(args: dict) -> (text, is_error)` and is paired with its
+   `{name, description, inputSchema}` via `REGISTRY.register(...)` (or the `@REGISTRY.tool(...)`
+   decorator). The JSON-RPC server iterates it: `tools/list` returns `REGISTRY.specs()` and `tools/call`
+   dispatches through `REGISTRY.call(name, args)` — an unknown tool returns `(None, False)` in exactly one
+   place, so the server answers a single `-32602 unknown tool` error. `_MCP_TOOLS` and `_mcp_tool` remain
+   as thin back-compat shims over the registry.
+2. **First reach-out tool (done), behind graceful degradation** (the `core/ai.py` pattern — probe, else a
+   helpful message, never raise):
+   - **`boost_discover_github`** — GitHub code-search for `SKILL.md` repos to grow the corpus, via the
+     one-shot `discovery.github_skill_search(query, limit)` helper. No `gh` CLI → returns an install hint
+     with `is_error=True`; a failed search → a retry hint; otherwise a ranked repo list. It never writes a
+     cache and never crashes the server.
+   - Future tools (Phase-2 vector store / a database query, a generic external API) plug in the same way.
+
+**Extension contract** — to add an MCP tool, no dispatcher or server edit is needed:
 
-Today the MCP tool layer is a declarative list `_MCP_TOOLS` (`configuration.py:867`) plus a flat
-`if/elif` dispatcher `_mcp_tool` (`configuration.py:895`). To make new capabilities drop-in:
+```python
+def _tool_x(args: dict) -> tuple[str | None, bool]:
+    # probe for any external dependency; degrade to a helpful message if absent
+    return "…result text…", False          # (text, is_error)
+
+REGISTRY.register("boost_x", "one-line description",
+                  {"type": "object", "properties": {…}}, _tool_x)
+```
 
-1. **Registry refactor.** Replace the `if/elif` with a `name -> handler` map; each handler is
-   `fn(args) -> (text, is_error)` and self-registers its `{name, description, inputSchema}`. `tools/list`
-   and `tools/call` (`_mcp_serve_stdio`, `configuration.py:965`) iterate the registry unchanged.
-2. **Reach-out tools, each behind graceful degradation** (the `core/ai.py` pattern — probe, else no-op
-   with a helpful message):
-   - `boost_discover_github` — grow the corpus by wrapping the existing `gh`-based `cmd_index`
-     (`discovery.py:217`) + auto-tap of promising repos.
-   - `boost_semantic_search` capabilities backed by the Phase-2 vector store / a database once present.
-   - a documented **extension contract** so any future dependency (a DB, an external API) becomes one new
-     handler file, no dispatcher edits.
+A handler that reaches out to a dependency **must** degrade (return a short message, not raise) so the
+long-lived stdio server survives a missing `gh`, offline network, or absent `[rag]` extra. Registration
+order is preserved and is the `tools/list` order.
 
-Phase 3 is intentionally *after* the retrieval core is proven, so the hub grows on a stable seam.
+Phase 3 landed *after* the retrieval core was proven, so the hub grew on a stable seam.
 
 ---
 
@@ -235,7 +253,7 @@ and RAG indexing compose automatically.
 |---|---|---|---|---|
 | **1** | Full-content BM25 retrieval + LLM rerank; `boost_search` upgraded in place; `boost reindex` | **none** (stdlib) | ✅ yes | New `core/rag.py` (mutation-gated) + tests; coverage ≥80%; ruff/mypy/smoke unaffected |
 | **2** | Dense embeddings + vector store | `[rag]` extra only | ❌ opt-in | Extra-only; default path unchanged; TF-IDF fallback keeps green |
-| **3** | MCP hub: GitHub/DB reach-out tools, registry refactor | none required (deps per tool, opt-in) | ❌ opt-in | Registry refactor covered by existing `TestMcp`; new handlers add tests |
+| **3** ✅ | MCP hub: extensible `core/mcp.py` registry + `boost_discover_github` reach-out | none required (deps per tool, opt-in) | ❌ opt-in | New `core/mcp.py` (mutation-gated) + `test_mcp.py`; `TestMcp`/`TestGithubSkillSearch` cover the tool; coverage 93% |
 
 **Invariant preserved at every phase:** `pip install boost-skill-cli` remains zero-runtime-dependency and
 `make check` stays green; all heavier machinery is opt-in behind the `[rag]` extra and the