AFC Commander (Free Edition)

# 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

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.

afc profile create myproject "My project"
afc profile switch myproject

Add a command with a readable alias:

afc add hello "echo hello" -d "Say hello"

Run it:

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:

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:

node setup.cjs --mcp-only

Uninstall the package and MCP registration:

node uninstall.cjs

Remove the user data directory as well:

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.