localcode 0.2.16__py3-none-any.whl → 0.3.0__py3-none-any.whl

localcode/__init__.py

@@ -1,3 +1,3 @@
 __all__ = ["__version__"]
 
-__version__ = "0.2.16"
+__version__ = "0.3.0"

localcode/mcp/__init__.py

@@ -0,0 +1,84 @@
+"""MCP (Model Context Protocol) client + tool-registration.
+
+Lets a user add MCP servers to LocalCode in `~/.localcode/mcp.json`.
+Each server's tools get auto-registered with the agent so the model
+can call them like any other tool.
+
+This package is built on the **official `mcp` Python SDK** (the
+`modelcontextprotocol` project). The SDK is fully async (anyio), but
+LocalCode's toolkit/agent are synchronous, so this package owns an
+async↔sync bridge: a single dedicated background thread runs a
+persistent asyncio event loop, and every public method submits a
+coroutine to that loop via `asyncio.run_coroutine_threadsafe(...)`.
+Each server's transport context + `ClientSession` are opened once and
+kept alive on that loop for the process lifetime; they're torn down in
+`shutdown_all()` / `MCPClient.close()`.
+
+Config shape — `~/.localcode/mcp.json`, key `mcpServers`, per server:
+
+    {
+      "mcpServers": {
+        "filesystem": {                       # stdio (default transport)
+          "command": "npx",
+          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me"],
+          "env": {}
+        },
+        "remote-http": {                      # streamable HTTP
+          "transport": "http",
+          "url": "https://example.com/mcp",
+          "headers": {"Authorization": "Bearer ..."},
+          "oauth": true                       # optional, http/sse only
+        },
+        "remote-sse": {                       # legacy SSE
+          "transport": "sse",
+          "url": "https://example.com/sse",
+          "headers": {}
+        }
+      }
+    }
+
+Transport is chosen by the `transport` field; it defaults to "stdio" so
+existing stdio configs (no `transport` key) keep working unchanged.
+
+We use `initialize`, `tools/list`, and `tools/call`. No prompts,
+resources, sampling, or notifications — good enough for the common
+"let the agent use my MCP server" case.
+
+This is a package; the implementation is split across `_bridge`,
+`_transports`, `_config`, and `client` submodules. The full public API
+is re-exported here so `from localcode.mcp import ...` is unchanged.
+"""
+from __future__ import annotations
+
+from ._bridge import _CONNECT_TIMEOUT, _DEFAULT_TIMEOUT, _EventLoopThread
+from ._config import MCP_CONFIG_PATH, _config_path, load_mcp_config
+from ._transports import _InMemoryTokenStorage, _build_oauth_provider
+from .client import (
+    MCPClient,
+    _client_from_config,
+    _clients,
+    call,
+    connect_all,
+    dispatch_mcp_tool,
+    get_client,
+    list_connected,
+    mcp_tool_schemas,
+    shutdown_all,
+)
+
+__all__ = [
+    # config
+    "MCP_CONFIG_PATH",
+    "load_mcp_config",
+    # client
+    "MCPClient",
+    # registry
+    "connect_all",
+    "list_connected",
+    "get_client",
+    "call",
+    "shutdown_all",
+    # tool schemas / dispatch
+    "mcp_tool_schemas",
+    "dispatch_mcp_tool",
+]

localcode/mcp/_bridge.py

@@ -0,0 +1,61 @@
+"""Async↔sync bridge for the MCP package.
+
+The official `mcp` SDK is fully async (anyio), but LocalCode's
+toolkit/agent are synchronous. This module owns a single dedicated
+background thread running a persistent asyncio event loop; every public
+MCP method submits a coroutine to that loop via
+`asyncio.run_coroutine_threadsafe(...)`. Each server's transport context
++ `ClientSession` are opened once and kept alive on that loop for the
+process lifetime.
+"""
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+import threading
+
+
+# Default time budget (seconds) for a single round-trip to an MCP server.
+_DEFAULT_TIMEOUT = 30.0
+# Time budget for the initial connect (spawning a subprocess / TCP + TLS +
+# initialize handshake can be slow, especially for `npx`/`uvx` cold starts).
+_CONNECT_TIMEOUT = 60.0
+
+
+class _EventLoopThread:
+    """A singleton background thread running a persistent asyncio loop.
+
+    All SDK coroutines run on this one loop, so a `ClientSession` opened on
+    it stays usable for the process lifetime. Sync callers submit work with
+    `run(coro, timeout)`.
+    """
+
+    _instance: "_EventLoopThread | None" = None
+    _instance_lock = threading.Lock()
+
+    def __init__(self) -> None:
+        self.loop = asyncio.new_event_loop()
+        self._thread = threading.Thread(
+            target=self._run_loop, name="localcode-mcp-loop", daemon=True
+        )
+        self._thread.start()
+
+    def _run_loop(self) -> None:
+        asyncio.set_event_loop(self.loop)
+        self.loop.run_forever()
+
+    @classmethod
+    def instance(cls) -> "_EventLoopThread":
+        with cls._instance_lock:
+            if cls._instance is None:
+                cls._instance = cls()
+            return cls._instance
+
+    def run(self, coro, timeout: float | None = None):
+        """Submit a coroutine to the loop and block for its result."""
+        fut = asyncio.run_coroutine_threadsafe(coro, self.loop)
+        return fut.result(timeout=timeout)
+
+    def submit(self, coro) -> concurrent.futures.Future:
+        """Submit a coroutine without blocking; returns its Future."""
+        return asyncio.run_coroutine_threadsafe(coro, self.loop)

localcode/mcp/_config.py

