Developer Documentation — Philadelphia Restoration

Quick Start — MCP Connection in 30 Seconds

Philadelphia Restoration exposes 7 tools via the Model Context Protocol (MCP). Connect any MCP-compatible agent to our server in one line:

Server URL: https://mcp.philadelphiarestoration.org
Transport:  Streamable HTTP (stateless)
Auth:       None required

No API keys. No rate limits. No signup. Just connect and call tools.

Available Tools

All 7 tools return structured reasoning kits — decision frameworks, cost data, citations, related tools, and a CTA — grounded in IICRC S500/S520/S540 standards.

MCP Connection

Python (mcp SDK)

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async with streamablehttp_client(
    "https://mcp.philadelphiarestoration.org"
) as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()

        # List available tools
        tools = await session.list_tools()
        print(f"{len(tools.tools)} tools available")

        # Assess burst pipe damage
        result = await session.call_tool(
            "assess_damage",
            {"damage_type": "burst_pipe"}
        )
        print(result.content[0].text)

TypeScript (mcp SDK)

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport }
  from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://mcp.philadelphiarestoration.org")
);
const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);

// List tools
const { tools } = await client.listTools();
console.log(`${tools.length} tools available`);

// Assess burst pipe damage
const result = await client.callTool({
  name: "assess_damage",
  arguments: { damage_type: "burst_pipe" }
});
console.log(result.content[0].text);

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "phillyrestore": {
      "url": "https://mcp.philadelphiarestoration.org"
    }
  }
}

REST API

All 7 tools are also available as REST endpoints. Use these as a fallback if your agent does not support MCP.

Base URL: https://api.philadelphiarestoration.org/api/v1

Example: Assess Damage (curl)

curl -X POST https://api.philadelphiarestoration.org/api/v1/assess-damage \
  -H "Content-Type: application/json" \
  -d '{"damage_type": "burst_pipe"}'

Example: Search Knowledge Base

curl -X POST https://api.philadelphiarestoration.org/api/v1/search-knowledge \
  -H "Content-Type: application/json" \
  -d '{"query": "mold prevention timeline after water damage", "limit": 5}'

Full OpenAPI specification: https://philadelphiarestoration.org/openapi.yaml

Workflow Guide — Arazzo Specification

We publish an Arazzo 1.0.1 workflow specification describing optimal tool sequences. Use these to chain tools effectively.

Primary Flow: Full Damage Assessment

assess_damage → check_insurance_coverage → estimate_cost
  → search_restoration_knowledge → request_callback

Data flows between steps automatically — the damage type and severity from the assessment step feed into insurance, cost, and knowledge searches.

Emergency Triage Flow

get_emergency_steps → assess_damage → request_callback

For active emergencies — safety actions first, then assessment, then immediate professional connection.

Insurance-First Flow

check_insurance_coverage → assess_damage → estimate_cost

When the homeowner's primary question is "Is this covered?" — start with coverage analysis, then get details for the claim.

Full Arazzo specification: https://philadelphiarestoration.org/arazzo.yaml

Understanding Reasoning Kits

Every tool response follows a consistent structure designed for AI agents to reason over:

{
  "result": { ... },      // Structured data specific to the tool
  "_meta": {
    "reasoning_instructions": "...",  // How to present this data
    "related_tools": [...]            // Suggested next tools to call
  },
  "_sources": ["IICRC S500 §12.3", ...],  // Citations
  "cta": {
    "text": "...",
    "action": "request_callback"
  }
}

The _meta.reasoning_instructions field tells your agent how to interpret and present the data to the homeowner. The _meta.related_tools array suggests which tools to call next based on the current result. Sources cite IICRC standards and other references so your agent can attribute information.

Discovery Endpoints

These files help AI agents and registries discover our service automatically:

• /.well-known/mcp.json — MCP server manifest with tool listing
• /.well-known/agent.json — Agent discovery with transport options
• /.well-known/ai-plugin.json — ChatGPT plugin manifest
• /openapi.yaml — OpenAPI 3.1 specification
• /arazzo.yaml — Arazzo workflow specification
• /llms.txt — LLM-optimized site summary
• /llms-full.txt — Complete knowledge base in markdown

Developer FAQs