Ahma

Provides an AI-driven, sandboxed MCP server to wrap CLI tools and orchestrate asynchronous workflows.

rust

1

GitHub Stars

rust

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "paulirotta-ahma_mcp": {
      "command": "~/github/ahma_mcp/target/release/ahma_mcp",
      "args": [
        "--tools-dir",
        "~/github/ahma_mcp/.ahma/tools"
      ],
      "env": {
        "AHMA_SANDBOX_SCOPE": "YOUR_PROJECT_PATH"
      }
    }
  }
}

Ahma MCP is a safe, multi-threaded command-line tool wrapper that lets you run any CLI tool as an AI-enabled agent. It provides sandboxed execution, asynchronous task orchestration, and easy tool definitions, so you can automate complex workflows with confidence and speed.

How to use

You interact with Ahma MCP through a client interface that asks tools to perform work on your behalf. Tools are defined as JSON configurations and can be chained to form powerful sequences, such as running a quality check pipeline that formats, lints, tests, and builds in one go. The system executes tools inside a kernel-level sandbox, ensuring your workspace remains protected. You can run operations asynchronously to let the AI continue progress while results are still being produced. Use synchronous mode when you need certain steps to finish before moving on.

Key usage patterns include:

Start a local MCP server in STDIO mode for direct integration with other tools.
Use the HTTP bridge mode for remote clients to talk through a proxy server.
List available tools to explore capabilities and test configurations.
Define your own tools by adding a single JSON file describing the tool invocation and sandboxed execution details.

Security is enforced at the kernel level, with a sandbox scope fixed at startup. In STDIO mode, the server runs locally and the AI can access resources only within the configured working directory. In HTTP mode, all clients share the same sandbox scope and you may run separate server instances for isolation across projects.

How to install

Prerequisites: a Rust toolchain with Cargo installed.

Clone the project, build, and run the server:

git clone https://github.com/paulirotta/ahma_mcp.git
cd ahma_mcp
cargo build --release
cargo run --release -- --help

Add the MCP definition and run tests

Define the MCP server configuration in your global mcp.json to reference the local binary and tool directory, enabling the STDIO mode for direct tool execution.

{
  "servers": {
    "Ahma": {
      "type": "stdio",
      "cwd": "~/github/ahma_mcp/",
      "command": "~/github/ahma_mcp/target/release/ahma_mcp",
      "args": ["--tools-dir", "~/github/ahma_mcp/.ahma/tools"]
    }
  }
}

Run tests to verify installation

Execute the test suite to ensure the build and tool integration work as expected.

cargo test