@@ -0,0 +1,33 @@
+"""Config loading for the MCP package.
+
+Reads `~/.localcode/mcp.json` (key `mcpServers`), honoring LOCALCODE_HOME
+like the rest of the app.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+
+MCP_CONFIG_PATH = Path.home() / ".localcode" / "mcp.json"
+
+
+def _config_path() -> Path:
+    """Resolve the mcp.json path, honoring LOCALCODE_HOME like the rest of
+    the app (config.get_home_dir). Falls back to ~/.localcode."""
+    override = os.environ.get("LOCALCODE_HOME")
+    if override:
+        return Path(override).expanduser() / "mcp.json"
+    return MCP_CONFIG_PATH
+
+
+def load_mcp_config() -> dict[str, dict]:
+    """Read ~/.localcode/mcp.json. Returns the `mcpServers` dict."""
+    path = _config_path()
+    if not path.is_file():
+        return {}
+    try:
+        return json.loads(path.read_text()).get("mcpServers", {})
+    except Exception:
+        return {}

localcode/mcp/_transports.py

@@ -0,0 +1,124 @@
+"""Transport construction + best-effort OAuth for the MCP package.
+
+`build_transport` returns the async context manager for a server's
+configured transport (stdio / streamable-HTTP / SSE). OAuth is a
+best-effort construction only: LocalCode runs headless, so the
+authorization-code callback degrades with a clear error instead of
+hanging — prefer a pre-minted token via `headers`.
+"""
+from __future__ import annotations
+
+import os
+
+# ── Official MCP SDK imports ─────────────────────────────────────────────
+from mcp.client.stdio import StdioServerParameters, stdio_client
+from mcp.client.streamable_http import streamablehttp_client
+from mcp.client.sse import sse_client
+
+
+class _InMemoryTokenStorage:
+    """A TokenStorage that keeps tokens/registration in process memory.
+
+    Tokens are NOT persisted across runs, so every process start triggers a
+    fresh OAuth flow. Good enough for a best-effort implementation; a real
+    deployment would persist these under ~/.localcode.
+    """
+
+    def __init__(self) -> None:
+        self._tokens = None
+        self._client_info = None
+
+    async def get_tokens(self):
+        return self._tokens
+
+    async def set_tokens(self, tokens) -> None:
+        self._tokens = tokens
+
+    async def get_client_info(self):
+        return self._client_info
+
+    async def set_client_info(self, client_info) -> None:
+        self._client_info = client_info
+
+
+def _build_oauth_provider(url: str):
+    """Build an SDK OAuthClientProvider for `url`, best-effort.
+
+    LIMITATION: a complete OAuth authorization-code flow needs an interactive
+    browser + a loopback redirect listener to capture the `code`. LocalCode
+    runs headless (CLI/agent), so we cannot drive that flow automatically.
+    We construct a real provider so the auth *config path* is exercised and
+    so a future interactive frontend could reuse it, but the callback handler
+    degrades with a clear, actionable error instead of hanging. For servers
+    that need OAuth, prefer passing a pre-minted token via `headers` (e.g.
+    {"Authorization": "Bearer ..."}) until interactive OAuth is wired up.
+    """
+    from mcp.client.auth import OAuthClientProvider
+    from mcp.shared.auth import OAuthClientMetadata
+
+    async def _redirect_handler(authorization_url: str) -> None:
+        # In an interactive frontend this would open a browser. Headless: noop.
+        # (The error is raised from the callback handler below.)
+        return None
+
+    async def _callback_handler() -> tuple[str, str | None]:
+        raise RuntimeError(
+            "OAuth for MCP requires an interactive browser flow, which is not "
+            "available in headless LocalCode. Configure the server with a "
+            "pre-minted token via `headers` (e.g. Authorization: Bearer ...) "
+            "instead of `oauth: true`."
+        )
+
+    return OAuthClientProvider(
+        server_url=url,
+        client_metadata=OAuthClientMetadata(
+            client_name="LocalCode",
+            redirect_uris=["http://localhost:8765/callback"],
+            grant_types=["authorization_code", "refresh_token"],
+            response_types=["code"],
+        ),
+        storage=_InMemoryTokenStorage(),
+        redirect_handler=_redirect_handler,
+        callback_handler=_callback_handler,
+    )
+
+
+def build_transport(
+    *,
+    name: str,
+    transport: str,
+    command: str,
+    args: list[str],
+    env: dict[str, str],
+    url: str,
+    headers: dict[str, str],
+    oauth: bool,
+):
+    """Return the async context manager for the configured transport."""
+    if transport in ("stdio", ""):
+        if not command:
+            raise RuntimeError(
+                f"MCP server {name!r}: stdio transport needs a 'command'"
+            )
+        full_env = os.environ.copy()
+        full_env.update(env)
+        params = StdioServerParameters(command=command, args=args, env=full_env)
+        return stdio_client(params)
+    if transport in ("http", "streamable-http", "streamable_http"):
+        if not url:
+            raise RuntimeError(
+                f"MCP server {name!r}: http transport needs a 'url'"
+            )
+        auth = _build_oauth_provider(url) if oauth else None
+        return streamablehttp_client(url, headers=headers or None, auth=auth)
+    if transport == "sse":
+        if not url:
+            raise RuntimeError(
+                f"MCP server {name!r}: sse transport needs a 'url'"
+            )
+        auth = _build_oauth_provider(url) if oauth else None
+        return sse_client(url, headers=headers or None, auth=auth)
+    raise RuntimeError(
+        f"MCP server {name!r}: unknown transport {transport!r} "
+        f"(use 'stdio', 'http', or 'sse')"
+    )

localcode/mcp/client.py

@@ -0,0 +1,316 @@
+"""MCPClient + the process-wide registry of connected MCP servers.
+
+`MCPClient` speaks one server connection through the official `mcp` SDK
+(stdio / streamable-HTTP / SSE). The transport context manager and the
+`ClientSession` are entered once inside a long-lived "runner" coroutine on
+the shared event loop (anyio cancel scopes must be entered/exited on the
+same task), and sync methods talk to the live session by submitting
+coroutines to the loop.
+
+The registry functions (`connect_all`/`list_connected`/`get_client`/
+`shutdown_all`, plus `call`/`mcp_tool_schemas`/`dispatch_mcp_tool`) manage
+a process-wide dict of connected clients.
+"""
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+
+# ── Official MCP SDK imports ─────────────────────────────────────────────
+from mcp import ClientSession
+
+from ._bridge import _CONNECT_TIMEOUT, _DEFAULT_TIMEOUT, _EventLoopThread
+from ._config import load_mcp_config
+from ._transports import build_transport
+
+
+# ── Client ───────────────────────────────────────────────────────────────
+class MCPClient:
+    """One MCP server connection, spoken through the official SDK.
+
+    Supports stdio, streamable-HTTP, and SSE transports. The transport
+    context manager and the `ClientSession` are entered once inside a
+    long-lived "runner" coroutine on the shared event loop (anyio cancel
+    scopes must be entered/exited on the same task, so we keep that one task
+    alive until close()). Sync methods talk to the live session by
+    submitting coroutines to the loop.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        transport: str = "stdio",
+        command: str = "",
+        args: list[str] | None = None,
+        env: dict[str, str] | None = None,
+        url: str = "",
+        headers: dict[str, str] | None = None,
+        oauth: bool = False,
+    ) -> None:
+        self.name = name
+        self.transport = (transport or "stdio").lower()
+        self.command = command
+        self.args = args or []
+        self.env = env or {}
+        self.url = url
+        self.headers = headers or {}
+        self.oauth = oauth
+
+        self._bridge = _EventLoopThread.instance()
+        self._session: ClientSession | None = None
+        self._runner_future: concurrent.futures.Future | None = None
+        self._ready: concurrent.futures.Future | None = None
+        self._stop_event: asyncio.Event | None = None
+        self._closed = False
+        self._post_error: Exception | None = None
+
+    # -- transport factory -------------------------------------------------
+    def _make_transport(self):
+        """Return the async context manager for the configured transport."""
+        return build_transport(
+            name=self.name,
+            transport=self.transport,
+            command=self.command,
+            args=self.args,
+            env=self.env,
+            url=self.url,
+            headers=self.headers,
+            oauth=self.oauth,
+        )
+
+    # -- runner coroutine --------------------------------------------------
+    async def _runner(self) -> None:
+        """Open transport + session, signal ready, then idle until stop.
+
+        Everything (enter and exit of the async-with blocks) happens inside
+        this single task so anyio's cancel scopes stay task-bound.
+        """
+        self._stop_event = asyncio.Event()
+        try:
+            async with self._make_transport() as streams:
+                # stdio/sse yield (read, write); streamable-http yields
+                # (read, write, get_session_id) — take the first two.
+                read, write = streams[0], streams[1]
+                async with ClientSession(read, write) as session:
+                    await session.initialize()
+                    self._session = session
+                    if self._ready is not None and not self._ready.done():
+                        self._ready.set_result(True)
+                    await self._stop_event.wait()
+        except Exception as exc:  # noqa: BLE001 - surface to connecting thread
+            if self._ready is not None and not self._ready.done():
+                self._ready.set_exception(exc)
+            else:
+                self._post_error = exc
+        finally:
+            self._session = None
+
+    # -- lifecycle ---------------------------------------------------------
+    def connect(self, timeout: float = _CONNECT_TIMEOUT) -> None:
+        """Start the runner and block until the session is initialized."""
+        if self._session is not None:
+            return
+        self._ready = concurrent.futures.Future()
+        self._runner_future = self._bridge.submit(self._runner())
+        try:
+            self._ready.result(timeout=timeout)
+        except Exception as exc:
+            # Make sure a half-started runner gets cleaned up.
+            self.close()
+            raise RuntimeError(
+                f"MCP server {self.name!r} failed to connect: {exc}"
+            ) from exc
+
+    def initialize(self) -> None:
+        """Back-compat alias — connect if not already connected."""
+        self.connect()
+
+    def _require_session(self) -> ClientSession:
+        if self._session is None:
+            raise RuntimeError(f"MCP server {self.name!r} is not connected")
+        return self._session
+
+    # -- public sync API ---------------------------------------------------
+    def list_tools(self) -> list[dict]:
+        """Return the server's tools as plain dicts with `name`,
+        `description`, and `inputSchema` (JSONSchema)."""
+        if self._session is None:
+            self.connect()
+        session = self._require_session()
+        result = self._bridge.run(session.list_tools(), timeout=_DEFAULT_TIMEOUT)
+        tools: list[dict] = []
+        for tool in result.tools:
+            tools.append(
+                {
+                    "name": tool.name,
+                    "description": tool.description or "",
+                    "inputSchema": tool.inputSchema
+                    or {"type": "object", "properties": {}},
+                }
+            )
+        return tools
+
+    def call_tool(self, name: str, arguments: dict) -> str:
+        """Invoke a tool; return the concatenated text content blocks."""
+        if self._session is None:
+            self.connect()
+        session = self._require_session()
+        result = self._bridge.run(
+            session.call_tool(name, arguments or {}),
+            timeout=_DEFAULT_TIMEOUT,
+        )
+        out: list[str] = []
+        for block in result.content:
+            # TextContent blocks have type == "text" and a .text attr.
+            text = getattr(block, "text", None)
+            if text is not None and getattr(block, "type", None) == "text":
+                out.append(text)
+        joined = "\n".join(out)
+        if not joined:
+            return "(MCP tool returned no text content)"
+        if result.isError:
+            return f"MCP tool {name!r} reported an error:\n{joined}"
+        return joined
+
+    def health(self) -> tuple[bool, str]:
+        """Lightweight liveness check used by Toolkit.diagnostics()."""
+        if self._closed:
+            return False, "closed"
+        if self._post_error is not None:
+            return False, f"errored ({self._post_error})"
+        if self._session is None:
+            return False, "not connected"
+        if self._runner_future is not None and self._runner_future.done():
+            return False, "runner exited"
+        return True, f"running ({self.transport})"
+
+    def close(self) -> None:
+        """Tear down the session + transport on the shared loop."""
+        if self._closed:
+            return
+        self._closed = True
+        # Signal the runner to leave its idle wait so the async-with blocks
+        # exit cleanly on their own task.
+        if self._stop_event is not None:
+            try:
+                self._bridge.loop.call_soon_threadsafe(self._stop_event.set)
+            except Exception:
+                pass
+        if self._runner_future is not None:
+            try:
+                self._runner_future.result(timeout=10)
+            except Exception:
+                # Best-effort: cancel if it didn't exit in time.
+                try:
+                    self._runner_future.cancel()
+                except Exception:
+                    pass
+        self._session = None
+
+
+# ── Process-wide registry ─────────────────────────────────────────────────
+# Registry of connected MCP clients (name → MCPClient).
+_clients: dict[str, MCPClient] = {}
+
+
+def _client_from_config(name: str, cfg: dict) -> MCPClient:
+    """Build an MCPClient from one server's config dict (transport-aware)."""
+    transport = (cfg.get("transport") or "stdio").lower()
+    return MCPClient(
+        name=name,
+        transport=transport,
+        command=cfg.get("command", "") or "",
+        args=cfg.get("args", []) or [],
+        env=cfg.get("env", {}) or {},
+        url=cfg.get("url", "") or "",
+        headers=cfg.get("headers", {}) or {},
+        oauth=bool(cfg.get("oauth", False)),
+    )
+
+
+def connect_all() -> tuple[int, list[str]]:
+    """Connect every configured MCP server. Returns (count_ok, errors)."""
+    errors: list[str] = []
+    config = load_mcp_config()
+    for name, server_cfg in config.items():
+        if name in _clients:
+            continue  # already connected
+        try:
+            cli = _client_from_config(name, server_cfg or {})
+            cli.connect()
+            _clients[name] = cli
+        except Exception as e:
+            errors.append(f"{name}: {e}")
+    return len(_clients), errors
+
+
+def get_client(name: str) -> "MCPClient | None":
+    """Return the connected MCPClient for `name`, or None if not connected."""
+    return _clients.get(name)
+
+
+def list_connected() -> list[tuple[str, list[dict]]]:
+    """Return [(server_name, [tools])] for every connected MCP server."""
+    out = []
+    for name, cli in _clients.items():
+        try:
+            out.append((name, cli.list_tools()))
+        except Exception:
+            out.append((name, []))
+    return out
+
+
+def call(server: str, tool_name: str, arguments: dict) -> str:
+    cli = _clients.get(server)
+    if cli is None:
+        return f"REJECTED: MCP server {server!r} is not connected."
+    try:
+        return cli.call_tool(tool_name, arguments)
+    except Exception as e:
+        return f"MCP call {server}.{tool_name} failed: {e}"
+
+
+def shutdown_all() -> None:
+    """Tear down all MCP connections on app exit."""
+    for cli in _clients.values():
+        try:
+            cli.close()
+        except Exception:
+            pass
+    _clients.clear()
+
+
+def mcp_tool_schemas() -> list[dict]:
+    """Return OpenAI-style tool schemas for every connected MCP
+    server's tools. Each tool is renamed `mcp_<server>_<tool>` so
+    multiple servers can expose tools with the same name without
+    collision."""
+    schemas = []
+    for server, tools in list_connected():
+        for t in tools:
+            name = f"mcp_{server}_{t.get('name', '')}"
+            schemas.append({
+                "type": "function",
+                "function": {
+                    "name": name,
+                    "description": (
+                        f"[MCP {server}] " + (t.get("description") or "")
+                    )[:1000],
+                    "parameters": t.get("inputSchema", {"type": "object"}),
+                },
+            })
+    return schemas
+
+
+def dispatch_mcp_tool(name: str, arguments: dict) -> str | None:
+    """If `name` is `mcp_<server>_<tool>`, dispatch to that server.
+    Returns None if not an MCP tool (so caller falls through to
+    normal tool dispatch)."""
+    if not name.startswith("mcp_"):
+        return None
+    rest = name[len("mcp_"):]
+    if "_" not in rest:
+        return None
+    server, tool = rest.split("_", 1)
+    return call(server, tool, arguments)

