Create agents from your command line tools with one JSON file, then watch them complete your work faster with true multi-threaded tool-use agentic AI workflows.

ahma_mcp is a toolbox for safely wrapping command line tools for AI use. This is done by creating (use AI) a ´.ahma/tools/somenewtool.json´.

"Ahma" is Finnish for wolverine. An ahama is fast and fearless, able to eat just about anything. Use the existing tools or add a PR for new ones you crate.

This project is actively used and still undergoing rapid evolution. http MCP is still a work in progress, setup isn't as smooth as we like yet and expect breaking changes including CLI parameters.

Ahma MCP follows a code-first documentation approach. Architectural details and technical guides are embedded directly in the source code using Rust doc comments (//!). This ensures documentation stays in sync with implementation.

• Ahma Core API & Architecture: Main engine, sandboxing, and SDD philosophy.
• Ahma HTTP Bridge: Session isolation and HTTP protocol bridge details.
• USAGE_GUIDE.md: Productive workflows and CLI flag inheritance.

If you are an AI agent interacting with this repository:

• Sandbox Boundary: You have full access within ${workspaceFolder} but zero access outside it. Use sandboxed_shell for multi-step tasks.
• Async Concurrency: Most tools are async by default. Use status to monitor progress and continue with other tasks.
• MTDF Schema: Reference docs/mtdf-schema.json when creating or modifying tool configurations (.ahma/tools/*.json).

• Sandboxed Execution: Strict path validation prevents accessing files outside the workspace.
• Asynchronous By Default with Sync Override: Operations run asynchronously by default, allowing the LLM to continue work while awaiting results. Use --sync flag or set "synchronous": true in tool config for operations that must complete before proceeding. Supports multiple concurrent long-running operations (builds, tests).
• Easy Tool Definition: Add any command-line tool to your AI's arsenal by creating a single JSON file. No recompilation needed.
• Multi-Step Workflows (Preferred): Run multi-command pipelines via sandboxed_shell (e.g., cargo fmt --all && cargo clippy --all-targets && cargo test).

Ahma MCP implements kernel-level sandboxing to protect your system. The sandbox scope is set once at server startup and cannot be changed during the session—the AI has full access within the sandbox but zero access outside it.

The sandbox scope defines the root directory boundary for all file system operations:

• STDIO mode: Defaults to the current working directory when the server starts. The IDE sets cwd in mcp.json to ${workspaceFolder}, so this "just works".
• HTTP mode: Set once when the HTTP server starts (cannot be changed during session). Configure via:
  1. --sandbox-scope <path> command-line parameter (highest priority)
  2. AHMA_SANDBOX_SCOPE environment variable
  3. Current working directory when server starts (default)
• Single sandbox per server: In HTTP mode, all clients share the same sandbox. For multiple projects, run separate server instances.

On Linux, Ahma uses Landlock for kernel-level file system sandboxing. No additional installation is required—Landlock is built into Linux kernels 5.13 and newer.

Requirements:

• Linux kernel 5.13 or newer (released June 2021)
• The server will refuse to start on older kernels and display upgrade instructions
• Check your kernel version with: uname -r

On macOS, Ahma uses Apple's built-in sandbox-exec with Seatbelt profiles for kernel-level file system sandboxing. No additional installation is required—sandbox-exec is built into macOS.

Requirements: Any modern version of macOS. The server generates a Seatbelt profile (SBPL) that restricts write access to only the sandbox scope.

Previous approaches that parsed command-line strings for dangerous patterns are fundamentally insufficient for security. AI models can easily construct commands that bypass string-based checks. Kernel-level enforcement provides a hard security boundary that cannot be circumvented by clever command construction.

Security Model: "AI can do whatever it likes inside the sandbox—it has no access outside the sandbox."

When running inside another sandboxed environment (like Cursor IDE, VS Code, or Docker), Ahma automatically detects that it cannot apply its own sandbox and gracefully degrades. This is because:

• Cursor/VS Code: These IDEs sandbox MCP servers, preventing nested sandbox-exec calls on macOS
• Docker: Containers may restrict the system calls needed for sandboxing

Auto-detection: Ahma tests if sandbox-exec can be applied at startup. If it detects a nested sandbox, it logs a warning and continues without Ahma's sandbox—the outer sandbox still provides security.

Manual override: You can also explicitly disable Ahma's sandbox:

# Via command-line flag
ahma_mcp --no-sandbox

# Via environment variable (useful for mcp.json configuration)
export AHMA_NO_SANDBOX=1
ahma_mcp

In mcp.json for Cursor/VS Code:

{
  "servers": {
    "Ahma": {
      "type": "stdio",
      "cwd": "${workspaceFolder}",
      "command": "/path/to/ahma_mcp",
      "args": ["--tools-dir", ".ahma/tools"]
    }
  }
}

Note: When --no-sandbox is used, Ahma relies on the outer sandbox for security. Only use this in environments that provide their own sandboxing.

Synchronous is simpler when the turns are fast. Async can be helpful for long-running tool calls.

Here's an example of Claude Sonnet 4.5's workflow. Notice both the tool and the AI are working at the same time:

Now let me run the tests again using the MCP server:

Ran cargo_test ahma_mcp (MCP Server)

While the tests run, let me continue with updating the requirements document:

Read SPEC.md

Let me add the JSON schema requirements to the product requirements:

SPEC.md+21-6

Now let me check on the test results:

Ran status ahma_mcp (MCP Server)

I can see the issue...

ahma_mcp is organized as a Cargo workspace with several crates:

• ahma_mcp: Library crate containing all core functionality (tool execution, configuration, async orchestration, MCP service)
• ahma_shell: Binary crate providing the CLI interface and server startup logic (includes --list-tools functionality)
• ahma_validate: Binary crate for validating tool configuration files against the MTDF schema
• ahma_simplify: Binary crate for code simplicity metrics aggregation using rust-code-analysis-cli

This modular architecture ensures clean separation of concerns and enables future extensions (e.g., web interface, authentication).

1. Clone and build the repository:

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

2. Add the MCP definition:

   In your global mcp.json file add the following (e.g., Mac: ~/Library/Application Support/Code/User/mcp.json or ~/Library/Application Support/Cursor/User/mcp.json, or Linux: ~/.config/Code/User/mcp.json or ~/.config/Cursor/User/mcp.json).

Update paths as needed. Use absolute paths (do not rely on ~ expansion). Use --sync if you want synchronous execution by default.

{
  "servers": {
    "Ahma": {
      "type": "stdio",
      "cwd": "/Users/yourname/workspace/project",
      "command": "/Users/yourname/github/ahma_mcp/target/release/ahma_mcp",
      "args": ["--tools-dir", "/Users/yourname/github/ahma_mcp/.ahma/tools"]
    },
    "chrome-devtools": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--no-performance-crux",
        "--no-usage-statistics"
      ]
    }
  }
}

Note: each server must be nested under its own key in servers. Also use the binary path directly for command (do not wrap it with bash unless you intentionally run a shell script).

3. Run tests to verify installation:

   cargo test

The compiled binary will be at target/release/ahma_mcp.

ahma_mcp supports three modes of operation:

Direct MCP server over stdio for integration with MCP clients:

ahma_mcp --mode stdio --tools-dir ./tools

HTTP server that proxies requests to the stdio MCP server:

# Start HTTP bridge on default port (3000)
# Clients that provide roots/list can lock sandbox from roots
ahma_mcp --mode http

# Explicit sandbox scope (required for clients that do not send roots/list)
ahma_mcp --mode http --sandbox-scope /path/to/your/project

# Or via environment variable
export AHMA_SANDBOX_SCOPE=/path/to/your/project
ahma_mcp --mode http

# Custom port
ahma_mcp --mode http --http-port 8080 --http-host 127.0.0.1

Important: In HTTP mode, sandbox scope is bound per client session via the MCP roots/list protocol. If a client does not provide roots/list, you must configure an explicit scope via --sandbox-scope or AHMA_SANDBOX_SCOPE.

Security Note: HTTP mode is for local development only. Do not expose to untrusted networks.

Then send JSON-RPC requests to http://localhost:3000/mcp:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Execute a single tool command:

ahma_mcp cargo_build --working-directory . -- --release

List all available tools from an MCP server for testing and development:

# List tools from a stdio MCP server (command after --)
ahma_mcp --list-tools -- /path/to/ahma_mcp --tools-dir ./tools

# List tools from an HTTP MCP server
ahma_mcp --list-tools --http http://localhost:3000

# List tools from mcp.json configuration
ahma_mcp --list-tools --mcp-config /path/to/mcp.json --server Ahma

# Output as JSON instead of text
ahma_mcp --list-tools --format json -- /path/to/ahma_mcp --tools-dir ./tools

To use ahma_mcp with GitHub Copilot in VS Code:

1. Enable MCP in VS Code Settings:

   "chat.mcp.enabled": true

2. Configure the MCP Server in your global mcp.json file (e.g., ~/Library/Application Support/Code/User/mcp.json on macOS).

   {
     "servers": {
       "ahma_mcp": {
         "type": "stdio",
         "cwd": "${workspaceFolder}",
         "command": "/path/to/your/ahma_mcp/target/release/ahma_mcp", // Use absolute path
         "args": ["--mode", "stdio", "--tools-dir", "tools"]
       }
     }
   }

   Important: Replace /path/to/your/ahma_mcp with the absolute path to the cloned repository.

3. Restart VS Code and start a chat with GitHub Copilot. You can now ask it to use ahma_mcp tools (e.g., "Use ahma_mcp to show the git status").

This project is guided by a clear set of principles and requirements.

• SPEC.md: This is the single source of truth for the project. It details the core mission, architecture, and the workflow an AI maintainer must follow. All new tasks and changes are driven by this document.
• docs/CONSTITUTION.md: This document outlines the core development principles for human contributors, ensuring consistency and quality.

For a list of available tools and instructions on how to add your own, please refer to the SPEC.md file and the examples in the tools/ directory.

• scripts/ahma-inspector.sh: Builds ahma_mcp and launches the MCP Inspector web interface (npx @modelcontextprotocol/inspector) for interactive debugging and testing of your tool definitions.

• MCP tools not working? Ensure the command path in mcp.json is an absolute path to the compiled ahma_mcp binary.
• "execution_failed" errors? Verify file permissions (chmod +x /path/to/binary) and ensure you have run cargo build --release.
• Operations timing out? The default timeout is 4 minutes. Use the status tool to check on long-running operations.

Licensed under either Apache License 2.0 or MIT License.