Metadata-Version: 2.4
Name: northstar-agent-bridge
Version: 0.1.2
Summary: Reference MCP bridge service for Northstar story execution
Author: Northstar
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn>=0.29
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: httpx>=0.27

# northstar-agent-bridge

Reference MCP bridge implementation for Northstar.

It exposes the endpoints Northstar calls:

- `GET /health`
- `POST /tools/run_story`
- `POST /tools/report_status`
- `POST /tools/submit_result`

## Install

```bash
pip install northstar-agent-bridge
```

Or for local dev in this repo:

```bash
pip install -e packages/northstar-agent-bridge
```

Initialize backend MCP config (recommended):

```bash
python -m northstar_agent_bridge init --backend-env backend/.env --runner-mode codex
```

Store PAT once:

```bash
python -m northstar_agent_bridge login --api-key <ns_pat_...>
```

## Configuration

Set these env vars:

```env
MCP_PROVIDER_NAME=codex-local-bridge
MCP_BRIDGE_HOST=127.0.0.1
MCP_BRIDGE_PORT=8787

# Optional runtime mode
MCP_RUNNER_MODE=mock
MCP_MOCK_DELAY_SECONDS=8
MCP_RUNNER_CMD=codex
MCP_CODEX_CMD=codex exec --json --full-auto -
MCP_RUNNER_TIMEOUT_SECONDS=1800
MCP_BACKEND_BASE_URL=http://127.0.0.1:8000
MCP_PAT_VALIDATE_URL=http://127.0.0.1:8000/api/v1/spec-cli/auth/pat/validate
MCP_PAT_CACHE_TTL_SECONDS=300
```

`MCP_RUNNER_MODE`:

- `mock`: in-memory simulated completion
- `command`: executes `MCP_RUNNER_CMD` with `task_markdown` piped to stdin
- `codex`: built-in codex runner using `MCP_CODEX_CMD` (or `MCP_RUNNER_CMD`, default `codex exec --json --full-auto -`)

## Run

```bash
northstar-agent-bridge
```

or:

```bash
python -m northstar_agent_bridge
```

This now starts the bridge in the background (daemon mode) and returns your shell immediately.

Useful commands:

```bash
northstar-agent-bridge status   # check daemon state
northstar-agent-bridge stop     # stop daemon
northstar-agent-bridge serve    # run foreground (debug mode)
```