localcode/toolkit.py

@@ -18,9 +18,9 @@ except ImportError:
 from .config import AppConfig
 from .context import IGNORE_DIRS, list_repo_files
 from .indexer import build_index, search_index
-# MCP client module removed in T0.9 purge — nobody configured MCP servers,
-# the dispatch loop was dead code. Reintroduce as a proper plugin system
-# (T0.9-followup) if a real MCP use case lands.
+# MCP tools are lazily wired in via ensure_mcp_tools() (the `mcp` module is
+# imported there, on demand, so a missing/broken MCP setup never affects
+# toolkit import). See ensure_mcp_tools() below.
 from .shell import run_shell
 from .undo import ChangeLog
 
@@ -1063,10 +1063,64 @@ class LocalCodeToolkit:
         """Plugin system removed — no-op."""
         pass
 
-    # MCP registration functions removed during T0.9 purge. Reintroduce
-    # alongside a real plugin system if needed; the prior implementation
-    # was never configured by any user, so keeping it as dead dispatch
-    # code was pure surface area for drift.
+    @staticmethod
+    def _make_mcp_handler(client: Any, tool_name: str) -> ToolHandler:
+        """Build a handler bound to a specific client + tool name.
+
+        Defined as its own method (not a lambda inside a loop) so the
+        client/tool_name are captured per-tool — no late-binding bug where
+        every registered MCP tool would point at the last loop iteration.
+        """
+        def handler(args: dict[str, Any]) -> str:
+            try:
+                return client.call_tool(tool_name, args or {})
+            except Exception as exc:  # never let a bad MCP call crash dispatch
+                return f"MCP tool {tool_name!r} call failed: {exc}"
+        return handler
+
+    def ensure_mcp_tools(self) -> None:
+        """Lazily connect configured MCP servers and register their tools.
+
+        Runs at most once per toolkit (guarded by self._mcp_loaded). Each
+        connected server's tools are registered as `mcp_<server>_<tool>`
+        LocalCodeTools so the model can call them like any builtin. Fully
+        defensive: a bad/missing MCP server never crashes the toolkit.
+        """
+        if self._mcp_loaded:
+            return
+        self._mcp_loaded = True  # set first so we only ever attempt once
+        try:
+            from . import mcp as _mcp
+        except Exception as exc:
+            self.mcp_errors.append(f"mcp import failed: {exc}")
+            return
+        try:
+            _count, errors = _mcp.connect_all()
+            if errors:
+                self.mcp_errors.extend(errors)
+            for server, tools in _mcp.list_connected():
+                client = _mcp.get_client(server)
+                if client is None:
+                    continue
+                self.mcp_clients[server] = client
+                for t in tools:
+                    tool_name = (t.get("name") or "").strip()
+                    if not tool_name:
+                        continue
+                    schema = t.get("inputSchema") or {"type": "object", "properties": {}}
+                    if not isinstance(schema, dict):
+                        schema = {"type": "object", "properties": {}}
+                    description = (
+                        f"[MCP {server}] " + (t.get("description") or "")
+                    ).strip()[:1000]
+                    self._register(LocalCodeTool(
+                        name=f"mcp_{server}_{tool_name}",
+                        description=description,
+                        parameters=schema,
+                        handler=self._make_mcp_handler(client, tool_name),
+                    ))
+        except Exception as exc:  # connect_all/list shouldn't raise, but be safe
+            self.mcp_errors.append(f"mcp wiring failed: {exc}")
 
     # ── Public API ───────────────────────────────────────────────────────
 
