Content
# 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.
