feat(lib): bundle MCP servers from .common/lib into factory/lib/

Copies source (no node_modules, dist, .tasks, .wiki, __pycache__) for:
- projects-meta-mcp v2.25.0 (TypeScript/Node)
- wiki-graph v0.3.1 (TypeScript/Node)
- interns-mcp v0.3.3 (Python/FastMCP)

.gitignore: exclude lib build artefacts (node_modules, dist, .venv, __pycache__, *.pyc)
bootstrap.ps1: add MCP build step — npm install+build for TS servers, venv+pip for Python

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

lib/interns-mcp/interns_mcp/__init__.py

@@ -0,0 +1 @@
+"""Interns MCP — cheap LLM interns for Claude Code."""

lib/interns-mcp/interns_mcp/client.py

@@ -0,0 +1,43 @@
+"""OpenAI-compatible HTTP client, persistent per-endpoint."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from openai import OpenAI
+
+# Bound every LLM call. Without this the SDK default (600s) lets a stalled
+# endpoint hang the worker thread that ran the tool; enough such threads exhaust
+# FastMCP's pool and wedge the whole stdio server. 90s is well above a healthy
+# deepseek-v4-flash response yet short enough to fail fast and free the thread.
+DEFAULT_REQUEST_TIMEOUT = 90.0
+
+
+def _resolve_timeout(endpoint_cfg: dict[str, Any]) -> float:
+    """Per-endpoint request timeout in seconds; falls back to the bounded default."""
+    return float(endpoint_cfg.get("request_timeout", DEFAULT_REQUEST_TIMEOUT))
+
+
+def make_client(endpoint_cfg: dict[str, Any], api_key: str) -> OpenAI:
+    """Create a persistent OpenAI client for an endpoint."""
+    kwargs: dict[str, Any] = {
+        "base_url": endpoint_cfg["base_url"],
+        "api_key": api_key,
+        "timeout": _resolve_timeout(endpoint_cfg),
+    }
+    defaults = endpoint_cfg.get("request_defaults", {})
+    if "extra_body" in defaults:
+        kwargs["default_query"] = {}
+    return OpenAI(**kwargs)
+
+
+class ClientPool:
+    """Manages persistent HTTP clients per endpoint."""
+
+    def __init__(self) -> None:
+        self._clients: dict[str, OpenAI] = {}
+
+    def get(self, name: str, endpoint_cfg: dict[str, Any], api_key: str) -> OpenAI:
+        if name not in self._clients:
+            self._clients[name] = make_client(endpoint_cfg, api_key)
+        return self._clients[name]

lib/interns-mcp/interns_mcp/interns/base.py

@@ -0,0 +1,52 @@
+"""Base intern protocol and response types."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class InternResponse:
+    text: str
+    usage: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class BlockedByPolicy:
+    path: str
+    pattern: str
+    reason: str
+
+
+@dataclass
+class BudgetExceededError:
+    tokens: int
+    limit: int
+    top_files: list[str] = field(default_factory=list)
+    hint: str = "use compress=True or narrow paths"
+
+
+class Intern:
+    id: str = ""
+    description: str = ""
+    endpoint: str | None = None
+    model: str | None = None
+    max_tokens: int = 4096
+    temperature: float = 0.2
+    system_prompt: str = ""
+    context_budget: int = 120000
+
+    def __init__(self, config: dict[str, Any] | None = None, client: Any = None, safety: Any = None):
+        self.client = client
+        self.safety = safety
+        if config:
+            self._apply_config(config)
+
+    def _apply_config(self, config: dict[str, Any]) -> None:
+        for k, v in config.items():
+            if hasattr(self, k):
+                setattr(self, k, v)
+
+    def run(self, paths: list[str], question: str, **kwargs: Any) -> InternResponse | BlockedByPolicy | BudgetExceededError:
+        raise NotImplementedError

lib/interns-mcp/interns_mcp/interns/bulk_text_read.py

