localcode 0.2.16__tar.gz → 0.3.0__tar.gz

{localcode-0.2.16/src/localcode.egg-info → localcode-0.3.0}/PKG-INFO

@@ -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 → localcode-0.3.0}/README.md

@@ -9,7 +9,7 @@
 <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>
 
@@ -63,7 +63,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 → localcode-0.3.0}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "localcode"
-version = "0.2.16"
+version = "0.3.0"
 description = "High-performance AI coding on consumer hardware."
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 license = "Apache-2.0"
 license-files = ["LICENSE"]
 authors = [
@@ -21,7 +21,6 @@ classifiers = [
   "Operating System :: MacOS",
   "Operating System :: POSIX :: Linux",
   "Programming Language :: Python :: 3",
-  "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
@@ -36,6 +35,7 @@ dependencies = [
   "httpx>=0.27.0",
   "huggingface_hub>=1.0.0",   # used as the fast path for GGUF downloads
   "jedi>=0.19.0",
+  "mcp>=1.28.0",              # official Model Context Protocol SDK (stdio/HTTP/SSE + OAuth)
   "prompt_toolkit>=3.0.52",
   "rich>=13.7.1",
   "scikit-learn>=1.3.0",

{localcode-0.2.16 → localcode-0.3.0}/src/localcode/__init__.py

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

localcode-0.3.0/src/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-0.3.0/src/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-0.3.0/src/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-0.3.0/src/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')"
+    )