commands

This MCP server runs a command-template based workflow for managing and executing user-defined commands described in a commands.yaml file. The server is configured under mcpServers with a single entry named commands, which points to the built MCP executable and the root path of the project to operate on. The commands.yaml file in your project defines individual tools (for example, zephyr_build or other custom tools) along with their arguments, descriptions, and templated command strings that can be executed by the MCP server. Built-in tooling support is available, including flash tools for firmware flashing, serial tools for log capture, and schematic tools to help the AI understand hardware layouts and board definitions, all configurable via the same commands.yaml configuration file. To use it, place a commands.yaml file in your project root and configure claude_desktop_config.json to reference the commands MCP server as shown in the usage snippet.

Prerequisites:

• A Rust toolchain installed (cargo and rustc).
• Git installed to clone or fetch sources if needed.
• Your project directory that will be used by the MCP server.

Installation steps:

1. Clone or download the commands-mcp repository and navigate to the project directory.
2. Build the MCP server binary (example using cargo):

git clone https://github.com/LISTENAI/commands-mcp.git
cd commands-mcp
cargo build --release

3. Ensure the built binary path is accessible and note the path to the executable (e.g., target/release/commands-mcp).
4. Update your claude_desktop_config.json to point to the built binary and the root of your project, as shown in the README usage example:

{
  "mcpServers": {
    "commands": {
      "command": "/path/to/commands-mcp",
      "args": [
        "/path/to/your/project"
      ]
    }
  }
}

5. Run the MCP server and verify that it can load and parse commands.yaml from your project root. If needed, adjust file permissions and ensure the environment has access to any required tools referenced by your commands.yaml templates.

Tips and reminders:

• The commands.yaml file defines tools with a description, a list of arguments, and a command template. Learn the templating syntax (Handlebars) used for injecting argument values.
• Built-in tools (flash, serial, schematic) can be enabled in commands.yaml by setting enabled: true under the respective sections.
• If you use Python-related commands, you can set shell: python and optionally specify a venv path to activate before executing the command.
• Ensure your project root contains the commands.yaml file and that paths referenced in the templates are valid within the runtime environment.
• When troubleshooting, check the MCP server logs for YAML parsing errors and template evaluation errors, and verify that the CLI arguments provided in claude_desktop_config.json align with the required inputs in commands.yaml.
• The MCP server supports templating with Handlebars, so structure your command strings to safely access provided arguments (e.g., {{board}} or {{source_dir}}) and conditionals (e.g., {{#if pristine}}--pristine{{/if}}).