@@ -0,0 +1,46 @@
+"""Bulk text read intern — read N files and answer a focused question."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .base import BlockedByPolicy, Intern, InternResponse
+
+
+class BulkTextRead(Intern):
+    id = "bulk_text_read"
+    description = "Read N files and answer a focused question. Returns concise summary."
+
+    def run(self, paths: list[str], question: str, **kwargs: Any) -> InternResponse | BlockedByPolicy:
+        contents: list[str] = []
+        for p in paths:
+            text = Path(p).read_text(encoding="utf-8", errors="replace")
+            contents.append(f"--- {p} ---\n{text}")
+
+        combined = "\n\n".join(contents)
+        prompt = f"Files:\n{combined}\n\nQuestion: {question}"
+
+        if self.client is None:
+            return InternResponse(text="No client configured", usage={})
+
+        extra_body = kwargs.get("extra_body", {})
+        resp = self.client.chat.completions.create(
+            model=self.model or "deepseek-v4-flash",
+            messages=[
+                {"role": "system", "content": self.system_prompt},
+                {"role": "user", "content": prompt},
+            ],
+            max_tokens=kwargs.get("max_tokens", self.max_tokens),
+            temperature=self.temperature,
+            extra_body=extra_body if extra_body else None,
+        )
+
+        choice = resp.choices[0]
+        return InternResponse(
+            text=choice.message.content or "",
+            usage={
+                "tokens_in": resp.usage.prompt_tokens if resp.usage else 0,
+                "tokens_out": resp.usage.completion_tokens if resp.usage else 0,
+            },
+        )

lib/interns-mcp/interns_mcp/interns/grep_audit.py

@@ -0,0 +1,104 @@
+"""Grep audit intern — deterministic matrix of N paths x M patterns. No LLM call."""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any, Callable, Literal
+
+from .base import Intern, InternResponse
+
+
+class GrepAudit(Intern):
+    id = "grep_audit"
+    description = (
+        "Deterministic grep matrix over N paths x M patterns (substring or regex). "
+        "No LLM call, no endpoint cost. Returns markdown table (default) or JSON."
+    )
+
+    def run(
+        self,
+        paths: list[str],
+        patterns: list[str | dict[str, Any]],
+        output: Literal["table", "json"] = "table",
+        case_sensitive: bool = True,
+        **_kwargs: Any,
+    ) -> InternResponse:
+        compiled = _compile_patterns(patterns, case_sensitive)
+
+        rows: list[dict[str, Any]] = []
+        matches_total = 0
+        for p in paths:
+            try:
+                text = Path(p).read_text(encoding="utf-8", errors="replace")
+            except (FileNotFoundError, PermissionError, IsADirectoryError, OSError) as exc:
+                rows.append(
+                    {
+                        "path": p,
+                        "matches": {c["name"]: None for c in compiled},
+                        "error": str(exc),
+                    }
+                )
+                continue
+            row_matches: dict[str, bool] = {}
+            for c in compiled:
+                hit = bool(c["matcher"](text))
+                row_matches[c["name"]] = hit
+                if hit:
+                    matches_total += 1
+            rows.append({"path": p, "matches": row_matches})
+
+        if output == "json":
+            rendered = json.dumps({"rows": rows}, ensure_ascii=False, indent=2)
+        else:
+            rendered = _render_table(rows, [c["name"] for c in compiled])
+
+        return InternResponse(
+            text=rendered,
+            usage={
+                "files_scanned": len(paths),
+                "patterns_evaluated": len(compiled),
+                "matches_total": matches_total,
+            },
+        )
+
+
+def _compile_patterns(
+    patterns: list[str | dict[str, Any]], case_sensitive: bool
+) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    for p in patterns:
+        if isinstance(p, str):
+            out.append({"name": p, "matcher": _substring_matcher(p, case_sensitive)})
+            continue
+        name = p.get("name", p["pattern"])
+        if p.get("regex"):
+            flags = 0 if case_sensitive else re.IGNORECASE
+            compiled = re.compile(p["pattern"], flags)
+            out.append({"name": name, "matcher": compiled.search})
+        else:
+            out.append(
+                {"name": name, "matcher": _substring_matcher(p["pattern"], case_sensitive)}
+            )
+    return out
+
+
+def _substring_matcher(needle: str, case_sensitive: bool) -> Callable[[str], bool]:
+    if case_sensitive:
+        return lambda text: needle in text
+    lowered = needle.lower()
+    return lambda text: lowered in text.lower()
+
+
+def _render_table(rows: list[dict[str, Any]], names: list[str]) -> str:
+    header = "| Path | " + " | ".join(names) + " |"
+    sep = "|" + "---|" * (len(names) + 1)
+    lines = [header, sep]
+    for row in rows:
+        cells: list[str] = []
+        for n in names:
+            v = row["matches"].get(n)
+            cells.append("⚠️" if v is None else ("✅" if v else "❌"))
+        lines.append(f"| `{row['path']}` | " + " | ".join(cells) + " |")
+    return "\n".join(lines)

lib/interns-mcp/interns_mcp/interns/repo_read.py

@@ -0,0 +1,164 @@
+"""Repo read intern — pack repo with repomix, answer question with LLM."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from .base import BudgetExceededError, Intern, InternResponse
+from ..safety import always_ask_globs
+
+
+# Conservative token estimate: chars/4 overestimates for repomix XML (tag overhead),
+# so BudgetExceededError fires early rather than late. Real enforcement is on the
+# endpoint side — this is a client-side safety net, not a precision counter.
+CHARS_PER_TOKEN = 4
+
+
+def _estimate_tokens(text: str) -> int:
+    return len(text) // CHARS_PER_TOKEN
+
+
+def _top_files_by_size(packed: str, n: int = 5) -> list[str]:
+    """Return the n largest files in repomix XML output, by block content size.
+
+    Parses each ``<file path="X">...</file>`` block and measures the byte length
+    of its content, so BudgetExceededError.top_files points the user at the real
+    overflow culprits — not the first files in document order.
+    """
+    sizes: list[tuple[int, str]] = []
+    pos = 0
+    while True:
+        open_idx = packed.find('<file ', pos)
+        if open_idx == -1:
+            break
+        close_idx = packed.find('</file>', open_idx)
+        if close_idx == -1:
+            break
+        path_start = packed.find('path="', open_idx) + 6
+        path_end = packed.find('"', path_start)
+        path = packed[path_start:path_end]
+        # Content sits between the opening tag's '>' and the closing '</file>'.
+        content_start = packed.find('>', open_idx) + 1
+        content_size = close_idx - content_start
+        sizes.append((content_size, path))
+        pos = close_idx + len('</file>')
+
+    sizes.sort(key=lambda x: x[0], reverse=True)
+    return [path for _, path in sizes[:n]]
+
+
+class RepoRead(Intern):
+    id = "repo_read"
+    description = "Pack directory/repo with repomix and answer a question. Cheap repo comprehension."
+
+    def run(
+        self,
+        paths: list[str],
+        question: str,
+        compress: bool = False,
+        **kwargs: Any,
+    ) -> InternResponse | BudgetExceededError:
+        if not paths:
+            return InternResponse(text="No paths provided", usage={})
+
+        # Build repomix args: pass all paths, not just first.
+        ignore_globs = always_ask_globs()
+
+        # Resolve npx via PATH. On Windows, subprocess.run(shell=False) does not
+        # expand PATHEXT, so passing bare "npx" fails to find npx.cmd; shutil.which
+        # finds the .cmd (or .exe / shell wrapper on POSIX) and returns a full path
+        # that CreateProcess / execve can dispatch directly.
+        npx = shutil.which("npx") or shutil.which("npx.cmd")
+        if npx is None:
+            return InternResponse(text="npx not found - install Node.js", usage={})
+
+        # Use mkstemp to avoid Windows file-sharing issues with NamedTemporaryFile.
+        # os.close(fd) releases the handle before repomix writes to the path.
+        fd, tmp_path = tempfile.mkstemp(suffix=".xml")
+        os.close(fd)
+        err_fd, err_path = tempfile.mkstemp(suffix=".stderr")
+        os.close(err_fd)
+        try:
+            args = [
+                npx, "-y", "repomix@latest",
+                *paths,
+                "--output", tmp_path,
+                "--style", "xml",
+            ]
+            if compress:
+                args.append("--compress")
+            for glob in ignore_globs:
+                args += ["--ignore", glob]
+
+            try:
+                # Redirect repomix's stdio to FILES/DEVNULL, never PIPES. capture_output
+                # spawns reader threads that communicate() joins; if any process in the
+                # child tree (an orphaned `node` grandchild, or — under concurrent launches
+                # on Windows — a sibling subprocess that inherited the pipe handle) keeps a
+                # pipe write-end open, that join blocks FOREVER, past the timeout, wedging
+                # the worker thread. repomix's real output already goes to --output, so its
+                # stdout is unused; stderr is captured to a file for error reporting only.
+                with open(err_path, "w", encoding="utf-8", errors="replace") as err_f:
+                    subprocess.run(
+                        args,
+                        stdin=subprocess.DEVNULL,
+                        stdout=subprocess.DEVNULL,
+                        stderr=err_f,
+                        timeout=120,
+                        check=True,
+                    )
+                packed_text = Path(tmp_path).read_text()
+            except subprocess.TimeoutExpired:
+                return InternResponse(text="Repomix timed out (120s)", usage={})
+            except subprocess.CalledProcessError:
+                err = Path(err_path).read_text(encoding="utf-8", errors="replace")
+                return InternResponse(text=f"Repomix failed: {err[:500]}", usage={})
+            except FileNotFoundError:
+                return InternResponse(text="npx not found - install Node.js", usage={})
+        finally:
+            # Always clean up the temp files, even on error.
+            for _p in (tmp_path, err_path):
+                try:
+                    os.unlink(_p)
+                except OSError:
+                    pass
+
+        # Budget check before sending to LLM.
+        tokens = _estimate_tokens(packed_text)
+        if tokens > self.context_budget:
+            return BudgetExceededError(
+                tokens=tokens,
+                limit=self.context_budget,
+                top_files=_top_files_by_size(packed_text),
+            )
+
+        prompt = f"# Packed repo\n\n{packed_text}\n\n# Question\n\n{question}"
+
+        if self.client is None:
+            return InternResponse(text="No client configured", usage={})
+
+        extra_body = kwargs.get("extra_body", {})
+        resp = self.client.chat.completions.create(
+            model=self.model or "deepseek-v4-flash",
+            messages=[
+                {"role": "system", "content": self.system_prompt},
+                {"role": "user", "content": prompt},
+            ],
+            max_tokens=kwargs.get("max_tokens", self.max_tokens),
+            temperature=self.temperature,
+            extra_body=extra_body if extra_body else None,
+        )
+
+        choice = resp.choices[0]
+        return InternResponse(
+            text=choice.message.content or "",
+            usage={
+                "tokens_in": resp.usage.prompt_tokens if resp.usage else 0,
+                "tokens_out": resp.usage.completion_tokens if resp.usage else 0,
+            },
+        )

