This directory contains tool configuration files for the Ahma server (ahma). These configurations define how AI agents can interact with various command-line tools in a safe and structured way.

AHMA has a three-tier tool model:

• run_terminal_command — Execute shell commands in the security sandbox
• await — Wait for async operations to complete
• status — Query operation status without blocking
• cancel — Cancel running operations

These are implemented directly in Rust and cannot be overridden by JSON configurations. Their names are reserved.

Standard tool configurations are compiled into the ahma binary. They are only offered to MCP clients when explicitly enabled via a CLI flag:

Example: ahma --mode stdio --rust --git --fileutils

If a .ahma/ directory exists in the current working directory, all *.json files in it are loaded automatically at startup — no CLI flag needed.

Override rule: If a local .ahma/*.json file defines a tool with the same name as a bundled tool, the local version replaces the bundled one entirely. This lets you customize tool descriptions, options, and subcommands for your project.

Example: placing a .ahma/rust.json with "name": "cargo" will override the bundled cargo tool definition when --rust is also passed.

Run the validation tool to ensure your configuration is correct:

# Validate a specific configuration using the example runners
cargo run --example cargo_tool
cargo run --example file-tools
cargo run --example gh_tool
cargo run --example git_tool
cargo run --example python_tool

# Or run schema validation tests
cargo test --test tool_config_schema_validation_test

# Or run all tests including execution tests
cargo nextest run --package ahma --test tool_config_schema_validation_test
cargo nextest run --package ahma --test tool_examples_execution_test

After copying and enabling a configuration in .ahma/, restart the ahma server to load the new tool. If you are actively iterating on tool definitions, you can instead opt into runtime watching with --hot-reload-tools:

# Safe default: load .ahma configs once at startup
ahma --tools-dir .ahma

# Tool development only: watch for runtime changes
ahma --tools-dir .ahma --hot-reload-tools

All tool configurations follow the MCP Tool Definition Format (MTDF) schema. Here's a minimal example:

{
    "name": "mytool",
    "description": "Description of what the tool does",
    "command": "command-to-execute",
    "enabled": true,
    "timeout_seconds": 300,
    "subcommand": [
        {
            "name": "subcommand_name",
            "description": "What this subcommand does",
            "options": [
                {
                    "name": "option-name",
                    "type": "string",
                    "description": "What this option does",
                    "required": false
                }
            ],
            "synchronous": true
        }
    ]
}

# Validate all example configs
cargo nextest run -p ahma_mcp tool_config_schema_validation

# Run a specific example to see detailed output
cargo run --example cargo_tool

# Check if configuration is parseable
jq . .ahma/cargo.json

Use the MtdfValidator from ahma:

use ahma::schema_validation::MtdfValidator;
use std::path::Path;

let validator = MtdfValidator::new();
let config_path = Path::new(".ahma/mytool.json");
let content = std::fs::read_to_string(config_path)?;

match validator.validate_tool_config(config_path, &content) {
    Ok(config) => println!("OK Valid configuration"),
    Err(errors) => {
        eprintln!("FAIL Validation errors:");
        for error in errors {
            eprintln!("  - {}: {}", error.field_path, error.message);
        }
    }
}

• Path Security: All file paths are automatically validated and scoped to the current working directory
• Sandbox Mode: Commands run in isolated environments with restricted permissions
• Timeout Protection: All operations have configurable timeouts to prevent hanging
• Command Whitelisting: Only explicitly configured commands and subcommands are available

1. Ensure the JSON file is valid: jq . .ahma/mytool.json
2. Check that "enabled": true is set
3. Verify file permissions: ls -la .ahma/
4. Check server logs for parsing errors

1. Run the corresponding example: cargo run --example mytool
2. Check for schema violations in the error output
3. Compare with working examples in ahma/examples/configs/
4. Verify all required fields are present: name, description, command, enabled

1. Restart the ahma server
2. Verify tool is enabled: grep enabled .ahma/mytool.json
3. Check server initialization logs
4. Ensure the underlying command is installed: which command-name

Full MTDF schema documentation is available at:

• docs/mtdf-schema.json - JSON Schema definition
• ahma/docs/mtdf-schema.json - Core library schema

To add a new tool configuration:

1. Create the JSON file in ahma/examples/configs/
2. Add a corresponding example in ahma/examples/toolname.rs
3. Add tests in ahma/tests/tool_config_schema_validation_test.rs
4. Add execution tests in ahma/tests/tool_examples_execution_test.rs
5. Update ahma/Cargo.toml with example declaration
6. Run all tests: cargo nextest run --workspace

Tool configurations in this directory follow the project's dual MIT/Apache-2.0 license.