@@ -1084,7 +1138,7 @@ class LocalCodeToolkit:
         compact: only core tools
         minimal: ultra-short descriptions for small models (saves ~500 tokens)
         """
-        # self.ensure_mcp_tools() removed during T0.9 purge
+        self.ensure_mcp_tools()
         if compact:
             tools = [tool for tool in self.tools.values() if tool.name in self.CORE_TOOLS]
         else:
@@ -1117,7 +1171,7 @@ class LocalCodeToolkit:
         }
 
     def list_tool_names(self) -> list[str]:
-        # self.ensure_mcp_tools() removed during T0.9 purge
+        self.ensure_mcp_tools()
         return sorted(self.tools.keys())
 
     def summarize_tool_calls(self, tool_calls: list[dict[str, Any]]) -> list[str]:
@@ -1145,7 +1199,7 @@ class LocalCodeToolkit:
     def execute_tool_calls(self, tool_calls: list[dict[str, Any]]) -> list[dict[str, str]]:
         """Execute tool calls — read-only tools run concurrently, writes run serially."""
         from concurrent.futures import ThreadPoolExecutor, as_completed
-        # self.ensure_mcp_tools() removed during T0.9 purge
+        self.ensure_mcp_tools()
 
         if len(tool_calls) <= 1:
             return self._execute_serial(tool_calls)

localcode/tui/screens/chat.py

@@ -636,6 +636,7 @@ _SLASH_COMMANDS = [
     ("/status", "Show runtime: server health, current model, perf config"),
     ("/restart", "Restart the model server (use when /status shows 'unreachable')"),
     ("/mcp", "List or reload MCP servers from ~/.localcode/mcp.json"),
+    ("/skills", "List loaded skills and where they're from"),
     ("/model", "List available models / switch (e.g. /model qwen)"),
     ("/thinking", "Show / set hidden reasoning policy (off|auto)"),
     ("/sounds", "Toggle completion + approval notification sounds"),
@@ -1933,6 +1934,8 @@ class ChatScreen(Screen):
             self._restart_for_vision_change(reason="Server restarted")
         elif text == "/mcp" or text.startswith("/mcp "):
             self._handle_mcp_command(text)
+        elif text == "/skills":
+            self._handle_skills_command(text)
         elif text == "/voice" or text.startswith("/voice "):
             self._handle_voice_command(text)
         elif text == "/audio" or text.startswith("/audio "):
@@ -2223,6 +2226,30 @@ class ChatScreen(Screen):
         except Exception:
             pass
 
+    def _handle_skills_command(self, text: str) -> None:
+        """List the skills the agent can use, grouped by origin, with token cost.
+
+        Skills are auto-discovered markdown files (frontmatter + body). Add one
+        by dropping a `.md` into ~/.localcode/skills/ (global) or
+        ./.localcode/skills/ (project); user/project override bundled by name.
+        """
+        from pathlib import Path as _Path
+        from ...skills import load_registry
+        log = self.query_one("#chat-log", ChatLog)
+        reg = load_registry(_Path.cwd())
+        skills = sorted(reg.skills.values(), key=lambda s: (s.origin, s.name))
+        if not skills:
+            log.append_info(
+                "No skills loaded. Drop a .md with `name:`/`description:` frontmatter "
+                "into ~/.localcode/skills/ (global) or ./.localcode/skills/ (project)."
+            )
+            return
+        log.append_info(f"{len(skills)} skill(s) loaded (auto-activated or via the skill tool):")
+        for s in skills:
+            tokens = max(1, (len(s.body) + len(s.description)) // 4)
+            where = "(bundled)" if s.origin == "bundled" else str(s.source_path)
+            log.append_info(f"  {s.name}  ·  {s.origin}  ·  ~{tokens} tok  ·  {where}")
+
     def _handle_mcp_command(self, text: str) -> None:
         """List + reload MCP servers configured in ~/.localcode/mcp.json.
 