lib/interns-mcp/interns_mcp/interns/transcript_distill.py

@@ -0,0 +1,46 @@
+"""Transcript distill intern — compress session transcript into structured action-list."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .base import BlockedByPolicy, Intern, InternResponse
+
+
+class TranscriptDistill(Intern):
+    id = "transcript_distill"
+    description = "Compress a session transcript/log into a structured action-list."
+
+    def run(self, paths: list[str], question: str = "Extract action items, decisions, and unresolved questions.", **kwargs: Any) -> InternResponse | BlockedByPolicy:
+        contents: list[str] = []
+        for p in paths:
+            text = Path(p).read_text(encoding="utf-8", errors="replace")
+            contents.append(f"--- {p} ---\n{text}")
+
+        combined = "\n\n".join(contents)
+        prompt = f"Transcript:\n{combined}\n\nTask: {question}"
+
+        if self.client is None:
+            return InternResponse(text="No client configured", usage={})
+
+        extra_body = kwargs.get("extra_body", {})
+        resp = self.client.chat.completions.create(
+            model=self.model or "deepseek-v4-flash",
+            messages=[
+                {"role": "system", "content": self.system_prompt},
+                {"role": "user", "content": prompt},
+            ],
+            max_tokens=kwargs.get("max_tokens", self.max_tokens),
+            temperature=self.temperature,
+            extra_body=extra_body if extra_body else None,
+        )
+
+        choice = resp.choices[0]
+        return InternResponse(
+            text=choice.message.content or "",
+            usage={
+                "tokens_in": resp.usage.prompt_tokens if resp.usage else 0,
+                "tokens_out": resp.usage.completion_tokens if resp.usage else 0,
+            },
+        )

lib/interns-mcp/interns_mcp/registry.py

@@ -0,0 +1,38 @@
+"""Load intern catalog from config.yaml."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .interns.base import Intern
+from .interns.bulk_text_read import BulkTextRead
+from .interns.grep_audit import GrepAudit
+from .interns.repo_read import RepoRead
+from .interns.transcript_distill import TranscriptDistill
+
+# Explicit registry — MVP choice (see design spec open questions).
+INTERN_CLASSES: dict[str, type[Intern]] = {
+    "bulk_text_read": BulkTextRead,
+    "grep_audit": GrepAudit,
+    "repo_read": RepoRead,
+    "transcript_distill": TranscriptDistill,
+}
+
+
+def load_config(config_path: Path) -> dict[str, Any]:
+    with open(config_path, encoding="utf-8") as f:
+        return yaml.safe_load(f)
+
+
+def load_interns(config: dict[str, Any], client: Any = None, safety: Any = None) -> list[Intern]:
+    """Instantiate interns from config, wiring shared client and safety."""
+    interns = []
+    for intern_id, intern_cfg in config.get("interns", {}).items():
+        cls = INTERN_CLASSES.get(intern_id)
+        if cls is None:
+            continue
+        interns.append(cls(config=intern_cfg, client=client, safety=safety))
+    return interns

lib/interns-mcp/interns_mcp/safety.py

