Submit
nhantruong96

bsdd-mcp

Community nhantruong96
Updated

MCP server for the buildingSMART Data Dictionary (bSDD)

bsdd-mcp

An MCP server that gives an AI assistant read-only access to thebuildingSMART Data Dictionary (bSDD) —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 orlogin is needed: every endpoint used here is part of the unsecured, public API.

Install

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

Use it with Claude Code

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:

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

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

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

{
  "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):

{
  "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 bereplaced 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 knowingwhen 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 dictionaryand 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 andheavily 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 keepresponses reasonable for a model context; pass limit explicitly when you need more.

Development

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. bSDD content itself is published by buildingSMART International andits dictionary owners under their own licenses (each dictionary reports its license field).

MCP Server · Populars

MCP Server · New