Upload 7 files

CLIENTS.md

@@ -0,0 +1,91 @@
+# Connecting clients
+
+Base URL: `https://<owner>-<space-name>.hf.space`
+(shown on the Space page once it's running — e.g. `https://razaali10-epanet-mcp-server.hf.space`)
+
+Two endpoints:
+- **Streamable HTTP** → `…/mcp`  (preferred by all five clients below)
+- **SSE** → `…/sse`  (legacy fallback; Claude Desktop via `mcp-remote`)
+
+If you set the `CLIENT_API_KEY` Space secret, every client must send
+`Authorization: Bearer <key>` (or `X-API-Key: <key>`).
+
+| Client | Transport | Static API-key header? | Notes |
+|--------|-----------|------------------------|-------|
+| HuggingChat | Streamable HTTP | ✅ | Add under Settings → add MCP server |
+| Codex | Streamable HTTP | ✅ | `http_headers` in `config.toml` |
+| Perplexity | Streamable HTTP | ✅ (API Key / header) | Pro/Max/Enterprise only |
+| Gemini CLI | Streamable HTTP | ✅ | `httpUrl` + `headers` in `settings.json` |
+| ChatGPT | Streamable HTTP | ❌ (OAuth/None only) | **Run the Space with no key**, select "No authentication" |
+
+> ⚠️ **ChatGPT** cannot send a static API key. To use it, leave `CLIENT_API_KEY`
+> unset (open mode). If you need the key on for the other four, that's fine —
+> just skip ChatGPT, or run a second open instance for it.
+
+---
+
+## HuggingChat (HF ChatUI)
+Settings → Tools / MCP → add server:
+- **URL**: `https://<space>.hf.space/mcp`
+- **Header**: `Authorization: Bearer <YOUR_KEY>`
+
+## Codex (`~/.codex/config.toml`)
+```toml
+[mcp_servers.epanet]
+url = "https://<space>.hf.space/mcp"
+http_headers = { Authorization = "Bearer <YOUR_KEY>" }
+```
+
+## Perplexity (Pro / Max / Enterprise)
+Account settings → Connectors → **+ Custom connector → Remote**:
+- **MCP Server URL**: `https://<space>.hf.space/mcp`
+- **Transport**: Streamable HTTP
+- **Authentication**: API Key → send as header `X-API-Key: <YOUR_KEY>`
+  (or `Authorization: Bearer <YOUR_KEY>`)
+
+## Gemini CLI (`~/.gemini/settings.json`)
+```json
+{
+  "mcpServers": {
+    "epanet": {
+      "httpUrl": "https://<space>.hf.space/mcp",
+      "headers": { "Authorization": "Bearer <YOUR_KEY>" },
+      "timeout": 30000
+    }
+  }
+}
+```
+Or one-liner:
+```bash
+gemini mcp add --transport http \
+  --header "Authorization: Bearer <YOUR_KEY>" \
+  epanet https://<space>.hf.space/mcp
+```
+
+## ChatGPT (Developer Mode — Plus/Pro/Business/Enterprise/Edu)
+Requires the Space in **open mode** (no `CLIENT_API_KEY`).
+Settings → Apps/Connectors → Advanced → **Developer mode** → Create app:
+- **URL**: `https://<space>.hf.space/mcp`
+- **Transport**: Streamable HTTP
+- **Authentication**: No authentication
+
+## Claude Desktop (SSE via mcp-remote)
+```json
+{
+  "mcpServers": {
+    "epanet": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://<space>.hf.space/sse",
+               "--header", "Authorization: Bearer <YOUR_KEY>"]
+    }
+  }
+}
+```
+
+---
+
+## First things to try
+1. "List the bundled networks."
+2. "Load net3.inp from /home/user/app/networks/ and summarise it."
+3. "Run a hydraulic simulation on net3 and tell me the lowest-pressure node at hour 12."
+4. "Simulate a 20% burst on a pipe in net3 and compare pressures to baseline."

Dockerfile

@@ -0,0 +1,24 @@
+FROM python:3.12-slim
+
+# ePyT loads the EPANET toolkit shared library; these keep it happy on slim.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libgomp1 \
+    && rm -rf /var/lib/apt/lists/*
+
+# HF Spaces run as uid 1000 / user "user".
+RUN useradd -m -u 1000 user
+USER user
+ENV PATH="/home/user/.local/bin:$PATH" \
+    HOME=/home/user \
+    PORT=7860
+
+WORKDIR /home/user/app
+
+COPY --chown=user requirements.txt .
+RUN pip install --no-cache-dir --user -r requirements.txt
+
+COPY --chown=user app.py smoke_test.py ./
+COPY --chown=user networks ./networks
+
+EXPOSE 7860
+CMD ["python", "app.py"]

README.md

@@ -0,0 +1,68 @@
+---
+title: EPANET MCP Server
+emoji: 💧
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
+pinned: false
+license: mit
+short_description: EPANET/ePyT water-network modelling over MCP (HTTP + SSE)
+---
+
+# 💧 EPANET MCP Server
+
+A remote [Model Context Protocol](https://modelcontextprotocol.io) server that exposes
+EPANET water-distribution modelling — powered by [ePyT](https://github.com/KIOS-Research/EPyT) —
+to any MCP-capable client. Load `.inp` models, run hydraulic/quality simulations, modify
+parameters, and generate what-if scenarios in natural language.
+
+It wraps the upstream [`epanet-mcp-server`](https://pypi.org/project/epanet-mcp-server/)
+(44 tools) and serves it over **both** modern transports at once, behind an optional API key.
+
+## Endpoints
+
+| Transport | Path | Clients |
+|-----------|------|---------|
+| Streamable HTTP | `/mcp` | HuggingChat, Codex, Perplexity, Gemini, ChatGPT (dev mode) |
+| HTTP + SSE | `/sse` | Claude Desktop (via `mcp-remote`), other legacy clients |
+| Health probe | `/health` | uptime checks (no auth) |
+
+Base URL once deployed: `https://<owner>-<space-name>.hf.space`
+
+## Authentication
+
+Set a Space **secret** named `CLIENT_API_KEY`. When present, every request to `/mcp`,
+`/sse`, and `/messages/` must send it:
+
+```
+Authorization: Bearer <YOUR_KEY>
+```
+
+(`X-API-Key: <YOUR_KEY>` is also accepted.) Leave the secret unset to run open — useful for
+ChatGPT connectors, which only support OAuth or no-auth. `/` and `/health` are always public.
+
+## Networks
+
+ePyT ships 52 benchmark networks (Net1/2/3, Hanoi, Anytown, L-TOWN, Balerma, …) — call
+`list_bundled_networks` to see them. Custom networks are bundled under
+`/home/user/app/networks/` and loaded by absolute path, e.g.:
+
+```
+load_network("/home/user/app/networks/net3.inp", "net3")
+```
+
+Bundled here: `net3.inp`, `net3_PDD.inp`, `ky4.inp`, `ky10.inp`, `Net6.inp`, `BIWS.inp`.
+
+## Smoke test
+
+`smoke_test.py` runs the full MCP handshake (initialize → tools/list → tools/call) over
+both transports and checks the auth gate:
+
+```
+python smoke_test.py --base-url https://<owner>-<space-name>.hf.space --api-key <YOUR_KEY>
+```
+
+See `CLIENTS.md` for copy-paste connection configs for each client.
+
+Built on `epanet-mcp-server` by Applied-AI-Eurecat (MIT).

app.py

@@ -0,0 +1,226 @@
+"""
+EPANET MCP Server — Hugging Face Space wrapper
+==============================================
+
+Wraps the `epanet-mcp-server` (ePyT/EPANET) FastMCP server and exposes it over
+BOTH modern MCP transports simultaneously, behind an optional API key:
+
+    /mcp        -> Streamable HTTP   (HuggingChat, Codex, Perplexity, Gemini, ChatGPT dev-mode)
+    /sse        -> HTTP + SSE        (legacy clients / Claude Desktop via mcp-remote)
+    /messages/  -> SSE message sink
+    /           -> human-readable landing / status page
+    /health     -> unauthenticated health probe (returns "ok")
+
+Design notes
+------------
+* A single Starlette parent app drives the Streamable-HTTP session manager
+  lifespan (required) and routes each transport to its own sub-app via a pure
+  ASGI dispatcher — no Starlette Mount prefix stripping, no double `/mcp/mcp`.
+* Auth is PURE ASGI middleware (not BaseHTTPMiddleware) so it never buffers or
+  breaks the streaming SSE / chunked responses.
+* Stateful HTTP is kept ON: loaded networks live in an in-process registry and
+  must persist across tool calls within one MCP session (single uvicorn worker).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hmac
+import os
+import textwrap
+
+from starlette.applications import Starlette
+from starlette.responses import HTMLResponse, JSONResponse, PlainTextResponse
+from starlette.routing import Route
+
+from epanet_mcp.server import mcp
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+# CLIENT_API_KEY : if set, every MCP request must present it as a bearer token
+#                  (Authorization: Bearer <key>) or X-API-Key header.
+#                  If unset AND REQUIRE_AUTH is not "true", the server runs OPEN
+#                  (handy for ChatGPT connectors, which are OAuth/none only).
+API_KEY = os.environ.get("CLIENT_API_KEY", "").strip()
+REQUIRE_AUTH = os.environ.get("REQUIRE_AUTH", "").strip().lower() in {"1", "true", "yes"}
+AUTH_ENABLED = bool(API_KEY) or REQUIRE_AUTH
+
+# Keep session state so load_network -> get_summary -> run_sim share one registry.
+mcp.settings.stateless_http = False
+
+streamable_app = mcp.streamable_http_app()  # serves /mcp  (+ owns session mgr lifespan)
+sse_app = mcp.sse_app()                      # serves /sse + /messages/
+
+PROTECTED_PREFIXES = ("/mcp", "/sse", "/messages")
+
+
+# ---------------------------------------------------------------------------
+# Pure-ASGI API key middleware
+# ---------------------------------------------------------------------------
+def _extract_key(headers: list[tuple[bytes, bytes]]) -> str | None:
+    hdr = {k.lower(): v for k, v in headers}
+    auth = hdr.get(b"authorization")
+    if auth:
+        text = auth.decode("latin-1").strip()
+        if text.lower().startswith("bearer "):
+            return text[7:].strip()
+        return text
+    xkey = hdr.get(b"x-api-key")
+    if xkey:
+        return xkey.decode("latin-1").strip()
+    return None
+
+
+class APIKeyMiddleware:
+    def __init__(self, app):
+        self.app = app
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] != "http" or not AUTH_ENABLED:
+            await self.app(scope, receive, send)
+            return
+
+        path = scope.get("path", "")
+        if not any(path == p or path.startswith(p + "/") or path.startswith(p)
+                   for p in PROTECTED_PREFIXES):
+            await self.app(scope, receive, send)
+            return
+
+        presented = _extract_key(scope.get("headers", []))
+        ok = presented is not None and API_KEY != "" and hmac.compare_digest(presented, API_KEY)
+        if not ok:
+            resp = JSONResponse(
+                {"error": "unauthorized",
+                 "detail": "Provide the API key via 'Authorization: Bearer <key>' "
+                           "or the 'X-API-Key' header."},
+                status_code=401,
+            )
+            await resp(scope, receive, send)
+            return
+
+        await self.app(scope, receive, send)
+
+
+# ---------------------------------------------------------------------------
+# Transport dispatcher (pure ASGI)
+# ---------------------------------------------------------------------------
+class MCPDispatcher:
+    """Route HTTP requests to the right transport sub-app by path prefix."""
+
+    def __init__(self, streamable, sse, fallback):
+        self.streamable = streamable
+        self.sse = sse
+        self.fallback = fallback
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] != "http":
+            # lifespan is handled by the parent Starlette app's lifespan_context
+            await self.fallback(scope, receive, send)
+            return
+        path = scope.get("path", "")
+        # Normalise a trailing slash on the transport roots — Gemini / ChatGPT
+        # sometimes append one (e.g. "/mcp/"), but the sub-app route is "/mcp".
+        if path in ("/mcp/", "/sse/"):
+            path = path.rstrip("/")
+            scope = dict(scope)
+            scope["path"] = path
+        if path == "/mcp" or path.startswith("/mcp/"):
+            await self.streamable(scope, receive, send)
+        elif path == "/sse" or path.startswith("/messages"):
+            await self.sse(scope, receive, send)
+        else:
+            await self.fallback(scope, receive, send)
+
+
+# ---------------------------------------------------------------------------
+# Landing / health routes (the fallback app)
+# ---------------------------------------------------------------------------
+def _base_url(request) -> str:
+    # Honour HF's proxy headers so printed URLs use the public https host.
+    proto = request.headers.get("x-forwarded-proto", request.url.scheme)
+    host = request.headers.get("x-forwarded-host", request.headers.get("host", request.url.netloc))
+    return f"{proto}://{host}"
+
+
+async def health(request):
+    return PlainTextResponse("ok")
+
+
+async def landing(request):
+    base = _base_url(request)
+    auth_line = (
+        "🔒 API key required — send <code>Authorization: Bearer &lt;key&gt;</code>"
+        if AUTH_ENABLED else
+        "🔓 Open access — no API key configured (set <code>CLIENT_API_KEY</code> to lock it down)"
+    )
+    tool_count = len(getattr(mcp._tool_manager, "_tools", {})) if hasattr(mcp, "_tool_manager") else "40+"
+    html = textwrap.dedent(f"""\
+    <!doctype html><html><head><meta charset="utf-8">
+    <title>EPANET MCP Server</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <style>
+      body{{font-family:system-ui,-apple-system,Segoe UI,Roboto,sans-serif;max-width:760px;
+           margin:40px auto;padding:0 20px;line-height:1.55;color:#0f172a;background:#f8fafc}}
+      code{{background:#e2e8f0;padding:1px 5px;border-radius:4px;font-size:.9em}}
+      pre{{background:#0f172a;color:#e2e8f0;padding:14px 16px;border-radius:8px;overflow:auto;font-size:.85em}}
+      h1{{margin-bottom:.2em}} .sub{{color:#475569;margin-top:0}}
+      .grid{{display:grid;grid-template-columns:auto 1fr;gap:6px 16px;margin:12px 0}}
+      .k{{color:#0369a1;font-weight:600}} a{{color:#0369a1}}
+      .pill{{display:inline-block;background:#dbeafe;color:#1e40af;border-radius:999px;padding:2px 10px;font-size:.8em}}
+    </style></head><body>
+    <h1>💧 EPANET MCP Server</h1>
+    <p class="sub">Water-distribution network modelling over MCP, powered by
+       <a href="https://github.com/KIOS-Research/EPyT">ePyT</a> / EPANET.
+       <span class="pill">{tool_count} tools</span></p>
+    <p>{auth_line}</p>
+    <h3>Endpoints</h3>
+    <div class="grid">
+      <span class="k">Streamable HTTP</span><span><code>{base}/mcp</code> — HuggingChat, Codex, Perplexity, Gemini, ChatGPT (dev mode)</span>
+      <span class="k">SSE</span><span><code>{base}/sse</code> — legacy clients / Claude Desktop via <code>mcp-remote</code></span>
+      <span class="k">Health</span><span><code>{base}/health</code></span>
+    </div>
+    <h3>Quick connect (Streamable HTTP)</h3>
+    <pre>{{
+  "mcpServers": {{
+    "epanet": {{
+      "url": "{base}/mcp",
+      "headers": {{ "Authorization": "Bearer &lt;YOUR_KEY&gt;" }}
+    }}
+  }}
+}}</pre>
+    <p>Bundled ePyT benchmark networks + custom networks under
+       <code>/home/user/app/networks/</code> (e.g. <code>net3.inp</code>, <code>ky4.inp</code>,
+       <code>Net6.inp</code>, <code>BIWS.inp</code>). Try:
+       <em>"List bundled networks, then load net3.inp and summarise it."</em></p>
+    </body></html>""")
+    return HTMLResponse(html)
+
+
+fallback_app = Starlette(routes=[
+    Route("/", landing),
+    Route("/health", health),
+])
+
+dispatcher = MCPDispatcher(streamable_app, sse_app, fallback_app)
+guarded = APIKeyMiddleware(dispatcher)
+
+
+# ---------------------------------------------------------------------------
+# Parent app: drives the Streamable-HTTP session-manager lifespan
+# ---------------------------------------------------------------------------
+@contextlib.asynccontextmanager
+async def lifespan(app):
+    async with streamable_app.router.lifespan_context(app):
+        yield
+
+
+app = Starlette(lifespan=lifespan)
+app.mount("/", guarded)
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    port = int(os.environ.get("PORT", "7860"))
+    uvicorn.run(app, host="0.0.0.0", port=port, log_level="info")

requirements.txt

@@ -0,0 +1,11 @@
+# EPANET MCP server (ePyT) + its deps
+epanet-mcp-server==0.1.2
+epyt==2.3.5.2
+
+# MCP + ASGI stack (transports, auth wrapper, landing page)
+mcp==1.28.1
+starlette==1.3.1
+uvicorn==0.50.0
+
+# Smoke-test client
+httpx==0.28.1

smoke_test.py

@@ -0,0 +1,134 @@
+"""
+Smoke test for the EPANET MCP Space.
+
+Runs the full MCP handshake (initialize -> tools/list -> tools/call) against a
+running server over BOTH transports, and verifies the API-key gate. This is the
+transport-level proof that every target client can connect:
+
+    Streamable HTTP  -> HuggingChat, Codex, Perplexity, Gemini, ChatGPT (dev)
+    SSE              -> Claude Desktop (via mcp-remote) and other legacy clients
+
+Usage:
+    python smoke_test.py --base-url http://127.0.0.1:7860 [--api-key KEY]
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+
+import httpx
+from mcp import ClientSession
+from mcp.client.sse import sse_client
+from mcp.client.streamable_http import streamablehttp_client
+
+PASS, FAIL = "✅", "❌"
+results: list[tuple[str, bool, str]] = []
+
+
+def record(name: str, ok: bool, detail: str = "") -> None:
+    results.append((name, ok, detail))
+    print(f"  {PASS if ok else FAIL} {name}" + (f" — {detail}" if detail else ""))
+
+
+def _headers(api_key: str | None) -> dict:
+    return {"Authorization": f"Bearer {api_key}"} if api_key else {}
+
+
+async def exercise(session: ClientSession, transport: str) -> None:
+    await session.initialize()
+    record(f"[{transport}] initialize", True)
+
+    tools = (await session.list_tools()).tools
+    names = {t.name for t in tools}
+    record(f"[{transport}] tools/list", len(tools) > 0, f"{len(tools)} tools")
+
+    expected = {"load_network", "get_network_summary", "run_hydraulic_simulation",
+                "list_bundled_networks", "create_leakage_event"}
+    missing = expected - names
+    record(f"[{transport}] core tools present", not missing,
+           "all present" if not missing else f"missing {missing}")
+
+    # Functional round-trip: list bundled -> load Net1 -> summarise
+    r = await session.call_tool("list_bundled_networks", {})
+    record(f"[{transport}] call list_bundled_networks", not r.isError)
+
+    r = await session.call_tool("load_network", {"path": "Net1.inp", "network_id": f"smoke_{transport}"})
+    record(f"[{transport}] call load_network(Net1)", not r.isError)
+
+    r = await session.call_tool("get_network_summary", {"network_id": f"smoke_{transport}"})
+    text = (r.content[0].text if r.content else "")
+    ok = (not r.isError) and ("junctions" in text or "nodes" in text)
+    record(f"[{transport}] call get_network_summary", ok,
+           "summary returned" if ok else "unexpected payload")
+
+
+async def test_streamable(base_url: str, api_key: str | None) -> None:
+    print("\n▶ Streamable HTTP  (/mcp)")
+    url = f"{base_url}/mcp"
+    try:
+        async with streamablehttp_client(url, headers=_headers(api_key)) as (r, w, _):
+            async with ClientSession(r, w) as session:
+                await exercise(session, "http")
+    except Exception as e:  # noqa: BLE001
+        record("[http] connection", False, repr(e))
+
+
+async def test_sse(base_url: str, api_key: str | None) -> None:
+    print("\n▶ SSE  (/sse)")
+    url = f"{base_url}/sse"
+    try:
+        async with sse_client(url, headers=_headers(api_key)) as (r, w):
+            async with ClientSession(r, w) as session:
+                await exercise(session, "sse")
+    except Exception as e:  # noqa: BLE001
+        record("[sse] connection", False, repr(e))
+
+
+async def test_health_and_auth(base_url: str, api_key: str | None) -> None:
+    print("\n▶ Health + auth gate")
+    async with httpx.AsyncClient(timeout=15) as c:
+        try:
+            resp = await c.get(f"{base_url}/health")
+            record("health returns 200/ok", resp.status_code == 200 and resp.text.strip() == "ok")
+        except Exception as e:  # noqa: BLE001
+            record("health probe", False, repr(e))
+
+        if api_key:
+            # No key -> must be 401 on a protected endpoint
+            try:
+                resp = await c.post(f"{base_url}/mcp",
+                                    json={"jsonrpc": "2.0", "id": 1, "method": "ping"},
+                                    headers={"Accept": "application/json, text/event-stream"})
+                record("unauthenticated /mcp rejected (401)", resp.status_code == 401,
+                       f"status {resp.status_code}")
+            except Exception as e:  # noqa: BLE001
+                record("unauthenticated /mcp rejected", False, repr(e))
+        else:
+            record("auth gate", True, "open mode (no key configured) — skipped")
+
+
+async def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--base-url", default="http://127.0.0.1:7860")
+    ap.add_argument("--api-key", default=None)
+    args = ap.parse_args()
+    base = args.base_url.rstrip("/")
+
+    print(f"Target: {base}   auth={'on' if args.api_key else 'off'}")
+    await test_health_and_auth(base, args.api_key)
+    await test_streamable(base, args.api_key)
+    await test_sse(base, args.api_key)
+
+    passed = sum(1 for _, ok, _ in results if ok)
+    total = len(results)
+    print(f"\n{'='*48}\nRESULT: {passed}/{total} checks passed")
+    failed = [n for n, ok, _ in results if not ok]
+    if failed:
+        print("Failed:", ", ".join(failed))
+    return 0 if passed == total else 1
+
+
+if __name__ == "__main__":
+    sys.exit(asyncio.run(main()))