py-codemode 0.1.1__tar.gz

py_codemode-0.1.1/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: py-codemode
+Version: 0.1.1
+Summary: Code Mode: use LLMs to generate executable code that performs tool calls.
+Keywords: llm,code-generation,tool-calling,mcp
+Author: Xin
+Author-email: Xin <xin@imfing.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: jsrun>=0.1.0
+Requires-Dist: mcp>=1.0,<2 ; extra == 'mcp'
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/imfing/codemode
+Project-URL: Repository, https://github.com/imfing/codemode
+Project-URL: Issues, https://github.com/imfing/codemode/issues
+Provides-Extra: mcp
+Description-Content-Type: text/markdown
+
+# codemode
+
+Instead of making tool calls one at a time, let the LLM write code that orchestrates your Python tools in a single, more token-efficient pass.
+
+Codemode runs that code in an in-process V8 isolate via [jsrun](https://github.com/imfing/jsrun). Isolates spin up in under 5ms with the same runtime performance as Node.js, have no network or filesystem access by default, and cannot reach the host except through functions you explicitly provide.
+
+> **Experimental**: this project is in early development
+
+## Install
+
+```bash
+pip install py-codemode[mcp]
+# or
+uv add py-codemode[mcp]
+```
+
+For the core executor without MCP: `pip install py-codemode`
+
+## Quick start
+
+Create an MCP server with built-in capabilities and custom tools:
+
+```python
+from codemode import EnvCapability, FsCapability, HttpCapability
+from codemode.mcp import CodeModeServer
+
+server = CodeModeServer(
+    name="example",
+    capabilities=[
+        EnvCapability(allowed_keys=["USER"]),
+        FsCapability(allowed_paths=["./examples"]),
+        HttpCapability(allowed_hosts=["httpbin.org"]),
+    ],
+    enable_search=True,
+)
+
+
+@server.tool()
+def add(a: int, b: int) -> int:
+    """Add two numbers"""
+    return a + b
+
+
+if __name__ == "__main__":
+    server.mcp.run(transport="streamable-http")
+```
+
+Run with `uv run python examples/mcp_server.py` and connect any MCP client.
+
+The `codemode[mcp]` extra wraps the executor as an MCP server, exposing:
+
+- **`execute`** -- runs JavaScript that calls your Python functions. TypeScript declarations are auto-generated from your type hints and embedded in the tool description so the LLM knows what is callable.
+- **`search`** (optional, via `enable_search=True`) -- searches registered capabilities and tools by name or description.
+
+## How it works
+
+```
+┌─────────────────────┐         ┌──────────────────────┐
+│  V8 isolate (jsrun) │         │  Python host         │
+│                     │         │                      │
+│  LLM-generated JS   │         │  Executor            │
+│  runs in async IIFE │         │                      │
+│                     │  bridge │                      │
+│  codemode.fn({...}) ├────────►│  _dispatch()         │
+│                     │◄────────┤  -> your_fn(**kwargs)│
+│                     │  result │                      │
+└─────────────────────┘         └──────────────────────┘
+```
+
+The executor wraps your code in a harness that captures console output and sets up a `codemode` proxy object. The proxy intercepts every `codemode.*()` call, serializes it to JSON, and bridges back to Python where `_dispatch()` routes it to the matching host function. The MCP server uses `Executor` under the hood.
+
+## Host functions
+
+Host functions use keyword-only parameters with type hints:
+
+```python
+async def read(*, path: str) -> str:
+    return open(path).read()
+```
+
+Called from JavaScript as `await codemode.read({ path: "/tmp/f" })`. The type hints are used to generate TypeScript stubs (`str` becomes `string`, `int/float` becomes `number`, `list[T]` becomes `T[]`, etc.).
+
+## Built-in capabilities
+
+Capabilities are namespaced host functions with allowlist-based security. The sandbox has no filesystem, network, or environment access by default.
+
+| Capability | Namespace | Description |
+|---|---|---|
+| `FsCapability(allowed_paths=[...])` | `codemode.fs` | Sandboxed read/write within allowed paths |
+| `EnvCapability(allowed_keys=[...])` | `codemode.env` | Read environment variables from an allowlist |
+| `HttpCapability(allowed_hosts=[...])` | `codemode.http` | HTTP requests to allowed hosts only |
+
+## Limitations
+
+- V8 runtime, not Node, so no Node built-in modules. JavaScript only.
+- No top-level `import` or `require` in sandbox code
+
+## Advanced
+
+For step-by-step control over host calls, use the session API directly:
+
+```python
+import asyncio
+from codemode import Executor, HostCallRequest, RunCompleted, RunFailed
+
+async def main():
+    executor = Executor(timeout_s=5)
+    session = await executor.start("""
+        async () => {
+          const a = await codemode.double({ n: 3 });
+          const b = await codemode.double({ n: a });
+          return b;
+        }
+    """)
+
+    while True:
+        event = await session.next_event()
+        if isinstance(event, HostCallRequest):
+            result = event.input["n"] * 2
+            await session.submit_result(event.call_id, result)
+        elif isinstance(event, (RunCompleted, RunFailed)):
+            break
+
+    await session.cancel()
+    executor.close()
+
+asyncio.run(main())
+```
+
+This gives you full control over each host call, useful for logging, approval flows, or routing to external services.
+
+jsrun also supports loading additional JavaScript libraries into the isolate via `Runtime.add_static_module()` or custom module loaders, V8 heap snapshots for faster cold starts, heap size limits, and per-call execution timeouts. See the [jsrun documentation](https://github.com/imfing/jsrun) for details.
+
+## Further reading
+
+- [jsrun](https://github.com/imfing/jsrun) -- the V8 isolate runtime that powers codemode
+- [src/codemode](https://github.com/imfing/codemode/tree/main/src/codemode) -- executor, capabilities, and stub generation source
+- [src/codemode/mcp](https://github.com/imfing/codemode/tree/main/src/codemode/mcp) -- MCP server and registry source
+- [examples/](https://github.com/imfing/codemode/tree/main/examples) -- runnable examples
+
+## License
+
+MIT

py_codemode-0.1.1/README.md

@@ -0,0 +1,143 @@
+# codemode
+
+Instead of making tool calls one at a time, let the LLM write code that orchestrates your Python tools in a single, more token-efficient pass.
+
+Codemode runs that code in an in-process V8 isolate via [jsrun](https://github.com/imfing/jsrun). Isolates spin up in under 5ms with the same runtime performance as Node.js, have no network or filesystem access by default, and cannot reach the host except through functions you explicitly provide.
+
+> **Experimental**: this project is in early development
+
+## Install
+
+```bash
+pip install py-codemode[mcp]
+# or
+uv add py-codemode[mcp]
+```
+
+For the core executor without MCP: `pip install py-codemode`
+
+## Quick start
+
+Create an MCP server with built-in capabilities and custom tools:
+
+```python
+from codemode import EnvCapability, FsCapability, HttpCapability
+from codemode.mcp import CodeModeServer
+
+server = CodeModeServer(
+    name="example",
+    capabilities=[
+        EnvCapability(allowed_keys=["USER"]),
+        FsCapability(allowed_paths=["./examples"]),
+        HttpCapability(allowed_hosts=["httpbin.org"]),
+    ],
+    enable_search=True,
+)
+
+
+@server.tool()
+def add(a: int, b: int) -> int:
+    """Add two numbers"""
+    return a + b
+
+
+if __name__ == "__main__":
+    server.mcp.run(transport="streamable-http")
+```
+
+Run with `uv run python examples/mcp_server.py` and connect any MCP client.
+
+The `codemode[mcp]` extra wraps the executor as an MCP server, exposing:
+
+- **`execute`** -- runs JavaScript that calls your Python functions. TypeScript declarations are auto-generated from your type hints and embedded in the tool description so the LLM knows what is callable.
+- **`search`** (optional, via `enable_search=True`) -- searches registered capabilities and tools by name or description.
+
+## How it works
+
+```
+┌─────────────────────┐         ┌──────────────────────┐
+│  V8 isolate (jsrun) │         │  Python host         │
+│                     │         │                      │
+│  LLM-generated JS   │         │  Executor            │
+│  runs in async IIFE │         │                      │
+│                     │  bridge │                      │
+│  codemode.fn({...}) ├────────►│  _dispatch()         │
+│                     │◄────────┤  -> your_fn(**kwargs)│
+│                     │  result │                      │
+└─────────────────────┘         └──────────────────────┘
+```
+
+The executor wraps your code in a harness that captures console output and sets up a `codemode` proxy object. The proxy intercepts every `codemode.*()` call, serializes it to JSON, and bridges back to Python where `_dispatch()` routes it to the matching host function. The MCP server uses `Executor` under the hood.
+
+## Host functions
+
+Host functions use keyword-only parameters with type hints:
+
+```python
+async def read(*, path: str) -> str:
+    return open(path).read()
+```
+
+Called from JavaScript as `await codemode.read({ path: "/tmp/f" })`. The type hints are used to generate TypeScript stubs (`str` becomes `string`, `int/float` becomes `number`, `list[T]` becomes `T[]`, etc.).
+
+## Built-in capabilities
+
+Capabilities are namespaced host functions with allowlist-based security. The sandbox has no filesystem, network, or environment access by default.
+
+| Capability | Namespace | Description |
+|---|---|---|
+| `FsCapability(allowed_paths=[...])` | `codemode.fs` | Sandboxed read/write within allowed paths |
+| `EnvCapability(allowed_keys=[...])` | `codemode.env` | Read environment variables from an allowlist |
+| `HttpCapability(allowed_hosts=[...])` | `codemode.http` | HTTP requests to allowed hosts only |
+
+## Limitations
+
+- V8 runtime, not Node, so no Node built-in modules. JavaScript only.
+- No top-level `import` or `require` in sandbox code
+
+## Advanced
+
+For step-by-step control over host calls, use the session API directly:
+
+```python
+import asyncio
+from codemode import Executor, HostCallRequest, RunCompleted, RunFailed
+
+async def main():
+    executor = Executor(timeout_s=5)
+    session = await executor.start("""
+        async () => {
+          const a = await codemode.double({ n: 3 });
+          const b = await codemode.double({ n: a });
+          return b;
+        }
+    """)
+
+    while True:
+        event = await session.next_event()
+        if isinstance(event, HostCallRequest):
+            result = event.input["n"] * 2
+            await session.submit_result(event.call_id, result)
+        elif isinstance(event, (RunCompleted, RunFailed)):
+            break
+
+    await session.cancel()
+    executor.close()
+
+asyncio.run(main())
+```
+
+This gives you full control over each host call, useful for logging, approval flows, or routing to external services.
+
+jsrun also supports loading additional JavaScript libraries into the isolate via `Runtime.add_static_module()` or custom module loaders, V8 heap snapshots for faster cold starts, heap size limits, and per-call execution timeouts. See the [jsrun documentation](https://github.com/imfing/jsrun) for details.
+
+## Further reading
+
+- [jsrun](https://github.com/imfing/jsrun) -- the V8 isolate runtime that powers codemode
+- [src/codemode](https://github.com/imfing/codemode/tree/main/src/codemode) -- executor, capabilities, and stub generation source
+- [src/codemode/mcp](https://github.com/imfing/codemode/tree/main/src/codemode/mcp) -- MCP server and registry source
+- [examples/](https://github.com/imfing/codemode/tree/main/examples) -- runnable examples
+
+## License
+
+MIT

py_codemode-0.1.1/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "py-codemode"
+version = "0.1.1"
+description = "Code Mode: use LLMs to generate executable code that performs tool calls."
+readme = "README.md"
+authors = [{ name = "Xin", email = "xin@imfing.com" }]
+license = "MIT"
+keywords = ["llm", "code-generation", "tool-calling", "mcp"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.28.1",
+    "jsrun>=0.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/imfing/codemode"
+Repository = "https://github.com/imfing/codemode"
+Issues = "https://github.com/imfing/codemode/issues"
+
+[project.optional-dependencies]
+mcp = [
+    "mcp>=1.0,<2",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.4,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "codemode"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "ruff>=0.13.0",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]

py_codemode-0.1.1/src/codemode/__init__.py

@@ -0,0 +1,25 @@
+from .capabilities import EnvCapability, FsCapability, HttpCapability
+from .executor import (
+    Capability,
+    Executor,
+    HostCallRequest,
+    RunCompleted,
+    RunEvent,
+    RunFailed,
+    RunSession,
+)
+from .stubs import generate_stubs
+
+__all__ = [
+    "Capability",
+    "Executor",
+    "RunSession",
+    "HostCallRequest",
+    "RunCompleted",
+    "RunFailed",
+    "RunEvent",
+    "EnvCapability",
+    "FsCapability",
+    "HttpCapability",
+    "generate_stubs",
+]

py_codemode-0.1.1/src/codemode/capabilities/__init__.py

@@ -0,0 +1,5 @@
+from .env import EnvCapability
+from .fs import FsCapability
+from .http import HttpCapability
+
+__all__ = ["EnvCapability", "FsCapability", "HttpCapability"]

py_codemode-0.1.1/src/codemode/capabilities/env.py

@@ -0,0 +1,20 @@
+import os
+
+from codemode.executor import HostFn
+
+
+class EnvCapability:
+    namespace = "env"
+    description = "Read environment variables from an allowlist"
+
+    def __init__(self, *, allowed_keys: list[str]) -> None:
+        self._allowed: set[str] = set(allowed_keys)
+
+    def exports(self) -> dict[str, HostFn]:
+        return {"get": self._get}
+
+    async def _get(self, *, key: str) -> str | None:
+        """Return the value of an environment variable, or null if unset."""
+        if key not in self._allowed:
+            raise ValueError(f"Key {key!r} is not allowed")
+        return os.environ.get(key)

py_codemode-0.1.1/src/codemode/capabilities/fs.py

@@ -0,0 +1,35 @@
+import asyncio
+from pathlib import Path
+
+from codemode.executor import HostFn
+
+
+class FsCapability:
+    namespace = "fs"
+    description = "Sandboxed file-system access within allowed paths"
+
+    def __init__(self, *, allowed_paths: list[str]) -> None:
+        self._allowed = [Path(p).resolve() for p in allowed_paths]
+
+    def exports(self) -> dict[str, HostFn]:
+        return {"read": self._read, "write": self._write}
+
+    def _check_path(self, raw: str) -> Path:
+        resolved = Path(raw).resolve()
+        for allowed in self._allowed:
+            try:
+                resolved.relative_to(allowed)
+                return resolved
+            except ValueError:
+                continue
+        raise ValueError(f"Path {raw!r} is not within allowed paths")
+
+    async def _read(self, *, path: str) -> str:
+        """Read a file and return its contents as UTF-8 text."""
+        checked = self._check_path(path)
+        return await asyncio.to_thread(checked.read_text)
+
+    async def _write(self, *, path: str, content: str) -> None:
+        """Write text content to a file, creating it if it does not exist."""
+        checked = self._check_path(path)
+        await asyncio.to_thread(checked.write_text, content)

py_codemode-0.1.1/src/codemode/capabilities/http.py

@@ -0,0 +1,49 @@
+from typing import Any
+from urllib.parse import urlparse
+
+import httpx
+
+from codemode.executor import HostFn
+
+
+class HttpCapability:
+    namespace = "http"
+    description = "Make outbound HTTP requests to allowed hosts"
+
+    def __init__(self, *, allowed_hosts: list[str] | None = None) -> None:
+        self._allowed_hosts: set[str] | None = (
+            set(allowed_hosts) if allowed_hosts is not None else None
+        )
+
+    def exports(self) -> dict[str, HostFn]:
+        return {"fetch": self._fetch}
+
+    def _check_host(self, url: str) -> None:
+        if self._allowed_hosts is None:
+            return
+        host = urlparse(url).hostname or ""
+        if host not in self._allowed_hosts:
+            raise ValueError(f"Host {host!r} is not allowed")
+
+    async def _fetch(
+        self,
+        *,
+        url: str,
+        method: str = "GET",
+        headers: dict[str, str] | None = None,
+        body: str | None = None,
+    ) -> dict[str, Any]:
+        """Make an HTTP request and return status, headers, and body."""
+        self._check_host(url)
+        async with httpx.AsyncClient() as client:
+            resp = await client.request(
+                method,
+                url,
+                headers=dict(headers or {}),
+                content=body,
+            )
+            return {
+                "status": resp.status_code,
+                "headers": dict(resp.headers),
+                "body": resp.text,
+            }

py_codemode-0.1.1/src/codemode/executor.py

@@ -0,0 +1,265 @@
+import asyncio
+import contextlib
+import inspect
+import json
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, Mapping, Protocol
+
+from jsrun import JavaScriptError, Runtime, RuntimeConfig
+
+HostFn = Callable[..., Awaitable[Any] | Any]
+
+
+class Capability(Protocol):
+    """Capability contract for executor registration."""
+
+    namespace: str
+    description: str
+
+    def exports(self) -> dict[str, HostFn]: ...
+
+
+@dataclass
+class HostCallRequest:
+    call_id: str
+    target: str
+    input: dict[str, Any]
+
+
+@dataclass
+class RunCompleted:
+    result: Any = None
+    logs: list[str] | None = None
+
+
+@dataclass
+class RunFailed:
+    error: str
+    logs: list[str] | None = None
+
+
+RunEvent = HostCallRequest | RunCompleted | RunFailed
+
+
+class RunSession:
+    def __init__(
+        self,
+        runtime: Runtime,
+        script: str,
+        all_fns: dict[str, HostFn],
+        timeout_s: float,
+    ) -> None:
+        self._runtime = runtime
+        self._timeout_s = timeout_s
+        self.events: asyncio.Queue[RunEvent] = asyncio.Queue()
+        self._pending: dict[str, asyncio.Future[Any]] = {}
+        self._counter = 0
+        self._task = asyncio.create_task(self._run(script, all_fns))
+
+    async def __aenter__(self) -> "RunSession":
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.cancel()
+
+    async def _run(self, script: str, all_fns: dict[str, HostFn]) -> None:
+        loop = asyncio.get_running_loop()
+
+        async def _dispatch(tool_name: str, args_json: str) -> str:
+            args = json.loads(args_json) if args_json else {}
+            if not isinstance(args, dict):
+                return json.dumps({"error": "Tool args must be an object"})
+
+            fn = all_fns.get(tool_name)
+            if fn is not None:
+                try:
+                    value = fn(**args)
+                    if inspect.isawaitable(value):
+                        value = await value
+                    return json.dumps({"result": value})
+                except Exception as exc:
+                    return json.dumps({"error": str(exc)})
+
+            call_id = str(self._counter)
+            self._counter += 1
+            fut: asyncio.Future[Any] = loop.create_future()
+            self._pending[call_id] = fut
+            await self.events.put(
+                HostCallRequest(call_id=call_id, target=tool_name, input=args)
+            )
+            try:
+                value = await fut
+                return json.dumps({"result": value})
+            except Exception as exc:
+                return json.dumps({"error": str(exc)})
+            finally:
+                self._pending.pop(call_id, None)
+
+        try:
+            self._runtime.bind_function("__codemode_call", _dispatch)
+            out = await self._runtime.eval_async(script, timeout=self._timeout_s)
+            if not isinstance(out, dict):
+                await self.events.put(RunFailed(error="Invalid response shape"))
+                return
+            error = out.get("error")
+            if error:
+                await self.events.put(RunFailed(error=str(error), logs=out.get("logs")))
+            else:
+                await self.events.put(
+                    RunCompleted(result=out.get("result"), logs=out.get("logs"))
+                )
+        except TimeoutError:
+            await self.events.put(RunFailed(error="Execution timed out"))
+        except JavaScriptError as exc:
+            await self.events.put(RunFailed(error=f"JavaScript runtime error: {exc}"))
+        except Exception as exc:
+            await self.events.put(RunFailed(error=f"Executor failure: {exc}"))
+        finally:
+            self._runtime.close()
+
+    async def next_event(self) -> RunEvent:
+        return await self.events.get()
+
+    def _get_pending(self, call_id: str) -> "asyncio.Future[Any]":
+        fut = self._pending.get(call_id)
+        if fut is None or fut.done():
+            raise KeyError(f"Unknown or already-settled call_id: {call_id!r}")
+        return fut
+
+    async def submit_result(self, call_id: str, value: Any) -> None:
+        self._get_pending(call_id).set_result(value)
+
+    async def submit_error(self, call_id: str, error: str) -> None:
+        self._get_pending(call_id).set_exception(RuntimeError(error))
+
+    async def cancel(self) -> None:
+        for fut in self._pending.values():
+            if not fut.done():
+                fut.set_exception(RuntimeError("session cancelled"))
+        self._pending.clear()
+        self._task.cancel()
+        with contextlib.suppress(asyncio.CancelledError):
+            await self._task
+
+
+class Executor:
+    def __init__(
+        self,
+        *,
+        timeout_s: float = 60.0,
+        max_heap_bytes: int = 16 * 1024 * 1024,
+        capabilities: list[Capability] | None = None,
+    ) -> None:
+        self._timeout_s = timeout_s
+        self._max_heap_bytes = max_heap_bytes
+        self._closed = False
+        self._capabilities: list[Capability] = capabilities or []
+
+    async def start(
+        self, code: str, fns: Mapping[str, HostFn] | None = None
+    ) -> RunSession:
+        if self._closed:
+            raise RuntimeError("Executor is closed")
+
+        all_fns: dict[str, HostFn] = dict(fns or {})
+        for cap in self._capabilities:
+            for fn_name, fn in cap.exports().items():
+                all_fns[f"{cap.namespace}.{fn_name}"] = fn
+
+        namespaces = [cap.namespace for cap in self._capabilities]
+        runtime = Runtime(RuntimeConfig(max_heap_size=self._max_heap_bytes))
+        script = self._build_script(code, namespaces)
+        return RunSession(runtime, script, all_fns, self._timeout_s)
+
+    async def execute(
+        self, code: str, fns: Mapping[str, HostFn] | None = None
+    ) -> RunCompleted | RunFailed:
+        session = await self.start(code, fns=fns)
+        try:
+            event = await session.next_event()
+            while isinstance(event, HostCallRequest):
+                await session.submit_error(
+                    event.call_id, f"Unknown tool: {event.target!r}"
+                )
+                event = await session.next_event()
+            return event
+        finally:
+            await session.cancel()
+
+    def close(self) -> None:
+        self._closed = True
+
+    async def __aenter__(self) -> "Executor":
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        self.close()
+
+    @staticmethod
+    def _build_script(code: str, namespaces: list[str]) -> str:
+        source = json.dumps(code)
+        ns_json = json.dumps(namespaces)
+        return f"""
+        (async () => {{
+          const __logs = [];
+          console.log = (...a) => __logs.push(a.map(String).join(" "));
+          console.warn = (...a) => __logs.push("[warn] " + a.map(String).join(" "));
+          console.error = (...a) => __logs.push("[error] " + a.map(String).join(" "));
+
+          const __ns = new Set({ns_json});
+          const __call = (key) => async (args) => {{
+            const resJson = await __codemode_call(key, JSON.stringify(args ?? {{}}));
+            const data = JSON.parse(resJson);
+            if (data.error) throw new Error(data.error);
+            return data.result;
+          }};
+
+          const codemode = new Proxy({{}}, {{
+            get: (_, key) => __ns.has(key)
+              ? new Proxy({{}}, {{ get: (_, fn) => __call(`${{key}}.${{fn}}`) }})
+              : __call(key)
+          }});
+
+          let fn;
+          try {{
+            fn = eval({source});
+          }} catch (err) {{
+            if (err instanceof SyntaxError) {{
+              // Fallback: wrap bare statements in an async function.
+              try {{
+                fn = eval(`(async () => {{\\n${{  {source}  }}\\n}})`);
+              }} catch (_) {{
+                return {{
+                  result: undefined,
+                  error: `Code parse error: ${{err.message}}`,
+                  logs: __logs
+                }};
+              }}
+            }} else {{
+              return {{
+                result: undefined,
+                error: `Code parse error: ${{err.message}}`,
+                logs: __logs
+              }};
+            }}
+          }}
+
+          if (typeof fn !== "function") {{
+            // The code evaluated to a non-function value; wrap it as a
+            // return expression inside an async function.
+            const __val = fn;
+            fn = async () => __val;
+          }}
+
+          try {{
+            const result = await fn();
+            return {{ result: result === undefined ? null : result, logs: __logs }};
+          }} catch (err) {{
+            return {{
+              result: undefined,
+              error: err?.message ?? String(err),
+              logs: __logs
+            }};
+          }}
+        }})()
+        """

py_codemode-0.1.1/src/codemode/mcp/__init__.py

@@ -0,0 +1,17 @@
+"""MCP integration package for CodeMode."""
+
+try:
+    import mcp as _mcp_sdk  # type: ignore[import-not-found]
+except ModuleNotFoundError as exc:
+    if exc.name not in (None, "mcp"):
+        raise
+    raise ModuleNotFoundError(
+        "codemode.mcp requires the optional MCP SDK dependency. "
+        "Install with `pip install codemode[mcp]`."
+    ) from exc
+else:
+    del _mcp_sdk
+    from .server import CodeModeServer
+
+
+__all__ = ["CodeModeServer"]

py_codemode-0.1.1/src/codemode/mcp/registry.py

@@ -0,0 +1,141 @@
+"""MCP registry and metadata assembly helpers."""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+from codemode.executor import Capability, HostFn
+from codemode.stubs import first_doc_line, generate_stubs
+
+
+class MCPRegistry:
+    """Stores capabilities and tools, assembles MCP-facing metadata."""
+
+    def __init__(self, capabilities: Iterable[Capability] | None = None) -> None:
+        self._capabilities: dict[str, Capability] = {}
+        self.tools: dict[str, HostFn] = {}
+        for capability in capabilities or ():
+            self.add_capability(capability)
+
+    def add_capability(self, capability: Capability) -> Capability:
+        namespace = capability.namespace
+        if namespace in self._capabilities:
+            raise ValueError(f"duplicate capability namespace: {namespace!r}")
+        if namespace in self.tools:
+            raise ValueError(
+                f"capability namespace conflicts with tool name: {namespace!r}"
+            )
+        self._capabilities[namespace] = capability
+        return capability
+
+    def register_tool(self, name: str, fn: HostFn) -> HostFn:
+        if name in self.tools:
+            raise ValueError(f"duplicate tool: {name!r}")
+        if name in self._capabilities:
+            raise ValueError(f"tool name conflicts with capability namespace: {name!r}")
+        self.tools[name] = fn
+        return fn
+
+    def _sorted_capabilities(self) -> list[Capability]:
+        return [self._capabilities[ns] for ns in sorted(self._capabilities)]
+
+    def build_execute_tool_description(self) -> str:
+        declarations = generate_stubs(self._sorted_capabilities(), flat_fns=self.tools)
+        return (
+            "Execute JavaScript with CodeMode host tools.\n\n"
+            "The `code` parameter accepts either:\n"
+            "1. A function expression (e.g. `async () => { ... }`). The "
+            "function is called automatically and its return value becomes "
+            "the `result`.\n"
+            "2. Bare statements (e.g. `const v = await codemode.env.get("
+            '{ key: "HOME" }); return v;`). These are auto-wrapped in an '
+            "async function. Use `return` to produce a `result`.\n\n"
+            "Rules:\n"
+            "- `return` a JSON-serializable value (string, number, boolean, "
+            "array, or plain object). Avoid returning `undefined`.\n"
+            "- `console.log()` output is captured in the `logs` field, not "
+            "in `result`.\n"
+            "- `await` works in both forms.\n\n"
+            "Examples:\n"
+            "```js\n"
+            "// Function expression\n"
+            "async () => {\n"
+            '  const val = await codemode.env.get({ key: "HOME" });\n'
+            "  return val;\n"
+            "}\n"
+            "```\n"
+            "```js\n"
+            "// Bare statements (auto-wrapped)\n"
+            'const val = await codemode.env.get({ key: "HOME" });\n'
+            "return val;\n"
+            "```\n\n"
+            "The `codemode` global provides the following TypeScript "
+            "declarations:\n\n"
+            "```ts\n"
+            f"{declarations}\n"
+            "```"
+        )
+
+    # ------------------------------------------------------------------
+    # Search
+    # ------------------------------------------------------------------
+
+    def search(self, query: str, *, limit: int = 20) -> list[dict[str, str | None]]:
+        normalized = query.strip().lower()
+        if not normalized or limit <= 0:
+            return []
+
+        entries = self._collect_entries()
+        scored: list[tuple[int, str, dict[str, str | None]]] = []
+
+        for entry in entries:
+            score = self._score(entry, normalized)
+            if score > 0:
+                scored.append((score, entry["name"] or "", entry))
+
+        scored.sort(key=lambda item: (-item[0], item[1]))
+        return [entry for _, _, entry in scored[:limit]]
+
+    def _collect_entries(self) -> list[dict[str, str | None]]:
+        entries: list[dict[str, str | None]] = []
+        for cap in self._sorted_capabilities():
+            namespace = cap.namespace
+            entries.append(
+                {
+                    "name": namespace,
+                    "kind": "capability",
+                    "description": cap.description or None,
+                }
+            )
+            for fn_name, fn in sorted(cap.exports().items()):
+                entries.append(
+                    {
+                        "name": f"{namespace}.{fn_name}",
+                        "kind": "method",
+                        "description": first_doc_line(fn),
+                    }
+                )
+        for name, fn in sorted(self.tools.items()):
+            entries.append(
+                {
+                    "name": name,
+                    "kind": "tool",
+                    "description": first_doc_line(fn),
+                }
+            )
+        return entries
+
+    @staticmethod
+    def _score(entry: dict[str, str | None], query: str) -> int:
+        name = (entry.get("name") or "").lower()
+        description = (entry.get("description") or "").lower()
+        searchable = f"{name} {description}"
+
+        if query not in searchable:
+            return 0
+
+        if name == query:
+            return 3
+        if query in name:
+            return 2
+        return 1

py_codemode-0.1.1/src/codemode/mcp/server.py

@@ -0,0 +1,139 @@
+"""CodeMode MCP server."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any, Callable, Iterable
+
+from codemode.executor import Capability, Executor, HostFn, RunCompleted, RunFailed
+
+from .registry import MCPRegistry
+
+
+class CodeModeServer:
+    """MCP server wrapper around CodeMode's executor and registry."""
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        capabilities: Iterable[Capability] | None = None,
+        timeout_s: float = 60.0,
+        max_heap_bytes: int = 16 * 1024 * 1024,
+        enable_search: bool = False,
+    ) -> None:
+        self.name = name
+        self.capabilities = list(capabilities or [])
+        self.timeout_s = timeout_s
+        self.max_heap_bytes = max_heap_bytes
+        self.enable_search = enable_search
+        self.registry = MCPRegistry(self.capabilities)
+        self._mcp_server: Any | None = None
+
+    def tool(self) -> Callable[[HostFn], HostFn]:
+        """Decorator to register a tool.
+
+        The tool name is taken from the function's ``__name__`` and the
+        description from its docstring.
+
+        Example::
+
+            @server.tool()
+            async def echo(text: str) -> str:
+                \"\"\"Echo the input text.\"\"\"
+                return text
+        """
+
+        def decorator(fn: HostFn) -> HostFn:
+            name = getattr(fn, "__name__", None)
+            if not name:
+                raise ValueError("tool function must have a __name__")
+            registered = self.registry.register_tool(name, fn)
+            self._mcp_server = None  # invalidate cached MCP server
+            return registered
+
+        return decorator
+
+    def build_executor(self) -> Executor:
+        return Executor(
+            timeout_s=self.timeout_s,
+            max_heap_bytes=self.max_heap_bytes,
+            capabilities=self.capabilities,
+        )
+
+    def search_tools(self, query: str, *, limit: int = 20) -> dict[str, Any]:
+        """Search registered tools/capabilities by name or description."""
+        return {
+            "query": query,
+            "results": self.registry.search(query, limit=limit),
+        }
+
+    async def execute_code(self, code: str) -> dict[str, Any]:
+        """Run JavaScript and return a transport-agnostic JSON-friendly payload."""
+        async with self.build_executor() as executor:
+            event = await executor.execute(code, fns=self.registry.tools)
+        return self._normalize_execute_result(event)
+
+    def _load_mcp_server_class(self) -> type[Any]:
+        try:
+            module = import_module("mcp.server.fastmcp")
+            return module.FastMCP
+        except Exception as exc:  # pragma: no cover
+            raise ImportError(
+                "MCP SDK is required for transport adapters. "
+                "Install with `codemode[mcp]`."
+            ) from exc
+
+    @property
+    def mcp(self) -> Any:
+        """Return the underlying ``FastMCP`` server instance.
+
+        The instance is lazily built and cached.  Registering new tools via
+        :meth:`tool` invalidates the cache so subsequent access picks up the
+        new tool.
+
+        Use the returned object's own transport methods, e.g.
+        ``server.mcp.run(transport="stdio")``.
+        """
+        if self._mcp_server is not None:
+            return self._mcp_server
+
+        mcp_server_cls = self._load_mcp_server_class()
+        mcp_server = mcp_server_cls(self.name)
+
+        @mcp_server.tool(
+            name="execute",
+            description=self.registry.build_execute_tool_description(),
+        )
+        async def execute(code: str) -> dict[str, Any]:
+            return await self.execute_code(code)
+
+        if self.enable_search:
+
+            @mcp_server.tool(
+                name="search",
+                description="Search registered CodeMode capabilities and tools.",
+            )
+            async def search(query: str, limit: int = 20) -> dict[str, Any]:
+                return self.search_tools(query, limit=limit)
+
+        self._mcp_server = mcp_server
+        return mcp_server
+
+    @staticmethod
+    def _normalize_execute_result(
+        event: RunCompleted | RunFailed,
+    ) -> dict[str, Any]:
+        if isinstance(event, RunCompleted):
+            return {
+                "success": True,
+                "result": event.result,
+                "error": None,
+                "logs": list(event.logs or []),
+            }
+        return {
+            "success": False,
+            "result": None,
+            "error": event.error,
+            "logs": list(event.logs or []),
+        }

py_codemode-0.1.1/src/codemode/stubs.py

@@ -0,0 +1,127 @@
+"""TypeScript declaration generation for codemode host functions."""
+
+from __future__ import annotations
+
+import inspect
+import types
+from typing import Any, Callable, Union, get_args, get_origin
+
+from .executor import Capability, HostFn
+
+
+def _py_to_ts(annotation: Any) -> str:
+    if (
+        annotation
+        in (
+            inspect.Signature.empty,
+            inspect.Parameter.empty,
+        )
+        or annotation is Any
+    ):
+        return "any"
+    if annotation is None or annotation is type(None):
+        return "null"
+    if annotation is str:
+        return "string"
+    if annotation in (int, float):
+        return "number"
+    if annotation is bool:
+        return "boolean"
+
+    origin = get_origin(annotation)
+    args = get_args(annotation)
+
+    if origin in (Union, types.UnionType):
+        non_none = [arg for arg in args if arg is not type(None)]
+        if len(non_none) == 1 and len(non_none) != len(args):
+            return f"{_py_to_ts(non_none[0])} | null"
+        return " | ".join(_py_to_ts(arg) for arg in args) if args else "any"
+
+    if origin is list:
+        item = _py_to_ts(args[0]) if args else "any"
+        return f"{item}[]"
+
+    if origin is dict:
+        if len(args) == 2 and args[0] is str:
+            return f"Record<string, {_py_to_ts(args[1])}>"
+        return "Record<string, any>"
+
+    return "any"
+
+
+def first_doc_line(value: object) -> str | None:
+    """Return the first non-empty docstring line, or *None*."""
+    doc = inspect.getdoc(value)
+    if not doc:
+        return None
+    line = doc.splitlines()[0].strip()
+    return line or None
+
+
+def _fn_stub(name: str, fn: Callable[..., Any], indent: str) -> list[str]:
+    lines: list[str] = []
+
+    doc_line = first_doc_line(fn)
+    if doc_line:
+        # Ensure trailing period for JSDoc consistency.
+        if not doc_line.endswith("."):
+            doc_line += "."
+        escaped = doc_line.replace("*/", "* /")
+        lines.append(f"{indent}/** {escaped} */")
+
+    try:
+        sig = inspect.signature(fn, eval_str=True)
+    except (TypeError, ValueError):
+        lines.append(f"{indent}{name}(args: Record<string, any>): Promise<any>;")
+        return lines
+
+    ret = sig.return_annotation
+    # Top-level `-> None` maps to `void`, while `_py_to_ts` keeps `None` as
+    # `null` for union members (e.g. `str | None` -> `string | null`).
+    ret_ts = "void" if ret in (None, type(None)) else _py_to_ts(ret)
+
+    params = [
+        p
+        for p in sig.parameters.values()
+        if p.name != "self"
+        and p.kind
+        not in (
+            inspect.Parameter.VAR_POSITIONAL,
+            inspect.Parameter.VAR_KEYWORD,
+        )
+    ]
+    fields = ", ".join(
+        (
+            f"{param.name}"
+            f"{'?' if param.default is not inspect.Parameter.empty else ''}: "
+            f"{_py_to_ts(param.annotation)}"
+        )
+        for param in params
+    )
+    args_type = "{}" if not fields else f"{{ {fields} }}"
+
+    lines.append(f"{indent}{name}(args: {args_type}): Promise<{ret_ts}>;")
+    return lines
+
+
+def generate_stubs(
+    capabilities: list[Capability],
+    flat_fns: dict[str, HostFn] | None = None,
+) -> str:
+    """Generate a TypeScript ``declare const codemode`` declaration block."""
+    lines = ["declare const codemode: {"]
+
+    for cap in capabilities:
+        if cap.description:
+            lines.append(f"  /** {cap.description.replace('*/', '* /')} */")
+        lines.append(f"  {cap.namespace}: {{")
+        exports = cap.exports()
+        for fn_name in sorted(exports):
+            lines.extend(_fn_stub(fn_name, exports[fn_name], indent="    "))
+        lines.append("  };")
+
+    for fn_name in sorted(flat_fns or {}):
+        lines.extend(_fn_stub(fn_name, (flat_fns or {})[fn_name], indent="  "))
+
+    lines.append("};")
+    return "\n".join(lines)