AFC-Commander-CLI-Registry-With-MCP

````markdown # AFC Commander Free Edition AFC Commander Free Edition is a JSON-backed command registry and pipeline runner with a Model Context Protocol (MCP) server for Cursor. It is built for teams that want a persistent alias layer for shell commands, profile-based separation between workspaces or projects, and repeatable command execution without hand-maintaining long terminal commands. ## What this project is for AFC Commander solves a simple operational problem: teams accumulate important shell commands, but those commands are easy to lose, hard to standardize, and tedious to retype. This tool keeps those commands in a durable registry, lets you organize them by profile, and gives you a single command-line interface (CLI) for adding, listing, searching, and executing them. The repository also includes a local MCP server named `afc-commander-core`, which exposes the same registry and execution capabilities to Cursor through standard input and standard output (stdio). That means agents can work with the command registry without needing direct shell access to your environment. ## Core capabilities AFC Commander includes: - Persistent command aliases stored in JSON. - Profile isolation so different projects or environments can keep separate command sets. - Command lookup, listing, editing, export, history, and statistics. - Pipeline support for chaining multiple commands into a repeatable flow. - Job tracking for longer-running or resumable executions. - A local MCP server for agent access from Cursor. ## What it does not try to be This is not a general-purpose task runner, and it is not a replacement for a full CI (continuous integration) system. It is a structured command registry and execution layer for shell workflows you want to keep organized, reusable, and accessible from both the terminal and MCP-aware tooling. ## Requirements - Node.js 20.12 or newer. Node.js is the JavaScript runtime that executes the CLI and server code. - npm, the Node.js package manager, for installation. - Cursor, if you want to register and use the MCP server from the editor. ## Installation From the repository root: ```bash node setup.cjs ```` That setup script: 1. Installs the package dependencies. 2. Installs `afc-commander-free` globally so the `afc` command is available in your terminal. 3. Creates a user data directory at `~/.afc-commander` unless you override it with `AFC_HOME`. 4. Registers the `afc-commander-core` MCP server in `~/.cursor/mcp.json`. After setup, reload MCP in Cursor so the server is detected. ## Verify the install ```bash afc version afc help afc profile list ``` ## Typical workflow Start by creating or switching to a profile. A profile is an isolated command namespace for a specific project, environment, or workflow. ```bash afc profile create myproject "My project" afc profile switch myproject ``` Add a command with a readable alias: ```bash afc add hello "echo hello" -d "Say hello" ``` Run it: ```bash afc -y hello ``` The `-y` flag confirms execution when the command would otherwise prompt. ## Working with profiles Profiles let you reuse the same alias in different contexts without collisions. For example, `deploy` can mean staging in one profile and production in another. That is useful when you want local command behavior to match the project you are currently working on. ## Working with pipelines Pipelines chain existing commands into an ordered execution flow. That is useful for repeatable routines such as build, test, deploy, cleanup, or environment preparation. Common pipeline commands include: ```bash afc pipeline create afc pipeline list afc pipeline show my-deploy afc pipeline execute my-deploy ``` ## MCP tools The local `afc-commander-core` server exposes these tools to MCP clients such as Cursor: * `afc-list-commands` * `afc-search-commands` * `afc-execute-command` * `afc-add-command` * `afc-remove-command` * `afc-list-profiles` * `afc-create-profile` * `afc-switch-profile` * `afc-list-pipelines` * `afc-create-pipeline` * `afc-execute-pipeline` ## Data locations By default, AFC Commander stores user data in: * `~/.afc-commander` Other important locations: * `~/.cursor/mcp.json` for MCP registration * `~/.afc-commander/install.json` for install metadata You can move the user data directory by setting `AFC_HOME` before running setup. ## Useful commands Refresh MCP paths after moving the package or reinstalling: ```bash node setup.cjs --mcp-only ``` Uninstall the package and MCP registration: ```bash node uninstall.cjs ``` Remove the user data directory as well: ```bash node uninstall.cjs --purge-data ``` ## Project layout * `afc-commander/` — CLI package and command implementation * `server.js` — MCP stdio entrypoint * `setup.cjs` — installation script * `uninstall.cjs` — uninstall script * `docs/` — usage, architecture, and help content ## Development notes The repository includes docs for the command parser, registry structure, help topics, and usage patterns. Those docs are useful if you want to understand how aliases are parsed, how profiles isolate commands, and how pipelines are stored. ## License See `license.md` for the project license. ```