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 | http://127.0.0.1:8000/api/v1/... |
| OpenAPI / docs | http://127.0.0.1:8000/docs |
| MCP (HTTP) | http://127.0.0.1:8000/mcp/ |
| MCP (stdio) | megmis-mcp / python -m megmis.mcp_stdio |
| Health | GET /healthz |
| Voice Lab (optional) | http://127.0.0.1:8000/voice/ |
| Console (optional) | http://127.0.0.1:8088/ |
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.
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, traffic - Roads — 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.
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-mcp
Build 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-api
2. 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 8000
All-in-one (API + DB + Redis + worker wiring):
docker compose up --build
Dev 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 | head
Interactive 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 | http://127.0.0.1:8000/mcp/ (same process as the API) |
| stdio | megmis-mcp or python -m megmis.mcp_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"
}
}
}
}
Remote / HTTP clients
With the API running (uvicorn or Docker), point Streamable HTTP clients at:
http://127.0.0.1:8000/mcp/
Production:
https://<your-host>/mcp/
Pass X-API-Key the way your client supports custom headers (or use tool api_key on mutating calls). Example Cursor-style remote entry (when your client supports URL transport):
{
"mcpServers": {
"mamiriro-http": {
"url": "http://127.0.0.1:8000/mcp/",
"headers": {
"X-API-Key": "meg_local_devkey00000000000000000001"
}
}
}
}
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 |
|---|---|
USE_PERSISTENCE |
true → PostGIS + Redis; false → memory fallback |
DATABASE_URL / DATABASE_APP_URL |
Owner vs RLS app role (megmis_app) |
USE_APP_ROLE |
Enforce tenant RLS via app role |
WEATHER_PROVIDER |
mock | open-meteo | openweather |
ROUTING_PROVIDER |
mock | valhalla | graphhopper | osrm |
GEOCODE_PROVIDER |
mock | nominatim |
SPEECH_PROVIDER / TTS_PROVIDER |
whisper / edge (voice extras) |
OSM_EXTRACT_PATH |
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_app
Worker 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/mutare - WebSocket:
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.py
CI: .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 v* tag after PyPI pending publisher) |
3 Deploy HTTPS /mcp |
Live: https://megmis-api.onrender.com (/mcp/) |
4 Official MCP Registry (server.json) |
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://YOURHOST
Set 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.0
Project 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, ops
Documentation map
| Doc | Contents |
|---|---|
docs/README.md |
Full document index |
docs/architecture/adr-0001-architecture-decisions.md |
ADRs |
docs/architecture/service-catalogue.md |
Service ownership |
docs/api/openapi.yaml |
REST contract |
docs/api/mcp-tool-contracts.md |
MCP tools / resources / prompts |
docs/planning/roadmap-and-milestones.md |
Gen 1–4 roadmap |
docs/operations/docker-and-compose.md |
Compose & env |
docs/operations/mcp-publish-and-discover.md |
Publish & discovery gate |
License
MIT — free to use, modify, and redistribute. Provided as-is; no warranty.
Metadata
Release files for megmis 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| megmis-0.1.0.tar.gz | 102.9 kB | With provenance | Details for megmis-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| megmis-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for megmis-0.1.0-py3-none-any.whl |
Total release size: 236.3 kB
Release files / megmis-0.1.0.tar.gz
| Download URL | megmis-0.1.0.tar.gz |
|---|---|
| Size | 102.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9a349bb7ea464eb7a272091723dbc9011181ac67a3c9a3b9839901420d73cbbd
|
|
BLAKE2b-256 checksum How to use checksums |
7215222ef6edebcdfcaabe75e2867e1c0a9436bb813431c71197cdd019832c77
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logRelease files / megmis-0.1.0-py3-none-any.whl
| Download URL | megmis-0.1.0-py3-none-any.whl |
|---|---|
| Size | 133.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fd21930867a0dfd4e5673d04e964fdf82cd92fe5ade8a33362af536aab7a13a8
|
|
BLAKE2b-256 checksum How to use checksums |
5279b0301b8c16992fe2090784499c1ae924a828c6445fc4a88d8496a6a12751
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logSecurity for megmis 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for megmis-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.