mcp-python-repl 0.1.0__py3-none-any.whl

mcp_python_repl/session.py

@@ -0,0 +1,142 @@
+"""
+Session management for mcp-python-repl.
+
+Each session holds an isolated Python namespace and execution history.
+Sessions are identified by an opaque ``session_id`` (UUID) and expire
+after a configurable TTL.
+"""
+
+from __future__ import annotations
+
+import threading
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+from .config import Config
+
+
+@dataclass
+class ExecutionRecord:
+    """A single code-execution record for audit / debug."""
+
+    timestamp: str
+    code_preview: str
+    status: str
+    new_vars: list[str] = field(default_factory=list)
+    modified_vars: list[str] = field(default_factory=list)
+    error: str | None = None
+
+
+@dataclass
+class Session:
+    """An isolated Python execution session."""
+
+    session_id: str
+    created_at: datetime
+    last_used: datetime
+    namespace: dict[str, Any] = field(default_factory=dict)
+    history: list[ExecutionRecord] = field(default_factory=list)
+
+    # ------------------------------------------------------------------
+    def touch(self) -> None:
+        self.last_used = datetime.now(timezone.utc)
+
+    def is_expired(self, ttl_minutes: int) -> bool:
+        return datetime.now(timezone.utc) - self.last_used > timedelta(minutes=ttl_minutes)
+
+    def variable_summary(self) -> dict[str, str]:
+        """Return {name: type_name} for every user variable."""
+        return {k: type(v).__name__ for k, v in self.namespace.items() if not k.startswith("_")}
+
+
+class SessionManager:
+    """Thread-safe session store with automatic eviction."""
+
+    def __init__(self, config: Config) -> None:
+        self._config = config
+        self._sessions: dict[str, Session] = {}
+        self._lock = threading.Lock()
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def create_session(self) -> Session:
+        """Create a new session, evicting stale ones first."""
+        self._evict_expired()
+
+        with self._lock:
+            if len(self._sessions) >= self._config.max_sessions:
+                # Evict the oldest session
+                oldest_id = min(
+                    self._sessions,
+                    key=lambda sid: self._sessions[sid].last_used,
+                )
+                del self._sessions[oldest_id]
+
+            now = datetime.now(timezone.utc)
+            session = Session(
+                session_id=uuid.uuid4().hex[:12],
+                created_at=now,
+                last_used=now,
+            )
+            self._sessions[session.session_id] = session
+            return session
+
+    def get_session(self, session_id: str) -> Session | None:
+        """Retrieve a session by id (returns *None* if expired / missing)."""
+        with self._lock:
+            session = self._sessions.get(session_id)
+            if session is None:
+                return None
+            if session.is_expired(self._config.session_ttl_minutes):
+                del self._sessions[session_id]
+                return None
+            session.touch()
+            return session
+
+    def get_or_create(self, session_id: str | None) -> Session:
+        """Return existing session or create a new one."""
+        if session_id:
+            session = self.get_session(session_id)
+            if session is not None:
+                return session
+        return self.create_session()
+
+    def delete_session(self, session_id: str) -> bool:
+        with self._lock:
+            return self._sessions.pop(session_id, None) is not None
+
+    def list_sessions(self) -> list[dict[str, Any]]:
+        self._evict_expired()
+        with self._lock:
+            return [
+                {
+                    "session_id": s.session_id,
+                    "created_at": s.created_at.isoformat(),
+                    "last_used": s.last_used.isoformat(),
+                    "variable_count": len(s.variable_summary()),
+                    "history_count": len(s.history),
+                }
+                for s in self._sessions.values()
+            ]
+
+    @property
+    def count(self) -> int:
+        return len(self._sessions)
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def _evict_expired(self) -> None:
+        with self._lock:
+            expired = [
+                sid
+                for sid, s in self._sessions.items()
+                if s.is_expired(self._config.session_ttl_minutes)
+            ]
+            for sid in expired:
+                del self._sessions[sid]

