board-spec-mcp

MCP server that serves Qualcomm Yocto board specs (machine_creation + partition_conf fields) from the 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).

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:

.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):

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

{
  "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.