Metadata-Version: 2.4
Name: agentbridge-mcp-server
Version: 0.1.0
Summary: AgentBridge Nexus MCP server for AI coding agents
Author-email: AgentBridge <hello@agentbridge.dev>
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.9.0
Requires-Dist: pydantic-settings>=2.5.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
Requires-Dist: ruff>=0.7.0; extra == "dev"

# AgentBridge Nexus MCP Server

Python MCP server that exposes AgentBridge backend actions as tools for AI coding agents.

## Status

The backend/MCP terminal MVP is implemented and live-tested. The package currently provides:

- backend HTTP client
- testable tool functions
- MCP `FastMCP` entrypoint
- core lifecycle, artifact, coordination, audit, memory, and validation tools

## Environment

Set these before running the MCP server:

```bash
export AGENTBRIDGE_API_URL="http://localhost:8000"
export AGENTBRIDGE_AGENT_KEY="abk_your_agent_key"
```

`AGENTBRIDGE_AGENT_KEY` should be one of the keys printed by:

```bash
cd services/api
.venv/bin/python scripts/seed_dev.py --apply
```

## Tools

- `agentbridge_heartbeat`
- `agentbridge_create_handoff`
- `agentbridge_list_handoffs`
- `agentbridge_claim_handoff`
- `agentbridge_submit_artifact`
- `agentbridge_get_artifact`
- `agentbridge_get_artifact_content`
- `agentbridge_request_review`
- `agentbridge_create_approval`
- `agentbridge_submit_review`
- `agentbridge_complete_handoff`
- `agentbridge_acquire_file_lock`
- `agentbridge_release_file_lock`
- `agentbridge_list_file_locks`
- `agentbridge_list_file_conflicts`
- `agentbridge_resolve_file_conflict`
- `agentbridge_list_audit_logs`
- `agentbridge_create_project_memory`
- `agentbridge_list_project_memory`
- `agentbridge_search_project_memory`
- `agentbridge_update_project_memory`
- `agentbridge_delete_project_memory`
- `agentbridge_start_work_session`
- `agentbridge_list_work_sessions`
- `agentbridge_checkpoint_progress`
- `agentbridge_resume_project`

Resume workflow tools:

- `agentbridge_start_work_session` starts tracking a feature/task in progress.
- `agentbridge_checkpoint_progress` records where the agent is before stopping.
- `agentbridge_resume_project` generates the continuation packet and prompt for another agent.

## Run

From this directory:

```bash
python -m agentbridge_mcp.server
```

When installed as a package:

```bash
agentbridge-mcp
```

## One-Command Resume

Record the current stopping point before switching agents or hitting a usage
limit:

```bash
PYTHONPATH=src ../api/.venv/bin/python -m agentbridge_mcp.checkpoint_cli \
  --project-id <project_id> \
  --summary "Implemented backend slice and verified focused tests." \
  --current-step "Ready to hand off" \
  --next-step "Continue from the recorded checkpoint"
```

When installed as a package:

```bash
agentbridge-checkpoint \
  --project-id <project_id> \
  --summary "Implemented backend slice and verified focused tests." \
  --next-step "Continue from the recorded checkpoint"
```

The checkpoint command reads local git state by default: branch, latest commit,
worktree path, and dirty files. Use `--no-git` to disable auto-detection.

Generate a resume packet for another agent:

```bash
PYTHONPATH=src ../api/.venv/bin/python -m agentbridge_mcp.resume_cli \
  --project-id <project_id> \
  --target-agent antigravity
```

Save it locally:

```bash
PYTHONPATH=src ../api/.venv/bin/python -m agentbridge_mcp.resume_cli \
  --project-id <project_id> \
  --target-agent antigravity \
  --output .agentbridge/resume-antigravity.md
```

When installed as a package:

```bash
agentbridge-resume --project-id <project_id> --target-agent antigravity
```

The command reads `AGENTBRIDGE_API_URL` and `AGENTBRIDGE_AGENT_KEY` from the
environment, calls the resume packet API, prints the generated prompt, and
optionally saves it. It also prints `safety_status` and `should_continue` so
the next agent can pause when locks or conflicts are present. If `expires_at`
has passed, it prints a stale packet warning and the agent should regenerate the
packet before continuing. It never prints agent keys.

With `--json`, the command also adds a local `is_expired` boolean so scripts can
block continuation without parsing timestamps themselves.

## Test

The tool layer can be tested without a live backend:

```bash
PYTHONPATH=src pytest tests -q
```

## Terminal Demo

Mock mode works without a backend:

```bash
PYTHONPATH=src python -m agentbridge_mcp.demo
```

Live mode uses `AGENTBRIDGE_API_URL` and `AGENTBRIDGE_AGENT_KEY`, then prompts for the Antigravity key, project ID, and agent IDs. Use the Codex key as `AGENTBRIDGE_AGENT_KEY`.

```bash
PYTHONPATH=src python -m agentbridge_mcp.demo --live
```

## Live Backend Validation

Run these after the API is running on `http://127.0.0.1:8000`:

```bash
PYTHONPATH=src ../api/.venv/bin/python -m agentbridge_mcp.live_artifact_validation
PYTHONPATH=src ../api/.venv/bin/python -m agentbridge_mcp.live_coordination_validation
PYTHONPATH=src ../api/.venv/bin/python -m agentbridge_mcp.live_resume_validation
PYTHONPATH=src ../api/.venv/bin/python -m agentbridge_mcp.live_cli_resume_validation \
  --output /tmp/agentbridge-cli-resume.md
PYTHONPATH=src ../api/.venv/bin/python -m agentbridge_mcp.live_reverse_resume_validation
```

Required environment variables:

```bash
export AGENTBRIDGE_API_URL="http://127.0.0.1:8000"
export AGENTBRIDGE_AGENT_KEY="<codex_agent_key>"
export AGENTBRIDGE_PROJECT_ID="<project_id>"
export AGENTBRIDGE_CODEX_AGENT_ID="<codex_agent_id>"
export AGENTBRIDGE_ANTIGRAVITY_AGENT_ID="<antigravity_agent_id>"
export AGENTBRIDGE_ANTIGRAVITY_AGENT_KEY="<antigravity_agent_key>"
```

`live_reverse_resume_validation` uses `AGENTBRIDGE_ANTIGRAVITY_AGENT_KEY` to
create/checkpoint a handoff targeting Codex, then uses `AGENTBRIDGE_AGENT_KEY`
as Codex to generate the resume packet and verify the latest Antigravity
checkpoint is preserved.

## IDE Validation Checklist

Use the adapter configs in `adapters/codex` and `adapters/antigravity`.

1. Start the API:

   ```bash
   cd services/api
   .venv/bin/uvicorn main:app --port 8000
   ```

2. Confirm health:

   ```bash
   curl http://127.0.0.1:8000/api/v1/health
   ```

3. Configure Codex with the Codex agent key and Antigravity with the Antigravity agent key.
4. From Codex, call `agentbridge_heartbeat`.
5. From Codex, create a handoff assigned to Antigravity.
6. From Antigravity, list assigned handoffs and claim the new handoff.
7. From Antigravity, submit an artifact and request Codex review.
8. From Codex, fetch the artifact content, submit the review, and complete the handoff.
9. If any MCP tool fails in the IDE but works from terminal validation, record the exact tool name, payload, and API error before changing backend behavior.
