localcode 0.2.15__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: localcode
-Version: 0.2.15
+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.11+-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.11+**
+- **Python 3.10+**
 - **~12 GB free disk** (10 GB model + server)
 
 ### Tested hardware
@@ -122,18 +122,35 @@ LocalCode is early software. Hardware support is expected to broaden, but only t
 | M4 Apple Silicon | 24 GB+ | Not yet tested | Expected to support larger contexts, but needs validation |
 | Intel Mac | Any | Not supported | LocalCode targets Apple Silicon |
 
+## Models
+
+On launch, LocalCode recommends the best model for **your Mac's RAM** — there's no fixed default. You can pick any of these (or a different quant) in the model picker.
+
+| Model | Size (quant) | Active params | Min RAM | Architecture |
+| --- | ---: | --- | ---: | --- |
+| Gemma 4 12B | 7.4 GB (Q4) | 12B (dense) | 16 GB | gemma4-iswa |
+| Gemma 4 26B-A4B | 11.2 GB (Q3) | 3.8B (8/128 experts) | 24 GB | gemma4-iswa |
+| Qwen 3.6 35B-A3B | 10.7 GB (Q2) | 3.0B (8+1/256) | 24 GB | qwen35moe |
+| DiffusionGemma 26B-A4B † | 15.7 GB (Q4) | 4B (diffusion MoE) | 32 GB | diffusion_gemma |
+| North-Mini-Code 30B-A3B † | 17.9 GB (Q4) | 3B (30B MoE) | 36 GB | cohere2_moe |
+| Gemma 4 12B (full) | 23.8 GB (BF16) | 12B (dense) | 48 GB | gemma4-iswa |
+| Gemma 4 26B-A4B | 28 GB (Q8) | 3.8B (8/128 experts) | 64 GB | gemma4-iswa |
+| Qwen 3.6 35B-A3B | 38.5 GB (Q8) | 3.0B (8+1/256) | 96 GB | qwen35moe |
+
+*Min RAM* is the threshold for auto-recommendation (weights ≤ ~55% of unified memory, leaving room for KV cache + OS); you can still pick a heavier model manually. **†** experimental — pickable but **not** auto-recommended (DiffusionGemma needs a separate runner; `cohere2_moe` is unvalidated on this stack).
+
 ## How LocalCode works
 
 LocalCode runs a custom [llama.cpp](https://github.com/ggerganov/llama.cpp) fork with **TurboQuant KV cache compression** — a technique from Google's ICLR 2026 paper that we patched into llama.cpp for Apple Silicon. This compresses the KV cache 3.8× — fitting 32K context in 355 MiB on a 16 GB MacBook.
 
-The default model (**Gemma 4 26B-A4B**) is a Mixture-of-Experts architecture — 25.2 B total parameters but only 3.8 B active per token. That's what makes ~27 tok/s possible on a laptop.
+LocalCode picks a model based on **your Mac's RAM** — there's no fixed default. It scales from Gemma 4 12B on 16 GB up to Qwen 3.6 35B-A3B on 64 GB+. The recommended models are Mixture-of-Experts — only ~3.8 B parameters active per token — which is what makes ~27 tok/s possible on a laptop.
 
 Under the hood:
 
 - **TurboQuant KV cache** — asymmetric q8\_0-K + turbo4-V quantization, 3.8× compression vs. f16
 - **Multi-region mmap patch** — fixes a Metal OOM crash where llama.cpp's loader spanned the entire GGUF file into one Metal buffer
 - **GPU memory unlock** — auto-prompts to raise `iogpu.wired_limit_mb` for full Metal offload
-- **Agent loop** — phased CREATE/EDIT/CHAT/RUN/SEARCH routing with task state, evidence-driven completion, and recovery modes for small-model failure patterns
+- **Agent loop** — goal-typed routing (build / edit / run / chat) with task state, evidence-driven completion, and recovery modes for small-model failure patterns
 
 ## Sponsors
 

{localcode-0.2.15 → 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.11+-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.11+**
+- **Python 3.10+**
 - **~12 GB free disk** (10 GB model + server)
 
 ### Tested hardware
@@ -77,18 +77,35 @@ LocalCode is early software. Hardware support is expected to broaden, but only t
 | M4 Apple Silicon | 24 GB+ | Not yet tested | Expected to support larger contexts, but needs validation |
 | Intel Mac | Any | Not supported | LocalCode targets Apple Silicon |
 
+## Models
+
+On launch, LocalCode recommends the best model for **your Mac's RAM** — there's no fixed default. You can pick any of these (or a different quant) in the model picker.
+
+| Model | Size (quant) | Active params | Min RAM | Architecture |
+| --- | ---: | --- | ---: | --- |
+| Gemma 4 12B | 7.4 GB (Q4) | 12B (dense) | 16 GB | gemma4-iswa |
+| Gemma 4 26B-A4B | 11.2 GB (Q3) | 3.8B (8/128 experts) | 24 GB | gemma4-iswa |
+| Qwen 3.6 35B-A3B | 10.7 GB (Q2) | 3.0B (8+1/256) | 24 GB | qwen35moe |
+| DiffusionGemma 26B-A4B † | 15.7 GB (Q4) | 4B (diffusion MoE) | 32 GB | diffusion_gemma |
+| North-Mini-Code 30B-A3B † | 17.9 GB (Q4) | 3B (30B MoE) | 36 GB | cohere2_moe |
+| Gemma 4 12B (full) | 23.8 GB (BF16) | 12B (dense) | 48 GB | gemma4-iswa |
+| Gemma 4 26B-A4B | 28 GB (Q8) | 3.8B (8/128 experts) | 64 GB | gemma4-iswa |
+| Qwen 3.6 35B-A3B | 38.5 GB (Q8) | 3.0B (8+1/256) | 96 GB | qwen35moe |
+
+*Min RAM* is the threshold for auto-recommendation (weights ≤ ~55% of unified memory, leaving room for KV cache + OS); you can still pick a heavier model manually. **†** experimental — pickable but **not** auto-recommended (DiffusionGemma needs a separate runner; `cohere2_moe` is unvalidated on this stack).
+
 ## How LocalCode works
 
 LocalCode runs a custom [llama.cpp](https://github.com/ggerganov/llama.cpp) fork with **TurboQuant KV cache compression** — a technique from Google's ICLR 2026 paper that we patched into llama.cpp for Apple Silicon. This compresses the KV cache 3.8× — fitting 32K context in 355 MiB on a 16 GB MacBook.
 
-The default model (**Gemma 4 26B-A4B**) is a Mixture-of-Experts architecture — 25.2 B total parameters but only 3.8 B active per token. That's what makes ~27 tok/s possible on a laptop.
+LocalCode picks a model based on **your Mac's RAM** — there's no fixed default. It scales from Gemma 4 12B on 16 GB up to Qwen 3.6 35B-A3B on 64 GB+. The recommended models are Mixture-of-Experts — only ~3.8 B parameters active per token — which is what makes ~27 tok/s possible on a laptop.
 
 Under the hood:
 
 - **TurboQuant KV cache** — asymmetric q8\_0-K + turbo4-V quantization, 3.8× compression vs. f16
 - **Multi-region mmap patch** — fixes a Metal OOM crash where llama.cpp's loader spanned the entire GGUF file into one Metal buffer
 - **GPU memory unlock** — auto-prompts to raise `iogpu.wired_limit_mb` for full Metal offload
-- **Agent loop** — phased CREATE/EDIT/CHAT/RUN/SEARCH routing with task state, evidence-driven completion, and recovery modes for small-model failure patterns
+- **Agent loop** — goal-typed routing (build / edit / run / chat) with task state, evidence-driven completion, and recovery modes for small-model failure patterns
 
 ## Sponsors
 

{localcode-0.2.15 → localcode-0.3.0}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "localcode"
-version = "0.2.15"
+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.15 → localcode-0.3.0}/src/localcode/__init__.py

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

{localcode-0.2.15 → localcode-0.3.0}/src/localcode/agent/__init__.py

@@ -16,7 +16,7 @@ re-exported here so external callers can continue to import from
 Background: before T0.1, agent.py was a 1792-line monolith. The split
 broke it into focused modules (each ≤ ~720 LoC), with __init__.py
 reduced to this re-export surface — well under the 400-LoC cap the
-plan sets for god modules (see eval/OPTIMIZATION_PLAN.md § T0).
+plan sets for god modules (see dev/eval/OPTIMIZATION_PLAN.md § T0).
 
 Unused-import warnings in this file are expected — every imported
 name is intentionally re-exported. The `# noqa: F401` comments
@@ -140,7 +140,7 @@ from .helpers import (  # noqa: F401
 
 # ── Prompt templates + project-instructions loader ────────────────────────
 # Moved to agent/prompts.py during the T0.1-b split. Re-exported here so
-# external callers (eval/prompt_variants.py, tests/promptfoo, app.py,
+# external callers (dev/eval/prompt_variants.py, tests/promptfoo, app.py,
 # tests/test_context_pipeline_e2e.py) that do
 #   `from localcode.agent import SYSTEM_PROMPT`
 # keep working unchanged. See agent/prompts.py for the commented
@@ -160,7 +160,6 @@ from .prompts import (  # noqa: F401 — re-exports for back-compat
 # and the dispatcher (for _execute_tool). Plan-mode gating still lives
 # here because it's cross-tool policy, not tool-specific logic.
 
-from ..tools import ALL_SCHEMAS as TOOL_SCHEMAS  # for agent-loop tool registry injection
 
 
 # ── Result Management ────────────────────────────────────────────────────

{localcode-0.2.15 → localcode-0.3.0}/src/localcode/agent/helpers.py

@@ -53,16 +53,6 @@ __all__: list[str] = []
 _SHRINK_GUARD_SOURCE_EXTS = {".py", ".js", ".jsx", ".ts", ".tsx", ".css", ".html"}
 
 
-def _canonical_creation_root(app: "LocalCodeApp") -> Path | None:
-    task = getattr(getattr(app, "session", None), "current_task", None)
-    if getattr(task, "task_kind", "") != "new_app":
-        return None
-    slug = str(getattr(task, "task_slug", "") or "").strip()
-    if not slug:
-        return None
-    return (app.repo_root / slug).resolve()
-
-
 def _path_within(path: Path, root: Path) -> bool:
     try:
         path.resolve().relative_to(root)

{localcode-0.2.15 → localcode-0.3.0}/src/localcode/agent/sections.py

@@ -14,14 +14,14 @@ Problems with the monolith:
     session, which means every new session re-evaluates the whole
     prompt. Our benchmark shows prompt_ms of ~48 ms warm; the
     theoretical floor with a stable prefix cache is ~5-10 ms.
-  • No way to A/B sections individually. `eval/prompt_variants.py`
+  • No way to A/B sections individually. `dev/eval/prompt_variants.py`
     only supports coarse "strip rule N" mutations. You can't
     answer "what if we drop the build-app rules for debugging
     tasks?" because there's no boundary between them.
   • No way to gate sections on trigger phrases. Every session ships
     rule 10 (open browser) whether or not a web app is in scope.
 
-This module is **Phase 1** of T0.11 (see eval/OPTIMIZATION_PLAN.md):
+This module is **Phase 1** of T0.11 (see dev/eval/OPTIMIZATION_PLAN.md):
 introduce the section-registry concept with behaviour-neutral
 defaults. The composer produces the same output as the old
 `SYSTEM_PROMPT.format(...)` for the default all-sections-on case.
@@ -55,11 +55,9 @@ work is an add-only operation.
 from __future__ import annotations
 
 from dataclasses import dataclass
-from pathlib import Path
 from typing import Callable
 
 from .prompts import SYSTEM_PROMPT
-from .prompts import _load_project_instructions
 
 
 __all__ = [
@@ -241,10 +239,3 @@ def compose_system_prompt(
         parts.insert(-1, CACHE_BOUNDARY_MARKER)
 
     return "".join(parts)
-
-
-def load_project_instructions(repo_root: Path) -> str:
-    """Convenience re-export so callers outside agent/ that don't
-    want to depend on `agent.prompts` internals can build a
-    SectionContext purely from this module."""
-    return _load_project_instructions(repo_root)

{localcode-0.2.15 → localcode-0.3.0}/src/localcode/app.py

@@ -4,7 +4,6 @@ from concurrent.futures import ThreadPoolExecutor, as_completed
 from dataclasses import replace
 import logging
 from pathlib import Path
-import re
 
 from rich.console import Console
 from rich.panel import Panel
@@ -41,7 +40,7 @@ from .autonomy import AutonomyLevel, apply_autonomy_to_permissions, get_policy
 from .hooks import HookRunner
 from .snapshots import SnapshotStore, create_snapshot
 from .turn_diff import TurnDiffTracker, print_turn_diff
-from .agent.goal import GoalState, infer_goal_state
+from .agent.goal import infer_goal_state
 from .performance import detect_machine_profile, benchmark_report, apply_preset, should_promote_legacy_default_to_laptop_26b
 
 
@@ -62,67 +61,6 @@ _FOLLOWUP_CHAT_ONLY = {
 _CODING_TASK_KINDS = {"new_app", "existing_app_edit", "run_or_launch"}
 
 
-def _looks_like_task_followup(user_text: str, current_task: object | None) -> bool:
-    """Return true when a short correction should continue the task.
-
-    This is deliberately conservative: it only attaches to a coding task
-    and only for short correction/addition wording. The actual feature
-    remains model/tool-driven; LocalCode does not classify domain terms.
-    """
-    if current_task is None:
-        return False
-    if getattr(current_task, "task_kind", "") not in _CODING_TASK_KINDS:
-        return False
-    text = (user_text or "").strip().lower()
-    if not text:
-        return False
-    first = next(iter(re.findall(r"[a-z0-9]+", text)), "")
-    if text in _FOLLOWUP_CHAT_ONLY:
-        return False
-    if len(text) <= 80 and "?" not in text and first not in {"what", "why", "how", "where", "when", "who"}:
-        return True
-    return any(
-        phrase in text
-        for phrase in (
-            "i meant",
-            "you forgot",
-            "missing",
-            "add ",
-            "also add",
-            "it should",
-            "should have",
-            "doesn't have",
-            "didn't add",
-        )
-    )
-
-
-def _continue_goal_for_task_followup(goal_state: GoalState, user_text: str, current_task: object) -> GoalState:
-    criteria = list(getattr(current_task, "success_criteria", []) or goal_state.success_criteria)
-    criteria.extend([
-        "Follow-up correction is implemented in the existing task context",
-        "Assistant does not stop with a permission question when the requested implementation is local and feasible",
-    ])
-    current_kind = getattr(current_task, "task_kind", goal_state.task_kind)
-    if current_kind in {"new_app", "existing_app_edit"}:
-        goal_type = "edit_existing"
-        task_kind = "existing_app_edit"
-    else:
-        goal_type = getattr(current_task, "goal_type", goal_state.goal_type)
-        task_kind = current_kind
-    # Preserve task identity; this turn is a correction on existing work,
-    # not a fresh task name.
-    return replace(
-        goal_state,
-        goal_type=goal_type,
-        task_kind=task_kind,
-        task_slug=getattr(current_task, "task_slug", goal_state.task_slug),
-        goal_summary=f"{getattr(current_task, 'goal_summary', '')}\nFollow-up: {user_text}".strip()[:240],
-        success_criteria=tuple(dict.fromkeys(criteria)),
-        allows_blocking_question=False,
-    )
-
-
 def _canonical_project_dir_has_files(repo_root: Path, slug: str) -> bool:
     """True when a creation task's canonical project directory already exists.
 

{localcode-0.2.15 → localcode-0.3.0}/src/localcode/autonomy.py

@@ -101,18 +101,3 @@ def apply_autonomy_to_permissions(permissions, policy: AutonomyPolicy) -> None:
 
     if policy.level == AutonomyLevel.FULL_AUTO:
         permissions.approve_all()
-
-
-def format_autonomy_status(level: AutonomyLevel) -> str:
-    """Format current autonomy level for display."""
-    policy = POLICIES[level]
-    icons = {True: "✓", False: "✗"}
-    return (
-        f"Autonomy: {level.value}\n"
-        f"  {policy.description}\n"
-        f"  reads:    {icons[policy.auto_approve_reads]}\n"
-        f"  writes:   {icons[policy.auto_approve_writes]}\n"
-        f"  bash:     {icons[policy.auto_approve_bash]}\n"
-        f"  installs: {icons[policy.auto_approve_installs]}\n"
-        f"  git:      {icons[policy.auto_approve_git]}"
-    )

{localcode-0.2.15 → localcode-0.3.0}/src/localcode/bootstrap.py

@@ -539,13 +539,16 @@ def download_model(
 ) -> tuple[bool, str]:
     """Download a GGUF model selected from `models_catalog.CHOICES`.
 
-    If `choice` is None, defaults to the first entry in CHOICES (Gemma 4 26B).
+    If `choice` is None, falls back to `recommend()` — the RAM-appropriate model
+    for this machine, not a hardcoded default.
     Returns (success, path_or_error_message).
     """
-    from .models_catalog import CHOICES
+    from .models_catalog import recommend
 
     if choice is None:
-        choice = CHOICES[0]
+        # No explicit choice → the RAM-appropriate model for THIS machine,
+        # not a hardcoded default.
+        choice = recommend()
 
     # Already present?
     existing = get_model_path(choice.filename)
@@ -1247,18 +1250,6 @@ def _ensure_ollama() -> bool:
     return result.returncode == 0
 
 
-def ensure_model_downloaded(model_tag: str, on_progress: Callable[[str], None] | None = None) -> tuple[bool, str]:
-    """Ensure the model is downloaded via Ollama. Installs Ollama if needed."""
-    if not _ensure_ollama():
-        return False, "Could not install Ollama. Install manually: https://ollama.com/download"
-    # Start Ollama service if not running
-    if platform.system().lower() == "darwin":
-        subprocess.Popen(["ollama", "serve"], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
-                        start_new_session=True)
-        import time; time.sleep(2)
-    return pull_model(model_tag, on_progress=on_progress)
-
-
 def build_turboquant(on_progress: Callable[[str], None] | None = None) -> tuple[bool, str]:
     """Build the TurboQuant llama.cpp fork from source with Metal support."""
     source = _find_turboquant_source()

{localcode-0.2.15 → localcode-0.3.0}/src/localcode/formatting.py

@@ -56,15 +56,6 @@ def truncate_with_tail(
     return "\n".join(head_block + [ellipsis] + tail_block)
 
 
-def truncate_one_line(text: str, max_chars: int = 80) -> str:
-    """Truncate to a single line for inline display (e.g. tool-call
-    args summary). Replaces newlines with spaces, hard-caps length."""
-    s = (text or "").replace("\n", " ").strip()
-    if len(s) <= max_chars:
-        return s
-    return s[: max_chars - 1] + "…"
-
-
 def split_stdout_stderr(text: str) -> tuple[str, str]:
     """Heuristic split of bash output into (stdout, stderr).
 

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 {}