# COBie MCP

MCP server for COBie Excel validation, updates, and PDF extraction.

Works with local `.xlsx` and PDF files over stdio. Compatible with Claude Desktop, Claude Code, Cursor, and other MCP clients.

<!-- mcp-name: io.github.roynertr/cobie-mcp -->

## Requirements

- Python 3.12+
- [uv](https://github.com/astral-sh/uv)

## Install

### Quick (PyPI / MCP Registry)

```bash
uvx cobie-mcp
```

### From source

```bash
git clone https://github.com/roynertr/cobie-mcp.git
cd cobie-mcp
uv sync
```

## Configure

### Claude Desktop / Cursor (recommended: uvx)

```json
{
  "mcpServers": {
    "cobie-mcp": {
      "command": "uvx",
      "args": ["cobie-mcp"],
      "env": {
        "ENABLE_HEALTH_SERVER": "false"
      }
    }
  }
}
```

### From a local clone

```json
{
  "mcpServers": {
    "cobie-mcp": {
      "command": "uv",
      "args": ["run", "python", "-m", "server.mcp_server"],
      "cwd": "/absolute/path/to/cobie-mcp",
      "env": {
        "ENABLE_HEALTH_SERVER": "false"
      }
    }
  }
}
```

On Windows, use an absolute path for `uv` / `uvx` if it is not on PATH, for example `C:\\Users\\<you>\\.local\\bin\\uv.exe`, and double backslashes in JSON.

### Claude Code

This repo includes [`.mcp.json`](.mcp.json). Open the project root, approve the server when prompted, then confirm tools with `/mcp`.

See [INSTALL.md](INSTALL.md) for checklists, test prompts, and troubleshooting.

## Main tools

| Tool | Purpose |
|------|---------|
| `load_cobie_summary` | Sheet and key counts |
| `validate_cobie` | Validation report |
| `list_floors` / `list_spaces` / `list_components` | Browse entities |
| `preview_update` / `update_cobie` | Dry-run or apply edits (`actor_contact` required for writes) |
| `extract_from_submittal` | PDF extraction |
| `capture_installation` | Installation capture with evidence |

Canonical tool names are listed in [`server/tool_manifest.json`](server/tool_manifest.json). Graph / Neo4j tools are optional and return a clear error when Neo4j is not configured.

## Smoke test

```bash
uv run pytest tests/test_mcp_smoke.py tests/test_tool_manifest_drift.py tests/test_mcp_tools.py -v
```

## License

MIT