{
  "markdown": "# Home Services MCP Server\n\nAn open-source, self-hostable Model Context Protocol server for home-service\ndiscovery, provider profiles and reviews, homeowner identity, booking\nrequests, and booking follow-up. The server supplies the workflow and MCP\ninterface; each operator supplies the APIs, data, credentials, branding, and\ndeployment environment.\n\nThis repository contains no customer data, provider data, API keys, or private\nproduction endpoints. It includes one documented public hosted MCP fallback\nfor convenience; operators can replace it with their own endpoint and\ncredentials for a fully self-hosted deployment.\n\n## What is included\n\n- Streamable HTTP MCP transport at `/mcp` (the root endpoint is also mapped for\n  clients that require it).\n- OAuth 2.0 authorization-code flow with PKCE, when OAuth credentials are\n  configured.\n- Provider search, details, reviews, homeowner profile, booking, previous-job,\n  booking-status, and rebooking workflows.\n- Optional category-specific find/book tool aliases.\n- Input validation, PII-aware logging, outbound host allowlisting, rate\n  limiting, and circuit-breaker behavior.\n- Local ASGI development, a generic Docker image, and AWS SAM/Lambda\n  deployment configuration.\n\nThe public MCP contract is intentionally stable. Operators can replace the\nbackends without changing the client-facing tool names or workflow semantics.\n\n## Quick start\n\n```bash\npython3.10 -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\ncp .env.example .env\n# The default setup uses the hosted MCP relay. For self-hosting, edit .env\n# with your own upstream MCP endpoint, API URLs, and credentials.\nuvicorn src.main:app --reload --port 8000\n```\n\nThe server is then available at `http://localhost:8000/mcp`.\n\nBefore opening a release or marketplace review, run the checks in\ndocs/RELEASE_CHECKLIST.md, including:\n\n    python3 scripts/audit_public_release.py\n\nFor a container build:\n\n```bash\ndocker build -t home-services-mcp .\ndocker run --env-file .env -p 8000:8080 home-services-mcp\n```\n\nFor AWS SAM, provide deployment-specific values through parameter overrides\nor your secret manager. Do not place secrets in `template.yaml`, `samconfig`\nfiles, container layers, or source control.\n\n## Configuration\n\nStart with [.env.example](.env.example). Empty optional endpoint variables\ndisable the related capability. The upstream MCP relay is the exception: it\ndefaults to the documented public hosted service and can be overridden.\n\nCore operator-owned endpoints:\n\n| Variable | Purpose |\n| --- | --- |\n| `PROVIDERS_API` | Provider search endpoint |\n| `COORDS_RESOLVE_API` | Text/coordinate location resolver |\n| `ZIP_RESOLVE_API` | Postal-code location resolver |\n| `GEOCODING_API` / `GEOCODING_API_KEY` | Optional address enrichment integration |\n| `REVIEWS_API` | Provider profile and review endpoint |\n| `BOOKING_API` | Booking/request creation endpoint |\n| `SERVICE_REQUESTS_URL` | Booking history/status endpoint |\n| `SERVICE_REQUESTS_METADATA_URL` | Optional endpoint for notification metadata |\n| `PROFILE_LOOKUP_API` | Optional phone/profile lookup endpoint |\n| `AUTH_WEBHOOK_URL` | Optional OTP send/verify endpoint |\n| `HOMEOWNER_PROFILE_API` | Optional profile-by-token endpoint |\n| `CANCEL_BOOKING_API` | Optional authenticated, ownership-enforcing cancellation endpoint |\n\nOptional integrations include notification endpoints, operator persistence,\nmonitoring webhooks, OAuth, and the OpenAI app verification challenge. All\nURLs and secrets must be supplied by the operator.\n\n### OAuth interoperability\n\nWhen OAuth is enabled, access and refresh tokens use separate ES256 signing\nkeys; the access-token public verification key\nis exposed through the metadata `jwks_uri`. Set\n`OAUTH_ALLOWED_REDIRECT_URIS` to the exact hosted or claimed-scheme callbacks\nyour clients use. Native clients may register HTTP loopback callbacks on\n`localhost`, `127.0.0.1`, or `[::1]` with any explicit port; these do not need\nto be enumerated because native apps commonly bind an ephemeral port. Other\ncustom schemes (including arbitrary `cursor://` or `vscode://` callbacks) are\nrejected unless their complete URI is explicitly configured, since dynamic\nregistration alone does not prove ownership of a private scheme. Enable\n`OAUTH_DYNAMIC_CLIENT_REGISTRATION_ENABLED` to let public PKCE clients obtain\nunique persisted client ids from `/oauth/register`; the legacy configured\nclient id and unregistered PKCE clients remain supported.\n\nUse at least 32 cryptographically random bytes for `OAUTH_CLIENT_SECRET`. The\nserver derives domain-separated ES256 keys from that secret so stateless\ninstances publish and verify the same access-token key without reusing it for\nrefresh-token signatures. OAuth tokens carry an opaque homeowner session id;\nprofile PII and upstream bearer credentials remain in the server-side state\nstore.\n\n### Upstream MCP relay\n\nBy default, the server relays requests from `/upstream/mcp` to\n`https://mcp.hirenimbus.com/mcp`. Set `UPSTREAM_MCP_URL` to use an\noperator-controlled MCP service instead. If the selected upstream requires\nauthentication, set `UPSTREAM_MCP_AUTH_TOKEN`; no token is bundled, and\ninbound client authorization is never forwarded automatically.\n\nReview the selected upstream's data handling, retention, terms, and access\npolicy before sending user requests to it. For a fully self-hosted deployment,\nreplace the default upstream and configure the operator-owned business APIs.\n\n## Security and data ownership\n\nThe server is a programmable integration layer, not a data processor with a\nbuilt-in tenant. Operators are responsible for:\n\n- API authorization, tenant isolation, data retention, backups, and deletion;\n- secret storage, rotation, least-privilege scopes, and production network\n  policy;\n- privacy notices, terms, support contacts, regional/legal requirements, and\n  any third-party processing disclosures;\n- confirming that configured APIs do not return more personal information than\n  the MCP client needs.\n\nThe default development configuration leaves external business APIs empty.\nProduction deployments should fail closed when a required capability is not\nconfigured, use durable shared state for OAuth and idempotency, and keep\nmonitoring disabled unless its endpoint is explicitly configured. Set\nAUTH_STATE_TABLE_NAME to a shared DynamoDB table and\nREQUIRE_DURABLE_STATE=true for multi-instance OAuth or booking workloads.\nWithout those settings, the development fallback is process-local and does\nnot provide cross-instance replay protection.\n\nConfirmed booking calls accept an optional client-generated\nidempotency_key. Clients should reuse that key after a timeout. The\nconfigured booking API should also honor the same field; the server never\nretries an ambiguous booking request automatically.\n\n## Testing\n\nInstall the development dependencies and run:\n\n```bash\npytest -q\nruff check .\n```\n\nTests must use mocks or local fixtures for external integrations. They must\nnot call a live operator endpoint.\n\n## Marketplace package\n\nThe server and portable workflow skills are independent of any hosted\ndeployment. A first-party distribution can add a separate marketplace\nmanifest that points to its own hosted MCP URL and branded app, without\nputting those values in this repository.\n\nThe portable home-service workflow is available at\n[`skills/home-service-concierge/SKILL.md`](skills/home-service-concierge/SKILL.md).\nIts app handoff uses the operator-configured `APP_LINK` value.\n\n## License\n\nLicensed under the [Apache License 2.0](LICENSE). Product names, trademarks,\nprivate services, and operator integrations are not included as defaults by\nthis codebase. The documented public hosted MCP fallback is an intentional\nexception and does not include credentials or customer data.\n",
  "bytes": 7792,
  "sha": "ea8ca622c0faa16a5af894e22ef1b688ed70c6a19a94b29ab1f1a1a0ee61385e",
  "repo_slug": "hire-nimbus/nimbus-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mishakivskiy_hirenimbus_mcp_5c0bf4ac/readme"
}