# symbolic_math_mcp


![](./head.png)

Symbolically verify any equation and calculation


## Requirements

- Python 3.11+
- `fastmcp>=3.4.2`
- `symbolic-math-verify>=0.1.4`

## Install

```bash
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -e .
```

## Configuration

Default configuration file: [config.json](/home/brosnan/symbolic_math_mcp/symbolic_math_mcp/config.json)

```json
{
  "mcp_server_name": "My Symbolic Math MCP Server",
  "mcp_server_url": "http://localhost:8753",
  "max_requests": 10,
  "total_timeout": 600
}
```

### Notes

- `stdio://...` runs the server over stdio.
- `http://...` runs the server over FastMCP's streamable HTTP transport.
- `https://...` is accepted by the config parser and uses the HTTP transport settings. In practice, TLS is typically terminated by a reverse proxy in front of the process.

## Run

From the project directory:

```bash
.venv/bin/python run_server.py --config config.json
```

Or after installation:

```bash
symbolic-math-mcp --config config.json
```

## Tool API

### `check_symbolic_math(filename)`

- input: absolute path to a `.yaml` symbolic math file
- behavior: blocks until `verify_yaml_file(filename)` completes or times out

Successful completion:

```json
{
  "status": "Tool call completed!",
  "filename": "proof.yaml",
  "result": "Math proofs are valid"
}
```

Timeout:

```json
{
  "status": "Tool call has timed out!",
  "filename": "proof.yaml",
  "result": "TIMEOUT ERROR!"
}
```

File not found:

```json
{
  "status": "Tool call cannot find the file based on the filename!",
  "filename": "proof.yaml",
  "result": "FILE NOT FOUND!"
}
```

File read error:

```json
{
  "status": "Tool call cannot read the file!",
  "filename": "proof.yaml",
  "result": "FILE CANNOT BE READ!"
}
```

Unknown error:

```json
{
  "status": "Tool call has unknown error!",
  "filename": "proof.yaml",
  "result": "UNKNOWN ERROR!"
}
```

### `check_symbolic_math_parallel(dir_path)`

- input: absolute directory path containing one or more `.yaml` symbolic math files
- behavior: starts verification for each `.yaml` file in parallel, bounded by `max_requests`, and blocks until all checks finish or the total timeout is exceeded
- result keys: absolute file paths for each `.yaml` file found in `dir_path`
- failure behavior: if `dir_path` is missing, not absolute, unreadable, or contains no `.yaml` files, the tool returns the same structured error shape used by `check_symbolic_math`

Successful completion:

```json
{
  "status": "Parallel Tool call completed!",
  "dir_path": "/abs/path/to/proofs",
  "result": {
    "/abs/path/to/proofs/one.yaml": "Math proofs are valid",
    "/abs/path/to/proofs/two.yaml": "Error! Math proofs are invalid"
  }
}
```

Timeout:

```json
{
  "status": "Tool call has timed out!",
  "filename": "/abs/path/to/proofs",
  "result": "TIMEOUT ERROR!"
}
```

Directory not found or no YAML files:

```json
{
  "status": "Tool call cannot find the file based on the filename!",
  "filename": "/abs/path/to/proofs",
  "result": "FILE NOT FOUND!"
}
```

## Tests

The test suite is intentionally sequential.

Run all tests:

```bash
PYTHONPATH=src /home/brosnan/symbolic_math_mcp/.venv/bin/python tests/run_tests_sequentially.py
```

The integration test starts a real stdio MCP server subprocess and validates:

- 5 valid YAML files in [tests_yaml](/home/brosnan/symbolic_math_mcp/symbolic_math_mcp/tests_yaml)
- 5 invalid YAML files in [tests_yaml](/home/brosnan/symbolic_math_mcp/symbolic_math_mcp/tests_yaml)

## Codex Config
```
[mcp_servers.symbolic_math_mcp]
url = "http://localhost:8753/mcp"

[mcp_servers.symbolic_math_mcp.tools.check_symbolic_math]
approval_mode = "approve"

[mcp_servers.symbolic_math_mcp.tools.check_symbolic_math_parallel]
approval_mode = "approve"
```