/ 
MCP-Run-0.100
/ MCP::Run

NAME

MCP::Run - MCP server with a command execution tool

VERSION

version 0.100

SYNOPSIS

use MCP::Run::Bash;

my $server = MCP::Run::Bash->new(
    allowed_commands  => ['ls', 'cat', 'grep'],
    working_directory => '/var/data',
    timeout           => 60,
);
$server->to_stdio;

DESCRIPTION

Base class for MCP servers that expose a command execution tool. Subclasses MCP::Server and registers a run tool via the MCP protocol when instantiated. Subclasses must implement "execute" to provide the actual execution mechanism.

The registered tool accepts a command string, an optional working_directory, and an optional timeout. The tool returns a text result containing the exit code, stdout, and stderr of the executed command.

See MCP::Run::Bash for a concrete implementation using bash -c.

allowed_commands

ArrayRef of command names (first words) that are permitted to run. When set, any command whose first word is not in this list is rejected with an error result. Defaults to undef, which allows all commands.

my $server = My::MCPServer->new(
    allowed_commands => ['ls', 'cat', 'grep'],
);

validator

Coderef that validates a command before execution. The coderef is called as:

my $allow = $validator->($command, $working_directory);

Return "1" (string or number) to allow the command. Return any other defined value (a string reason, undef, or a false value) to deny it.

my $server = MCP::Run::Bash->new(
    validator => sub {
        my ($cmd, $dir) = @_;
        return 1 if $cmd =~ /^ls|^cat|^git/;
        return "blocked by security policy";
    },
);

If not set (undef), all commands are allowed after the allowed_commands check.

working_directory

Default working directory for command execution. Can be overridden per invocation via the working_directory argument passed to the MCP tool. Defaults to undef, which leaves the working directory unchanged.

timeout

Default timeout in seconds for command execution. Can be overridden per invocation via the timeout argument passed to the MCP tool. Defaults to 30.

tool_name

Name of the MCP tool registered by this server. Defaults to run.

tool_description

Description of the MCP tool registered by this server. Defaults to Execute a command and return stdout, stderr, and exit code.

compress

Enable output compression for LLM efficiency. When enabled, command output is passed through a filter pipeline that removes noise, truncates lines, and limits output. Can be set at server construction time or per-tool-call via the compress argument.

my $server = MCP::Run::Bash->new(compress => 1);
# Or per call: { command => 'ls -la', compress => 1 }

run_stdio

MCP::Run::Bash->run_stdio(%args);
$server->run_stdio;

Convenience wrapper that constructs the server (when called as a class method) and hands it to "to_stdio" in MCP::Server. Intended as the one-liner entry point for bin/ scripts.

execute

my $result = $self->execute($command, $working_directory, $timeout);

Abstract method that subclasses must implement. Executes $command in $working_directory (may be undef) with the given $timeout in seconds.

Must return a hashref with the following keys:

  • exit_code - Integer exit code of the process.

  • stdout - Captured standard output as a string.

  • stderr - Captured standard error as a string.

  • error - Optional. A string describing an execution-level error (e.g. timeout or spawn failure).

See MCP::Run::Bash for the reference implementation.

format_result

my $mcp_result = $self->format_result($tool, $result);

Formats the hashref returned by "execute" into an MCP tool result. Produces a text block showing the exit code, stdout, and stderr (each section only included when non-empty). Sets the MCP error flag when the exit code is non-zero.

Override this method in a subclass to change the output format.

SEE ALSO

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-mcp-run/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.