PRIMS provides a Python-focused MCP server that exposes a single tool, run_code, to execute arbitrary Python code inside a secure, ephemeral sandbox. Each invocation starts a fresh virtual environment, installs requested pip packages, and can mount files before executing the user’s code, then cleans up afterward. This makes it suitable for running isolated Python snippets, testing dependencies, and analyzing outputs without leaking state between runs. The server also ships auxiliary tools (list_dir, preview_file, persist_artifact, mount_file) to inspect workspace, preview files, persist outputs, and manage data mounts, all within the same session context.

To use the server, start it with Python, which binds to http://0.0.0.0:9000/mcp by default. You can interact with the tools via the provided client examples (e.g., python examples/run_code.py, list_tools.py) or directly via MCP calls. The run_code tool accepts Python source and optional dependencies, runs it in a sandbox, streams stdout and stderr back to you, and cleans up the environment after the run. You can also mount remote files once per session with mount_file, then access them from run_code without re-supplying URLs. The available tools together provide a compact, end-to-end environment for executing Python code safely and reproducibly.

Prerequisites:

• Python 3.8+ installed on your system
• Basic familiarity with virtual environments
• Internet access to install dependencies

Local development / running from source:

1. Create a virtual environment and install dependencies: bash chmod +x scripts/setup_env.sh # once, to make the script executable ./scripts/setup_env.sh # creates .venv & installs deps

2. Activate the virtual environment for your shell: source .venv/bin/activate

3. Run the MCP server locally: python -m server.main

   Server binds to http://0.0.0.0:9000/mcp

4. Optional: run the quick start script to dockerize (if provided in repo): bash scripts/docker_run.sh

   Will build and run the container, printing the MCP URL when ready

Docker (alternative):

• Build and run the image, then expose port 9000 as needed. Ensure any required environment variables are set per the container’s README (if applicable).

Prerequisites summary:

• Python 3.8+
• Network access for dependency installation
• Optional: Docker if you plan to use the Docker workflow

Notes and tips:

• The server runs in a sandbox per run; no long-term state is persisted unless you use explicit artifacts or mounts within the session.
• Tools available: run_code, list_dir, preview_file, persist_artifact, mount_file. Use list_tools.py to discover current capabilities in your deployment.
• When using mount_file, the file is downloaded once per session into mounts/<path> and can be accessed by run_code without re-downloading.
• Persist_artifact uploads outputs to a client-provided presigned URL; ensure your relative_path points to existing files in output/.
• If you encounter port binding or network issues, verify that 0.0.0.0:9000 is accessible and that firewall rules allow access to the MCP endpoint.
• If you need to customize dependencies for a run, specify them within the run_code call or provide a session-managed environment configuration if supported by your client.