mcp_python_repl-0.1.0.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: mcp-python-repl
+Version: 0.1.0
+Summary: A production-grade MCP server providing a persistent Python REPL with multi-session support, sandboxing, and timeout protection.
+Project-URL: Homepage, https://github.com/soufiane-aazizi/mcp-python-repl
+Project-URL: Repository, https://github.com/soufiane-aazizi/mcp-python-repl
+Project-URL: Issues, https://github.com/soufiane-aazizi/mcp-python-repl/issues
+Author: Soufiane Aazizi
+License-Expression: MIT
+Keywords: agent,interpreter,llm,mcp,model-context-protocol,python,repl
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Interpreters
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.7.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 🐍 mcp-python-repl
+
+A **production-grade** MCP server providing a persistent Python REPL with multi-session support, sandboxing, and timeout protection.
+
+Built for LLM agents that need to execute Python code across multiple turns with **variables that persist between calls**.
+
+## ✨ Features
+
+| Feature | Description |
+|---|---|
+| **Multi-session** | Isolated sessions with unique IDs — run parallel workflows |
+| **Persistent namespace** | Variables survive across calls within a session |
+| **Timeout protection** | Configurable execution timeout (SIGALRM on Unix) |
+| **Sandboxing** | Optional mode blocks dangerous modules (`subprocess`, `socket`, etc.) |
+| **Package install** | Install pip packages on-the-fly (prefers `uv` for speed) |
+| **File execution** | Run `.py` files inside the persistent session |
+| **Dual transport** | stdio (local) and streamable-http (remote) |
+| **Full introspection** | List variables, get history, check server status |
+| **Env-based config** | All settings via `REPL_*` environment variables |
+
+## 🚀 Quick Start
+
+### With Claude Desktop / Cursor (stdio)
+
+Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "python-repl": {
+      "command": "uvx",
+      "args": ["mcp-python-repl"]
+    }
+  }
+}
+```
+
+### With uv (local dev)
+
+```bash
+# Clone and run
+git clone https://github.com/soufiane-aazizi/mcp-python-repl.git
+cd mcp-python-repl
+uv run mcp-python-repl
+```
+
+### HTTP transport (remote / multi-client)
+
+```bash
+REPL_TRANSPORT=streamable-http REPL_PORT=8000 uv run mcp-python-repl
+```
+
+## 🛠️ Tools
+
+### Code Execution
+
+| Tool | Description |
+|---|---|
+| `repl_run_code` | Execute Python code with persistent namespace |
+| `repl_run_file` | Execute a `.py` file in the session |
+| `repl_install_package` | Install a pip package (uses `uv` if available) |
+
+### Namespace Management
+
+| Tool | Description |
+|---|---|
+| `repl_list_namespace` | List all variables in a session |
+| `repl_get_variable` | Get the full value of a variable |
+| `repl_set_variable` | Inject a variable from JSON |
+| `repl_delete_variable` | Delete a specific variable |
+| `repl_clear_namespace` | Clear all variables in a session |
+
+### Session Management
+
+| Tool | Description |
+|---|---|
+| `repl_list_sessions` | List all active sessions |
+| `repl_delete_session` | Delete a session and its data |
+
+### Debugging
+
+| Tool | Description |
+|---|---|
+| `repl_get_history` | Get execution history for a session |
+| `repl_server_status` | Server config, Python version, session count |
+
+## 🔄 How Persistence Works
+
+```
+Call 1:  repl_run_code(code="data = [1,2,3]; total = sum(data); result = total")
+         → returns: {"result": 6, "session_id": "a1b2c3d4e5f6", "new_variables": ["data", "total"]}
+
+Call 2:  repl_run_code(code="doubled = [x*2 for x in data]; result = doubled", session_id="a1b2c3d4e5f6")
+         → returns: {"result": [2,4,6], "new_variables": ["doubled"]}
+```
+
+> **Important:** The `result` variable is for returning output to the caller. It does **NOT** persist. Use named variables instead.
+
+## ⚙️ Configuration
+
+All settings are configurable via environment variables:
+
+| Variable | Default | Description |
+|---|---|---|
+| `REPL_TIMEOUT` | `30` | Max execution time in seconds |
+| `REPL_MAX_SESSIONS` | `50` | Maximum concurrent sessions |
+| `REPL_SESSION_TTL` | `120` | Session expiry in minutes |
+| `REPL_MAX_OUTPUT` | `1048576` | Max stdout/stderr capture (bytes) |
+| `REPL_SANDBOX` | `false` | Enable sandboxing (`true`/`false`) |
+| `REPL_TRANSPORT` | `stdio` | Transport: `stdio` or `streamable-http` |
+| `REPL_HOST` | `127.0.0.1` | HTTP host (when using HTTP transport) |
+| `REPL_PORT` | `8000` | HTTP port (when using HTTP transport) |
+| `REPL_WORKDIR` | `cwd` | Working directory for executions |
+
+### Sandbox Mode
+
+When `REPL_SANDBOX=true`, the following modules are blocked:
+
+`subprocess`, `shutil`, `ctypes`, `socket`, `http.server`, `xmlrpc`, `ftplib`, `smtplib`, `telnetlib`, `webbrowser`
+
+And the following builtins are removed: `exec`, `eval`, `compile`, `__import__` (replaced with a restricted version).
+
+## 🧪 Development
+
+```bash
+# Install dev dependencies
+uv sync --extra dev
+
+# Run tests
+uv run pytest -v
+
+# Lint
+uv run ruff check src/ tests/
+
+# Test with MCP Inspector
+npx @modelcontextprotocol/inspector uv run mcp-python-repl
+```
+
+## 📦 Project Structure
+
+```
+mcp-python-repl/
+├── src/mcp_python_repl/
+│   ├── __init__.py       # Package metadata
+│   ├── config.py         # Env-based configuration
+│   ├── session.py        # Multi-session manager with TTL
+│   ├── executor.py       # Python code executor (timeout + sandbox)
+│   └── server.py         # MCP server with all tools
+├── tests/
+│   └── test_core.py      # Unit + integration tests
+├── pyproject.toml        # uv/hatch project config
+├── LICENSE               # MIT
+└── README.md
+```
+
+## 📄 License
+
+MIT — See [LICENSE](LICENSE).

mcp_python_repl-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+mcp_python_repl/config.py,sha256=V1bcy6z8fcTUMzKlhZSPDE2wAguG9Ug32b79BdCCXMg,2570
+mcp_python_repl/executor.py,sha256=uFfw4P6fzAuE4zgKM6VEy82voQslGU3zxI1rrvOAsrw,7575
+mcp_python_repl/server.py,sha256=Shnug32hOh31Qr7TQjnxVrPmg-VxaJGMOhV4m3rn9qQ,21998
+mcp_python_repl/session.py,sha256=GkljC4OtmHojF51grUDYYJ5NAhEW00zPUQmtTPUxmNQ,4671
+mcp_python_repl-0.1.0.dist-info/METADATA,sha256=S_UJIR7zgFeJJV6l334yf3N7oD5P4iObAxnJB0uzPlI,6309
+mcp_python_repl-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mcp_python_repl-0.1.0.dist-info/entry_points.txt,sha256=DHFkUiJlWbQ8SDZpEvCaH1EvOfeuJcDwJ1rWKwTvMww,64
+mcp_python_repl-0.1.0.dist-info/RECORD,,

mcp_python_repl-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mcp_python_repl-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-python-repl = mcp_python_repl.server:main