letscode 0.5.0__tar.gz → 0.6.1__tar.gz

{letscode-0.5.0 → letscode-0.6.1}/PKG-INFO

@@ -1,9 +1,7 @@
 Metadata-Version: 2.4
 Name: letscode
-Version: 0.5.0
+Version: 0.6.1
 Summary: A minimal coding agent for the terminal.
-Project-URL: Homepage, https://git.sr.ht/~sfermigier/letscode
-Project-URL: Source Code, https://git.sr.ht/~sfermigier/letscode
 Author-email: Stefane Fermigier <sf@abilian.com>
 Requires-Python: >=3.12
 Requires-Dist: aiofiles>=24.0
@@ -13,6 +11,7 @@ Requires-Dist: openai>=1.0
 Requires-Dist: pluggy>=1.5
 Requires-Dist: prompt-toolkit>=3.0
 Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.0
 Description-Content-Type: text/markdown
 
@@ -20,10 +19,12 @@ Description-Content-Type: text/markdown
 
 A minimal, OpenAI-compatible coding agent for the terminal — written in Python. Point it at any OpenAI-API-compatible endpoint (Ollama, Fireworks, OpenRouter, vLLM, llama.cpp's `llama-server`, …) and get a streaming agent loop with the four tools that cover 95% of coding sessions — `read`, `write`, `edit`, `bash` — plus skills, slash commands, and a plugin system you can extend.
 
-**Status:** v0.5, alpha.
+**Status:** v0.6, alpha.
 
 The full docs live in [`docs/`](docs/) and build via [Zensical](https://zensical.org) — run `make docs-serve` for a live preview, or `make docs` for a static build.
 
+Or go to <https://letscode.hop3.abilian.com> for the online doc.
+
 ## What it does
 
 - **Streaming agent loop** with parallel tool execution.

{letscode-0.5.0 → letscode-0.6.1}/README.md

@@ -2,10 +2,12 @@
 
 A minimal, OpenAI-compatible coding agent for the terminal — written in Python. Point it at any OpenAI-API-compatible endpoint (Ollama, Fireworks, OpenRouter, vLLM, llama.cpp's `llama-server`, …) and get a streaming agent loop with the four tools that cover 95% of coding sessions — `read`, `write`, `edit`, `bash` — plus skills, slash commands, and a plugin system you can extend.
 
-**Status:** v0.5, alpha.
+**Status:** v0.6, alpha.
 
 The full docs live in [`docs/`](docs/) and build via [Zensical](https://zensical.org) — run `make docs-serve` for a live preview, or `make docs` for a static build.
 
+Or go to <https://letscode.hop3.abilian.com> for the online doc.
+
 ## What it does
 
 - **Streaming agent loop** with parallel tool execution.

letscode-0.6.1/plugins/letscode-mcp/README.md

@@ -0,0 +1,65 @@
+# letscode-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io/) client plugin for [letscode](https://github.com/abilian/letscode). Configure an MCP server in TOML; restart `letscode`; the server's tools show up in `/tools` and the model can call them — same shape as any other letscode tool.
+
+**Scope (v0.6):** stdio transport, tools only (resources and prompts deferred). Design: `notes/21-mcp-integration.md` in the letscode repo.
+
+## Install
+
+```sh
+uv tool install letscode-mcp     # or: pipx install letscode-mcp
+```
+
+Once installed alongside `letscode`, the plugin is auto-discovered via the `letscode` entry-point group — no extra wiring.
+
+## Configure
+
+Edit `~/.letscode/config.toml` (or `.letscode/config.toml` in a project — project overrides user per key):
+
+```toml
+[mcp.servers.filesystem]
+command = "uvx"
+args    = ["mcp-server-filesystem", "/path/to/project"]
+
+[mcp.servers.github]
+command = "npx"
+args    = ["-y", "@modelcontextprotocol/server-github"]
+env     = { GITHUB_TOKEN = "$GITHUB_TOKEN" }   # $VAR / ${VAR} expand from your env
+prefix  = "gh_"                                # optional; default = "mcp_<server>_"
+timeout = 10                                   # seconds for initialize + list_tools
+```
+
+Per-server keys:
+
+| key | required | meaning |
+|---|---|---|
+| `command` | yes | executable to spawn (resolved on `PATH`) |
+| `args` | no | command-line args (default `[]`) |
+| `env` | no | extra env vars; values support `$VAR` / `${VAR}` expansion; unset → empty string |
+| `prefix` | no | tool-name prefix override; default `mcp_<server>_` |
+| `timeout` | no | seconds for the startup handshake (default `10`) |
+
+## Tool naming
+
+Discovered tools are namespaced to avoid colliding with letscode built-ins (`read`, `write`, `edit`, `bash`) and with each other. A server keyed `filesystem` exposing `read_file` registers as `mcp_filesystem_read_file`. Use `prefix = "fs_"` to shorten if the token cost matters more than the safety margin.
+
+## Failure model
+
+Every failure surfaces as a one-line stderr warning at registration or a `ToolResult(is_error=True)` at call time. Never a traceback into the agent loop.
+
+| When | Failure | You see |
+|---|---|---|
+| register | `command` not on `PATH` | warning, server skipped, other servers continue |
+| register | startup exceeds `timeout` | warning, server skipped |
+| call | server crashed | `is_error=True` carrying the error message |
+| call | server returns `isError=True` | `is_error=True` carrying the server's content |
+
+No auto-restart in v0.6 — restart `letscode` to recover.
+
+## Trust model
+
+A configured MCP server runs with your full shell power, same model as letscode's built-in `bash` tool. Only configure servers you trust to read your code, write your files, and hit network endpoints on your behalf.
+
+## License
+
+MIT.

letscode-0.6.1/plugins/letscode-mcp/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "letscode-mcp"
+version = "0.1.0"
+description = "MCP (Model Context Protocol) client plugin for letscode. Surface tools from any MCP server as native letscode tools."
+readme = "README.md"
+authors = [
+    { name = "letscode contributors" },
+]
+requires-python = ">=3.12"
+dependencies = [
+    "letscode>=0.6",
+    "pluggy>=1.5",
+    "pydantic>=2.0",
+    "mcp>=1.0",
+]
+
+[project.entry-points.letscode]
+mcp = "letscode_mcp.plugin"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/letscode_mcp"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src" = ""
+
+# Dev only: resolve letscode to the local checkout when this plugin's own
+# venv is built. uv ignores [tool.uv.sources] in published wheels.
+[tool.uv.sources]
+letscode = { path = "../..", editable = true }
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-asyncio>=0.24",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

letscode-0.6.1/plugins/letscode-mcp/src/letscode_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""letscode-mcp: client for the Model Context Protocol."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"

letscode-0.6.1/plugins/letscode-mcp/src/letscode_mcp/plugin.py

@@ -0,0 +1,304 @@
+"""letscode-mcp: discover MCP servers from TOML config, expose their tools.
+
+Design: ``notes/21-mcp-integration.md``. One file does it all — config
+read, background asyncio loop, MCP discovery, tool wrapping. The plugin
+contract (``letscode_register_tools``) is sync, the MCP SDK is async; a
+single daemon thread owning a dedicated event loop bridges the two
+(``asyncio.run_coroutine_threadsafe``).
+
+Failure model is uniform: bad config, missing binary, hung server,
+malformed schema, mid-session crash — every one becomes a one-line
+stderr warning at registration *or* a ``ToolResult(is_error=True)`` at
+call time. Never a traceback into the agent loop.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import atexit
+import logging
+import os
+import re
+import sys
+import threading
+from typing import TYPE_CHECKING, Any
+
+import pluggy
+from pydantic import BaseModel, ConfigDict
+
+from letscode.agent.tools import ToolResult
+from letscode.config import load_config
+from letscode.llm.types import TextPart
+
+if TYPE_CHECKING:
+    from collections.abc import Coroutine
+    from concurrent.futures import Future as _CFuture
+
+    from letscode.agent.tools import ToolContext, ToolRegistry
+
+_logger = logging.getLogger(__name__)
+hookimpl = pluggy.HookimplMarker("letscode")
+
+_DEFAULT_TIMEOUT = 10.0
+# $VAR or ${VAR}. Empty string when unset — keeps configs portable
+# instead of erroring on a host that doesn't have an optional secret.
+_ENV_RE = re.compile(r"\$(?:\{([^}]+)\}|([A-Za-z_][A-Za-z0-9_]*))")
+
+
+# ---------------------------------------------------------------------------
+# Background asyncio loop (one daemon thread for all MCP sessions)
+# ---------------------------------------------------------------------------
+
+_bg_loop: asyncio.AbstractEventLoop | None = None
+_bg_thread: threading.Thread | None = None
+_bg_lock = threading.Lock()
+# Stop-events for every live session task. atexit flips them to drain
+# the bg loop cleanly on process exit.
+_stop_events: list[asyncio.Event] = []
+
+
+def _ensure_bg_loop() -> asyncio.AbstractEventLoop:
+    """Start the daemon thread + event loop on first use; idempotent."""
+    global _bg_loop, _bg_thread  # noqa: PLW0603 — process-wide singleton, locked init
+    with _bg_lock:
+        if _bg_loop is not None:
+            return _bg_loop
+        loop = asyncio.new_event_loop()
+        thread = threading.Thread(
+            target=loop.run_forever, name="letscode-mcp", daemon=True
+        )
+        thread.start()
+        _bg_loop = loop
+        _bg_thread = thread
+        atexit.register(_shutdown)
+        return loop
+
+
+def _run_in_bg(coro: Coroutine[Any, Any, Any], *, timeout: float | None = None) -> Any:  # noqa: ANN401
+    """Run a coroutine on the bg loop from a sync caller; block for result."""
+    loop = _ensure_bg_loop()
+    fut: _CFuture[Any] = asyncio.run_coroutine_threadsafe(coro, loop)
+    return fut.result(timeout=timeout)
+
+
+def _shutdown() -> None:
+    """Best-effort cleanup. Subprocesses die with the parent regardless."""
+    loop = _bg_loop
+    if loop is None:
+        return
+    for stop in _stop_events:
+        loop.call_soon_threadsafe(stop.set)
+    # ponytail: no join — daemon thread, OS reaps the subprocess children
+    loop.call_soon_threadsafe(loop.stop)
+
+
+# ---------------------------------------------------------------------------
+# Config helpers
+# ---------------------------------------------------------------------------
+
+
+def _expand_env(env_in: dict[str, str]) -> dict[str, str]:
+    """Expand ``$VAR`` / ``${VAR}`` in env values against ``os.environ``."""
+    return {
+        k: _ENV_RE.sub(lambda m: os.environ.get(m.group(1) or m.group(2), ""), v)
+        for k, v in env_in.items()
+    }
+
+
+# ---------------------------------------------------------------------------
+# Pydantic params model synthesised from an MCP tool's inputSchema
+# ---------------------------------------------------------------------------
+
+
+def _params_model(class_name: str, schema: dict[str, Any]) -> type[BaseModel]:
+    """A permissive ``BaseModel`` whose ``model_json_schema`` is the MCP schema.
+
+    The LLM sees the real schema (so it knows required fields and types);
+    incoming arg dicts are accepted verbatim via ``extra="allow"``. The
+    MCP server itself validates on receive — re-validating here would
+    just be a second source of truth that could disagree.
+    """
+    fixed = schema or {"type": "object", "properties": {}}
+
+    class _Params(BaseModel):
+        model_config = ConfigDict(extra="allow")
+
+        @classmethod
+        def model_json_schema(cls, **_kw: Any) -> dict[str, Any]:  # type: ignore[override]  # noqa: ANN401
+            return fixed
+
+    _Params.__name__ = class_name
+    return _Params
+
+
+# ---------------------------------------------------------------------------
+# letscode Tool wrapping one discovered MCP tool
+# ---------------------------------------------------------------------------
+
+
+class _McpTool:
+    """A letscode Tool whose ``execute`` marshals a call to the bg loop."""
+
+    execution_mode = "parallel"
+
+    def __init__(  # noqa: PLR0913 — six small kwargs read better than a config object
+        self,
+        *,
+        name: str,
+        description: str,
+        parameters: type[BaseModel],
+        session: Any,  # noqa: ANN401 — opaque mcp ClientSession
+        remote_name: str,
+        timeout: float,
+    ) -> None:
+        self.name = name
+        self.description = description
+        self.parameters = parameters
+        self._session = session
+        self._remote_name = remote_name
+        self._timeout = timeout
+
+    async def execute(self, params: BaseModel, ctx: ToolContext) -> ToolResult:
+        del ctx
+        args = params.model_dump()
+        try:
+            cfut = asyncio.run_coroutine_threadsafe(self._call(args), _ensure_bg_loop())
+            return await asyncio.wrap_future(cfut)
+        except Exception as exc:  # noqa: BLE001 — deliberate fail-soft; design §5
+            return ToolResult(
+                content=[TextPart(text=f"MCP call failed: {exc}")],
+                is_error=True,
+            )
+
+    async def _call(self, args: dict[str, Any]) -> ToolResult:
+        result = await asyncio.wait_for(
+            self._session.call_tool(self._remote_name, args), timeout=self._timeout
+        )
+        parts = [TextPart(text=_part_text(p)) for p in (result.content or [])]
+        if not parts:
+            parts = [TextPart(text="")]
+        return ToolResult(
+            content=parts, is_error=bool(getattr(result, "isError", False))
+        )
+
+
+def _part_text(part: Any) -> str:  # noqa: ANN401 — opaque mcp content union
+    """MCP TextContent has ``.text``; image/embedded-resource falls back to repr."""
+    return getattr(part, "text", None) or repr(part)
+
+
+# ---------------------------------------------------------------------------
+# Server bring-up (runs on the bg loop)
+# ---------------------------------------------------------------------------
+
+
+async def _spawn_server(
+    server_name: str,
+    command: str,
+    args: list[str],
+    env: dict[str, str],
+    timeout: float,
+) -> tuple[Any, list[Any], asyncio.Event]:
+    """Open one MCP server in a long-running task.
+
+    Returns ``(session, tools, stop_event)``. The task holds the
+    ``stdio_client`` + ``ClientSession`` context managers open until
+    ``stop_event`` is set — the right pattern for anyio task scopes
+    (enter and exit on the same task).
+    """
+    # ponytail: imports inside the function so the plugin module loads
+    # even when the mcp SDK is absent (rare; matters during plugin discovery).
+    from mcp import ClientSession, StdioServerParameters  # noqa: PLC0415
+    from mcp.client.stdio import stdio_client  # noqa: PLC0415
+
+    params = StdioServerParameters(command=command, args=args, env=env or None)
+    loop = asyncio.get_running_loop()
+    ready: asyncio.Future[tuple[Any, list[Any]]] = loop.create_future()
+    stop = asyncio.Event()
+
+    async def _serve() -> None:
+        try:  # noqa: PLW0717 — one long-lived async-with is the whole body
+            async with (
+                stdio_client(params) as (read, write),
+                ClientSession(read, write) as session,
+            ):
+                await asyncio.wait_for(session.initialize(), timeout=timeout)
+                listed = await asyncio.wait_for(session.list_tools(), timeout=timeout)
+                if not ready.done():
+                    ready.set_result((session, list(listed.tools)))
+                await stop.wait()
+        except Exception as exc:  # noqa: BLE001 — surfaces to caller via ready.set_exception
+            if not ready.done():
+                ready.set_exception(exc)
+
+    # The bg loop holds the running task; the linter's "store the handle"
+    # warning doesn't apply — the task lives until `stop` is set.
+    asyncio.create_task(_serve(), name=f"mcp-{server_name}")  # noqa: RUF006
+    session, tools = await ready
+    return session, tools, stop
+
+
+# ---------------------------------------------------------------------------
+# The hook
+# ---------------------------------------------------------------------------
+
+
+@hookimpl
+def letscode_register_tools(registry: ToolRegistry) -> None:
+    """Discover every configured MCP server, register its tools."""
+    try:
+        cfg = load_config()
+        servers = cfg.sections.get("mcp", {}).get("servers", {})
+    except Exception:
+        _logger.warning("mcp: could not read config; skipping", exc_info=True)
+        return
+    if not servers:
+        return
+    for server_name, server_cfg in servers.items():
+        _register_one_server(registry, server_name, server_cfg or {})
+
+
+def _register_one_server(
+    registry: ToolRegistry, server_name: str, server_cfg: dict[str, Any]
+) -> None:
+    command = server_cfg.get("command")
+    if not command:
+        _warn(f"server {server_name!r} missing 'command'; skipped")
+        return
+    args = list(server_cfg.get("args", []))
+    env = _expand_env(dict(server_cfg.get("env", {})))
+    prefix = server_cfg.get("prefix") or f"mcp_{server_name}_"
+    timeout = float(server_cfg.get("timeout", _DEFAULT_TIMEOUT))
+
+    try:
+        session, tools, stop = _run_in_bg(
+            _spawn_server(server_name, command, args, env, timeout),
+            timeout=timeout + 5,
+        )
+    except Exception as exc:  # noqa: BLE001 — fail-soft; design §5
+        _warn(f"server {server_name!r} ({command}) failed: {exc}")
+        return
+    _stop_events.append(stop)
+
+    for t in tools:
+        try:
+            tool_name = f"{prefix}{t.name}"
+            registry.add(
+                _McpTool(
+                    name=tool_name,
+                    description=t.description or "",
+                    parameters=_params_model(
+                        f"_McpParams_{server_name}_{t.name}",
+                        dict(t.inputSchema or {}),
+                    ),
+                    session=session,
+                    remote_name=t.name,
+                    timeout=timeout,
+                )
+            )
+        except Exception as exc:  # noqa: BLE001 — fail-soft per tool
+            _warn(f"server {server_name!r} tool {t.name!r} skipped: {exc}")
+
+
+def _warn(msg: str) -> None:
+    print(f"letscode-mcp: {msg}", file=sys.stderr)