agent-repl-mcp 0.0.1__tar.gz

agent_repl_mcp-0.0.1/.gitignore

@@ -0,0 +1,4 @@
+.venv
+__pycache__
+dist
+.ruff_cache

agent_repl_mcp-0.0.1/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.5
+Name: agent-repl-mcp
+Version: 0.0.1
+Author: David Vujic
+License-Expression: MIT
+Requires-Python: >=3.12
+Requires-Dist: fastmcp
+Requires-Dist: ipykernel
+Description-Content-Type: text/markdown
+
+# Python REPL MCP
+A REPL that agents can use during development.
+
+Current status: __Work in Progress__.

agent_repl_mcp-0.0.1/README.md

@@ -0,0 +1,4 @@
+# Python REPL MCP
+A REPL that agents can use during development.
+
+Current status: __Work in Progress__.

agent_repl_mcp-0.0.1/agent_repl_mcp/agenticpytools/environment/__init__.py

@@ -0,0 +1,2 @@
+from agent_repl_mcp.agenticpytools.environment.core import is_windows, venv_python
+__all__ = ['is_windows', 'venv_python']

agent_repl_mcp-0.0.1/agent_repl_mcp/agenticpytools/environment/core.py

@@ -0,0 +1,29 @@
+import os
+from pathlib import Path
+
+
+def is_windows() -> bool:
+    return os.name == "nt"
+
+
+def windows_venv(venv_dir: Path) -> Path:
+    return venv_dir / "Scripts" / "python.exe"
+
+
+def venv_path(venv_dir: Path) -> Path:
+    return windows_venv(venv_dir) if is_windows() else venv_dir / "bin" / "python"
+
+
+def venv_python(project_path: str | Path) -> Path:
+    """Find the Python interpreter of the project's venv."""
+    project = Path(project_path).expanduser().resolve()
+
+    candidates = [project / ".venv"]
+
+    for venv_dir in candidates:
+        exe = venv_path(venv_dir)
+
+        if exe.exists():
+            return exe
+
+    raise FileNotFoundError(f"No virtual environment found in {project}")

agent_repl_mcp-0.0.1/agent_repl_mcp/agenticpytools/kernel/__init__.py

@@ -0,0 +1,3 @@
+from agent_repl_mcp.agenticpytools.kernel import client
+from agent_repl_mcp.agenticpytools.kernel.content import capture
+__all__ = ['capture', 'client']

agent_repl_mcp-0.0.1/agent_repl_mcp/agenticpytools/kernel/client.py

@@ -0,0 +1,43 @@
+from pathlib import Path
+from agent_repl_mcp.agenticpytools import storage
+from agent_repl_mcp.agenticpytools.kernel.close import shutdown_adopted
+from agent_repl_mcp.agenticpytools.kernel.core import get_kernel_name
+from agent_repl_mcp.agenticpytools.kernel.create import create_and_start_kernel
+from jupyter_client import BlockingKernelClient
+
+def create(path: str, timeout: int) -> BlockingKernelClient:
+    project = Path(path).expanduser().resolve()
+    kernel_name = get_kernel_name(project.name)
+    stored = storage.load_entry(kernel_name)
+    if stored:
+        try:
+            kc = BlockingKernelClient()
+            kc.load_connection_file(stored['connection_file'])
+            kc.start_channels()
+            kc.wait_for_ready(timeout=timeout)
+            if kc.is_alive():
+                return kc
+            else:
+                shutdown_adopted(stored['connection_file'])
+                storage.delete_entry(kernel_name)
+        except (FileNotFoundError, RuntimeError):
+            shutdown_adopted(stored['connection_file'])
+            storage.delete_entry(kernel_name)
+    km = create_and_start_kernel(project)
+    kc = km.client()
+    kc.start_channels()
+    kc.wait_for_ready(timeout=timeout)
+    if not kc.is_alive():
+        shutdown_adopted(str(km.connection_file))
+        raise RuntimeError('Failed to create or connect to kernel.')
+    storage.save_entry(kernel_name, str(km.connection_file), path)
+    return kc
+
+def close(project: Path) -> None:
+    kernel_name = get_kernel_name(project.name)
+    stored = storage.load_entry(kernel_name)
+    if not stored:
+        print('not running')
+        return
+    shutdown_adopted(stored['connection_file'])
+    storage.delete_entry(kernel_name)

agent_repl_mcp-0.0.1/agent_repl_mcp/agenticpytools/kernel/close.py

@@ -0,0 +1,32 @@
+import time
+from pathlib import Path
+
+from jupyter_client import BlockingKernelClient
+
+
+def shutdown_adopted(connection_file: str) -> None:
+    """Shut down a kernel we didn't spawn and clean up its files."""
+    kc = BlockingKernelClient()
+
+    try:
+        kc.load_connection_file(connection_file)
+    except FileNotFoundError:
+        return
+
+    try:
+        kc.start_channels()
+        kc.shutdown()
+        deadline = time.monotonic() + 10
+
+        while time.monotonic() < deadline:
+            if not kc.is_alive():
+                break
+
+            time.sleep(0.2)
+    finally:
+        kc.stop_channels()
+
+    Path(connection_file).unlink(missing_ok=True)
+
+    for f in Path(connection_file).parent.glob(Path(connection_file).stem + "-ipc-*"):
+        f.unlink(missing_ok=True)

