# brick-ontology-mcp

An MCP server that gives LLMs native access to the [Brick Schema](https://brickschema.org/) ontology — the open standard for describing building metadata (equipment, sensors, locations, and relationships).

**Validate, search, and explore 1000+ Brick classes** without leaving your AI coding assistant. Fully offline after install.

## Why

If you work with smart building data, you've hit these problems:

1. **Assigning classes that don't exist** — RDF silently accepts `brick:Chilled_Water_Thingy` without complaint
2. **Not knowing what's available** — with 1000+ classes, it's hard to find the right one
3. **Reinventing existing classes** — creating `My_Custom_Temp_Sensor` when `Zone_Air_Temperature_Sensor` already exists
4. **Wrong specificity level** — using `brick:Sensor` when a more precise subclass is available

This MCP server solves all four by making any MCP-compatible client (Claude Code, Claude Desktop, Cursor, etc.) aware of the full Brick class hierarchy.

## Tools

| Tool | What it does |
|------|-------------|
| `brick_validate_class` | Check if a class exists. Handles camelCase, spaces, typos — returns fuzzy suggestions if not found. |
| `brick_search_classes` | Search classes by keyword with optional category filter. |
| `brick_get_hierarchy` | Get ancestors and/or descendants of a class. |
| `brick_list_classes` | List all classes under a category (Equipment, Sensor, Setpoint, etc.) as a tree. |

All tools are **read-only** and **fully offline** — the Brick ontology is bundled with the `brickschema` Python package. No API keys, no network calls.

## Installation

### From source

```bash
git clone https://github.com/ucl-sbde/brick-ontology-mcp.git
cd brick-ontology-mcp
pip install .
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
uv pip install .
```

## Configuration

### Claude Code

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "brick-ontology": {
      "command": "brick-ontology-mcp"
    }
  }
}
```

Or globally in `~/.claude.json`:

```json
{
  "mcpServers": {
    "brick-ontology": {
      "command": "brick-ontology-mcp"
    }
  }
}
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "brick-ontology": {
      "command": "brick-ontology-mcp"
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "brick-ontology": {
      "command": "brick-ontology-mcp"
    }
  }
}
```

## Example Usage

### "Does this class exist?"

> You: Assign `brick:Chilled_Water_Thingy` to this valve

The LLM calls `brick_validate_class("Chilled_Water_Thingy")` and gets:

```json
{
  "exists": false,
  "normalized_to": "Chilled_Water_Thingy",
  "suggestions": [
    {"class_name": "Chilled_Water_Valve", "similarity": 0.8},
    {"class_name": "Chilled_Water_Pump", "similarity": 0.65}
  ]
}
```

### "What classes exist for temperature sensors?"

> You: What types of temperature sensors does Brick have?

The LLM calls `brick_search_classes("temperature sensor")` and gets all matching classes with their categories and parent classes.

### "Am I reinventing the wheel?"

> You: I'll create a custom `Hot_Water_Supply_Temp` class

The LLM calls `brick_search_classes("hot water temperature")` and discovers `Hot_Water_Supply_Temperature_Sensor` already exists.

### "What's the hierarchy?"

> You: Where does Zone_Air_Temperature_Sensor sit in the ontology?

The LLM calls `brick_get_hierarchy("Zone_Air_Temperature_Sensor", direction="ancestors")` and gets:

```
Zone_Air_Temperature_Sensor
  -> Air_Temperature_Sensor
    -> Temperature_Sensor
      -> Sensor
        -> Point
```

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Test the server with MCP Inspector
npx @modelcontextprotocol/inspector brick-ontology-mcp
```

## How It Works

The server loads the [Brick Schema](https://brickschema.org/) ontology (v1.4+) at startup using the [`brickschema`](https://pypi.org/project/brickschema/) Python library. It pre-indexes all class names, parent/child relationships, and category assignments into in-memory data structures. Tool calls are sub-millisecond lookups against this index — no SPARQL queries at runtime for validation and search.

Built with [FastMCP](https://github.com/modelcontextprotocol/python-sdk) (the official MCP Python SDK).

## License

MIT