Create Standalone Code Execution MCP With Agent Zero

by ADMIN 53 views

This article will guide you through the process of creating a standalone Model Context Protocol (MCP) server using Agent Zero's powerful code execution capabilities. We'll focus on building a minimal, self-contained package that leverages existing Agent Zero code, ensuring a streamlined and efficient solution. If you are looking to execute terminal commands and python code in a secure and controlled environment, this guide is for you. Let's dive in and see how you can easily set this up!

Overview: Building a Standalone MCP

The primary goal here is to package Agent Zero's code execution tool into a standalone MCP. This MCP will enable agents to execute terminal commands and Python code on a host system via standard input/output (stdio) communication. Think of it as creating a mini-application that provides a specific function without needing the full Agent Zero environment. This approach is perfect for scenarios where you need a lightweight, isolated code execution environment.

The key is to reuse as much of the existing Agent Zero code as possible. We're not reinventing the wheel; we're simply repackaging it for a specific purpose. This minimizes the risk of introducing bugs and ensures that we benefit from the robustness of Agent Zero's battle-tested components.

Architecture Pattern: Following Agent Zero's Lead

To ensure consistency and maintainability, we'll adhere strictly to Agent Zero's established architectural patterns. This means:

  • Keeping helper modules unchanged wherever feasible.
  • Preserving the print_style and log utilities.
  • Using the established tty_session and shell_local architecture.
  • Maintaining the core logic of the code execution tool.

By sticking to these patterns, we ensure that our standalone MCP integrates seamlessly with existing Agent Zero workflows and remains easy to understand and maintain. This approach also simplifies troubleshooting and future updates.

Package Structure: Organizing Our MCP

The standalone MCP will have a well-defined directory structure, making it easy to navigate and manage. Here's the layout:

code-execution-mcp/
├── main.py                          # MCP server entry point
├── code_execution_tool.py           # Stripped version of Agent Zero's tool
├── helpers/
│   ├── tty_session.py              # Copy as-is
│   ├── shell_local.py              # Copy as-is
│   ├── print_style.py              # Copy as-is
│   ├── log.py                      # Minimal placeholder version
│   └── strings.py                  # Copy as-is
├── prompts/
│   ├── fw.code.info.md             # Copy as-is
│   ├── fw.code.no_output.md        # Copy as-is
│   ├── fw.code.max_time.md         # Copy as-is
│   ├── fw.code.no_out_time.md      # Copy as-is
│   ├── fw.code.pause_time.md     # Copy as-is
│   ├── fw.code.pause_dialog.md     # Copy as-is
│   └── fw.code.reset.md            # Copy as-is
├── pyproject.toml                   # Package definition
└── README.md                        # Usage instructions

Let's break down each component:

  • main.py: This is the entry point for our MCP server. It initializes the server, registers the tools, and handles communication.
  • code_execution_tool.py: A stripped-down version of Agent Zero's code execution tool, tailored for standalone use.
  • helpers/: This directory contains helper modules, including tty_session.py, shell_local.py, print_style.py, log.py, and strings.py. These modules provide essential functionalities for terminal session management, output formatting, and logging.
  • prompts/: This directory holds markdown prompt files used by the code execution tool.
  • pyproject.toml: This file defines the package metadata and dependencies.
  • README.md: This file provides instructions on how to use the MCP.

File Specifications: Diving into the Details

Now, let's take a closer look at each file and its role in the standalone MCP.

1. main.py: The MCP Server Entry Point

main.py is the heart of our standalone MCP. It's responsible for initializing the MCP server, registering the tools, and handling communication via stdio. Here's what it does:

  • Initializes the MCP server with stdio transport using the fastmcp package.
  • Registers four core tools: execute_terminal, execute_python, get_output, and reset_terminal. These tools expose the code execution capabilities of our MCP.
  • Reads configuration from environment variables or stdin, allowing for flexible setup.
  • Each tool calls corresponding methods in the CodeExecutionTool class, delegating the actual execution logic.
  • Crucially, there's no networking involved. All communication happens via stdio, keeping the MCP lightweight and secure.

The configuration structure supports the following parameters:

{
  "executable": "/bin/bash",
  "init_commands": ["source /venv/bin/activate"],
  "options": {
    "first_output_timeout": 30,
    "between_output_timeout": 15,
    "dialog_timeout": 5,
    "max_exec_timeout": 180
  }
}
  • executable: The path to the shell executable (e.g., /bin/bash or cmd.exe).
  • init_commands: A list of commands to execute when a new shell session is created (e.g., activating a virtual environment).
  • options: A dictionary of timeout settings, including first_output_timeout, between_output_timeout, dialog_timeout, and max_exec_timeout. These timeouts help prevent runaway processes and ensure the MCP remains responsive.

