# agent-coordination-mcp

An experimental local MCP server for coordinating installed CLI agents across projects that use file-based task boards, locks, and shared status files.

The goal is not to replace the `ai-agent-teamwork` workflow. It is to expose that workflow as a small MCP control plane so a primary agent can see which CLI agents are available, assign work, inspect project coordination state, and keep durable assignment records.

## Why This Works

The workflow works if the MCP server stays narrow:

- MCP is the coordination surface, not the editor.
- Project state remains in plain files owned by each project.
- CLI agents continue to run as separate tools with their own approval and sandbox behavior.
- Assignment and heartbeat records are explicit JSON state, not inferred from hidden sessions.

The risky part is supervising long-running CLI processes. This first slice records assignments and generates dispatch intent; later slices can add process launch adapters per CLI once the approval and lifecycle model is clear.

## Current Tools

- `list_cli_agents` - detect known local CLI agents on `PATH`.
- `get_project_status` - summarize `.agent-tasks.json`, `.agent-manifest.json`, and `.agent-status.md` for a project.
- `list_assignments` - read active and historical assignment records.
- `assign_task` - record a task assignment to a detected CLI agent.
- `update_assignment_status` - update assignment status and notes.

## Install

```bash
uv sync
uv run agent-coordination-mcp
```

## Dynamic MCP Proxy Entry

Add this to `/home/stephen/dynamic-mcp-proxy-server/user.catalogue.json`:

```json
{
  "name": "agent-coordination",
  "description": "Local MCP control plane for detecting CLI agents and coordinating file-based project task boards",
  "command": "uv --project /home/stephen/projects/agent-coordination-mcp run agent-coordination-mcp",
  "tags": ["agents", "coordination", "mcp", "cli", "local"],
  "tech_stack": ["python", "mcp", "cli-agents"],
  "runtime": "stdio",
  "env_vars": []
}
```

## Planned Slices

1. Inventory and assignment tracking.
2. `ai-agent-teamwork` task board adapters.
3. CLI-specific dispatch adapters for `opencode`, `codex`, `gemini`, `claude`, and other installed agents.
4. Process/session tracking where supported by the CLI.
5. Dynamic proxy integration and research tools such as `devto-mcp-server`.

See [docs/ROADMAP.md](docs/ROADMAP.md) for the current implementation plan. The next slice is capability-aware inventory before automated dispatch.

## Non-Goals

- No hidden project edits by the MCP server.
- No generic shell execution tool.
- No automatic force-unlocking or stale-task rewrites without explicit tool calls.
- No assumption that every CLI supports resumable sessions.