@@ -0,0 +1,65 @@
+"""Always-ask path matcher — safety enforcement for intern calls."""
+
+from __future__ import annotations
+
+from pathlib import PurePath
+
+# Patterns that always require explicit user approval before sending to an intern.
+ALWAYS_ASK_PATTERNS: list[str] = [
+    "**/.env",
+    "**/.env.*",
+    "**/secrets/**",
+    "**/projects-secrets/**",
+    "**/credentials*",
+    "**/*.key",
+    "**/*.pem",
+    "**/.ssh/**",
+    "**/.aws/credentials",
+    "**/.aws/config",
+    "**/.netrc",
+    "**/.npmrc",
+    "**/.pypirc",
+]
+
+ALWAYS_ASK_REASON = (
+    "Path matched always-ask pattern. "
+    "Sending this file to an external endpoint requires explicit approval."
+)
+
+
+def check_paths(paths: list[str], extra_patterns: list[str] | None = None) -> list[dict]:
+    """Check each path against always-ask patterns.
+
+    Returns list of blocked entries: [{"path": ..., "pattern": ..., "reason": ...}].
+    Empty list = all paths clear.
+    """
+    patterns = list(ALWAYS_ASK_PATTERNS)
+    if extra_patterns:
+        patterns.extend(extra_patterns)
+
+    blocked = []
+    for p in paths:
+        pp = PurePath(p)
+        for pattern in patterns:
+            if pp.match(pattern):
+                blocked.append({"path": p, "pattern": pattern, "reason": ALWAYS_ASK_REASON})
+                break
+    return blocked
+
+
+def always_ask_globs() -> list[str]:
+    """Return glob patterns for always-ask paths, suitable for --ignore flags.
+
+    Used by tool-wrapping interns (e.g. repo_read) to inject --ignore flags
+    into subprocess calls, preventing repomix from packaging sensitive files
+    even if they exist inside the target directory.
+    """
+    # Convert PurePath-style patterns to glob patterns repomix understands.
+    # Strip leading **/ since repomix --ignore uses gitignore-style patterns.
+    globs = []
+    for p in ALWAYS_ASK_PATTERNS:
+        if p.startswith("**/"):
+            globs.append(p[3:])
+        else:
+            globs.append(p)
+    return globs

lib/interns-mcp/interns_mcp/server.py