2. code_execution_tool.py: The Stripped-Down Execution Engine

This file is a modified version of Agent Zero's code execution tool, optimized for standalone operation. The goal is to remove unnecessary dependencies and features while retaining the core functionality.

What we remove:

  • All SSH-related code, as we're focusing on stdio communication.
  • All NodeJS-related code, simplifying the execution environment.
  • Agent context dependencies (references to self.agent), making the tool more self-contained.
  • Tool base class inheritance, as we don't need the complexity of a larger framework.
  • handle_intervention calls, streamlining the execution flow.

What we keep:

  • All terminal session management logic, ensuring we can handle multiple sessions effectively.
  • Python execution via IPython, allowing agents to run Python code.
  • Terminal command execution, enabling agents to interact with the underlying system.
  • Output reading with all timeout logic, crucial for preventing hangs and ensuring timely responses.
  • Reset terminal functionality, allowing agents to clear sessions and start fresh.
  • Session management (the shells dictionary), tracking active terminal sessions.
  • Prompt detection patterns, used to identify when a command has finished executing.
  • Output formatting and truncation, ensuring responses are concise and readable.

What we modify:

  • Replace self.agent.read_prompt() calls with direct file reading from the prompts/ directory. This eliminates the dependency on the Agent Zero context.
  • Replace self.agent.config references with init parameters (executable, init_commands, timeouts). This makes the tool configurable without relying on a global configuration object.
  • Replace self.agent.context.log with a minimal log placeholder, as we don't need full-fledged logging in this standalone setup.
  • Make the State class hold the shells dictionary and configuration, centralizing session management.
  • Initialize LocalInteractiveSession with a configurable executable instead of hardcoding /bin/bash. This allows users to specify their preferred shell.

3. helpers/tty_session.py: Terminal Session Management

This file is copied as-is from Agent Zero. It provides the core logic for managing terminal sessions, including handling input, output, and signals. No modifications are needed, as it's already designed to be standalone.

4. helpers/shell_local.py: Local Shell Interaction

This file is also copied from Agent Zero, with one crucial modification: the __init__ method is changed to accept an executable parameter instead of hardcoding /bin/bash. This allows us to specify the shell executable via the MCP configuration.

5. helpers/print_style.py: Output Formatting and Logging

This file is copied as-is from Agent Zero. It provides utilities for formatting output and logging messages. We keep all functionality, including log file creation, as the MCP server can write to its own log file for debugging and monitoring.

6. helpers/log.py: Minimal Logging Placeholder

In this standalone MCP, we don't need a full-fledged logging system. However, the code_execution_tool.py still references logging functions. To avoid errors, we create a minimal placeholder version of log.py.

This placeholder includes only the Log and LogItem classes with their signatures. All methods are no-ops or return empty values. This allows the code_execution_tool.py to call self.log.update() without issues, while effectively disabling logging.

7. helpers/strings.py: Text Manipulation Utilities

This file is copied as-is from Agent Zero. It provides utilities for text manipulation, such as truncation, which are used by the code_execution_tool.py to ensure responses are concise and readable.

8. Prompt Files: System Messages

We copy all seven markdown prompt files from Agent Zero's prompts/ directory. These files contain system messages that are returned to the agent in various scenarios, such as when a command times out or produces no output. By including these files, we ensure that our standalone MCP behaves consistently with Agent Zero.

MCP Tool Definitions: Exposing Functionality

Our standalone MCP exposes four core tools:

Tool 1: execute_terminal

This tool allows agents to execute terminal commands in a specified session.

{
  "name": "execute_terminal",
  "description": "Execute a terminal command in the specified session",
  "inputSchema": {
    "type": "object",
    "properties": {
      "command": {"type": "string"},
      "session": {"type": "integer", "default": 0}
    },
    "required": ["command"]
  }
}

Tool 2: execute_python

This tool allows agents to execute Python code via IPython in a specified session.

{
  "name": "execute_python",
  "description": "Execute Python code via IPython in the specified session",
  "inputSchema": {
    "type": "object",
    "properties": {
      "code": {"type": "string"},
      "session": {"type": "integer", "default": 0}
    },
    "required": ["code"]
  }
}

Tool 3: get_output

This tool allows agents to retrieve accumulated output from a terminal session.

{
  "name": "get_output",
  "description": "Get accumulated output from a terminal session",
  "inputSchema": {
    "type": "object",
    "properties": {
      "session": {"type": "integer", "default": 0}
    }
  }
}

Tool 4: reset_terminal

This tool allows agents to reset a terminal session, closing and reopening it.

{
  "name": "reset_terminal",
  "description": "Reset a terminal session, closing and reopening it",
  "inputSchema": {
    "type": "object",
    "properties": {
      "session": {"type": "integer", "default": 0}
    }
  }
}