{localcode-0.2.16.dist-info → localcode-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: localcode
-Version: 0.2.16
+Version: 0.3.0
 Summary: High-performance AI coding on consumer hardware.
 Author: LocalCode contributors
 License-Expression: Apache-2.0
@@ -15,14 +15,13 @@ Classifier: Intended Audience :: Developers
 Classifier: Operating System :: MacOS
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development
 Classifier: Topic :: Software Development :: Code Generators
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: certifi>=2024.0.0
@@ -31,6 +30,7 @@ Requires-Dist: hf_xet>=1.1.0
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: huggingface_hub>=1.0.0
 Requires-Dist: jedi>=0.19.0
+Requires-Dist: mcp>=1.28.0
 Requires-Dist: prompt_toolkit>=3.0.52
 Requires-Dist: rich>=13.7.1
 Requires-Dist: scikit-learn>=1.3.0
@@ -54,7 +54,7 @@ Dynamic: license-file
 <p align="center">
   <img src="https://img.shields.io/pypi/v/localcode?style=flat-square&color=7c4dff" alt="PyPI">
   <img src="https://img.shields.io/badge/license-Apache_2.0-4caf50?style=flat-square" alt="License">
-  <img src="https://img.shields.io/badge/python-3.9+-3776ab?style=flat-square" alt="Python">
+  <img src="https://img.shields.io/badge/python-3.10+-3776ab?style=flat-square" alt="Python">
   <img src="https://img.shields.io/badge/platform-Apple%20Silicon-999999?style=flat-square" alt="Platform">
 </p>
 
@@ -108,7 +108,7 @@ We are building for a world of truly democratized AI — where everyone has acce
 
 - **Mac with Apple Silicon**
 - **16 GB RAM** minimum
-- **Python 3.9+**
+- **Python 3.10+**
 - **~12 GB free disk** (10 GB model + server)
 
 ### Tested hardware

{localcode-0.2.16.dist-info → localcode-0.3.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-localcode/__init__.py,sha256=SRPX8BmTXMUfGe0MxaIfwl6B0h5Hm73gVI0sJvHjKpg,50
+localcode/__init__.py,sha256=9IFfTvFMTu1mt_TdJvM_vZAmNF_poHZSvDz-APZippc,49
 localcode/__main__.py,sha256=_4Tblte9F1KOpB-oGBQuTlaSN-IncLmhihqhBkpH3pU,69
 localcode/_subproc_env.py,sha256=eltq_kKvqGj22pIFivB5BZft9-s5fziBW0lsV9FhEV4,2383
 localcode/app.py,sha256=-zkxi06XeYno_y-N1DimFssqD6LnV8n_pbP0iB6odLg,90616
@@ -30,7 +30,6 @@ localcode/injection_defense.py,sha256=sggmoowHEAKYV3v-1PTWtv8KjekEL0kZ0-O03hb3Dm
 localcode/launcher.py,sha256=uDsIy66q-VexbvdIb7iwzYwDmmYhWRP10SNX4GiEWQ4,11462
 localcode/logging_utils.py,sha256=mFn_LO26IkT7OLxKs1ke4mND8BJeDLf-UULCYSSxyz0,920
 localcode/lsp.py,sha256=WTtdbdgforZdWMRqlzCQp2ndkKRbfIE1f5GfGeRH1xU,5939
-localcode/mcp.py,sha256=PeYUPG4ImYqir5eod9s6sHoiMdBl0_CTzo8ssYrclhE,8376
 localcode/memory_guard.py,sha256=Y4wUlPdV4zRzwkNmPVbCJCIBf40j_OrQ0rc7xGXGoNs,8815
 localcode/model_config.py,sha256=4iPw5M6tnjMvdILtWlRkOdE6QMFRJCAIYBmadc82ZjQ,14261
 localcode/model_families.py,sha256=mEBIoEMe-qL93Twxm-4mYv76dWEkKVp5CiQlY43mkWA,11203
@@ -61,7 +60,7 @@ localcode/thermal.py,sha256=q2A-HlIs-Uaqpf6bUswE2q9qbvdZCMKe6b9Fg--yHV4,6229
 localcode/thinking.py,sha256=Cv2vPMO94hIAtPO8DtvPiGlymrtG2wROBMDZoTLrBPc,2025
 localcode/tool_parsing.py,sha256=3jXSWvhXF6k1eau2o8RA0-zp0tfNb0VM0GkuwUGN57w,13565
 localcode/tool_router.py,sha256=bmCwTAhFqo8oadJZ-FDSTdEvfwu3fHok8qVOBbxnQG4,9832
-localcode/toolkit.py,sha256=MlhAGgSYVe0oMgWxIKUTlCDa1QbfeXClZFDVxgRXiFI,55467
+localcode/toolkit.py,sha256=PEToa9AUjp4D1xcdSBk9DT-0bU0zGigKhBR6aiwf4OA,57843
 localcode/turn_diff.py,sha256=ls5soQdYthLaep3eP20Xc5giFAlAx0ObVAzz7egy6Jk,6101
 localcode/undo.py,sha256=jAVtelQM2MiWQjS0Q86BtuQHDR1FYMB976dzxlCNGic,3956
 localcode/verification.py,sha256=UExbGJSB0Ts_PB68yrrqpBAE84rfHfjPAgkELBDGdDs,3010
@@ -84,6 +83,11 @@ localcode/agent/tool_orchestration.py,sha256=QRK7U7lSrmWJ578dG44tq9b6DWdFI8Khpw0
 localcode/agent/turn_finalization.py,sha256=n5h0aA_EPDS8ZY6TBvbUo7qu2IkgEwnwcO0PKBd6930,4884
 localcode/bin/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 localcode/bin/llama-server,sha256=-_OT5uZUVhpaxSLsIkmfmyF88rvsu8ue1K8VaegNHW0,16378096
+localcode/mcp/__init__.py,sha256=R3R0Grp25Xkwakyo23WPQ3mOXsWiSDh-KfUoS4Ws4XQ,2854
+localcode/mcp/_bridge.py,sha256=s0GuyyWzO1IUfMCu6A9J7yRYXyYYnLLb7fAdu2PyxJk,2175
+localcode/mcp/_config.py,sha256=8Al3ZoVnZTfO9jbVOueauywbZ8OCUW68PIEDemTJgqk,905
+localcode/mcp/_transports.py,sha256=_6qLkpJpxQcqXwgM2Q_-cZAWaHLIGPI2MbuGPSa3DOU,4765
+localcode/mcp/client.py,sha256=qOi19h7l5hN9Am6YvFNBZgdYD6KZ-rgJ7lNS5ZJAYp0,12147
 localcode/skills/debug.md,sha256=ENVZR8Do3H8Xe0dqhxCAgnprQNGsV0BOtoqiIry9cSE,1287
 localcode/skills/edit-verified.md,sha256=Jy4lOk7sDb16YzHcM1HMc2ejmo-KsSrvfvKAxz712Kk,1755
 localcode/skills/explain.md,sha256=NJpu_bht2UH6Sa3AMlhsKLlSiHfOn0WNARolcelQXe4,906
@@ -115,7 +119,7 @@ localcode/tui/__init__.py,sha256=Yfy9bvw3l1iY4FDhRX8qZVgnZLuYiq8lc9SDYl4cWwc,61
 localcode/tui/app.py,sha256=8LJkCjpUZQuCwNXtXBhoGJ2lMTl4MDl48japyDTJtMI,19317
 localcode/tui/bridge.py,sha256=urPPCqC_nisAYawWk3juvMI8IaoJfv4g7USpGOZOqQc,2803
 localcode/tui/screens/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-localcode/tui/screens/chat.py,sha256=QxvJJmrZu5iy-VSnx6NPp-Wg1ZrQ3DfO2bhrGo6GfoU,180759
+localcode/tui/screens/chat.py,sha256=831h6IDZPFUWzoLigxaIihnxmJ4bdEgbwRs9wHE6ZVQ,182159
 localcode/tui/screens/mode_picker.py,sha256=cK_xNo7ytOwJXJwzUevMTcb5dwQKtjMfh60of-ntRz4,2347
 localcode/tui/screens/model_picker.py,sha256=pH5C4_ecxm3wPPydgMabgOhmn3DgffUMHiPuriCFsMk,35861
 localcode/tui/screens/setup.py,sha256=eyV2WsddXy12pBsp6t-2hKtXxHL1BitCPWPnbSKR2Ks,42478
@@ -127,9 +131,9 @@ localcode/tui/widgets/chat_log.py,sha256=T80JeW9257tTqNPRRhvfMLrVriDEgeB9URNCsUC
 localcode/tui/widgets/voice_visualizer.py,sha256=zOhrIxaMcg-F2Y8LvHJTddq227phmiTjtEyRbkx1XxU,4709
 localcode/tui/widgets/messages/__init__.py,sha256=952AZ1qVMGUIqPIry7mwxnYbMkgPlcY5FAwZtEa5YPg,967
 localcode/tui/widgets/messages/diff.py,sha256=fF7GMDSrJtVEzw1FfqlNMlg51MzOi4DwWIe9Oz6Bu6Y,8457
-localcode-0.2.16.dist-info/licenses/LICENSE,sha256=Ahg0cteZ-6bIRB7KC15WEtdqWnzy8HY_yzsZBoVRql0,11294
-localcode-0.2.16.dist-info/METADATA,sha256=ljbgm7Jv0Cei_481MlRsBgIGAV8dED3OicbjWaDLexY,7834
-localcode-0.2.16.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-localcode-0.2.16.dist-info/entry_points.txt,sha256=rE7elTGUvMsBd-Quy22cuTVJ-zGVOmx0nEuC6ni9Tg4,87
-localcode-0.2.16.dist-info/top_level.txt,sha256=58eL3Rw8v0OGmYNxjx8uS4ERWatrzUbyCL5inlukkTo,10
-localcode-0.2.16.dist-info/RECORD,,
+localcode-0.3.0.dist-info/licenses/LICENSE,sha256=Ahg0cteZ-6bIRB7KC15WEtdqWnzy8HY_yzsZBoVRql0,11294
+localcode-0.3.0.dist-info/METADATA,sha256=SlZVGa5UtcFRpKq9hmOo1Ql1aJHWYaA_GrhMGiv2gDc,7813
+localcode-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+localcode-0.3.0.dist-info/entry_points.txt,sha256=rE7elTGUvMsBd-Quy22cuTVJ-zGVOmx0nEuC6ni9Tg4,87
+localcode-0.3.0.dist-info/top_level.txt,sha256=58eL3Rw8v0OGmYNxjx8uS4ERWatrzUbyCL5inlukkTo,10
+localcode-0.3.0.dist-info/RECORD,,

localcode/mcp.py

@@ -1,242 +0,0 @@
-"""MCP (Model Context Protocol) client + tool-registration.
-
-Lets a user add MCP servers to LocalCode in `~/.localcode/mcp.json`.
-Each server's tools get auto-registered with the agent so the model
-can call them like any other tool.
-
-Config shape (standard MCP server convention):
-
-    {
-      "mcpServers": {
-        "filesystem": {
-          "command": "npx",
-          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me"],
-          "env": {}
-        },
-        "github": {
-          "command": "uvx",
-          "args": ["mcp-server-github"],
-          "env": {"GITHUB_TOKEN": "ghp_..."}
-        }
-      }
-    }
-
-For each server, we spawn the subprocess once at startup, speak the
-MCP JSON-RPC protocol over its stdin/stdout, and expose each declared
-tool as `mcp_<server>_<tool>` in the agent's tool list.
-
-This is a minimal viable client — covers `initialize`, `tools/list`,
-and `tools/call`. No prompts, resources, sampling, or notifications.
-Good enough for the common "let the agent use my filesystem MCP" case.
-"""
-from __future__ import annotations
-
-import json
-import os
-import subprocess
-import threading
-from pathlib import Path
-from typing import Any
-
-
-MCP_CONFIG_PATH = Path.home() / ".localcode" / "mcp.json"
-
-
-class MCPClient:
-    """One stdio-spoken MCP server connection."""
-
-    def __init__(self, name: str, command: str, args: list[str], env: dict[str, str] | None = None):
-        self.name = name
-        self._proc: subprocess.Popen | None = None
-        self._req_id = 0
-        self._lock = threading.Lock()
-        self._initialized = False
-        full_env = os.environ.copy()
-        if env:
-            full_env.update(env)
-        try:
-            self._proc = subprocess.Popen(
-                [command, *args],
-                stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
-                text=True, bufsize=1, env=full_env,
-            )
-        except FileNotFoundError as e:
-            raise RuntimeError(f"MCP server {name!r} command not found: {command}") from e
-
-    def _next_id(self) -> int:
-        with self._lock:
-            self._req_id += 1
-            return self._req_id
-
-    def _send(self, method: str, params: dict | None = None) -> dict:
-        if self._proc is None or self._proc.poll() is not None:
-            raise RuntimeError(f"MCP server {self.name!r} is not running")
-        req = {
-            "jsonrpc": "2.0",
-            "id": self._next_id(),
-            "method": method,
-            "params": params or {},
-        }
-        with self._lock:
-            self._proc.stdin.write(json.dumps(req) + "\n")
-            self._proc.stdin.flush()
-            # Read one line of JSON-RPC response. MCP servers may emit
-            # notifications (no id) — skip those and keep reading.
-            for _ in range(50):
-                line = self._proc.stdout.readline()
-                if not line:
-                    raise RuntimeError(f"MCP server {self.name!r} closed stdout")
-                try:
-                    msg = json.loads(line)
-                except json.JSONDecodeError:
-                    continue
-                if "id" not in msg:
-                    continue  # notification, not our response
-                if msg.get("id") == req["id"]:
-                    if "error" in msg:
-                        raise RuntimeError(f"MCP {self.name}.{method}: {msg['error']}")
-                    return msg.get("result", {})
-            raise RuntimeError(f"MCP server {self.name!r} response timeout")
-
-    def initialize(self) -> None:
-        if self._initialized:
-            return
-        self._send("initialize", {
-            "protocolVersion": "2024-11-05",
-            "capabilities": {},
-            "clientInfo": {"name": "localcode", "version": "0.2"},
-        })
-        self._initialized = True
-
-    def list_tools(self) -> list[dict]:
-        """Return the list of tools the server exposes — each has a
-        `name`, `description`, and `inputSchema` (JSONSchema)."""
-        self.initialize()
-        result = self._send("tools/list")
-        return result.get("tools", [])
-
-    def call_tool(self, name: str, arguments: dict) -> str:
-        """Invoke a tool by name with JSON-encoded arguments. Returns
-        the text content of the response."""
-        self.initialize()
-        result = self._send("tools/call", {"name": name, "arguments": arguments})
-        content = result.get("content", [])
-        # MCP spec: content is a list of {type, text|data|...} blocks.
-        # We concatenate text blocks; ignore image/blob for now.
-        out = []
-        for block in content:
-            if isinstance(block, dict) and block.get("type") == "text":
-                out.append(block.get("text", ""))
-        return "\n".join(out) or "(MCP tool returned no text content)"
-
-    def close(self) -> None:
-        if self._proc is not None and self._proc.poll() is None:
-            try:
-                self._proc.terminate()
-                self._proc.wait(timeout=2)
-            except Exception:
-                try:
-                    self._proc.kill()
-                except Exception:
-                    pass
-
-
-# Process-wide registry of connected MCP clients (name → MCPClient).
-_clients: dict[str, MCPClient] = {}
-
-
-def load_mcp_config() -> dict[str, dict]:
-    """Read ~/.localcode/mcp.json. Returns the `mcpServers` dict."""
-    if not MCP_CONFIG_PATH.is_file():
-        return {}
-    try:
-        return json.loads(MCP_CONFIG_PATH.read_text()).get("mcpServers", {})
-    except Exception:
-        return {}
-
-
-def connect_all() -> tuple[int, list[str]]:
-    """Spawn every configured MCP server. Returns (count_ok, errors)."""
-    errors: list[str] = []
-    config = load_mcp_config()
-    for name, server_cfg in config.items():
-        if name in _clients:
-            continue  # already connected
-        try:
-            cli = MCPClient(
-                name=name,
-                command=server_cfg.get("command", ""),
-                args=server_cfg.get("args", []) or [],
-                env=server_cfg.get("env", {}) or {},
-            )
-            cli.initialize()
-            _clients[name] = cli
-        except Exception as e:
-            errors.append(f"{name}: {e}")
-    return len(_clients), errors
-
-
-def list_connected() -> list[tuple[str, list[dict]]]:
-    """Return [(server_name, [tools])] for every connected MCP server."""
-    out = []
-    for name, cli in _clients.items():
-        try:
-            out.append((name, cli.list_tools()))
-        except Exception:
-            out.append((name, []))
-    return out
-
-
-def call(server: str, tool_name: str, arguments: dict) -> str:
-    cli = _clients.get(server)
-    if cli is None:
-        return f"REJECTED: MCP server {server!r} is not connected."
-    try:
-        return cli.call_tool(tool_name, arguments)
-    except Exception as e:
-        return f"MCP call {server}.{tool_name} failed: {e}"
-
-
-def shutdown_all() -> None:
-    """Tear down all MCP subprocesses on app exit."""
-    for cli in _clients.values():
-        try:
-            cli.close()
-        except Exception:
-            pass
-    _clients.clear()
-
-
-def mcp_tool_schemas() -> list[dict]:
-    """Return OpenAI-style tool schemas for every connected MCP
-    server's tools. Each tool is renamed `mcp_<server>_<tool>` so
-    multiple servers can expose tools with the same name without
-    collision."""
-    schemas = []
-    for server, tools in list_connected():
-        for t in tools:
-            name = f"mcp_{server}_{t.get('name', '')}"
-            schemas.append({
-                "type": "function",
-                "function": {
-                    "name": name,
-                    "description": (
-                        f"[MCP {server}] " + (t.get("description") or "")
-                    )[:1000],
-                    "parameters": t.get("inputSchema", {"type": "object"}),
-                },
-            })
-    return schemas
-
-
-def dispatch_mcp_tool(name: str, arguments: dict) -> str | None:
-    """If `name` is `mcp_<server>_<tool>`, dispatch to that server.
-    Returns None if not an MCP tool (so caller falls through to
-    normal tool dispatch)."""
-    if not name.startswith("mcp_"):
-        return None
-    rest = name[len("mcp_"):]
-    if "_" not in rest:
-        return None
-    server, tool = rest.split("_", 1)
-    return call(server, tool, arguments)