# board-spec-mcp

MCP server that serves Qualcomm Yocto board specs (`machine_creation` +
`partition_conf` fields) from the [roshs189/board-spec](https://github.com/roshs189/board-spec)
git repo — one branch per machine. Built to replace reading a Confluence
"Partition Spec" page in the `qcom-yocto-new-machine` and
`qcom-partition-conf-new-board` Claude Code skills.

## What it does

- Clones/fetches `board-spec` into a local cache (`~/.cache/board-spec-mcp/repo`
  by default).
- Reads a board's spec straight from its branch (`origin/<machine>:boards/<machine>/spec.yaml`)
  without checking it out — no working-tree conflicts, always in sync with a
  `refresh_specs` call.
- Validates specs against `schema/board-spec.schema.json` (on `main`) plus the
  cross-checks the skills used to do by hand: `delta=new` partitions need a
  `notes` justification and must not collide with SoC-mandated names
  (`xbl`/`tz`/`hyp`/`aop`/...), `partition_files_subdir` must equal
  `partitions/<machine>/<storage_type>`, chip IDs shouldn't collide across
  boards.

## Setup (anyone, from scratch)

Requires Python 3.10+ and an SSH key with read access to
`github.com/roshs189/board-spec` (or set `BOARD_SPEC_REPO_URL` to a repo you
do have access to — see Configuration below).

```sh
git clone <this-repo-url> board-spec-mcp
cd board-spec-mcp
python3 -m venv .venv
.venv/bin/pip install -e .
```

Verify it starts cleanly:

```sh
.venv/bin/board-spec-mcp   # should hang waiting on stdin — Ctrl-C to exit
```

### Register with Claude Code

Add a `.mcp.json` in the project you want this available in (or merge into
an existing one):

```json
{
  "mcpServers": {
    "board-spec": {
      "command": "/absolute/path/to/board-spec-mcp/.venv/bin/board-spec-mcp"
    }
  }
}
```

Restart Claude Code (or run `/mcp` to reconnect) and the tools below become
available.

## Configuration

Environment variables, all optional:

| Variable | Default | Purpose |
|---|---|---|
| `BOARD_SPEC_REPO_URL` | `git@github.com:roshs189/board-spec.git` | Remote to clone/fetch |
| `BOARD_SPEC_CACHE_DIR` | `~/.cache/board-spec-mcp/repo` | Local bare-ish clone location |

Set these in the `.mcp.json` entry's `"env"` block if you need a fork or a
different cache path:

```json
{
  "mcpServers": {
    "board-spec": {
      "command": "/absolute/path/to/board-spec-mcp/.venv/bin/board-spec-mcp",
      "env": { "BOARD_SPEC_REPO_URL": "git@github.com:<you>/board-spec.git" }
    }
  }
}
```

## Tools

- `list_boards()` — every machine with a branch in `board-spec` (excludes `main`).
- `get_board_spec(machine)` — full spec.
- `get_machine_creation_fields(machine)` — just the `machine_creation` section.
- `get_partition_conf_fields(machine)` — just the `partition_conf` section.
- `validate_board_spec(machine)` — `{valid, schema_errors, warnings}`.
- `refresh_specs()` — fetch latest branches/commits (call after a spec is pushed).

Also exposed as a resource: `board-spec://<machine>`.

## Adding a new board

Specs are human-authored and PR-reviewed in `board-spec` itself — this server
only reads, never writes. See that repo's README for the branch/PR workflow.