# bsdd-mcp

An [MCP](https://modelcontextprotocol.io) server that gives an AI assistant read-only access to the
[buildingSMART Data Dictionary (bSDD)](https://www.buildingsmart.org/users/services/buildingsmart-data-dictionary/) —
the shared library of construction classifications (IFC, ETIM, Uniclass, national dictionaries, …),
their classes, properties, units and relations.

It talks to the public bSDD API at `https://api.bsdd.buildingsmart.org`. No account, API key or
login is needed: every endpoint used here is part of the unsecured, public API.

## Install

```bash
git clone <this repo>
cd bsdd-mcp
npm install       # builds automatically via the prepare script
```

## Use it with Claude Code

```bash
claude mcp add bsdd -- node /absolute/path/to/bsdd-mcp/dist/index.js
```

## Use it with Claude Cowork / Claude Desktop

Cowork installs local MCP servers as `.mcpb` bundles. Build one:

```bash
npm run bundle     # -> build/bsdd-mcp-<version>.mcpb
```

The bundle is self-contained (compiled server + production dependencies), so it does not
depend on this checkout after installation. Install it from **Settings → Connectors →
Install extension…** and pick the `.mcpb` file. Local MCP servers run natively on your
machine, not inside the Cowork sandbox, so the server reaches the bSDD API over your normal
network connection.

If your workplace disables desktop extensions, add the server by hand instead under
**Settings → Developer → Local MCP servers**:

```json
{
  "mcpServers": {
    "bsdd": {
      "command": "node",
      "args": ["C:\\path\\to\\bsdd-mcp\\dist\\index.js"]
    }
  }
}
```

## Use it with any other MCP client

Add this to the client's MCP configuration (`claude_desktop_config.json` for Claude Desktop):

```json
{
  "mcpServers": {
    "bsdd": {
      "command": "node",
      "args": ["C:\\path\\to\\bsdd-mcp\\dist\\index.js"]
    }
  }
}
```

## Tools

| Tool | What it does | bSDD endpoint |
| --- | --- | --- |
| `bsdd_list_dictionaries` | List/filter the published dictionaries | `GET /api/Dictionary/v1` |
| `bsdd_list_dictionary_classes` | Browse the classes of one dictionary (flat or nested) | `GET /api/Dictionary/v1/Classes` |
| `bsdd_list_dictionary_properties` | Browse the properties of one dictionary | `GET /api/Dictionary/v1/Properties` |
| `bsdd_search_classes` | Free-text class search across dictionaries | `GET /api/Class/Search/v1` |
| `bsdd_search_text` | Free-text search returning classes *and* properties | `GET /api/TextSearch/v2` |
| `bsdd_get_class` | Class details, optionally with child classes and relations | `GET /api/Class/v1` |
| `bsdd_get_class_properties` | The properties of a class, with data types and units | `GET /api/Class/Properties/v1` |
| `bsdd_get_class_relations` | Forward or reverse relations of a class | `GET /api/Class/Relations/v1` |
| `bsdd_get_property` | Property details | `GET /api/Property/v5` |
| `bsdd_get_property_classes` | Which classes use a property | `GET /api/Property/Classes/v1` |
| `bsdd_get_property_value` | Details of one value of an enumeration | `GET /api/PropertyValue/v2` |
| `bsdd_list_reference_data` | Countries, languages, units or reference documents | `GET /api/Country\|Language\|Unit\|ReferenceDocument/v1` |

All tools are read-only and annotated as such.

### Typical flow

1. `bsdd_list_dictionaries` — find the dictionary URI you need. URIs always contain a version,
   e.g. `https://identifier.buildingsmart.org/uri/buildingsmart/ifc/4.3`; the version can be
   replaced by `latest`.
2. `bsdd_search_classes` — find a class by name, e.g. *"which class describes a wall?"*.
3. `bsdd_get_class` for the definition, `bsdd_get_class_properties` for its properties,
   `bsdd_get_class_relations` to map it onto classes in other dictionaries.

## Configuration

All optional, read from the environment:

| Variable | Default | Purpose |
| --- | --- | --- |
| `BSDD_API_BASE_URL` | `https://api.bsdd.buildingsmart.org` | Point at another bSDD instance |
| `BSDD_TIMEOUT_MS` | `30000` | Per-request timeout |
| `BSDD_MAX_RETRIES` | `3` | Retries on HTTP 429 / 5xx |
| `BSDD_USER_AGENT` | `bsdd-mcp/<version>` | User-Agent sent to bSDD |

## Notes on the bSDD API

These are behaviours of the upstream API that the server works around, and that are worth knowing
when reading the results:

- **Rate limiting.** bSDD answers with HTTP 429 and a message like *"Try again in 4 seconds"*.
  The client honours `Retry-After` (and that message) and retries with exponential backoff.
- **IFC and text search.** `/api/TextSearch/v2` treats the IFC dictionary as a *preview* dictionary
  and leaves it out unless `IncludePreview` is set, so `bsdd_search_text` sets it by default.
  `bsdd_search_classes` (`/api/Class/Search/v1`) always covers IFC.
- **Class properties.** The `IncludeClassProperties` option of `/api/Class/v1` is deprecated and
  heavily rate limited; `bsdd_get_class_properties` uses the dedicated paginated endpoint instead.
- **Page size.** The API returns up to 1000 items per call. These tools default to 50 to keep
  responses reasonable for a model context; pass `limit` explicitly when you need more.

## Development

```bash
npm run build      # compile TypeScript to dist/
npm run typecheck  # type-check only
npm test           # build + unit tests (no network; fetch is stubbed)
npm run test:live  # calls every tool against the real bSDD API
```

## License

MIT — see [LICENSE](LICENSE). bSDD content itself is published by buildingSMART International and
its dictionary owners under their own licenses (each dictionary reports its `license` field).