AiDD MCP Server

An MCP server that provides a comprehensive set of tools for AI-driven development workflows. Features include file system operations, code analysis using tree-sitter for multiple programming languages, Git operations, code execution, and system information retrieval. Designed to enhance AI's capability to assist in software development tasks.

Installation

Installing via Smithery

To install AiDD for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install mcp-server-aidd --client claude

Manual Installation

# Using mcp-get
npx @michaellatman/mcp-get@latest install mcp-server-aidd

# Using pip
pip install mcp-server-aidd

# Using uv
uvx mcp-server-aidd

Claude Desktop Setup

Add to your claude_desktop_config.json:

{
    "mcpServers": {
        "aidd-ai-software-development-utilities": {
            "command": "uvx",
            "args": ["mcp-server-aidd"]
        }
    }
}

SkyDeck AI Helper App

If you're using SkyDeck AI Helper app, you can search for "AiDD" and install the mcp-server-aidd.

Key Features

• File system operations (read, write, edit, move, delete)
• Directory management and traversal
• Multi-language code analysis using tree-sitter
• Multi-language code execution with safety measures
• Git operations (status, diff, commit, branch management)
• Security controls with configurable workspace boundaries
• Screenshot and screen context tools
• Image handling tools

Available Tools

Basic File Operations

| Tool | Parameters | Returns | | ------------------- | ----------------------------------- | --------------------------------------------- | | read_file | path: string | File content | | read_multiple_files | paths: string[] | Multiple file contents with headers | | write_file | path: string, content: string | Success confirmation | | move_file | source: string, destination: string | Success confirmation | | delete_file | path: string | Success confirmation | | get_file_info | path: string | File metadata (size, timestamps, permissions) |

Common usage:

# Read file
aidd-cli --tool read_file --args '{"path": "src/main.py"}'

# Write file
aidd-cli --tool write_file --args '{"path": "output.txt", "content": "Hello World"}'

# Get file info
aidd-cli --tool get_file_info --args '{"path": "src/main.py"}'

Complex File Operations

edit_file

Pattern-based file editing with preview support:

{
    "path": "src/main.py",
    "edits": [
        {
            "oldText": "def old_function():",
            "newText": "def new_function():"
        }
    ],
    "dryRun": false,
    "options": {
        "preserveIndentation": true,
        "normalizeWhitespace": true,
        "partialMatch": true
    }
}

Returns: Diff of changes or preview in dry run mode.

Directory Operations

| Tool | Parameters | Returns | | ------------------------ | -------------------------------------------------------- | ------------------------------ | | get_allowed_directory | none | Current allowed directory path | | update_allowed_directory | directory: string (absolute path) | Success confirmation | | list_directory | path: string | Directory contents list | | create_directory | path: string | Success confirmation | | search_files | pattern: string, path?: string, include_hidden?: boolean | Matching files list |

directory_tree

Generates complete directory structure:

{
    "path": "src",
    "include_hidden": false
}

Returns: JSON tree structure of directory contents.

Common usage:

# List directory
aidd-cli --tool list_directory --args '{"path": "."}'

# Search for Python files
aidd-cli --tool search_files --args '{"pattern": ".py", "path": "src"}'

Git Operations

| Tool | Parameters | Returns | | ------------ | -------------------------------------- | -------------------------------- | | git_init | path: string, initial_branch?: string | Repository initialization status | | git_status | repo_path: string | Working directory status | | git_add | repo_path: string, files: string[] | Staging confirmation | | git_reset | repo_path: string | Unstaging confirmation | | git_checkout | repo_path: string, branch_name: string | Branch switch confirmation |

Complex Git Operations

git_commit

{
    "repo_path": ".",
    "message": "feat: add new feature"
}

Returns: Commit hash and confirmation.

git_diff

{
    "repo_path": ".",
    "target": "main"
}

Returns: Detailed diff output.

git_log

{
    "repo_path": ".",
    "max_count": 10
}

Returns: Array of commit entries with hash, author, date, and message.