@@ -0,0 +1,114 @@
+"""FastMCP stdio server — MCP entry point for interns."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from dotenv import load_dotenv
+from fastmcp import FastMCP
+
+from .client import ClientPool
+from .registry import load_config, load_interns
+from .safety import check_paths
+
+# Resolve config path relative to .common root; secrets live outside the git tree.
+_COMMON_ROOT = Path(__file__).resolve().parents[3]  # lib/interns-mcp/interns_mcp/ → .common/
+CONFIG_PATH = _COMMON_ROOT / "config" / "interns" / "config.yaml"
+SECRETS_PATH = Path(
+    os.environ.get("INTERNS_SECRETS_PATH")
+    or (Path.home() / ".config" / "projects-secrets" / "interns.env")
+)
+
+mcp = FastMCP("interns")
+
+
+def _get_api_key(endpoint_name: str, endpoints: dict[str, Any]) -> str:
+    env_var = endpoints[endpoint_name]["api_key_env"]
+    key = os.environ.get(env_var, "")
+    if not key:
+        raise RuntimeError(f"Missing API key: set {env_var} in {SECRETS_PATH}")
+    return key
+
+
+def _build_extra_body(endpoint_cfg: dict[str, Any]) -> dict[str, Any]:
+    return endpoint_cfg.get("request_defaults", {}).get("extra_body", {})
+
+
+def register_tool(intern: Any, client_pool: ClientPool, endpoints: dict[str, Any]) -> None:
+    """Register a single intern as an MCP tool."""
+
+    @mcp.tool(name=intern.id, description=intern.description)
+    def intern_tool(paths: list[str], question: str, max_tokens: int | None = None) -> dict:
+        if intern.safety:
+            blocked = check_paths(paths)
+            if blocked:
+                return {"blocked": True, "path": blocked[0]["path"], "pattern": blocked[0]["pattern"], "reason": blocked[0]["reason"]}
+
+        # Wire endpoint client if intern needs one.
+        if intern.endpoint and intern.client is None:
+            ep_cfg = endpoints[intern.endpoint]
+            api_key = _get_api_key(intern.endpoint, endpoints)
+            intern.client = client_pool.get(intern.endpoint, ep_cfg, api_key)
+
+        kwargs: dict[str, Any] = {}
+        if intern.endpoint and intern.endpoint in endpoints:
+            kwargs["extra_body"] = _build_extra_body(endpoints[intern.endpoint])
+        if max_tokens is not None:
+            kwargs["max_tokens"] = max_tokens
+
+        result = intern.run(paths, question, **kwargs)
+        if isinstance(result, dict) and result.get("blocked"):
+            return result
+        return {"text": result.text, "usage": result.usage}
+
+
+def register_grep_audit_tool(intern: Any) -> None:
+    """Register grep_audit with its distinct (paths, patterns, output, case_sensitive) shape.
+
+    Deterministic: no LLM client wiring path. Safety gate still applies — server is
+    the single trust boundary regardless of whether the intern hits an endpoint.
+    """
+
+    @mcp.tool(name=intern.id, description=intern.description)
+    def grep_audit_tool(
+        paths: list[str],
+        patterns: list[Any],
+        output: str = "table",
+        case_sensitive: bool = True,
+    ) -> dict:
+        if intern.safety:
+            blocked = check_paths(paths)
+            if blocked:
+                return {"blocked": True, "path": blocked[0]["path"], "pattern": blocked[0]["pattern"], "reason": blocked[0]["reason"]}
+
+        result = intern.run(
+            paths=paths,
+            patterns=patterns,
+            output=output,
+            case_sensitive=case_sensitive,
+        )
+        return {"text": result.text, "usage": result.usage}
+
+
+def main() -> None:
+    load_dotenv(SECRETS_PATH)
+    config = load_config(CONFIG_PATH)
+    endpoints = config.get("endpoints", {})
+
+    pool = ClientPool()
+    from . import safety as _safety_mod
+
+    interns = load_interns(config, safety=_safety_mod, client=None)
+    for intern in interns:
+        if intern.id == "grep_audit":
+            register_grep_audit_tool(intern)
+        else:
+            register_tool(intern, pool, endpoints)
+
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

lib/interns-mcp/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "interns-mcp"
+version = "0.3.3"
+description = "FastMCP stdio server exposing cheap intern LLM tools for Claude Code"
+requires-python = ">=3.11"
+dependencies = [
+    "fastmcp>=2.0",
+    "openai>=1.0",
+    "pyyaml>=6.0",
+    "python-dotenv>=1.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"

lib/interns-mcp/tests/test_client.py

@@ -0,0 +1,21 @@
+"""Tests for HTTP client construction — esp. the request timeout that bounds
+LLM calls so a stalled endpoint can never hang a worker thread forever."""
+
+from interns_mcp.client import make_client, _resolve_timeout, DEFAULT_REQUEST_TIMEOUT
+
+
+def test_default_timeout_is_bounded():
+    # A bare endpoint config must still get a finite, short-ish timeout —
+    # the OpenAI SDK default (600s) is long enough to wedge the server.
+    assert _resolve_timeout({}) == DEFAULT_REQUEST_TIMEOUT
+    assert DEFAULT_REQUEST_TIMEOUT <= 120
+
+
+def test_configured_timeout_overrides_default():
+    assert _resolve_timeout({"request_timeout": 42}) == 42.0
+
+
+def test_client_is_built_with_timeout():
+    c = make_client({"base_url": "http://example.invalid", "request_timeout": 30}, "k")
+    # OpenAI client exposes the configured timeout; must not be None.
+    assert c.timeout is not None

lib/interns-mcp/tests/test_grep_audit.py

@@ -0,0 +1,237 @@
+"""Tests for grep_audit intern — deterministic, LLM-free."""
+
+import json
+
+from interns_mcp.interns.base import Intern, InternResponse
+from interns_mcp.interns.grep_audit import GrepAudit
+
+
+def test_substring_case_sensitive(tmp_path):
+    f = tmp_path / "claude.md"
+    f.write_text("follow project discipline\nuse superpowers\n", encoding="utf-8")
+
+    intern = GrepAudit()
+    result = intern.run(
+        paths=[str(f)],
+        patterns=["follow project discipline", "Follow Project Discipline"],
+        output="json",
+    )
+
+    assert isinstance(result, InternResponse)
+    data = json.loads(result.text)
+    matches = data["rows"][0]["matches"]
+    assert matches["follow project discipline"] is True
+    assert matches["Follow Project Discipline"] is False
+
+
+def test_substring_case_insensitive(tmp_path):
+    f = tmp_path / "claude.md"
+    f.write_text("follow project discipline\n", encoding="utf-8")
+
+    intern = GrepAudit()
+    result = intern.run(
+        paths=[str(f)],
+        patterns=["FOLLOW PROJECT DISCIPLINE"],
+        output="json",
+        case_sensitive=False,
+    )
+
+    data = json.loads(result.text)
+    assert data["rows"][0]["matches"]["FOLLOW PROJECT DISCIPLINE"] is True
+
+
+def test_regex_named(tmp_path):
+    f = tmp_path / "pyproject.toml"
+    f.write_text('version = "0.3.0"\n', encoding="utf-8")
+
+    intern = GrepAudit()
+    result = intern.run(
+        paths=[str(f)],
+        patterns=[{"pattern": r'version\s*=\s*"\d+\.\d+\.\d+"', "name": "version-line", "regex": True}],
+        output="json",
+    )
+
+    data = json.loads(result.text)
+    assert data["rows"][0]["matches"]["version-line"] is True
+
+
+def test_dict_substring(tmp_path):
+    f = tmp_path / "skill.md"
+    f.write_text("trigger string here\n", encoding="utf-8")
+
+    intern = GrepAudit()
+    result = intern.run(
+        paths=[str(f)],
+        patterns=[{"pattern": "trigger string", "name": "trigger"}],
+        output="json",
+    )
+
+    data = json.loads(result.text)
+    assert data["rows"][0]["matches"]["trigger"] is True
+
+
+def test_output_table(tmp_path):
+    f1 = tmp_path / "a.md"
+    f1.write_text("alpha beta\n", encoding="utf-8")
+    f2 = tmp_path / "b.md"
+    f2.write_text("gamma\n", encoding="utf-8")
+
+    intern = GrepAudit()
+    result = intern.run(
+        paths=[str(f1), str(f2)],
+        patterns=["alpha", "gamma"],
+        output="table",
+    )
+
+    text = result.text
+    assert text.splitlines()[0].startswith("| Path |")
+    assert "alpha" in text.splitlines()[0]
+    assert "gamma" in text.splitlines()[0]
+    # f1 has alpha but not gamma
+    f1_line = [l for l in text.splitlines() if str(f1) in l][0]
+    assert "✅" in f1_line
+    assert "❌" in f1_line
+    # f2 has gamma but not alpha
+    f2_line = [l for l in text.splitlines() if str(f2) in l][0]
+    assert "✅" in f2_line
+    assert "❌" in f2_line
+
+
+def test_output_json(tmp_path):
+    f = tmp_path / "a.md"
+    f.write_text("alpha\n", encoding="utf-8")
+
+    intern = GrepAudit()
+    result = intern.run(
+        paths=[str(f)],
+        patterns=["alpha", "missing"],
+        output="json",
+    )
+
+    data = json.loads(result.text)
+    assert "rows" in data
+    assert len(data["rows"]) == 1
+    assert data["rows"][0]["path"] == str(f)
+    assert data["rows"][0]["matches"]["alpha"] is True
+    assert data["rows"][0]["matches"]["missing"] is False
+
+
+def test_file_not_found_partial_result(tmp_path):
+    f_real = tmp_path / "exists.md"
+    f_real.write_text("hello\n", encoding="utf-8")
+    f_ghost = tmp_path / "ghost.md"  # never created
+
+    intern = GrepAudit()
+    result = intern.run(
+        paths=[str(f_real), str(f_ghost)],
+        patterns=["hello"],
+        output="json",
+    )
+
+    data = json.loads(result.text)
+    assert len(data["rows"]) == 2  # partial result, no abort
+    rows_by_path = {r["path"]: r for r in data["rows"]}
+    assert rows_by_path[str(f_real)]["matches"]["hello"] is True
+    # Ghost row: match is None (unreadable cell), error field present
+    assert rows_by_path[str(f_ghost)]["matches"]["hello"] is None
+    assert "error" in rows_by_path[str(f_ghost)]
+
+
+def test_file_not_found_table_renders_warning(tmp_path):
+    f_ghost = tmp_path / "ghost.md"  # never created
+
+    intern = GrepAudit()
+    result = intern.run(
+        paths=[str(f_ghost)],
+        patterns=["x"],
+        output="table",
+    )
+
+    assert "⚠️" in result.text
+
+
+def test_empty_paths():
+    intern = GrepAudit()
+    result = intern.run(paths=[], patterns=["x"], output="json")
+    data = json.loads(result.text)
+    assert data["rows"] == []
+    assert result.usage["files_scanned"] == 0
+    assert result.usage["matches_total"] == 0
+
+
+def test_empty_patterns(tmp_path):
+    f = tmp_path / "a.md"
+    f.write_text("alpha\n", encoding="utf-8")
+
+    intern = GrepAudit()
+    result = intern.run(paths=[str(f)], patterns=[], output="json")
+    data = json.loads(result.text)
+    assert len(data["rows"]) == 1
+    assert data["rows"][0]["matches"] == {}
+    assert result.usage["patterns_evaluated"] == 0
+
+
+def test_unicode_content_utf8(tmp_path):
+    f = tmp_path / "ru.md"
+    f.write_text("русский текст\n", encoding="utf-8")
+
+    intern = GrepAudit()
+    result = intern.run(
+        paths=[str(f)],
+        patterns=["русский"],
+        output="json",
+    )
+
+    data = json.loads(result.text)
+    assert data["rows"][0]["matches"]["русский"] is True
+
+
+def test_unicode_content_binary_garbage_does_not_crash(tmp_path):
+    f = tmp_path / "binary.bin"
+    f.write_bytes(b"\xff\xfe\x00\x01\x02 hello \xff")
+
+    intern = GrepAudit()
+    # errors="replace" should let us still grep for "hello"
+    result = intern.run(
+        paths=[str(f)],
+        patterns=["hello"],
+        output="json",
+    )
+
+    data = json.loads(result.text)
+    assert data["rows"][0]["matches"]["hello"] is True
+
+
+def test_usage_counts(tmp_path):
+    f1 = tmp_path / "a.md"
+    f1.write_text("alpha\n", encoding="utf-8")
+    f2 = tmp_path / "b.md"
+    f2.write_text("alpha beta\n", encoding="utf-8")
+
+    intern = GrepAudit()
+    result = intern.run(
+        paths=[str(f1), str(f2)],
+        patterns=["alpha", "beta"],
+        output="json",
+    )
+
+    assert result.usage["files_scanned"] == 2
+    assert result.usage["patterns_evaluated"] == 2
+    # f1: alpha ✓, beta ✗  → 1
+    # f2: alpha ✓, beta ✓  → 2
+    assert result.usage["matches_total"] == 3
+
+
+def test_endpoint_null_no_client_no_crash():
+    """LLM-free intern must not require client wiring."""
+    intern = GrepAudit(config={"endpoint": None})
+    assert intern.client is None
+    assert intern.endpoint is None
+
+
+def test_base_intern_accepts_endpoint_null_config():
+    """Base class survives config with explicit endpoint=null (no LLM init triggered)."""
+    intern = Intern(config={"endpoint": None, "model": None})
+    assert intern.endpoint is None
+    assert intern.model is None
+    assert intern.client is None

lib/interns-mcp/tests/test_registry.py

@@ -0,0 +1,40 @@
+"""Tests for registry loading."""
+
+from interns_mcp.registry import load_interns, INTERN_CLASSES
+
+
+def test_classes_registered():
+    assert "bulk_text_read" in INTERN_CLASSES
+    assert "repo_read" in INTERN_CLASSES
+    assert "transcript_distill" in INTERN_CLASSES
+
+
+def test_load_creates_interns():
+    config = {
+        "endpoints": {},
+        "interns": {
+            "bulk_text_read": {
+                "description": "test",
+                "endpoint": None,
+                "model": "test-model",
+                "max_tokens": 1024,
+                "temperature": 0.1,
+                "system_prompt": "test prompt",
+            },
+        },
+    }
+    interns = load_interns(config)
+    assert len(interns) == 1
+    assert interns[0].id == "bulk_text_read"
+    assert interns[0].model == "test-model"
+
+
+def test_unknown_intern_skipped():
+    config = {
+        "endpoints": {},
+        "interns": {
+            "unknown_intern": {"description": "ghost"},
+        },
+    }
+    interns = load_interns(config)
+    assert len(interns) == 0

lib/interns-mcp/tests/test_repo_read.py

@@ -0,0 +1,283 @@
+"""Tests for repo_read intern."""
+
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+from interns_mcp.interns.base import BudgetExceededError, InternResponse
+from interns_mcp.interns.repo_read import RepoRead, _top_files_by_size
+
+
+def _make_llm_mock(text="The code prints hello", prompt_tokens=100, completion_tokens=50):
+    """Build a mock LLM response."""
+    mock = MagicMock()
+    mock.choices = [MagicMock()]
+    mock.choices[0].message.content = text
+    mock.usage.prompt_tokens = prompt_tokens
+    mock.usage.completion_tokens = completion_tokens
+    return mock
+
+
+def test_happy_path(tmp_path):
+    """Repomix pack + LLM answer works."""
+    intern = RepoRead()
+    intern.system_prompt = "You are a helpful assistant."
+
+    mock_client = MagicMock()
+    mock_client.chat.completions.create.return_value = _make_llm_mock()
+
+    target = str(tmp_path)
+
+    with patch("subprocess.run") as mock_run, \
+         patch("interns_mcp.interns.repo_read.always_ask_globs", return_value=[".env"]):
+        def fake_run(args, **kwargs):
+            out_idx = args.index("--output")
+            Path(args[out_idx + 1]).write_text("# Repo\n\n```python\nprint('hello')\n```")
+            return MagicMock(returncode=0, stdout="", stderr="")
+
+        mock_run.side_effect = fake_run
+
+        intern.client = mock_client
+        result = intern.run([target], "What does this repo do?")
+
+        assert isinstance(result, InternResponse)
+        assert "hello" in result.text.lower()
+        assert result.usage["tokens_in"] == 100
+        assert result.usage["tokens_out"] == 50
+
+        # Verify --ignore flag injected
+        call_args = mock_run.call_args[0][0]
+        assert "--ignore" in call_args
+        ignore_idx = call_args.index("--ignore")
+        assert call_args[ignore_idx + 1] == ".env"
+
+        # Verify --style xml
+        assert "--style" in call_args
+        style_idx = call_args.index("--style")
+        assert call_args[style_idx + 1] == "xml"
+
+
+def test_tempfile_cleaned_up(tmp_path):
+    """Temp file is removed after successful call."""
+    intern = RepoRead()
+    intern.system_prompt = "assistant"
+    intern.client = MagicMock()
+    intern.client.chat.completions.create.return_value = _make_llm_mock()
+
+    created_files = []
+
+    with patch("subprocess.run") as mock_run, \
+         patch("interns_mcp.interns.repo_read.always_ask_globs", return_value=[]):
+        original_mkstemp = tempfile.mkstemp
+
+        def tracking_mkstemp(*args, **kwargs):
+            fd, path = original_mkstemp(*args, **kwargs)
+            created_files.append(path)
+            return fd, path
+
+        with patch("interns_mcp.interns.repo_read.tempfile.mkstemp", side_effect=tracking_mkstemp):
+            def fake_run(args, **kwargs):
+                out_idx = args.index("--output")
+                Path(args[out_idx + 1]).write_text("packed")
+                return MagicMock(returncode=0, stdout="", stderr="")
+
+            mock_run.side_effect = fake_run
+            intern.run([str(tmp_path)], "summarize")
+
+    # Temp file should be cleaned up
+    for f in created_files:
+        assert not os.path.exists(f), f"Temp file not cleaned up: {f}"
+
+
+def test_tempfile_cleaned_up_on_error(tmp_path):
+    """Temp file is removed even when repomix fails."""
+    intern = RepoRead()
+
+    created_files = []
+
+    with patch("subprocess.run") as mock_run, \
+         patch("interns_mcp.interns.repo_read.always_ask_globs", return_value=[]):
+        original_mkstemp = tempfile.mkstemp
+
+        def tracking_mkstemp(*args, **kwargs):
+            fd, path = original_mkstemp(*args, **kwargs)
+            created_files.append(path)
+            return fd, path
+
+        with patch("interns_mcp.interns.repo_read.tempfile.mkstemp", side_effect=tracking_mkstemp):
+            mock_run.side_effect = subprocess.TimeoutExpired("npx", 120)
+            intern.run([str(tmp_path)], "summarize")
+
+    for f in created_files:
+        assert not os.path.exists(f), f"Temp file leaked on error: {f}"
+
+
+def test_compress_flag_passed(tmp_path):
+    """compress=True adds --compress to repomix args."""
+    intern = RepoRead()
+    intern.system_prompt = "assistant"
+    intern.client = MagicMock()
+    intern.client.chat.completions.create.return_value = _make_llm_mock()
+
+    with patch("subprocess.run") as mock_run, \
+         patch("interns_mcp.interns.repo_read.always_ask_globs", return_value=[]):
+        def fake_run(args, **kwargs):
+            out_idx = args.index("--output")
+            Path(args[out_idx + 1]).write_text("packed content")
+            return MagicMock(returncode=0, stdout="", stderr="")
+
+        mock_run.side_effect = fake_run
+
+        intern.run([str(tmp_path)], "summarize", compress=True)
+
+        call_args = mock_run.call_args[0][0]
+        assert "--compress" in call_args
+
+
+def test_multiple_paths_passed_to_repomix(tmp_path):
+    """All paths are forwarded to repomix, not just the first."""
+    intern = RepoRead()
+    intern.system_prompt = "assistant"
+    intern.client = MagicMock()
+    intern.client.chat.completions.create.return_value = _make_llm_mock()
+
+    dir1 = tmp_path / "a"
+    dir2 = tmp_path / "b"
+    dir1.mkdir()
+    dir2.mkdir()
+
+    with patch("subprocess.run") as mock_run, \
+         patch("interns_mcp.interns.repo_read.always_ask_globs", return_value=[]):
+        def fake_run(args, **kwargs):
+            out_idx = args.index("--output")
+            Path(args[out_idx + 1]).write_text("packed")
+            return MagicMock(returncode=0, stdout="", stderr="")
+
+        mock_run.side_effect = fake_run
+
+        intern.run([str(dir1), str(dir2)], "overview")
+
+        call_args = mock_run.call_args[0][0]
+        assert str(dir1) in call_args
+        assert str(dir2) in call_args
+
+
+def test_empty_paths_returns_error():
+    """Empty paths list returns error."""
+    intern = RepoRead()
+    result = intern.run([], "summarize")
+    assert isinstance(result, InternResponse)
+    assert "no paths" in result.text.lower()
+
+
+def test_repomix_timeout_returns_error(tmp_path):
+    """Repomix timeout returns graceful error."""
+    intern = RepoRead()
+
+    with patch("subprocess.run", side_effect=subprocess.TimeoutExpired("npx", 120)), \
+         patch("interns_mcp.interns.repo_read.always_ask_globs", return_value=[]):
+        result = intern.run([str(tmp_path)], "summarize")
+        assert isinstance(result, InternResponse)
+        assert "timed out" in result.text.lower()
+
+
+def test_repomix_failure_returns_error(tmp_path):
+    """Repomix non-zero return returns stderr."""
+    intern = RepoRead()
+
+    with patch("subprocess.run") as mock_run, \
+         patch("interns_mcp.interns.repo_read.always_ask_globs", return_value=[]):
+        mock_run.side_effect = subprocess.CalledProcessError(
+            1, "npx", stderr="package not found"
+        )
+
+        result = intern.run([str(tmp_path)], "summarize")
+        assert isinstance(result, InternResponse)
+        assert "failed" in result.text.lower()
+
+
+def test_npx_not_found_returns_error(tmp_path):
+    """Missing npx returns helpful message."""
+    intern = RepoRead()
+
+    with patch("subprocess.run", side_effect=FileNotFoundError), \
+         patch("interns_mcp.interns.repo_read.always_ask_globs", return_value=[]):
+        result = intern.run([str(tmp_path)], "summarize")
+        assert isinstance(result, InternResponse)
+        assert "node.js" in result.text.lower()
+
+
+def test_budget_exceeded_returns_error(tmp_path):
+    """Large packed output triggers BudgetExceededError."""
+    intern = RepoRead()
+    intern.context_budget = 10  # very low to force overflow
+
+    with patch("subprocess.run") as mock_run, \
+         patch("interns_mcp.interns.repo_read.always_ask_globs", return_value=[]):
+        def fake_run(args, **kwargs):
+            out_idx = args.index("--output")
+            Path(args[out_idx + 1]).write_text("x" * 200)
+            return MagicMock(returncode=0, stdout="", stderr="")
+
+        mock_run.side_effect = fake_run
+
+        result = intern.run([str(tmp_path)], "summarize")
+        assert isinstance(result, BudgetExceededError)
+        assert result.tokens > result.limit
+        assert result.hint
+
+
+def test_top_files_by_size_sorts_by_content_length():
+    """_top_files_by_size returns files sorted by content size, not document order."""
+    packed = (
+        '<file path="small.py">x</file>\n'
+        '<file path="large.py">' + "y" * 500 + '</file>\n'
+        '<file path="medium.py">' + "z" * 100 + '</file>\n'
+    )
+    result = _top_files_by_size(packed, n=3)
+    assert result[0] == "large.py", f"Expected large.py first, got {result[0]}"
+    assert result[1] == "medium.py", f"Expected medium.py second, got {result[1]}"
+    assert result[2] == "small.py", f"Expected small.py third, got {result[2]}"
+
+
+def test_repomix_runs_without_pipes(tmp_path):
+    """Anti-deadlock invariant: repomix must NOT be launched with captured pipes.
+
+    capture_output / stdout=PIPE spawns reader threads that communicate() joins;
+    an orphaned grandchild holding the pipe write-end makes that join hang forever
+    (the real-world 6-minute repo_read wedge). stdout must be DEVNULL, stdin DEVNULL,
+    and stderr a real file (has fileno) — never subprocess.PIPE.
+    """
+    intern = RepoRead()
+    intern.system_prompt = "assistant"
+    intern.client = MagicMock()
+    intern.client.chat.completions.create.return_value = _make_llm_mock()
+
+    with patch("subprocess.run") as mock_run, \
+         patch("interns_mcp.interns.repo_read.always_ask_globs", return_value=[]):
+        def fake_run(args, **kwargs):
+            out_idx = args.index("--output")
+            Path(args[out_idx + 1]).write_text("packed")
+            return MagicMock(returncode=0)
+
+        mock_run.side_effect = fake_run
+        intern.run([str(tmp_path)], "summarize")
+
+        kwargs = mock_run.call_args.kwargs
+        assert kwargs.get("capture_output") is not True, "must not capture_output (pipes)"
+        assert kwargs.get("stdout") is subprocess.DEVNULL, "stdout must be DEVNULL"
+        assert kwargs.get("stdin") is subprocess.DEVNULL, "stdin must be DEVNULL"
+        assert kwargs.get("stderr") is not subprocess.PIPE, "stderr must not be a PIPE"
+
+
+def test_top_files_by_size_limits_count():
+    """_top_files_by_size respects the n parameter."""
+    packed = (
+        '<file path="a.py">xx</file>\n'
+        '<file path="b.py">yy</file>\n'
+        '<file path="c.py">zz</file>\n'
+    )
+    result = _top_files_by_size(packed, n=2)
+    assert len(result) == 2

lib/interns-mcp/tests/test_safety.py

@@ -0,0 +1,54 @@
+"""Tests for safety path matcher."""
+
+from interns_mcp.safety import check_paths
+
+
+def test_clean_paths_pass():
+    assert check_paths(["/home/user/project/src/main.py"]) == []
+
+
+def test_env_file_blocked():
+    blocked = check_paths(["project/.env"])
+    assert len(blocked) == 1
+    assert blocked[0]["pattern"] == "**/.env"
+
+
+def test_env_local_blocked():
+    blocked = check_paths(["project/.env.local"])
+    assert len(blocked) == 1
+
+
+def test_secrets_dir_blocked():
+    blocked = check_paths(["project/secrets/api_key.txt"])
+    assert len(blocked) == 1
+
+
+def test_pem_file_blocked():
+    blocked = check_paths(["/home/user/.ssh/id_rsa.pem"])
+    assert len(blocked) == 1
+
+
+def test_ssh_dir_blocked():
+    blocked = check_paths(["/home/user/.ssh/config"])
+    assert len(blocked) == 1
+
+
+def test_credentials_blocked():
+    blocked = check_paths(["project/credentials.json"])
+    assert len(blocked) == 1
+
+
+def test_key_file_blocked():
+    blocked = check_paths(["project/server.key"])
+    assert len(blocked) == 1
+
+
+def test_mixed_paths():
+    blocked = check_paths(["src/app.py", "project/.env", "README.md"])
+    assert len(blocked) == 1
+    assert blocked[0]["path"] == "project/.env"
+
+
+def test_extra_patterns():
+    blocked = check_paths(["data/private.csv"], extra_patterns=["data/**"])
+    assert len(blocked) == 1