symbolic_math_mcp

symbolic_math_mcp is a standalone FastMCP server that validates symbolic math proof files in YAML format.

It uses exactly one function from symbolic-math-verify for verification:

• symbolic_math_verify.verify_yaml_file()

Features

• exposes one synchronous MCP tool: check_symbolic_math

• exposes one synchronous MCP tool for parallel directory validation: check_symbolic_math_parallel

• supports stdio://, http://, and https:// configuration URLs

• queues requests above max_requests

• enforces a total per-request timeout

• automatically switches to a free port if the configured HTTP port is already in use

Related MCP server: Simple MCP POC

Requirements

• Python 3.11+

• fastmcp>=3.4.2

• symbolic-math-verify>=0.1.4

Install

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

{
  "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:

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

Or after installation:

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:

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

Timeout:

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

File not found:

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

File read error:

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

Unknown error:

{
  "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:

{
  "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:

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

Directory not found or no YAML files:

{
  "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:

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

• 5 invalid YAML files in 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"