Agentic Control Framework

You run the Agentic Control Framework MCP server to expose its orchestration tools to MCP clients over stdio or HTTP/SSE. This server enables you to drive context engineering, task management, and browser/terminal automation from IDEs, CLIs, or remote clients using a consistent, JSON‑RPC based protocol.

How to use

Choose your preferred access method and connect with an MCP client. You can run the MCP server locally for IDE integrations or expose it remotely via a cloud proxy. Once connected, you can manage tasks, generate context artifacts, run tooling like searches or edits, and drive automated actions from your MCP client. The server supports both a local stdio connection and an HTTP/SSE remote endpoint, so you can integrate with editors, CLIs, or web clients.

How to install

Prerequisites include Node.js 18+ and, optionally, macOS if you plan to use AppleScript or Playwright browser tooling.

# Install dependencies for the project
npm ci

# Ensure executables are runnable (on Unix-like systems)
chmod +x bin/*

# Optional: install browser tooling if you plan to use browser automation
npx playwright install

MCP server configuration

You can run the MCP server locally in stdio mode or expose it via an HTTP endpoint for remote MCP clients. The local stdio command starts the MCP server, and the cloud setup shows how to run an HTTP/SSE proxy that fronts the MCP server.

{
  "mcpServers": [
    {
      "type": "http",
      "name": "acf_cloud_http",
      "url": "http://localhost:8080",
      "args": []
    },
    {
      "type": "stdio",
      "name": "acf_local_stdio",
      "command": "node",
      "args": ["./bin/agentic-control-framework-mcp", "--workspaceRoot", "$(pwd)"] ,
      "env": [
        {"name": "ACF_PATH", "value": "/FULL/PATH/TO/agentic-control-framework"},
        {"name": "WORKSPACE_ROOT", "value": "$(pwd)"},
        {"name": "ALLOWED_DIRS", "value": "/FULL/PATH/TO/YOUR/WORKSPACE:/tmp"},
        {"name": "READONLY_MODE", "value": "false"}
      ]
    }
  ]
}

Security and guardrails

Filesystem access is constrained by allowed directories and readonly mode. Read URL reads are explicit, and edits use surgical replacements to minimize unintended changes. Terminal execution supports timeouts and can be restricted or terminated as needed.

Usage notes and examples

The MCP server supports a cloud deployment pattern using an HTTP/SSE proxy. Start the MCP server locally, then forward it through a proxy to expose a remote endpoint for MCP clients. You can use the same tooling from editors like Claude Code, Claude Desktop, Cursor, or VS Code by configuring the MCP client to connect to the remote endpoint.

Troubleshooting

If you encounter issues, verify the following common points: the MCP server binary is executable, environment variables are set correctly (ACF_PATH, WORKSPACE_ROOT, ALLOWED_DIRS, READONLY_MODE), and the correct start command is used for the stdio configuration. When using the cloud route, ensure the proxy is running and reachable at the expected port.

Notes on cloud deployment

To provide remote access, you can run an mcp-proxy in front of the local MCP server. The proxy exposes endpoints that MCP clients can consume via HTTP/SSE, while the MCP server handles the actual tool invocation and state management.

Available tools

listTasks

List all tasks with IDs, titles, and statuses.

addTask

Create a new task with a title, description, priority, and optional dependencies.

updateStatus

Change the status of an existing task and optionally attach a log message.

getNextTask

Retrieve the next actionable task based on priorities and dependencies.

generateTaskFiles

Materialize per-task Markdown files and a project overview file.

recalculatePriorities

Recompute priorities considering dependencies and time decay.

read_file

Read contents of a file for context or editing.

write_file

Write or overwrite file contents as part of context edits.

search_code

Search codebase with advanced ripgrep powered queries.

edit_block

Apply surgical replacements to code blocks with precise edits.

execute_command

Run terminal commands within a controlled environment.

browser_navigate

Navigate to a URL in an automated browser session.

browser_take_screenshot

Capture a screenshot of the current browser page.

applescript_execute

Run macOS AppleScript for system automation.