{
  "markdown": "# ProjectPermit / BuildRequirements\n\nProjectPermit is a **building permit requirements API & MCP for contractors and AI agents**. It checks proposed construction and renovation scope across 7 Canadian municipalities and returns deterministic permit signals, official-source evidence, workflow routing, and an automation-ready action bundle. **BuildRequirements** is the deterministic rules engine inside it.\n\n## Try free in 30 seconds\n\nNo account, API key, wallet, MCP client, or platform integration is required for the current structured-facts validation preview.\n\n- Free HTTP preview: `POST https://projectpermit-api-v2-production.up.railway.app/v1/preview-project-requirements`\n- Free capability discovery: `GET https://projectpermit-api-v2-production.up.railway.app/v1/capabilities`\n- Free standard MCP preview: `https://projectpermit-mcp-production.up.railway.app/mcp`\n\nSee [`TRY_PROJECTPERMIT.md`](TRY_PROJECTPERMIT.md) for a copy-paste `curl` example and the preview privacy boundary. The anonymous HTTP preview intentionally excludes civic-address/GIS resolution; use the standard MCP developer preview for a bounded address-aware validation workflow.\n\n## Current jurisdiction coverage\n\nCurrent deterministic rule footprint:\n\n- `gatineau_qc`\n- `ottawa_on`\n- `toronto_on`\n- `mississauga_on`\n- `laval_qc`\n- `longueuil_qc`\n- `vancouver_bc`\n\nThe engine covers 8 normalized project families, preserves uncertainty instead of guessing, attaches official-source evidence to rule results, and exposes the same jurisdiction router through HTTP, standard MCP, and x402-paid MCP.\n\nFirst-party municipal/open-data address resolution is available for Gatineau, Ottawa, Toronto, Mississauga and Vancouver. Laval and Longueuil currently support rule preflight with `resolve_address=false`.\n\nThe engine deliberately does **not** call an LLM. A calling agent normalizes natural-language scope into structured facts; BuildRequirements applies deterministic municipal rules.\n\n## Agent workflow differentiation\n\nEvery successful preflight now includes an additive deterministic `workflow` object so a contractor, property or field-service agent can use the result inside a real operating workflow instead of merely displaying a permit answer.\n\nStable routing signals include:\n\n- `ADD_PERMIT_TASK`\n- `CONTINUE_WITH_EVIDENCE`\n- `COLLECT_MISSING_FACTS`\n- `ROUTE_SPECIAL_REVIEW`\n- `MUNICIPAL_CONFIRMATION`\n- `MANUAL_SCOPE_REVIEW`\n\nThe workflow package also includes a quote-handling signal, a deliberately narrow `automation_safe` flag, and up to three high-value follow-up questions when another deterministic call can resolve missing context. Workflow guidance never changes the underlying permit determination and never represents municipal authorization.\n\nSee [`docs/AGENT_WORKFLOW_GUIDANCE.md`](docs/AGENT_WORKFLOW_GUIDANCE.md).\n\n## Live endpoints and commercial x402 pricing\n\n- HTTP API: `https://projectpermit-api-v2-production.up.railway.app`\n- Free HTTP developer-validation preview: `POST https://projectpermit-api-v2-production.up.railway.app/v1/preview-project-requirements`\n- Standard MCP developer-validation preview: `https://projectpermit-mcp-production.up.railway.app/mcp`\n- Paid MCP: `https://projectpermit-x402-mcp-production.up.railway.app/mcp`\n\nThe HTTP API exposes free machine-readable capability discovery at `GET /v1/capabilities`.\n\nCommercial x402 resources are configured on **Base mainnet** (`eip155:8453`) with USDC payment. The current launch price intentionally minimizes first-use friction while paid adoption and repeat-call behavior are being validated:\n\n- single paid HTTP preflight: **$0.05 USDC / call**\n- single paid MCP preflight: **$0.05 USDC / call**\n- paid HTTP batch, up to 50 normalized projects: **$2.00 USDC / batch** *(full 50-item batch = $0.04/item, 20% below 50 single calls)*\n\nThe production facilitator is `https://facilitator.payai.network`.\n\nThe paid MCP exposes a free `projectpermit_info` tool and the x402-paid `check_project_requirements` tool. The paid HTTP routes return an x402 `402 Payment Required` challenge when no valid payment is supplied.\n\nThe result is a preflight information package, **not municipal authorization, legal advice, engineering certification, or building-code design approval**.\n\n## Market thesis\n\nThe business target is not a homeowner-only `Do I need a permit?` wizard and not a managed permit-submission service. ProjectPermit is intended to become a **cross-jurisdiction permit-requirements intelligence layer** embedded in contractor, property-management, construction/design, permitting, and real-estate software/Agent workflows.\n\nMarket validation remains active in parallel with product development. Differentiated product work and commercial distribution no longer wait for outreach replies. Geography expansion remains evidence-led because every additional municipality adds ongoing rule/source maintenance cost; priority goes to requested geographies or workflows with credible repeated volume.\n\nThe first commercially meaningful internal checkpoint is roughly **10,000 monthly external preflight calls**. A preferred proof shape is approximately **5 integrations × 2,000 calls/month**, or one platform workflow capable of the same volume. This is a validation target, not a forecast.\n\nRead:\n\n- `docs/MARKET_VALIDATION.md` — market background, pricing thesis and original call-volume model\n- `docs/DISTRIBUTION_VALIDATION.md` — 2026 platform evidence, competition and validation plan\n- `docs/CALL_VOLUME_THRESHOLDS.md` — bottom-up monthly-call and revenue thresholds\n- `docs/PAIN_EVIDENCE.md` — observed field/community pain evidence separated from assumptions\n- `docs/TARGET_ACCOUNT_RANKING.md` — ranked design-partner targets by pain and distribution leverage\n- `docs/OUTREACH_BATCH_01.md` — tailored first outreach batch\n- `docs/DESIGN_PARTNER_TRIAL.md` — low-friction 20-case pilot protocol\n- `docs/EXTERNAL_USAGE_BASELINE.md` — clean external-usage starting baseline\n- `docs/INTEGRATION_QUICKSTART.md` — copy-paste developer integration examples\n\n## Architecture\n\nAll transports call the same shared address-aware preflight pipeline:\n\n`HTTP / standard MCP / x402 paid MCP -> preflight_service -> municipal address/GIS adapters -> jurisdiction router -> deterministic rules -> workflow guidance`\n\nResolved non-null municipal property facts can enrich a request before rule evaluation. Unknown overlays remain unknown and never silently overwrite an explicit caller value.\n\nSuccessful preflight calls also emit privacy-minimal structured usage telemetry for market validation. The telemetry excludes civic address, coordinates, property identifiers, payment credentials, IP/user-agent data and raw client tags. Internal CI/owner smoke traffic is explicitly tagged so it can be excluded from external call counts. Municipal HTTP request URL logging is suppressed so address/query details are not leaked indirectly through `httpx` INFO logs.\n\n## Quick start\n\n```bash\npython -m venv .venv\nsource .venv/bin/activate\npip install -e .\nuvicorn projectpermit.api:app --host 127.0.0.1 --port 8000\n```\n\nFor standard MCP support:\n\n```bash\npip install -e '.[mcp]'\nprojectpermit-mcp\n```\n\n`projectpermit-mcp` uses MCP Python SDK v2 Streamable HTTP, JSON responses, and stateless HTTP. It listens on `127.0.0.1:8001` by default. Override with `PROJECTPERMIT_MCP_HOST` and `PROJECTPERMIT_MCP_PORT`.\n\nRun tests:\n\n```bash\nPYTHONPATH=src python -m unittest discover -s tests -v\n```\n\n## API\n\nFor no-wallet validation, use the free structured-facts route:\n\n`POST /v1/preview-project-requirements`\n\nFor the x402-paid HTTP contract, use:\n\n`POST /v1/check-project-requirements`\n\nBoth use the same normalized project shape; the anonymous free preview intentionally rejects address/GIS resolution. Example project facts:\n\n```json\n{\n  \"jurisdiction\": \"toronto_on\",\n  \"resolve_address\": false,\n  \"project\": {\n    \"family\": \"window_door\",\n    \"action\": \"replace_same_size\",\n    \"single_dwelling_house\": true,\n    \"structural_change\": false,\n    \"new_exit\": false\n  }\n}\n```\n\nA successful preflight response also contains `workflow`, for example:\n\n```json\n{\n  \"workflow\": {\n    \"mode\": \"NO_PERMIT_SIGNAL\",\n    \"recommended_route\": \"CONTINUE_WITH_EVIDENCE\",\n    \"quote_handling\": \"NO_PERMIT_ALLOWANCE_SIGNAL\",\n    \"automation_safe\": true,\n    \"follow_up_questions\": []\n  }\n}\n```\n\nFor an address-aware jurisdiction, set `resolve_address=true` and supply `address` through the standard MCP preview or paid route; the anonymous HTTP preview deliberately does not accept address resolution.\n\n## Developer-validation workflow\n\nThe standard MCP endpoint remains free so a design partner can test workflow fit without a wallet or billing setup. A recommended pilot uses **20 anonymized real scopes**, a stable non-PII `context.client_tag`, and measures whether the result actually changes the next workflow step.\n\nPartner evidence is tracked in:\n\n- `data/partner_targets.csv` — 20 candidate design-partner accounts\n- `data/partner_feedback.csv` — structured conversation/pilot/call-volume outcomes\n- `data/design_partner_scope_template.csv` — anonymized pilot-case template\n\nSummarize validation evidence with:\n\n```bash\npython scripts/summarize_partner_feedback.py\n```\n\nUnknown interview values remain unknown rather than being silently converted to zero. Commercial decisions therefore depend on recorded external evidence, not optimistic inference, while engineering/distribution work continues in parallel.\n\n## Repository map\n\n- `src/projectpermit/engine.py` — original Gatineau/Ottawa deterministic rules\n- `src/projectpermit/expansion_rules.py` — Toronto/Mississauga rules\n- `src/projectpermit/quebec_expansion_rules.py` — Laval/Longueuil rules\n- `src/projectpermit/vancouver_rules.py` — Vancouver rules\n- `src/projectpermit/jurisdiction_router.py` — public jurisdiction dispatcher\n- `src/projectpermit/preflight_service.py` — shared address-aware preflight pipeline\n- `src/projectpermit/workflow_advice.py` — deterministic agent routing and missing-fact guidance\n- `src/projectpermit/address.py` — Gatineau/Ottawa/Toronto address/GIS adapters\n- `src/projectpermit/mississauga_address.py` — Mississauga address/property adapter\n- `src/projectpermit/vancouver_address.py` — Vancouver first-party open-data adapter\n- `src/projectpermit/telemetry.py` — privacy-minimal usage events\n- `src/projectpermit/http_fetch.py` — municipal HTTP fetch with request-URL log suppression\n- `src/projectpermit/api.py` — HTTP API\n- `src/projectpermit/mcp_server.py` — standard MCP v2 developer preview\n- `src/projectpermit/paid_mcp_server.py` — x402-native paid MCP v2 server\n- `src/projectpermit/mcp_v2_x402_compat.py` — MCP SDK v2 / x402 result compatibility shim\n- `data/source_manifest.json` — official source registry/freshness metadata\n- `data/partner_targets.csv` — first 20 design-partner targets\n- `data/partner_feedback.csv` — structured external-validation tracker\n- `data/design_partner_scope_template.csv` — anonymized 20-case pilot template\n- `schemas/` — public request/response schemas\n- `scripts/mcp_remote_smoke.py` — seven-city + Vancouver address-aware public MCP smoke\n- `scripts/paid_mcp_unpaid_smoke.py` — no-cost remote payment-challenge test\n- `scripts/paid_mcp_buyer_smoke.py` — historical buyer-side paid smoke tooling; do not spend merely to re-prove plumbing\n- `scripts/facilitator_capability_probe.py` — no-cost facilitator capability matrix\n- `scripts/projectpermit_bazaar_lookup.py` — read-only Bazaar catalog lookup\n- `scripts/summarize_usage_logs.py` — external/internal usage-log summarizer\n- `scripts/summarize_partner_feedback.py` — partner conversation/call-volume gate summarizer\n- `docs/AGENT_WORKFLOW_GUIDANCE.md` — workflow-routing response contract and integration pattern\n- `docs/PHASE0_SPEC.md` — original product/engineering scope\n- `docs/PHASE0_RELEASE_READINESS.md` — completed Phase 0 release gate\n- `docs/MARKET_VALIDATION.md` — market background and original business gates\n- `docs/DISTRIBUTION_VALIDATION.md` — platform distribution validation plan\n- `docs/CALL_VOLUME_THRESHOLDS.md` — monthly API-call economics and go/no-go thresholds\n- `docs/PAIN_EVIDENCE.md` — observed workflow pain evidence\n- `docs/TARGET_ACCOUNT_RANKING.md` — account prioritization model\n- `docs/PARTNER_OUTREACH.md` — outreach/discovery playbook\n- `docs/OUTREACH_BATCH_01.md` — first tailored outreach batch\n- `docs/DESIGN_PARTNER_TRIAL.md` — design-partner pilot package\n- `docs/EXTERNAL_USAGE_BASELINE.md` — telemetry baseline before outreach\n- `docs/INTEGRATION_QUICKSTART.md` — developer quickstart\n- `docs/X402_ARCHITECTURE.md` — payment/discovery design\n\n## Production verification\n\nThe seven-city public MCP footprint and Vancouver address-aware resolution have been verified from GitHub Actions against Railway production. The Vancouver production smoke resolved the City Hall civic address `453 W 12TH AV` and City zoning `CD-1 (46)` through Vancouver first-party open data.\n\nHistorical buyer-side paid HTTP and paid MCP settlement were verified end-to-end on testnet. The commercial production services are now configured for Base mainnet and can be verified without spending funds by checking their x402 `402 Payment Required` challenges. A real mainnet payment should only be made when there is a reason to verify actual settlement or a genuine buyer call.\n\n## x402 / discovery status\n\nCanonical paid HTTP resources:\n\n- `https://projectpermit-api-v2-production.up.railway.app/v1/check-project-requirements`\n- `https://projectpermit-api-v2-production.up.railway.app/v1/check-project-requirements-batch`\n\nCanonical paid MCP resource:\n\n- `https://projectpermit-x402-mcp-production.up.railway.app/mcp`\n\nCommercial network: `eip155:8453` (Base mainnet)\n\nProduction facilitator: `https://facilitator.payai.network`\n\nThe single HTTP resource publishes Bazaar discovery metadata; paid MCP publishes MCP x402 discovery metadata. Both advertise the Agent workflow-routing differentiation.\n\n## CI / verification\n\nCurrent CI covers:\n\n- Python 3.11 + 3.13\n- deterministic jurisdiction-rule and schema tests\n- workflow-guidance routing tests\n- address-adapter and shared-preflight regressions\n- telemetry privacy contract\n- municipal request-log privacy guard\n- partner-validation metric summarizer tests\n- official source-manifest contracts\n- MCP v2 integration\n- x402 wire behavior\n- MCP v2 settlement-receipt compatibility\n- Docker build + live `/health`\n- public seven-jurisdiction MCP tool invocation\n- public Vancouver address-aware MCP invocation\n- public paid-MCP unpaid challenge\n- public HTTP Bazaar unpaid challenge\n- public paid-bulk HTTP unpaid challenge\n- facilitator capability checks\n\nSee `STATUS.md` for the broader engineering/validation state and the distribution documents above for market evidence.\n\n## Safety boundary\n\nDeterminations intentionally use preflight language such as `REQUIRED`, `LIKELY_REQUIRED`, `LIKELY_NOT_REQUIRED`, `ADDITIONAL_REVIEW_REQUIRED`, and `MUNICIPAL_CONFIRMATION_REQUIRED` where uncertainty exists. Ambiguous official thresholds are conservatively routed to confirmation instead of being silently resolved.\n\nThe engine should not be presented as a municipality, permit issuer, lawyer, architect, or engineer.\n",
  "bytes": 15215,
  "sha": "4167d125c677292f3fc8d3bffd2251369daf07f475be9a6ba6d5a9dd2caf4800",
  "repo_slug": "changhuliu/projectpermit-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_changhuliu_projectpermit_530f3a67/readme"
}