{"id":47590133,"url":"https://github.com/resq-software/pypi","last_synced_at":"2026-04-05T15:01:30.651Z","repository":{"id":344538521,"uuid":"1179506219","full_name":"resq-software/pypi","owner":"resq-software","description":"FastMCP server exposing ResQ platform capabilities—including digital twin simulations, drone coordination, and incident response—to AI clients like Claude Desktop and Cursor.","archived":false,"fork":false,"pushed_at":"2026-03-31T13:25:41.000Z","size":666,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-02T06:25:56.729Z","etag":null,"topics":["ai-agents","digital-twin","drone-coordination","fastmcp","incident-response","mcp-server","model-context-protocol","python"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/resq-mcp/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/resq-software.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-12T05:03:18.000Z","updated_at":"2026-03-30T19:41:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/resq-software/pypi","commit_stats":null,"previous_names":["resq-software/mcp","resq-software/pypi"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/resq-software/pypi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/resq-software%2Fpypi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/resq-software%2Fpypi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/resq-software%2Fpypi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/resq-software%2Fpypi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/resq-software","download_url":"https://codeload.github.com/resq-software/pypi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/resq-software%2Fpypi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31439442,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T13:13:19.330Z","status":"ssl_error","status_checked_at":"2026-04-05T13:13:17.778Z","response_time":75,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","digital-twin","drone-coordination","fastmcp","incident-response","mcp-server","model-context-protocol","python"],"created_at":"2026-04-01T17:15:57.421Z","updated_at":"2026-04-05T15:01:30.646Z","avatar_url":"https://github.com/resq-software.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\n  Copyright 2026 ResQ\n\n  Licensed under the Apache License, Version 2.0 (the \"License\");\n  you may not use this file except in compliance with the License.\n  You may obtain a copy of the License at\n\n      http://www.apache.org/licenses/LICENSE-2.0\n\n  Unless required by applicable law or agreed to in writing, software\n  distributed under the License is distributed on an \"AS IS\" BASIS,\n  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n  See the License for the specific language governing permissions and\n  limitations under the License.\n--\u003e\n\n# ResQ MCP: Disaster Response Intelligence for AI\n\n[![CI](https://img.shields.io/github/actions/workflow/status/resq-software/pypi/ci.yml?branch=main\u0026label=ci\u0026style=flat-square)](https://github.com/resq-software/pypi/actions)\n[![PyPI](https://img.shields.io/pypi/v/resq-mcp?style=flat-square)](https://pypi.org/project/resq-mcp/)\n[![Docker](https://img.shields.io/docker/v/resqsoftware/mcp?label=docker\u0026style=flat-square)](https://hub.docker.com/r/resqsoftware/mcp)\n[![GHCR](https://img.shields.io/badge/ghcr.io-resq--software%2Fmcp-blue?style=flat-square)](https://github.com/resq-software/pypi/pkgs/container/mcp)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg?style=flat-square)](./LICENSE)\n\nA production-ready Model Context Protocol (MCP) server that connects AI agents to the ResQ platform's robotics, physics simulations, and disaster telemetry.\n\n### Key Features\n\n- **Drone Fleet Command** — Real-time telemetry, sector scanning, and autonomous swarm deployment via the Hybrid Coordination Engine (HCE).\n- **Predictive Intelligence** — Probabilistic disaster forecasting and sector-level vulnerability mapping (PDIE).\n- **Digital Twin Simulations** — Physics-based RL optimization strategies for incident response (DTSOP).\n- **Safe-Mode Execution** — Built-in protection prevents destructive platform mutations by default.\n\n### Requirements\n\n- Python 3.11 or newer\n- VS Code, Cursor, Claude Desktop, or any other MCP client\n\n---\n\n## Getting Started\n\nInstall the ResQ MCP server with your client. The **standard config** works in most tools:\n\n```json\n{\n  \"mcpServers\": {\n    \"resq\": {\n      \"command\": \"uvx\",\n      \"args\": [\"resq-mcp\"],\n      \"env\": {\n        \"RESQ_SAFE_MODE\": \"true\"\n      }\n    }\n  }\n}\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eVS Code\u003c/summary\u003e\n\nA pre-configured [`.vscode/mcp.json`](.vscode/mcp.json) is included in this repo — just open the project and the server is available.\n\nOr install manually. Add to your user or workspace `mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"resq-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"resq-mcp\"],\n      \"env\": {\n        \"RESQ_SAFE_MODE\": \"true\"\n      }\n    }\n  }\n}\n```\n\nFor local development (from a cloned repo), replace `\"command\": \"uvx\"` and `\"args\"` with `\"command\": \"uv\"` and `\"args\": [\"run\", \"resq-mcp\"]`.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eClaude Desktop\u003c/summary\u003e\n\nAdd to your `claude_desktop_config.json` ([MCP install guide](https://modelcontextprotocol.io/quickstart/user)):\n\n```json\n{\n  \"mcpServers\": {\n    \"resq\": {\n      \"command\": \"uvx\",\n      \"args\": [\"resq-mcp\"],\n      \"env\": {\n        \"RESQ_API_KEY\": \"your-prod-token\",\n        \"RESQ_SAFE_MODE\": \"true\"\n      }\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eClaude Code\u003c/summary\u003e\n\n```bash\nclaude mcp add resq -- uvx resq-mcp\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eCursor\u003c/summary\u003e\n\nGo to `Cursor Settings` → `MCP` → `Add new MCP Server`. Use `command` type with the command `uvx resq-mcp`.\n\nOr add manually to your MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"resq\": {\n      \"command\": \"uvx\",\n      \"args\": [\"resq-mcp\"]\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eWindsurf\u003c/summary\u003e\n\nFollow Windsurf MCP [documentation](https://docs.windsurf.com/windsurf/cascade/mcp). Use the standard config above.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eDocker\u003c/summary\u003e\n\nRun the server as a container in SSE mode:\n\n```json\n{\n  \"mcpServers\": {\n    \"resq\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"-i\", \"--rm\", \"--init\",\n        \"-e\", \"RESQ_SAFE_MODE=true\",\n        \"resqsoftware/mcp\"\n      ]\n    }\n  }\n}\n```\n\nOr pull from GitHub Container Registry:\n\n```bash\ndocker pull ghcr.io/resq-software/pypi:latest\n```\n\nTo run as a long-lived SSE service:\n\n```bash\ndocker run -d --rm --init \\\n  --name resq-mcp \\\n  -p 8000:8000 \\\n  -e RESQ_SAFE_MODE=true \\\n  resqsoftware/mcp\n```\n\nThen point your MCP client at the HTTP endpoint:\n\n```json\n{\n  \"mcpServers\": {\n    \"resq\": {\n      \"url\": \"http://localhost:8000/mcp\"\n    }\n  }\n}\n```\n\nYou can also build the image yourself:\n\n```bash\ndocker build -t resq-mcp .\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eLocal development\u003c/summary\u003e\n\n```bash\ngit clone https://github.com/resq-software/pypi.git\ncd mcp\nuv sync\nuv run resq-mcp\n```\n\n\u003c/details\u003e\n\n---\n\n## Configuration\n\nControl server behavior via environment variables or a `.env` file:\n\n| Variable | Description | Default |\n| :--- | :--- | :--- |\n| `RESQ_API_KEY` | Platform authentication token | `resq-dev-token` |\n| `RESQ_SAFE_MODE` | Prevents destructive mutations | `true` |\n| `RESQ_PORT` | Port for SSE (networked) mode | `8000` |\n| `RESQ_HOST` | Host to bind the SSE server | `0.0.0.0` |\n| `RESQ_DEBUG` | Enable verbose logging | `false` |\n| `RESQ_TELEMETRY_BACKEND` | Observability backend (`none`, `console`, `jaeger`, `otlp`) | `none` |\n| `RESQ_OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP exporter endpoint (when backend is `otlp`) | `http://localhost:4317` |\n| `RESQ_OTEL_SERVICE_NAME` | Service name reported to the telemetry backend | `resq-mcp` |\n\n\u003e **Note**: `RESQ_API_KEY` defaults to `resq-dev-token` for local development. No external token is needed to run the server — it works out of the box.\n\n---\n\n## Security \u0026 Safety\n\n**Safe Mode** is enabled by default (`RESQ_SAFE_MODE=true`). In this state, any tool that performs platform mutations (e.g., dispatching a drone swarm or starting a high-fidelity simulation) will raise a `FastMCPError`. This allows AI agents to plan missions safely without triggering real-world consequences. Disable this only when you are ready for autonomous execution.\n\n---\n\n## Tools\n\n### Mission Control (HCE)\n\n- **validate_incident** — Submit a confirmation or rejection for an incident report. Supports idempotent re-submission and conflict detection for opposing validations.\n  - Parameters: `incident_id`, `is_confirmed`, `validation_source`, `correlated_pre_alert_id` (optional), `notes`\n\n- **update_mission_params** — Push authorized mission parameters to a specific drone for an approved strategy. Includes urgency escalation, conflict guards, and idempotent re-dispatch.\n  - Parameters: `drone_id`, `strategy_id`, `is_urgent` (optional, default `false`)\n\n### Simulation (DTSOP)\n\n- **run_simulation** — Queue a high-fidelity Digital Twin physics simulation (flood, wildfire, earthquake). Returns a job ID — subscribe to the resource URI for progress updates.\n  - Parameters: `scenario_id`, `sector_id`, `disaster_type`, `parameters`, `priority`\n\n- **get_deployment_strategy** — Generate an RL-optimized drone deployment and evacuation strategy for a confirmed incident or PDIE pre-alert.\n  - Parameters: `incident_id`\n\n### Resources\n\n| URI | Description |\n| :--- | :--- |\n| `resq://drones/active` | Real-time fleet status — drone types, battery levels, sector assignments. |\n| `resq://simulations/{sim_id}` | Simulation progress and results. Supports SSE subscriptions for push updates on state transitions. |\n\n### Prompts\n\n| Prompt | Description |\n| :--- | :--- |\n| `incident_response_plan` | Structured crisis coordination template that guides an AI agent through situation analysis, asset allocation, and risk assessment for a given incident. |\n\n---\n\n## Example Workflows\n\n### Run a Flood Simulation\n\n```\nYou:   \"Run a flood simulation for Sector-3 with water level 4.2m\"\nAgent: Calls run_simulation → receives SIM-ABCD1234\n       Subscribes to resq://simulations/SIM-ABCD1234\n       Waits for status: completed\n       Returns result URL and analysis\n```\n\n### Full Incident Response\n\n```\nYou:   \"Validate incident INC-789 and deploy drones\"\nAgent: 1. Calls validate_incident(INC-789, confirmed=True)\n       2. Calls get_deployment_strategy(\"INC-789\")\n       3. Reviews strategy with operator\n       4. Calls update_mission_params(\"DRONE-Alpha\", \"STRAT-XYZ\", urgent=True)\n       5. Returns mission parameters and audit hash\n```\n\n### Crisis Planning with Prompts\n\n```\nYou:   Use the incident_response_plan prompt for INC-456\nAgent: Receives structured template → calls tools → produces:\n       - Situation Summary\n       - Asset Allocation\n       - Risk Assessment\n```\n\n---\n\n## Technical Architecture\n\n```mermaid\nC4Context\n    title ResQ MCP Integration\n    Person(ai, \"AI Client\", \"Claude / VS Code / Cursor\")\n    System_Boundary(resq_boundary, \"resq-mcp Server\") {\n        System(server, \"resq-mcp Server\", \"FastMCP Interface\")\n        System_Boundary(backend, \"ResQ Platform\") {\n            Component(dtsop, \"DTSOP Engine\", \"Physics/RL Simulations\")\n            Component(hce, \"HCE Engine\", \"Coordination Logic\")\n            Component(telemetry, \"Drone Telemetry\", \"Real-time Status\")\n        }\n    }\n    Rel(ai, server, \"Uses MCP (STDIO/SSE)\")\n    Rel(server, dtsop, \"Executes Simulation\")\n    Rel(server, hce, \"Validates Incidents\")\n    Rel(server, telemetry, \"Subscribes to Data\")\n```\n\n### Module Overview\n\n```\nsrc/resq_mcp/\n├── server.py              # FastMCP init, lifespan, background tasks\n├── resources.py           # @mcp.resource() endpoints (drones, sims)\n├── prompts.py             # @mcp.prompt() templates (incident response)\n├── core/                  # Cross-cutting: config, errors, security, telemetry, timeout\n├── drone/                 # Drone feed: scan, swarm, deployment (models + service)\n├── dtsop/                 # Digital Twin: simulation, optimization (models + service + tools)\n├── hce/                   # Hybrid Coordination: incidents, missions (models + service + tools)\n└── pdie/                  # Predictive Intelligence: vulnerability, alerts (models + service)\n```\n\n---\n\n## Contributing\n\nWe use `uv` for dependency management and `ruff` for linting.\n\n1.  **Setup**: `uv sync` (installs all dependencies including dev group).\n2.  **Test**: `uv run pytest`\n3.  **Lint**: `uv run ruff check .`\n\nDistributed under the Apache-2.0 License. Copyright 2026 ResQ.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fresq-software%2Fpypi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fresq-software%2Fpypi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fresq-software%2Fpypi/lists"}