Mamiriro
Mamiriro (MEGMIS)
Mamiriro Environmental, Geospatial & Mobility Intelligence Server — weather, geospatial, explained routing, road conditions, and journey-risk intelligence for Zimbabwe corridors (and beyond), exposed as REST and MCP (stdio + Streamable HTTP).
Python 3.12 · FastAPI · PostGIS · Redis · official MCP Python SDK
Surface | Endpoint |
REST API |
|
OpenAPI / docs |
|
MCP (HTTP) |
|
MCP (stdio) |
|
Health |
|
Voice Lab (optional) |
|
Console (optional) |
|
Status: MIT-licensed public prototype (v0.1.0) — local mocks by default; live providers optional via env. Not a paid SLA or production weather/routing product yet. Listings must say prototype / mock providers.
Naming: Mamiriro is the product; MEGMIS is the project acronym (Environmental, Geospatial & Mobility Intelligence Server); megmis is the PyPI / CLI package.
Public surface | URL |
PyPI | |
Hosted API / MCP | |
MCP Streamable HTTP | |
Server card | |
AI catalog |
Engineering docs live under docs/.
What it does
Weather — current, forecast, hourly, alerts, historical, air quality, ag conditions, activity risk
Geo — geocode, reverse geocode, nearby places, emergency facilities
Routing — multi-criteria
optimize_routewith cost breakdown (safest / fastest / …), reroute, corridor conditions, trafficRoads — incident reporting & crowdsourced condition pipeline
Risk — journey risk assessment (REST + MCP)
Platform — API keys, webhooks (HMAC), tenant RLS, rate limits, worker jobs
Voice (Gen 3) — Whisper STT + edge-tts, agent sessions, WebSocket + Voice Lab
Commercial (Gen 4) — provider failover, Insurance/GovTech packs, GPS cost calibration, object-store retention,
/metrics
Providers are swappable with health-gated failover (mock by default; Open-Meteo / OpenWeather, Valhalla / GraphHopper / OSRM via env). Open-Meteo free API is non-commercial — see OPEN_METEO_COMMERCIAL_OK.
Related MCP server: CommuteScout
Requirements
Python 3.12+
Docker (recommended for PostGIS + Redis)
Optional:
[voice]extras for Whisper / TTS
Install (PyPI / local package)
Once published (or from a built wheel):
pip install megmis
# optional voice extras: pip install "megmis[voice]"
# stdio MCP for Cursor / Claude / VS Code / Windsurf
USE_PERSISTENCE=false megmis-mcp
# or one-shot without a permanent install:
uvx --from megmis megmis-mcpBuild locally without uploading:
pip install -e ".[dev]"
python -m build
twine check dist/*Release to PyPI: push a v* tag after configuring Trusted Publishing (see .github/workflows/release.yml).
Quick start
1. API only (in-memory / no Docker)
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
# USE_PERSISTENCE=false # optional for offline unit work
uvicorn megmis.main:app --reload --host 0.0.0.0 --port 8000
# or: megmis-api2. Full stack (PostGIS + Redis)
Postgres is published on host 5433 (avoids clashing with a local 5432).
docker compose up --build -d postgres redis
cp .env.example .env
export DATABASE_URL=postgresql+psycopg://megmis:megmis@localhost:5433/megmis
export REDIS_URL=redis://localhost:6379/0
export USE_PERSISTENCE=true
alembic upgrade head
python scripts/seed.py
uvicorn megmis.main:app --reload --port 8000All-in-one (API + DB + Redis + worker wiring):
docker compose up --buildDev API keys
X-API-Key: meg_local_devkey00000000000000000001 # demo tenant
X-API-Key: meg_local_tenantb00000000000000000002 # tenant-b (isolation tests)Auth
REST and MCP HTTP: send
X-API-Key: meg_…on every request (hashed at rest; scopes enforced).MCP stdio: seeds the demo tenant from
DEV_API_KEY/ settings (no header needed locally).Mutating MCP tools also accept an
api_keyargument when no HTTP context is present.OAuth / OIDC for remote connectors is planned for commercial hosting — not required for local stdio.
Details:
docs/engineering/security-and-tenancy.md.
REST examples
export DEV_API_KEY=meg_local_devkey00000000000000000001
curl -s -H "X-API-Key: $DEV_API_KEY" \
"http://127.0.0.1:8000/api/v1/weather/current?name=Harare" | jq
curl -s -H "X-API-Key: $DEV_API_KEY" -H "Content-Type: application/json" \
-d '{"origin":{"name":"Harare"},"destination":{"name":"Bulawayo"},"profile":"safest"}' \
http://127.0.0.1:8000/api/v1/routes/optimize | jq
# Gen 4 commercial pack + provider health
curl -s -H "X-API-Key: $DEV_API_KEY" http://127.0.0.1:8000/api/v1/packs | jq
curl -s -H "X-API-Key: $DEV_API_KEY" http://127.0.0.1:8000/api/v1/ops/providers | jq
curl -s http://127.0.0.1:8000/metrics | headInteractive docs: http://127.0.0.1:8000/docs.
Contract: docs/api/openapi.yaml (v0.4.0). Gen 4 ops notes: docs/operations/gen4-commercial.md.
MCP
Same tools as REST (weather, geo, routing, roads, journey risk, traffic), plus create_journey. Contracts: docs/api/mcp-tool-contracts.md.
Mutating tools (report_road_condition, create_journey, reroute) require X-API-Key on HTTP /mcp, or an api_key argument. Stdio seeds the demo tenant automatically.
Transport | How |
Streamable HTTP |
|
stdio |
|
Cursor / Claude Desktop (stdio)
After pip install -e . (or a published megmis wheel), point the client at the console script or module:
{
"mcpServers": {
"mamiriro": {
"command": "megmis-mcp",
"env": {
"USE_PERSISTENCE": "false",
"DEV_API_KEY": "meg_local_devkey00000000000000000001"
}
}
}
}Editable checkout (absolute venv path):
{
"mcpServers": {
"mamiriro": {
"command": "/ABS/PATH/TO/.venv/bin/python",
"args": ["-m", "megmis.mcp_stdio"],
"cwd": "/ABS/PATH/TO/megmis"
}
}
}VS Code (MCP extension / mcp.json)
{
"servers": {
"mamiriro": {
"type": "stdio",
"command": "megmis-mcp",
"env": {
"USE_PERSISTENCE": "false",
"DEV_API_KEY": "meg_local_devkey00000000000000000001"
}
}
}
}Windsurf
Same stdio shape as Cursor — add under MCP servers:
{
"mcpServers": {
"mamiriro": {
"command": "megmis-mcp",
"env": {
"USE_PERSISTENCE": "false",
"DEV_API_KEY": "meg_local_devkey00000000000000000001"
}
}
}
}Claude Code
Stdio (after pip install megmis or uvx):
claude mcp add mamiriro --env USE_PERSISTENCE=false -- megmis-mcpOr remote HTTP (when the CLI supports URL transports):
https://megmis-api.onrender.com/mcp/Remote / HTTP clients
Local API (uvicorn or Docker):
http://127.0.0.1:8000/mcp/Hosted prototype (Render):
https://megmis-api.onrender.com/mcp/Pass X-API-Key the way your client supports custom headers (or use tool api_key on mutating calls). Cursor-style remote entry:
{
"mcpServers": {
"mamiriro-http": {
"url": "https://megmis-api.onrender.com/mcp/",
"headers": {
"X-API-Key": "YOUR_RENDER_DEV_API_KEY"
}
}
}
}Local override while developing:
{
"mcpServers": {
"mamiriro-http-local": {
"url": "http://127.0.0.1:8000/mcp/",
"headers": {
"X-API-Key": "meg_local_devkey00000000000000000001"
}
}
}
}ChatGPT (Connectors / custom MCP)
Use a ChatGPT plan that supports custom MCP / connectors.
Add a connector pointing at Streamable HTTP:
https://megmis-api.onrender.com/mcp/Send auth as
X-API-Key: <key>if the UI exposes custom headers (mutating tools require it).Label the connector prototype / mock providers until live adapters are the default.
Discovery without a directory: open https://megmis-api.onrender.com/.well-known/mcp.json.
Example prompts
Plan the safest Harare → Bulawayo drive and explain the cost breakdown.
Assess weather risk for outdoor work in Mutare tomorrow.
List road incidents on the Harare–Bulawayo corridor.
Assess journey risk from Harare to Bulawayo for a light truck.
Configuration
Copy .env.example → .env. Important knobs:
Variable | Purpose |
|
|
| Owner vs RLS app role ( |
| Enforce tenant RLS via app role |
|
|
|
|
|
|
|
|
| Corridor graph for local Dijkstra |
OSM seed extract: data/osm/zimbabwe-harare-bulawayo.osm
Optional full country PBF: ./scripts/download_osm_extract.sh
Worker & console
docker compose up -d worker
docker compose --profile console up -d console # http://127.0.0.1:8088/
# or locally
megmis-worker # or: python -m megmis.worker
python -m megmis.console_appWorker drains webhooks, validates road reports, fan-outs alerts, and marks OSM graph refresh.
Voice Lab (optional)
pip install -e ".[voice]"
# SPEECH_PROVIDER=whisper WHISPER_MODEL=base TTS_PROVIDER=edge
uvicorn megmis.main:app --reload --port 8000
# open http://127.0.0.1:8000/voice/STT: OpenAI Whisper via
faster-whisper(falls back to mock if deps missing)TTS:
edge-tts(ZA English; Shona/Ndebele localized reply text)Scenario:
POST /api/v1/agents/scenarios/mutareWebSocket:
ws://127.0.0.1:8000/ws/voice/{session_id}?api_key=...
Tests
# unit + contract + BDD + tenant isolation (no Docker)
USE_PERSISTENCE=false pytest -q -m "not integration"
# integration (PostGIS + Redis required)
INTEGRATION=1 USE_PERSISTENCE=true pytest -q -m integration
# Gen 2 platform + provider HTTP mocks
INTEGRATION=1 USE_PERSISTENCE=true USE_APP_ROLE=true \
pytest -q tests/test_gen2_platform.py tests/test_providers_http.py
# deep smokes (API must be running)
python scripts/gen1_deep_smoke.py
python scripts/gen2_deep_smoke.py
python scripts/gen12_deep_smoke.pyCI: .github/workflows/ci.yml. Strategy: docs/quality/test-strategy.md.
Publish & discovery
Playbook: docs/operations/mcp-publish-and-discover.md
Phase | Status |
0 Pre-flight | Done |
2 PyPI package + Trusted Publishing workflow | Done (upload on first |
3 Deploy HTTPS | Live: https://megmis-api.onrender.com ( |
4 Official MCP Registry ( | Manifest ready; publish after PyPI |
6+ Directories / GEO | After registry |
Hosted MCP (Phase 3)
# fastest: Render Blueprint (render.yaml) or: fly deploy
# then:
./scripts/verify_remote_mcp.sh https://YOURHOSTSet PUBLIC_BASE_URL=https://YOURHOST so MCP Host allowlisting and /.well-known/mcp.json include the public URL.
# after PyPI Trusted Publisher is linked:
git tag v0.1.0
git push origin v0.1.0Project layout
src/megmis/
main.py FastAPI app + /mcp mount + voice static
mcp_stdio.py stdio MCP entry (megmis-mcp)
worker.py background jobs (megmis-worker)
console_app.py optional ops console
api/v1/ REST routers
mcp/ MCP tools, resources, prompts
engines/ weather, geo, routing, road, risk, …
providers/ Protocol adapters (mock + live)
db/ SQLAlchemy models, Redis, repos
common/ auth, schemas, errors
alembic/ migrations (+ RLS)
scripts/ seed, entrypoint, smokes, OSM download
data/osm/ Zimbabwe corridor extract
tests/ unit, contract, BDD, isolation, integration
docs/ ADRs, OpenAPI, MCP contracts, opsDocumentation map
Doc | Contents |
Full document index | |
ADRs | |
Service ownership | |
REST contract | |
MCP tools / resources / prompts | |
Gen 1–4 roadmap | |
Compose & env | |
Publish & discovery gate |
License
MIT — free to use, modify, and redistribute. Provided as-is; no warranty.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Geocoding, routing, isochrones, traffic, weather, and place search for AI agents. 19 MCP tools.
African intelligence infrastructure for AI apps, developers, and data products via MCP.
Hosted MCP for live place search, geocoding & turn-by-turn routes. No Maps API key to manage.
Geospatial AI MCP server — satellite imagery, embeddings, weather, GNS governance
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables to interact with comprehensive weather data through the MCP protocol, including current conditions, multi-day forecasts, hourly forecasts, and geocoding.11 npmMIT
- AlicenseAqualityBmaintenanceProvides live California road conditions, route planning, and an AI assistant over MCP, enabling natural-language queries about traffic, closures, chain controls, and more.185MIT
- AlicenseAqualityDmaintenanceEnables MCP clients to search for locations, fetch weather forecasts, and retrieve forecast meteogram images through the meteoblue Weather API.317 npm1MIT
- FlicenseNot gradedqualityCmaintenanceEnables logistics route optimization by exposing tools for traffic factors, holiday and circulation restrictions, and fuel price references over a remote MCP HTTPS endpoint.-