agent_repl_mcp-0.0.1/agent_repl_mcp/agenticpytools/kernel/content.py

@@ -0,0 +1,36 @@
+from queue import Empty
+from typing import Any
+
+from jupyter_client import BlockingKernelClient
+
+
+def capture(
+    kc: BlockingKernelClient,
+    msg_id: Any,
+    timeout: int,
+) -> tuple[list, list, dict[str, Any] | None, str | None]:
+    """Capture the stdout, stderr, result and error."""
+    stdout, stderr, result, error = [], [], None, None
+
+    while True:
+        try:
+            msg = kc.get_iopub_msg(timeout=timeout)
+        except Empty:
+            raise TimeoutError("kernel didn't finish")
+
+        if msg["parent_header"].get("msg_id") != msg_id:
+            continue
+
+        msg_type = msg["header"]["msg_type"]
+        content = msg["content"]
+
+        if msg_type == "stream":
+            (stdout if content["name"] == "stdout" else stderr).append(content["text"])
+        elif msg_type in ("display_data", "execute_result"):
+            result = content["data"]
+        elif msg_type == "error":
+            error = "\n".join(content["traceback"])
+        elif msg_type == "status" and content["execution_state"] == "idle":
+            break
+
+    return stdout, stderr, result, error

agent_repl_mcp-0.0.1/agent_repl_mcp/agenticpytools/kernel/core.py

@@ -0,0 +1,16 @@
+from pathlib import Path
+from agent_repl_mcp.agenticpytools.environment import is_windows
+from jupyter_core.paths import jupyter_runtime_dir
+
+def get_kernel_name(project_name: str) -> str:
+    return f'repl-{project_name}'
+
+def get_connection_file_path(kernel_id: str) -> Path:
+    runtime_dir = Path(jupyter_runtime_dir())
+    return runtime_dir / f'kernel-{kernel_id}.json'
+
+def get_transport() -> str:
+    return 'tcp' if is_windows() else 'ipc'
+
+def spec_data(argv: list[str], kernel_name: str) -> dict:
+    return {'argv': argv, 'display_name': f'Python REPL ({kernel_name})', 'language': 'python'}

agent_repl_mcp-0.0.1/agent_repl_mcp/agenticpytools/kernel/create.py

@@ -0,0 +1,37 @@
+import json
+import tempfile
+import uuid
+from pathlib import Path
+from agent_repl_mcp.agenticpytools.environment import venv_python
+from agent_repl_mcp.agenticpytools.kernel.core import get_connection_file_path, get_kernel_name, get_transport, spec_data
+from jupyter_client import KernelManager
+from jupyter_client.kernelspec import KernelSpecManager
+
+def create_kernel_manager(kernel_name: str, connection_file: str, **_kwargs) -> KernelManager:
+    transport = get_transport()
+    return KernelManager(kernel_name=kernel_name, connection_file=connection_file, transport=transport)
+
+def ensure_project_spec(kernel_name: str, current_python: str) -> None:
+    """Install a kernelspec pointing at the project's venv, if missing."""
+    argv = [current_python, '-m', 'ipykernel_launcher', '-f', '{connection_file}']
+    ksm = KernelSpecManager()
+    if kernel_name in ksm.get_all_specs():
+        return
+    with tempfile.TemporaryDirectory() as tmp:
+        spec_dir = Path(tmp) / kernel_name
+        spec_dir.mkdir()
+        data = spec_data(argv, kernel_name)
+        spec_path = spec_dir / 'kernel.json'
+        spec_path.write_text(json.dumps(data))
+        ksm.install_kernel_spec(str(spec_dir), kernel_name=kernel_name, user=True)
+
+def create_and_start_kernel(project: Path) -> KernelManager:
+    kernel_name = get_kernel_name(project.name)
+    current_python = str(venv_python(project))
+    ensure_project_spec(kernel_name, current_python)
+    transport = get_transport()
+    kernel_id = str(uuid.uuid4())
+    connection_file = str(get_connection_file_path(kernel_id))
+    km = KernelManager(kernel_name=kernel_name, connection_file=connection_file, transport=transport)
+    km.start_kernel()
+    return km

agent_repl_mcp-0.0.1/agent_repl_mcp/agenticpytools/repl_mcp/__init__.py

@@ -0,0 +1,2 @@
+from agent_repl_mcp.agenticpytools.repl_mcp import core
+__all__ = ['core']

agent_repl_mcp-0.0.1/agent_repl_mcp/agenticpytools/repl_mcp/core.py

