Hyperia CLI

The hyperia command‑line tool is installed alongside the library and lets you run, test, and package MCP servers without touching Python code.

$ hyperia --help

---

🚦 Command Matrix

Command	Purpose	Dependency Handling	Typical Stage
run	Launch a Hyperia server or proxy	Uses current environment. You ensure deps	Prod & local quick runs
dev	Spin up server + Inspector UI	Creates isolated env; specify extras via --with	Interactive testing
install	Package server for Claude Desktop (STDIO)	Isolated env; extras via --with	End‑user distribution
version	Print version info	n/a	Diagnostics

hyperia <command> [options]

---

1 · run — One‑Shot Runner / Proxy

Run local code or create a quick proxy to a remote MCP.

hyperia run server.py          # local file
hyperia run server.py:mcp_alt  # explicit object name
hyperia run https://api.example.com/mcp  # proxy remote → stdio

Core Flags

Flag	Short	Description
--transport	-t	stdio (default), streamable-http, sse (deprecated)
--host		Bind host for HTTP/SSE (default 127.0.0.1)
--port	-p	Bind port (default 8000)
--log-level	-l	DEBUG / INFO / WARNING / ERROR / CRITICAL

When passing a file path, the CLI ignores any if __name__ == "__main__": block and directly calls .run() on the discovered object (mcp, server, or app). This lets you override transport without editing code.

Examples

# Override transport defined in code
hyperia run server.py -t streamable-http -p 9000

# Proxy remote HTTP server as local STDIO (for IDE)
hyperia run https://store.example.com/mcp

# Verbose logs
hyperia run backend.py -l DEBUG

---

2 · dev — Inspector + Sandbox Env

Launches server in an isolated virtual env and opens the MCP Inspector GUI.

hyperia dev server.py -e . --with pandas --with matplotlib

• Defaults to STDIO transport (Inspector dropdown).

• Not for HTTP testing—start server separately with run -t streamable-http then connect Inspector manually.

Flag	Short	Description
--with-editable <dir>	-e	Install local project in editable mode (requires pyproject.toml)
--with <pkg>		Extra pip packages (can repeat)
--inspector-version <ver>		Pin Inspector release
--ui-port <port>		Port for Inspector web UI
--server-port <port>		Port for Inspector proxy backend

---

3 · install — Package for Claude Desktop

Packages server into Claude Desktop’s plugin directory (always STDIO transport).

hyperia install server.py -n "My Analysis" -e . --with numpy --env-var API_KEY=123

Flag	Short	Purpose
--name	-n	Friendly display name
--with-editable	-e	Editable project path
--with		Extra packages (repeatable)
--env-var KEY=VAL	-v	Inject env var
--env-file <file>	-f	Load vars from .env

Claude will launch the server per session under STDIO regardless of code transport settings.

---

4 · version

Print versions of Hyperia, MCP spec, Python, and platform.

$ hyperia version
Hyperia:      0.5.0
MCP spec:     2025‑03‑26
Python:       3.12.2
Platform:     macOS‑15.4‑arm64

---

5 · Advanced Tips

• Shebang stub – add #!/usr/bin/env hyperia run at top of script for UNIX executable.

• .hyperiarc – place default CLI flags in project root to avoid long commands.

• CI/CD – run hyperia run inside Docker to smoke‑test Streamable HTTP startup (curl -f http://localhost:8000/mcp/health).