Common usage:

# Check status
aidd-cli --tool git_status --args '{"repo_path": "."}'

# Create and switch to new branch
aidd-cli --tool git_create_branch --args '{"repo_path": ".", "branch_name": "feature/new-branch"}'

Code Analysis

tree_sitter_map

Analyzes source code structure:

{
    "path": "src"
}

Returns:

• Classes and their methods
• Functions and parameters
• Module structure
• Code organization statistics
• Inheritance relationships

Supported Languages:

• Python (.py)
• JavaScript (.js, .jsx, .mjs, .cjs)
• TypeScript (.ts, .tsx)
• Java (.java)
• C++ (.cpp, .hpp, .cc)
• Ruby (.rb, .rake)
• Go (.go)
• Rust (.rs)
• PHP (.php)
• C# (.cs)
• Kotlin (.kt, .kts)

System Information

| Tool | Parameters | Returns | | --------------- | ---------- | ---------------------------- | | get_system_info | none | Comprehensive system details |

Returns:

{
  "working_directory": "/path/to/project",
  "system": {
    "os", "os_version", "architecture", "python_version"
  },
  "wifi_network": "MyWiFi",
  "cpu": {
    "physical_cores", "logical_cores", "total_cpu_usage"
  },
  "memory": { "total", "available", "used_percentage" },
  "disk": { "total", "free", "used_percentage" },
  "mac_details": {  // Only present on macOS
    "model": "Mac mini",
    "chip": "Apple M2",
    "serial_number": "XXX"
  }
}

Provides essential system information in a clean, readable format.

# Get system information
aidd-cli --tool get_system_info

Screen Context and Image Tools

get_active_apps

Returns a list of currently active applications on the user's system.

{
    "with_details": true
}

Parameters: | Parameter | Type | Required | Description | |-----------|---------|----------|---------------------------------------| | with_details | boolean | No | Whether to include additional details about each application (default: false) |

Returns:

{
    "success": true,
    "platform": "macos",
    "app_count": 12,
    "apps": [
        {
            "name": "Firefox",
            "has_windows": true,
            "window_count": 3,
            "visible_windows": [
                { "name": "GitHub - Mozilla Firefox", "width": 1200, "height": 800 }
            ]
        },
        {
            "name": "VSCode",
            "has_windows": true
        }
    ]
}

This tool provides valuable context about applications currently running on the user's system, which can help with providing more relevant assistance.

get_available_windows

Returns detailed information about all available windows currently displayed on the user's screen.

{}

Returns:

{
    "success": true,
    "platform": "macos",
    "count": 8,
    "windows": [
        {
            "id": 42,
            "title": "Document.txt - Notepad",
            "app": "Notepad",
            "visible": true
        },
        {
            "title": "Terminal",
            "app": "Terminal",
            "visible": true,
            "active": true
        }
    ]
}

This tool helps understand what's visible on the user's screen and can be used for context-aware assistance.

capture_screenshot

Captures a screenshot of the user's screen or a specific window.

{
    "output_path": "screenshots/capture.png",
    "capture_mode": {
        "type": "named_window",
        "window_name": "Visual Studio Code"
    }
}

Parameters: | Parameter | Type | Required | Description | |-----------|---------|----------|---------------------------------------| | output_path | string | No | Path where the screenshot should be saved (default: generated path) | | capture_mode | object | No | Specifies what to capture | | capture_mode.type | string | No | Type of screenshot: 'full', 'active_window', or 'named_window' (default: 'full') | | capture_mode.window_name | string | No | Name of window to capture (required when type is 'named_window') |

Returns:

{
    "success": true,
    "path": "/path/to/screenshots/capture.png"
}

This tool captures screenshots for visualization, debugging, or context-aware assistance.

read_image_file

Reads an image file from the file system and returns its contents as a base64-encoded string.

{
    "path": "images/logo.png"
}

