ACE Swarm MCP Server

ACE Swarm packages the ACE framework (agents, skills, schemas, prompts, tasks, handoffs, and state scaffolding) as an MCP server and turnkey CLI.

Swarm agents (orchestrator, vos, ui, coders) and composable agents (skeptic, ops, research, spec, builder, qa, docs) are treated as one unified agent system, with composable agents available as subagents for every swarm workflow.

Suggestions and collaborations: [email protected].

Install

npm install -g ace-swarm

You can run the same CLI as either:

ace mcp
# or
ace-swarm mcp

For one-off execution:

npx -y ace-swarm mcp

Turnkey Setup (Recommended)

Bootstrap everything into the current workspace, including .agents, agent-state, scripts, and multi-client MCP config bundle:

npx -y ace-swarm turnkey --project "My Project"

Equivalent command:

npx -y ace-swarm init --project "My Project"

This writes:

• agent-state/*
• .agents/ACE/* and .agents/skills/*
• tasks/*
• scripts/ace/*
• .vscode/mcp.json
• .mcp-config/{codex.config.toml,vscode.mcp.json,claude_desktop_config.json,cursor.mcp.json,antigravity.mcp.json}

Turnkey with Ollama (Local Models)

Bootstrap ACE + local model profile in one command:

npx -y ace-swarm turnkey --project "My Project" --llm ollama --model llama3.1:8b

Then enable and verify local runtime:

ollama serve
ollama pull llama3.1:8b
ace doctor --llm ollama --model llama3.1:8b

If you need to explicitly (re)write MCP config for your editor:

ace mcp-config --client vscode > .vscode/mcp.json
# or choose codex|claude|cursor|antigravity

Artifacts written for local-model flow:

• .ace/llm-profile.json
• .ace/doctor-checks.md

Rollout status:

• P0: init/turnkey supports --llm ollama --model --ollama-url.
• P1: ace doctor validates MCP config, Ollama endpoint, and model presence.
• P2: MCP bootstrap_state supports llm_provider, ollama_model, ollama_base_url.

Client Compatibility

ACE Swarm ships config templates for:

• Codex
• VS Code
• Claude Desktop
• Cursor
• Antigravity

Get config snippets from CLI

ace mcp-config --client codex
ace mcp-config --client vscode
ace mcp-config --all

Expected config targets

• codex: $CODEX_HOME/config.toml (or ~/.codex/config.toml)
• vscode: .vscode/mcp.json (workspace)
• claude: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or ~/.config/Claude/claude_desktop_config.json (Linux)
• cursor: ~/.cursor/mcp.json
• antigravity: import/use .mcp-config/antigravity.mcp.json from the client MCP settings UI

CLI Commands

ace mcp                                 # start MCP server on stdio
ace serve                               # alias for mcp
ace tui [options]                       # launch interactive terminal dashboard
ace init [options]                      # bootstrap ACE files into current workspace
ace turnkey [options]                   # same as init (turnkey alias)
ace doctor [options]                    # local LLM + MCP readiness checks
ace mcp-config [--client <name>|--all]  # print one/all MCP client snippets
ace paths                               # show resolved package/workspace paths

Interactive TUI

Launch a full-screen terminal dashboard with provider-aware model chat, agent tabs, telemetry, and task tracking:

ace tui
ace tui --model llama3.1:8b --ollama-url http://127.0.0.1:11434

The TUI starts regardless of whether Ollama is running. Use /ollama inside the TUI to check status, or /pull <model> to download Ollama models. The TUI also refreshes the Ollama catalog in the background so /model completion can surface local models even when another provider is selected.

For non-ollama providers, configure an OpenAI-compatible endpoint before chatting:

• OPENAI_API_KEY (required) and optional OPENAI_BASE_URL
• or provider-specific vars ${PROVIDER}_API_KEY and ${PROVIDER}_BASE_URL (example: CODEX_API_KEY, CODEX_BASE_URL)

VS Code Copilot model hints such as copilot/gpt-5-mini are discovery-only in the standalone terminal TUI. They reflect models visible in VS Code chat, but the TUI cannot send directly through the VS Code chatbox from a terminal process without an extension-side bridge.

Key commands inside TUI:

| Command | Description | |---------|-------------| | /provider [name] | Show or switch active provider | | /providers | List discovered providers | | /models | List available models for active provider | | /model <name> | Switch active model (Tab searches discovered models, including Ollama) | | /pull <name> | Download an Ollama model | | /ollama | Check Ollama connection status and hints | | /agent <role> | Start a subagent in a new tab | | /agents | List all agent roles and status | | /status | Show orchestrator status | | /chat | Open new chat tab | | /logs | Open logs tab | | /help | List all commands | | /quit | Exit TUI |

Keyboard shortcuts: Alt+1-9 switch tabs, Tab/Shift+Tab cycle tabs, Ctrl+N new chat, Ctrl+R refresh, Ctrl+D quit.

Options for init / turnkey:

--project <name>                # Project name for global-state/MASTER_PLAN.md
--force                         # Overwrite scaffolded files
--no-mcp-config                 # Skip .vscode/mcp.json
--no-client-config-bundle       # Skip .mcp-config client bundle
--llm <provider>                # ollama
--model <name>                  # local model name (default: llama3.1:8b)
--ollama-url <url>              # Ollama base URL (default: http://127.0.0.1:11434)

Options for doctor:

--llm <provider>                # ollama (or auto from .ace/llm-profile.json)
--model <name>                  # override model to check
--ollama-url <url>              # override Ollama URL to check

Initiate ACE Swarm

After bootstrap, start your MCP host and issue:

initiate ACE

Schema Validation (Runtime)

Schema validation is wired into MCP tool execution paths:

• create_handoff: validates handoff payload before write
• validate_handoff: supports schema_mode: auto|swarm|agent-state
• write_workspace_file: blocks invalid writes for:
  • agent-state/HANDOFF.json
  • agent-state/HANDOFF_HISTORY/*.json
  • agent-state/STATUS_EVENTS.ndjson
  • ARTIFACT_MANIFEST.json
  • SWARM_HANDOFF.*.json

Validation code is in src/schemas.ts.

Kanban Snapshot (Runtime)

ACE Swarm now maintains a lightweight Kanban board in workspace state:

• agent-state/kanban.json
• agent-state/kanban.html

You can regenerate manually with MCP tool generate_kanban_ui, and the server auto-refreshes Kanban after major artifact writes (update_todo, create_handoff, bootstrap_state, and write_workspace_file on ACE state/task/code paths).

Resources:

• ace://kanban (JSON)
• ace://kanban/html (HTML)

Scheduler Queue (Runtime)

ACE Swarm now supports a lease-owned dispatcher for handoff/job execution:

• agent-state/job-queue.json
• agent-state/job-locks.json
• agent-state/scheduler-lease.json

Dispatch model:

• Priority-aware (P0 > P1 > P2 > P3) with FIFO ordering inside each band.
• Immediate dispatch of runnable jobs; no interval gating.
• Collision-free resource locks held until explicit completion/failure.
• Lease heartbeat/recovery handles crash detection instead of slice overruns.

Handoff integration:

• create_handoff and ack_handoff automatically sync lifecycle updates into scheduler jobs.
• Existing open/accepted handoffs are backfilled into scheduler state on startup.

New Runtime State Stores

ACE Swarm now persists additional orchestration stores:

• agent-state/run-ledger.json (major updates + regressions)
• agent-state/todo-state.json (explicit TODO statuses, dependencies, transition gates)
• agent-state/index.json (workspace delta scan index)
• agent-state/handoff-registry.json (handoff lifecycle: open|accepted|blocked|completed)
• agent-state/job-queue.json (scheduler jobs with dependency/priority metadata)
• agent-state/job-locks.json (active resource lock table)
• agent-state/scheduler-lease.json (active scheduler owner/heartbeat)

New/extended tools:

• update_todo now supports either full board replacement (new_content) or gated node transitions (node_id, status)
• scan_workspace_delta writes indexed changed/unchanged/deleted diffs
• ack_handoff updates handoff lifecycle status
• get_run_ledger, get_todo_state, get_handoff_status expose persisted store state
• Scheduler: enqueue_job, list_jobs, ack_job, dispatch_jobs, dispatch_job_now, complete_job, get_lock_table, get_scheduler_lease

New resources:

• ace://run-ledger
• ace://index
• ace://handoffs/status
• ace://scheduler/queue
• ace://scheduler/locks
• ace://scheduler/lease
• ace://kernel/directive_kernel
• ace://kernel/agent_registry

New tool:

• get_kernel_artifact (directive_kernel | agent_registry)

ACE Assets Included

Agents (17)

• Swarm (4): Orchestrator, VOS, UI, Coders
• Composable (13): agent-astgrep, agent-skeptic, agent-ops, agent-research, agent-spec, agent-builder, agent-qa, agent-docs, agent-memory, agent-security, agent-observability, agent-eval, agent-release

Skills

• Existing: ace-orchestrator, codemunch, codesnipe
• New: state-auditor, schema-forge, handoff-lint, memory-curator, risk-quant, eval-harness, incident-commander, release-sentry

Tasks and Handoff Artifacts

• todo.md, lessons.md, role_tasks.md, cli_work_split.md
• SWARM_HANDOFF.template.json and examples

Development

cd ace-mcp-server
npm install
npm run build
npm run start

Documentation References

• OpenAI Codex MCP config: platform.openai.com/docs/codex/mcp
• VS Code MCP: code.visualstudio.com/docs/copilot/chat/mcp-servers
• Cursor MCP: docs.cursor.com/context/model-context-protocol
• Claude Desktop MCP quickstart: modelcontextprotocol.io/quickstart/user
• Antigravity MCP server setup: docs.antigravity.dev/how-to/configuring-an-mcp-server