Metadata-Version: 2.5
Name: backplane-mcp
Version: 0.7.1
Summary: MCP server exposing Backplane platform tools for AI agents
Project-URL: Homepage, https://github.com/Valaris-Studio/backplane
Project-URL: Repository, https://github.com/Valaris-Studio/backplane.git
Project-URL: Issues, https://github.com/Valaris-Studio/backplane/issues
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.12
Requires-Dist: google-auth>=2.29.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp[cli]<2,>=1.12.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# Backplane MCP Server

An [MCP](https://modelcontextprotocol.io) server that exposes the
[Backplane](https://github.com/Valaris-Studio/backplane) platform to AI agents.
The live catalog spans workspaces, boards, cards, executions, approvals, notes,
resources, and pipeline configuration, plus role-specific prompts and resources.
Use `get_server_info` or the in-app MCP reference for the catalog served by the
version you are running instead of relying on a frozen tool count.

Point any MCP-capable client (Claude Code, Claude Desktop, or your own agent) at
a Backplane instance and it can read board state, claim and move cards, log
executions, and request approvals.

## Install

```bash
uvx backplane-mcp
```

Or from source:

```bash
uvx --from "git+https://github.com/Valaris-Studio/backplane.git#subdirectory=mcp-server" backplane-mcp
```

## Configure

Add to your MCP client's config (e.g. `~/.claude.json` or
`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "valaris": {
      "command": "uvx",
      "args": ["backplane-mcp"],
      "env": {
        "VALARIS_API_URL": "https://your-backplane-host",
        "VALARIS_API_KEY": "vlr_..."
      }
    }
  }
}
```

| Variable | Required | Purpose |
|---|---|---|
| `VALARIS_API_URL` | yes | Base URL of your Backplane backend |
| `VALARIS_API_KEY` | yes | Platform API key (`vlr_…`). Create one in the UI from your account menu (API Keys), or `POST /api/me/api-keys`. |
| `VALARIS_AGENT_EMAIL` | no | development fallback identity when neither a bearer API key nor an authenticated proxy supplies identity. It is ignored when `VALARIS_API_KEY` is used. |
| `VALARIS_MCP_TOOLSETS` | no | Which slice of the tool surface this session lists at startup. Unset loads the default interactive hand (or every tool when `VALARIS_MCP_ALLOWLIST` is set, the runner shape); `all` loads every tool; a comma list of group/category ids (with `default` as an alias, e.g. `default,autonomous-operations`) composes a custom hand. An unknown id fails startup. A running session widens its hand with the `enable_toolsets` tool (same ids). |

### Upgrading from 0.5.0

0.6.0 lists the interactive default hand instead of every tool. To keep the
full surface an existing config had, add one line to the server env:

```json
"VALARIS_MCP_TOOLSETS": "all"
```

Runner launches need nothing: a present `VALARIS_MCP_ALLOWLIST` with no
toolsets env loads every toolset, and new runner binaries pin `all`.

For an autonomous runner, or whenever you want the full surface, add
`VALARIS_MCP_TOOLSETS`:

```json
{
  "mcpServers": {
    "valaris": {
      "command": "uvx",
      "args": ["backplane-mcp"],
      "env": {
        "VALARIS_API_URL": "https://your-backplane-host",
        "VALARIS_API_KEY": "vlr_...",
        "VALARIS_MCP_TOOLSETS": "all"
      }
    }
  }
}
```

The default hand covers project context, search, boards, cards, notes and
the other knowledge tools, plus a few read-only helpers (linked git repos,
the board's skills, velocity and cost), leaving workspace-admin and
destructive verbs, the collaboration setup tools and the rest of the
autonomous-operations tools opt-in. The env var picks the initial hand only.
Every hand, including the default one, also carries the `server-info` category:
`get_server_info`, `whoami` and `enable_toolsets`. Call `get_server_info` and
read its `toolsets` key to see what is loaded and which toolset ids exist; call
`enable_toolsets(toolset_ids)` with any of those ids (`all`, `default`, or a
group/category id) to widen the running session without a restart. Widening is
widen-only, idempotent and per-process, and after one that adds tools the
server sends `notifications/tools/list_changed` (the handshake advertises
`tools.listChanged: true`). A client that ignores that notification still
needs `VALARIS_MCP_TOOLSETS` to see a wider hand. `VALARIS_MCP_ALLOWLIST`
stays a ceiling the tool never lifts: `resolved_tool_count` in
`get_server_info` is the size of the loaded toolsets before the allowlist
intersection; `enabled_tools` is the hand after it.

> The server name `valaris` is a stable, permanent namespace — agent tool names
> are `mcp__valaris__*`. It is intentionally not renamed alongside product
> branding, because renaming it would break every existing agent config. The
> `valaris-mcp` console script remains as an alias of `backplane-mcp`.

## Upgrading

### Upgrading from 0.7.0

0.7.1 changes nothing in existing configs. It adds `enable_toolsets`, so an
interactive session widens its hand at runtime instead of restarting with a
wider `VALARIS_MCP_TOOLSETS`; runner grants are unaffected.

Retired or renamed tools stay callable for one minor version as deprecated
aliases: `get_server_info` lists them under `deprecated_aliases` with their
replacement and `deprecated_removed_in`, and `allowlist_deprecated` names the
ones a `VALARIS_MCP_ALLOWLIST` still grants. The CHANGELOG carries the
rename → replacement table for each release.

## Getting started as an agent

Start with `get_project_context` — one call returns the board definition, a board
summary, notes, git repos, and recent activity. Then use the prompt matching your
role (`init_project`, `standup`, `plan_work`, `pickup`, …).

Autonomous runners must claim work through `next_assignment`, never by searching
and claiming manually: the backend scheduler applies every role-aware filter and
atomically reserves one card with its bundled context. Interactive agents and
humans claim by moving the card into the column resolved by `column_type` and
adding themselves as a participant.

## Development

```bash
pip install -e ".[dev]"
pytest
ruff check src/
```

A drift guard in the platform's backend test suite asserts this server's tool
catalog stays in sync with the frontend's documentation catalog, so adding a tool
requires updating both.

## License

AGPL-3.0-or-later — see [LICENSE](LICENSE). The MCP **tool and prompt schemas**
(names, descriptions, input/output JSON Schemas) are additionally available under
Apache-2.0 so integrations can implement against them freely; see
[LICENSES.md](../LICENSES.md) in the repository root.