Parameters: | Parameter | Type | Required | Description | |-----------|---------|----------|---------------------------------------| | path | string | Yes | Path to the image file to read | | max_size | integer | No | Maximum file size in bytes (default: 100MB) |

Returns: Base64-encoded image data that can be displayed or processed.

This tool supports common image formats like PNG, JPEG, GIF, and WebP, and automatically resizes images for optimal viewing.

Code Execution

execute_code

Executes code in various programming languages with safety measures and restrictions.

{
    "language": "python",
    "code": "print('Hello, World!')",
    "timeout": 5
}

Supported Languages:

• Python (python3)
• JavaScript (Node.js)
• Ruby
• PHP
• Go
• Rust

Parameters: | Parameter | Type | Required | Description | |-----------|---------|----------|---------------------------------------| | language | string | Yes | Programming language to use | | code | string | Yes | Code to execute | | timeout | integer | No | Maximum execution time (default: 5s) |

Example Usage:

# Python example
aidd-cli --tool execute_code --args '{
    "language": "python",
    "code": "print(sum(range(10)))"
}'

# JavaScript example
aidd-cli --tool execute_code --args '{
    "language": "javascript",
    "code": "console.log(Array.from({length: 5}, (_, i) => i*2))"
}'

# Ruby example
aidd-cli --tool execute_code --args '{
    "language": "ruby",
    "code": "puts (1..5).reduce(:+)"
}'

# Go example
aidd-cli --tool execute_code --args '{
    "language": "go",
    "code": "fmt.Println(\"Hello, Go!\")"
}'

Requirements:

• Respective language runtimes must be installed
• Commands must be available in system PATH
• Proper permissions for temporary file creation

⚠️ Security Warning: This tool executes arbitrary code on your system. Always:

1. Review code thoroughly before execution
2. Understand the code's purpose and expected outcome
3. Never execute untrusted code
4. Be aware of potential system impacts
5. Monitor execution output

execute_shell_script

Executes shell scripts (bash/sh) with safety measures and restrictions.

{
    "script": "echo \"Current directory:\" && pwd",
    "timeout": 300
}

Parameters: | Parameter | Type | Required | Description | |-----------|---------|----------|---------------------------------------| | script | string | Yes | Shell script to execute | | timeout | integer | No | Maximum execution time (default: 300s, max: 600s) |

Example Usage:

# List directory contents with details
aidd-cli --tool execute_shell_script --args '{
    "script": "ls -la"
}'

# Find all Python files recursively
aidd-cli --tool execute_shell_script --args '{
    "script": "find . -name \"*.py\" -type f"
}'

# Complex script with multiple commands
aidd-cli --tool execute_shell_script --args '{
    "script": "echo \"System Info:\" && uname -a && echo \"
Disk Usage:\" && df -h"
}'

Features:

• Uses /bin/sh for maximum compatibility across systems
• Executes within the allowed directory
• Separate stdout and stderr output
• Proper error handling and timeout controls

⚠️ Security Warning: This tool executes arbitrary shell commands on your system. Always:

1. Review the script thoroughly before execution
2. Understand the script's purpose and expected outcome
3. Never execute untrusted scripts
4. Be aware of potential system impacts
5. Monitor execution output

Configuration

Configuration file: ~/.aidd/config.json

{
    "allowed_directory": "/path/to/workspace"
}

CLI Usage

Basic command structure:

aidd-cli --tool <tool_name> --args '<json_arguments>'

# List available tools
aidd-cli --list-tools

# Enable debug output
aidd-cli --debug --tool <tool_name> --args '<json_arguments>'

Debugging

Use MCP Inspector for debugging:

npx @modelcontextprotocol/inspector run

Security

• Operations restricted to configured allowed directory
• Path traversal prevention
• File permission preservation
• Safe operation handling

Upcoming Features

• GitHub tools:
  • PR Description Generator
  • Code Review
  • Actions Manager
• Pivotal Tracker tools:
  • Story Generator
  • Story Manager

Development Status

Currently in active development. Features and API may change.

License

Apache License 2.0 - see LICENSE