# bpm-mcp

MCP server for [BPM](https://www.usebpm.dev) - discover, inspect, and install behavioral packages from within agent sessions.

Instead of switching to a terminal to manage packages, the agent can search the registry, show you what a package does, and install it after you approve.

## Install

```bash
cd ~/development/bpm-mcp
uv pip install -e .
```

Requires the BPM CLI: `npm install -g @dakotafabrodev/agent-bpm`

## Goose Config

Add to `~/.config/goose/config.yaml`:

```yaml
bpm:
  enabled: true
  type: stdio
  name: BPM
  description: Discover and install behavioral packages
  cmd: uv
  args:
    - run
    - --directory
    - /path/to/bpm-mcp
    - bpm-mcp
  envs: {}
  env_keys: []
  timeout: 30
  bundled: false
  available_tools: []
```

## Tools

### `bpm_search(query)`

Search the BPM registry by keyword. Returns matching packages with name, type, description, version, and token cost.

### `bpm_inspect(package_name)`

Get full details about a package including its README, review status, dependencies, and peers. Use this before recommending installation.

### `bpm_install(package_name)`

Install a package. Enforces human approval before installing. Returns an approval prompt that the human must confirm before the install proceeds.

### `bpm_confirm_install(package_name, always_allow?)`

Execute the install after human approval. Set `always_allow=true` to auto-approve this package in the future.

After a successful install, the result includes:

- any warnings `bpm install` printed, such as `[BPM_INSTALL_CONFLICT]`, deprecations and review notices, each with its `Action:` line
- the package's instructions (its entry file, or the merged file when it has an overlay), so they apply for the rest of the session instead of waiting for the next session's AGENTS.md. Text over 20,000 characters is cut off with the path to the full file.

### `bpm_remove(package_name)`

Remove an installed package. Warnings from `bpm remove`, such as `[BPM_REMOVE_STILL_NEEDED]` when another installed package depends on it, are included in the result.

### `bpm_list()`

List all installed packages and their total token cost.

### `bpm_set_approval_policy(mode)`

Control how installs are approved:

- `always_ask` (default) - every install requires explicit human approval
- `auto_approve_known` - packages the human has previously approved install automatically, new packages still require approval

## Approval Flow

Package installation changes agent behavior. The server enforces a two-step approval:

1. Agent calls `bpm_install("package-name")`
2. Server returns an approval prompt (not the install)
3. Human says "approve install package-name" or "always allow package-name"
4. Agent calls `bpm_confirm_install("package-name")` or `bpm_confirm_install("package-name", always_allow=true)`
5. Package installs

The approval policy is stored at `~/.bpm/mcp-policy.json`.

## How It Works

- **Search and inspect** hit the usebpm.dev registry API directly (read-only, no auth needed)
- **Install, remove, and list** shell out to the local `bpm` CLI
- The server never installs packages without going through the approval gate
- All operations are local - no data leaves your machine except registry search queries

## Testing

```bash
uv run --with pytest --with pytest-asyncio pytest -q tests
```

## License

Apache 2.0