README.md

metadata

title: Hydraulic Solver MCP Server
emoji: 💧
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
license: mit

Hydraulic Solver MCP + REST Server

This repository exposes the Hydraulic Solver Teaching Mode backend as two agent-facing surfaces over the same hydraulic_core.py.

Surface	File	Serves
MCP server	server.py	Claude, Cursor, LM Studio, n8n, HuggingChat, Codex, LangChain/LangGraph, AutoGen
REST / OpenAPI	rest_api.py	ChatGPT Custom GPT Actions, Gemini, Zapier/Make/curl, HTTP clients

The tool set is intentionally deterministic. The Gradio Space remains the human-facing teaching app; this server is the agent-facing calculation layer.

Included tools

• load_network
• upload_network
• close_session
• network_summary
• solve_single_pipe
• solve_hardy_cross_loop
• solve_two_loop_hardy_cross
• solve_three_reservoir
• solve_pdd_demand
• simulate_tank_eps
• evaluate_valve_behavior
• solve_pump_operating_point
• pressure_zone_analysis
• leakage_nrw_analysis
• water_age_analysis
• chlorine_decay_analysis
• generate_epanet_validation_inp

Unit systems

Quantity	MKS	FPS
Flow/demand	L/s	gpm
Length/head	m	ft
Diameter	mm	in
Pressure	m of head	psi

Internal calculations are SI-normalized.

Local stdio MCP

pip install -r requirements.txt
python server.py

Claude Desktop local config:

{
  "mcpServers": {
    "hydraulic-solver": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

Remote MCP on HF Spaces

The included Dockerfile runs MCP HTTP by default on port 7860.

Set Space secret:

CLIENT_API_KEY=your-secret

Run command used by Docker:

TRANSPORT=http PORT=7860 python server.py

Expected MCP URL:

https://your-space.hf.space/mcp

Some clients use SSE:

TRANSPORT=sse PORT=7860 python server.py

Expected SSE URL:

https://your-space.hf.space/sse

REST / OpenAPI surface

Run locally:

CLIENT_API_KEY=your-secret uvicorn rest_api:app --host 0.0.0.0 --port 8000

OpenAPI schema:

http://localhost:8000/openapi.json

Interactive docs:

http://localhost:8000/docs

For a REST HF Space, change the Dockerfile command to:

CMD ["uvicorn", "rest_api:app", "--host", "0.0.0.0", "--port", "7860"]

Then use:

https://your-rest-space.hf.space/openapi.json

Platform guide

Platform	Surface	Transport
Claude Desktop	MCP	stdio local or SSE remote via mcp-remote
Claude.ai web	MCP	Streamable HTTP
Cursor	MCP	stdio or HTTP
LM Studio	MCP	stdio or HTTP
n8n	MCP	HTTP Streamable
HuggingChat	MCP	Streamable HTTP
Codex	MCP	Streamable HTTP
LangChain / LangGraph	MCP	langchain-mcp-adapters
AutoGen	MCP	MCP extension
ChatGPT Custom GPT	REST	OpenAPI Action
Gemini	REST	OpenAPI function tool
Zapier / Make / curl	REST	HTTP

ChatGPT Custom GPT Action

Use the REST surface, not MCP.

In GPT Builder:

1. Create Action
2. Import schema from URL:

   https://your-rest-space.hf.space/openapi.json
   

3. Authentication:
   • API Key
   • Bearer
   • paste your secret

Example REST call

curl -X POST "https://your-rest-space.hf.space/tools/solve_three_reservoir" \
  -H "Authorization: Bearer your-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "unit_system": "MKS / L/s",
    "reservoir_heads": [140, 120, 105],
    "demand": 20,
    "initial_head": 100,
    "lengths": [500, 700, 600],
    "diameters": [300, 250, 250],
    "c_values": [120, 120, 120]
  }'

Important note

This package exposes the current teaching solvers and component-learning calculations. It is prepared for later WNTR/EPANET engine wiring, but it does not yet run a full WNTR hydraulic simulation unless you add a WNTR layer.

HF App tab shows "Not Found" — fixed in v2

A pure MCP server does not behave like a Gradio app. The actual MCP endpoint is /mcp, so opening the Space root URL in a browser may show Not Found if no landing route is defined.

This v2 package adds:

• / human-readable status page
• /health JSON health check
• /mcp Streamable HTTP MCP endpoint
• bearer-token middleware for MCP routes when CLIENT_API_KEY is set

Expected browser checks:

https://your-space.hf.space/
https://your-space.hf.space/health

Expected MCP client URL:

https://your-space.hf.space/mcp