@@ -0,0 +1,35 @@
+from pathlib import Path
+from typing import Any
+from agent_repl_mcp.agenticpytools.kernel import capture, client
+from fastmcp import FastMCP
+mcp = FastMCP('My MCP Server')
+TIMEOUT = 30
+
+def return_data(stdout: list | None=None, stderr: list | None=None, result: dict | None=None, error: str | None=None) -> dict[str, Any | None]:
+    return {'stdout': stdout, 'stderr': stderr, 'result': result, 'error': error}
+
+@mcp.tool
+def run(data: str, project_full_path: str) -> dict[str, Any | None]:
+    """Execute code in the kernel and return the output.
+
+    Returns a dictionary
+    stdout: from standard output
+    stderr: from standard error
+    result: from code evaluation
+    error: any caught errors during evaluation
+    """
+    kc = client.create(project_full_path, TIMEOUT)
+    msg_id = kc.execute(data)
+    try:
+        stdout, stderr, result, error = capture(kc, msg_id, TIMEOUT)
+    except TimeoutError:
+        return return_data(error='Timeout: try again.')
+    return return_data(stdout, stderr, result, error)
+
+@mcp.tool
+def close(project_full_path: str) -> None:
+    """Close the kernel."""
+    project = Path(project_full_path).expanduser().resolve()
+    client.close(project)
+if __name__ == '__main__':
+    mcp.run()

agent_repl_mcp-0.0.1/agent_repl_mcp/agenticpytools/storage/__init__.py

@@ -0,0 +1,2 @@
+from agent_repl_mcp.agenticpytools.storage.core import delete_entry, list_entries, load_entry, save_entry
+__all__ = ['delete_entry', 'list_entries', 'load_entry', 'save_entry']

agent_repl_mcp-0.0.1/agent_repl_mcp/agenticpytools/storage/connection.py

@@ -0,0 +1,14 @@
+import sqlite3
+from pathlib import Path
+from agent_repl_mcp.agenticpytools.storage.schema import PROJECT_KERNEL_SCHEMA
+DB_PATH = Path.home() / '.python-repl-mcp' / 'kernels.db'
+
+def get_conn() -> sqlite3.Connection:
+    """Open a connection with sane settings. Caller owns it (use as context manager)."""
+    DB_PATH.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(DB_PATH, timeout=10)
+    conn.row_factory = sqlite3.Row
+    conn.execute('PRAGMA journal_mode=WAL')
+    conn.execute('PRAGMA foreign_keys=ON')
+    conn.execute(PROJECT_KERNEL_SCHEMA)
+    return conn

agent_repl_mcp-0.0.1/agent_repl_mcp/agenticpytools/storage/core.py

@@ -0,0 +1,22 @@
+"""Sqlite-backed kernel registry."""
+from agent_repl_mcp.agenticpytools.storage.connection import get_conn
+
+def load_entry(kernel_name: str) -> dict | None:
+    with get_conn() as conn:
+        row = conn.execute('SELECT kernel_name, connection_file, project_path FROM kernels WHERE kernel_name = ?', (kernel_name,)).fetchone()
+    return dict(row) if row else None
+
+def save_entry(kernel_name: str, connection_file: str, project_path: str) -> None:
+    with get_conn() as conn:
+        conn.execute("INSERT INTO kernels (kernel_name, connection_file, project_path)\n               VALUES (?, ?, ?)\n               ON CONFLICT(kernel_name) DO UPDATE SET\n                   connection_file = excluded.connection_file,\n                   project_path    = excluded.project_path,\n                   updated_at      = datetime('now')", (kernel_name, connection_file, project_path))
+        conn.commit()
+
+def delete_entry(kernel_name: str) -> None:
+    with get_conn() as conn:
+        conn.execute('DELETE FROM kernels WHERE kernel_name = ?', (kernel_name,))
+        conn.commit()
+
+def list_entries() -> list[dict]:
+    """Handy for a future 'status' tool."""
+    with get_conn() as conn:
+        return [dict(r) for r in conn.execute('SELECT * FROM kernels ORDER BY updated_at DESC')]

agent_repl_mcp-0.0.1/agent_repl_mcp/agenticpytools/storage/schema.py

@@ -0,0 +1,9 @@
+PROJECT_KERNEL_SCHEMA = """
+CREATE TABLE IF NOT EXISTS kernels (
+    kernel_name     TEXT PRIMARY KEY,
+    connection_file TEXT NOT NULL,
+    project_path    TEXT NOT NULL,
+    created_at      TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at      TEXT NOT NULL DEFAULT (datetime('now'))
+);
+"""

agent_repl_mcp-0.0.1/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling", "hatch-polylith-bricks"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agent-repl-mcp"
+version = "0.0.1"
+authors = [
+    { name = "David Vujic" }
+]
+requires-python = ">=3.12"
+repository = "https://github.com/DavidVujic/agentic-python-tools"
+license = "MIT"
+readme = "README.md"
+dependencies = ["fastmcp", "ipykernel"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["agent_repl_mcp"]
+
+[tool.hatch.build.hooks.polylith-bricks]
+
+[tool.polylith.build]
+top-namespace = "agent_repl_mcp"
+
+[tool.polylith.bricks]
+"../../bases/agenticpytools/repl_mcp" = "agenticpytools/repl_mcp"
+"../../components/agenticpytools/environment" = "agenticpytools/environment"
+"../../components/agenticpytools/kernel" = "agenticpytools/kernel"
+"../../components/agenticpytools/storage" = "agenticpytools/storage"