Dependencies: Defining Our Requirements

Our standalone MCP has a few dependencies, which are defined in the pyproject.toml file:

[project]
name = "code-execution-mcp"
version = "0.1.0"
dependencies = [
    "fastmcp>=2.0.0",
    "ipython>=8.0.0",
    "asyncio",
    "nest_asyncio",
]

[project.optional-dependencies]
windows = ["pywinpty>=2.0.0"]

[project.scripts]
code-execution-mcp = "main:main"
  • fastmcp: The library for creating MCP servers.
  • ipython: The interactive Python shell, used for executing Python code.
  • asyncio and nest_asyncio: Libraries for asynchronous programming.
  • pywinpty (optional): A library for terminal emulation on Windows.

Implementation Notes: Key Considerations

Session Management

We use Agent Zero's existing session dictionary pattern to manage multiple terminal sessions. Each session maintains its own shell state, allowing agents to run commands and code in isolation.

Executable Configuration

We default to /bin/bash on Unix-like systems and cmd.exe on Windows. However, users can override this via the MCP configuration, allowing them to specify their preferred shell.

Init Commands

The MCP supports executing a list of initialization commands when a new session is created. This is useful for tasks such as activating virtual environments or setting environment variables.

Timeout Configuration

We map timeout options from the MCP configuration to the code execution tool's parameters, allowing users to control the execution time of commands and code.

Output Handling

We ensure that all output returned by the MCP is clean and free of control codes. We also use Agent Zero's truncation logic to limit the size of responses.

Python Execution

We execute Python code via the ipython -c command, ensuring proper escaping of special characters. We also add a python> prefix to the output for clarity.

Windows Compatibility

The tty_session module already handles Windows via pywinpty. We default to cmd.exe on Windows and include pywinpty as an optional dependency.

Critical Don'ts: Staying on Track

To ensure we build a focused and maintainable MCP, it's crucial to avoid certain pitfalls:

  • DO NOT implement new shell/TTY logic. Use Agent Zero's tested implementation.
  • DO NOT add any networking/HTTP capabilities. Sticking to stdio is key.
  • DO NOT create new logging systems. The existing print_style is sufficient.
  • DO NOT add configuration validation beyond basic type checks.
  • DO NOT implement authentication/security. The MCP client is responsible for this.
  • DO NOT add progress bars, spinners, or UI elements. Keep it simple.
  • DO NOT create custom exception types. Use standard Python exceptions.
  • DO NOT add caching/optimization layers. Focus on functionality first.
  • DO NOT implement plugin systems or extensibility hooks. This is a standalone tool.
  • DO NOT write any code not directly from Agent Zero or required for MCP glue.

Testing Considerations: Ensuring Quality

Virtual Environment Behavior

When the MCP is launched from a virtual environment, the shell session may not inherit the environment activation. Users should use init_commands to explicitly activate the virtual environment if needed. This behavior should be clearly documented in the README.

Windows Testing

The tty_session module uses pywinpty, which should work on Windows but is not thoroughly tested in this context. Windows support should be considered experimental, and users should be encouraged to test with cmd.exe and PowerShell.

Success Criteria: Defining Done

We'll consider the standalone MCP a success when it meets the following criteria:

  1. The MCP server starts via stdio without errors.
  2. All four tools are discoverable via MCP list_tools.
  3. Terminal commands execute and return output.
  4. Python code executes via IPython.
  5. Multiple sessions work independently.
  6. Reset clears the session and starts fresh.
  7. Timeouts work as configured.
  8. Output is clean (no ANSI codes in responses).
  9. Init commands execute on session creation.
  10. Works on Linux (tested) and Windows (untested but should work).

Notes: Key Takeaways

  • This MCP allows any agent to execute code on the host system.
  • Security is the MCP client's responsibility, not the server's.
  • The implementation should be under 500 lines of code (excluding copied helpers).
  • The goal is to expose existing functionality, not recreate it.
  • We should preserve all of Agent Zero's battle-tested code execution logic.
  • The only "new" code is the MCP server glue in main.py.

Conclusion

Creating a standalone code execution MCP with Agent Zero is a powerful way to leverage existing functionality in a focused and efficient manner. By following the guidelines outlined in this article, you can build a minimal, self-contained package that enables agents to execute terminal commands and Python code securely and reliably. This approach is ideal for scenarios where you need a lightweight code execution environment without the overhead of a full Agent Zero deployment. By reusing existing code and adhering to established patterns, you'll create a solution that is easy to maintain, troubleshoot, and integrate into your workflows. So go ahead, start building your standalone MCP and unlock the power of Agent Zero's code execution capabilities!