# RoofScope MCP Server (unofficial)

An [MCP](https://modelcontextprotocol.io) server for the [RoofScope](https://roofscope.com) API by Scope Technologies. It lets an AI assistant such as Claude, Cursor or any other MCP client:

- find your RoofScope reports by address or name;
- read a report's measurements: roof area by pitch, eaves, rakes, ridges, hips, valleys, flashing, every roof plane, gutters and downspouts, siding, and links to the PDF, DXF and DWG files;
- look up your account's report prices and delivery options;
- order new reports and upgrade RoofScopeX reports, **only if you turn ordering on**.

> **Unofficial.** This project is not affiliated with, endorsed by, or supported by Scope Technologies. RoofScope is a trademark of Scope Technologies. It uses their public API as documented at [docs.myscopetech.io](https://docs.myscopetech.io).

Try asking:

- "Pull the RoofScope measurements for 100 Example Ave."
- "How many squares is the roof on the Johnson job, and what's the pitch breakdown?"
- "What would a rush residential RoofScope cost us?"

## What you need

1. **Node.js 20 or later.**
2. **An API key from Scope Technologies.** Every app that uses the RoofScope API needs one. Email [support@myscopetech.com](mailto:support@myscopetech.com) to request it.
3. **Your account's Scope API Token.** In RoofScope, open **My Details** and copy the token from the **Third-Party** section. Tokens last a year; when one expires, click refresh there and update your configuration. RoofScope gives tokens to Growth and Advantage members, L1/L2 deposit holders and partner customers.

## Set it up

### Claude Desktop

Open **Settings → Developer → Edit Config** and add this to `claude_desktop_config.json`, then restart Claude:

```json
{
  "mcpServers": {
    "roofscope": {
      "command": "npx",
      "args": ["-y", "github:cogear/roofscope-mcp"],
      "env": {
        "ROOFSCOPE_API_KEY": "your-scope-technologies-api-key",
        "ROOFSCOPE_TOKEN": "your-scope-api-token"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add roofscope \
  -e ROOFSCOPE_API_KEY=your-scope-technologies-api-key \
  -e ROOFSCOPE_TOKEN=your-scope-api-token \
  -- npx -y github:cogear/roofscope-mcp
```

### Other MCP clients

Any client that can start a local (stdio) server works. The command is `npx -y github:cogear/roofscope-mcp`, with the environment variables below.

### From source

```bash
git clone https://github.com/cogear/roofscope-mcp.git
cd roofscope-mcp
npm install        # also builds dist/
```

Then point your client at `node /path/to/roofscope-mcp/dist/index.js`.

## Configuration

| Variable | Required | What it is |
| --- | --- | --- |
| `ROOFSCOPE_API_KEY` | yes | The API key Scope Technologies issued you. |
| `ROOFSCOPE_TOKEN` | yes | Your account's Scope API Token (My Details → Third-Party). |
| `ROOFSCOPE_ALLOW_ORDERS` | no | Set to `true` to let the assistant place paid orders. Off by default. |
| `ROOFSCOPE_SOURCE_ID` | no | Only if Scope Technologies assigned you a source id. |

## Tools

| Tool | What it does |
| --- | --- |
| `search_roofscope_scopes` | Find reports by address or name, with status, hold reason and order date. |
| `get_roofscope_scope` | One report's measurements, per building and per plane, plus file links. |
| `get_roofscope_prices` | What each report costs on your account. |
| `get_roofscope_delivery_options` | Standard and rush delivery charges. |
| `check_roofscope_connection` | Whether the key and token work, and whether ordering is on. |
| `order_roofscope_report` | Order a new report. **Charges your account.** Only with `ROOFSCOPE_ALLOW_ORDERS=true`. |
| `upgrade_roofscope_x` | Upgrade a RoofScopeX to a full report. **Charges your account.** Only with `ROOFSCOPE_ALLOW_ORDERS=true`. |

## Ordering is off by default

RoofScope charges every order to your account, and orders can't be cancelled through the API. So the two ordering tools don't exist unless you start the server with `ROOFSCOPE_ALLOW_ORDERS=true`. When they're on:

- the assistant is told to search for an existing report first, quote the price, and get your explicit go-ahead on the address, product, size, structures and delivery;
- RoofScope's own order rules (buildings per order, required fields, date and email formats) are checked before anything is sent;
- an order is sent exactly once and never retried. If RoofScope doesn't answer in time, the tool says the order *may* have gone through and to check before ordering again.

## Limits and privacy

- Scope Technologies limits each API key to 100 requests a second and 10,000 a month. This server sends at most four requests at a time and retries a failed read once.
- The server runs on your own computer and talks only to `api.myscopetech.io`. It doesn't log or store report contents, names or addresses.

## Development

```bash
npm install
npm test             # offline tests: no network, no keys
npm run typecheck
ROOFSCOPE_API_KEY=… ROOFSCOPE_TOKEN=… npm run live-check   # read-only check against the real API
```

The live check never calls the order endpoints and prints only counts and field names.

## Using RoofScope across a team

This server connects one RoofScope account for one person. If your team wants RoofScope alongside your email, calendar and CRM, with a separate access level for each role, it's built into [Higgs Hub](https://higgshub.pro), which is where this code came from.

## License

[MIT](LICENSE)