Metadata-Version: 2.4
Name: backplane-mcp
Version: 0.1.0
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 —
98 tools across workspaces, boards, cards, executions, approvals, notes,
resources, and pipeline configuration, plus role-specific prompts for the
project-initializer, secretary, architect, and coding-agent workflows.

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 under Platform Settings, or `POST /api/me/api-keys`. |
| `VALARIS_AGENT_EMAIL` | no | Identity recorded on writes when running as an agent |

> 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`.

## 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            # 285 tests
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.
