(page_compile_run)=

# PETSc compile-run MCP server

<http://mcp.petsc-ai.org:8080/mcp> or <https://mcp.petsc-ai.org:8443/mcp>

Hosts a bash shell with a PETSc installation.

The agent can
- compile and run PETSc C programs (eventually Fortran and Python as well),
- upload and download files
- git grep in the PETSc repository

If you are using a developer tool such as Claude code, Gemini Cli, VSCode, or Warp that has access to your file system, compilers, and a PETSc installation
then this MCP server is redundant and unnecessary since your development environment can already compile and run PETSc programs;
see Purpose immediately below.

## Purpose

The purpose of this MCP agent is to enable the implementation of "higher-level" PETSc MCP agents that write, manipulate, and evaluate PETSc
code without requiring a PETSc installation environment inside each of the "higher-level" agents.

## Usage

The MCP agent may be tested from the command line using

```bash
python petsc_compile_run_mcp_client.py [--stdio] [--url PETSC_MCP_SERVERS_URL] --ls [directory]
python petsc_compile_run_mcp_client.py [--stdio] [--url PETSC_MCP_SERVERS_URL] --make executable [--dependencies dependencies]
python petsc_compile_run_mcp_client.py [--stdio] [--url PETSC_MCP_SERVERS_URL] --create_file_from_string filename --file_contents file_contents
python petsc_compile_run_mcp_client.py [--stdio] [--url PETSC_MCP_SERVERS_URL] --run_executable executable [--nsize nsize] [--args args] [--valgrind True] [--timeout timeout]
python petsc_compile_run_mcp_client.py [--stdio] [--url PETSC_MCP_SERVERS_URL] --run_bash_command command
python petsc_compile_run_mcp_client.py [--stdio] [--url PETSC_MCP_SERVERS_URL] --git_grep_petsc_repository string
```

Run with `--help` to get a complete list of available MCP tools.

The bash shell in the server has no history, each bash_command is processed in a new bash shell.

The client Python file also contains a `PetscCompileRunMCPClient()` class that connects to the server has a (mirror)
method for each tool provided by the server.
This class can be used when writing new MCP agents that utilize the compile-run server.

To start the MCP server locally

```bash
PETSC_DIR=xxx PETSC_ARCH=yyy python petsc_compile_run_mcp_server.py [--stdio]
```

The server option `--stdio` causes the server to be run with a transport of `stdio` and should only be used when `PetscCompileRunMCPClient()`
is started using the `--stdio` argument. In this model, the client starts up the server for its run and the server shuts down
when the client shuts down. Set the environmental variable `PETSC_MCP_SERVERS_STDIO` to have all the servers run locally and connected to
the clients using `stdio` (an alternative to passing the `--stdio` argument.
Set `PETSC_MCP_SERVERS_URL` to `localhost` have the clients look for the servers on the local machine.

## Limitations

The agent has no concept of users, each command it receives is processed in the same directory tree as the previous commands meaning
multiple users will be problematic.

There is only trivial security, this agent gives access to a Unix shell environment.