Ada MCP Server

An MCP (Model Context Protocol) server that wraps the Ada Language Server (ALS) to provide semantic Ada language features to AI coding agents like GitHub Copilot.

Why Ada MCP Server?

AI agents working with Ada code face significant limitations without semantic understanding:

Without This Tool	With Ada MCP Server
Text-based grep searches miss context	Semantic navigation to exact definitions
Must build to detect type errors	Real-time diagnostics without compilation
Can't jump to definitions or usages	Full code navigation (definitions, references, implementations)
No awareness of Ada's strong types	Type information via hover and completions

Features

• 🧭 Semantic Navigation: Go to definition, find references, type definitions, implementations
• 🔍 Symbol Search: Document and workspace symbol search with filtering
• ⚠️ Diagnostics: Real-time compiler errors and warnings
• 📁 Project Intelligence: GPR project parsing, call hierarchy, dependency graphs
• ✨ Code Intelligence: Context-aware completions, signature help
• 🔧 Refactoring: Safe symbol renaming, code formatting
• 🏗️ Build Integration: GPRbuild integration, Alire support
• 💪 Reliability: Auto-restart on crashes with exponential backoff
• ⚡ Performance: TTL-based caching for faster responses

Prerequisites

1. Ada Language Server (ALS)

Install via one of these methods:

# Option 1: Alire (recommended)
alr get ada_language_server
cd ada_language_server*
alr build --release
# Binary will be at ./bin/ada_language_server

# Option 2: Pre-built from GitHub releases
# https://github.com/AdaCore/ada_language_server/releases

# Option 3: VS Code Ada extension (usually already installed)
# Found at: ~/.vscode/extensions/adacore.ada-*/x64/linux/ada_language_server

2. Python 3.11+

python --version  # Should be 3.11 or higher

Installation

# From PyPI
pip install ada-mcp-server

# From source
git clone https://github.com/ada-mcp/ada-mcp-server
cd ada-mcp-server
pip install -e .

# With uvx (isolated environment)
uvx ada-mcp-server

Quick Start

VS Code / Copilot Configuration

Add to your VS Code settings.json:

{
  "mcpServers": {
    "ada": {
      "command": "ada-mcp",
      "env": {
        "ALS_PATH": "/path/to/ada_language_server",
        "ADA_PROJECT_ROOT": "/path/to/your/ada/project"
      }
    }
  }
}

Using uvx (Recommended for Isolation)

{
  "mcpServers": {
    "ada": {
      "command": "uvx",
      "args": ["ada-mcp-server"],
      "env": {
        "ALS_PATH": "ada_language_server",
        "ADA_PROJECT_FILE": "project.gpr"
      }
    }
  }
}

Direct Execution

# Set environment
export ALS_PATH=/path/to/ada_language_server
export ADA_PROJECT_ROOT=/path/to/project

# Run the server
ada-mcp

# Or via Python module
python -m ada_mcp

---

Available Tools

Navigation Tools

Tool	Description
ada_goto_definition	Navigate to symbol definition
ada_find_references	Find all references to a symbol
ada_type_definition	Navigate to a symbol's type definition
ada_implementation	Navigate from spec to body
ada_hover	Get type info and documentation
ada_get_spec	Navigate from body to spec

Symbol Tools

Tool	Description
ada_document_symbols	List all symbols in a file (outline)
ada_workspace_symbols	Search symbols across workspace

Diagnostics & Build

Tool	Description
ada_diagnostics	Get compiler errors and warnings
ada_build	Build project with GPRbuild
ada_alire_info	Get Alire project information

Code Intelligence

Tool	Description
ada_completions	Get context-aware completions
ada_signature_help	Get function signature hints
ada_code_actions	Get available quick fixes

Project Tools

Tool	Description
ada_project_info	Get project structure info
ada_call_hierarchy	Get incoming/outgoing calls
ada_dependency_graph	Get package dependencies

Refactoring

Tool	Description
ada_rename_symbol	Rename symbol across project
ada_format_file	Format Ada source file

---

Tool Examples

ada_goto_definition

Navigate to where a symbol is defined.

{
  "file": "/project/src/main.adb",
  "line": 10,
  "column": 12
}

Response:

{
  "found": true,
  "file": "/project/src/utils.ads",
  "line": 25,
  "column": 4,
  "preview": "procedure Process_Data (Input : String);"
}

ada_find_references

Find all usages of a symbol across the project.

{
  "file": "/project/src/utils.ads",
  "line": 25,
  "column": 12,
  "include_declaration": true
}

Response:

{
  "symbol": "Process_Data",
  "references": [
    {"file": "/project/src/utils.ads", "line": 25, "column": 12, "isDefinition": true},
    {"file": "/project/src/main.adb", "line": 10, "column": 4, "isDefinition": false},
    {"file": "/project/src/tests.adb", "line": 8, "column": 8, "isDefinition": false}
  ],
  "totalCount": 3
}

ada_hover

Get type information and documentation for a symbol.

{
  "file": "/project/src/main.adb",
  "line": 15,
  "column": 8
}

Response:

{
  "found": true,
  "contents": "function Calculate_Sum (A, B : Integer) return Integer",
  "documentation": "Calculate the sum of two integers.",
  "range": {"start": {"line": 15, "column": 4}, "end": {"line": 15, "column": 17}}
}

ada_diagnostics

Get compiler errors and warnings.

{
  "file": "/project/src/main.adb",
  "severity": "error"
}

Response:

{
  "diagnostics": [
    {
      "file": "/project/src/main.adb",
      "line": 12,
      "column": 10,
      "severity": "error",
      "message": "expected type \"Integer\", found type \"String\""
    }
  ],
  "errorCount": 1,
  "warningCount": 0,
  "hintCount": 0
}

ada_document_symbols

Get all symbols in a file (outline view).

{
  "file": "/project/src/utils.ads"
}

Response:

{
  "file": "/project/src/utils.ads",
  "symbols": [
    {
      "name": "Utils",
      "kind": "package",
      "line": 1,
      "children": [
        {"name": "Process_Data", "kind": "procedure", "line": 10, "children": []},
        {"name": "Calculate_Sum", "kind": "function", "line": 15, "children": []}
      ]
    }
  ]
}

ada_completions

Get context-aware code completions.

{
  "file": "/project/src/main.adb",
  "line": 20,
  "column": 10,
  "trigger": "."
}

Response:

{
  "completions": [
    {
      "label": "Process_Data",
      "kind": "procedure",
      "detail": "procedure (Input : String)",
      "insertText": "Process_Data"
    },
    {
      "label": "Calculate_Sum",
      "kind": "function",
      "detail": "function (A, B : Integer) return Integer",
      "insertText": "Calculate_Sum"
    }
  ],
  "isIncomplete": false
}

ada_rename_symbol

Rename a symbol across the entire project.

{
  "file": "/project/src/utils.ads",
  "line": 10,
  "column": 12,
  "new_name": "Handle_Data",
  "preview": true
}

Response:

{
  "oldName": "Process_Data",
  "newName": "Handle_Data",
  "changes": [
    {"file": "/project/src/utils.ads", "line": 10, "oldText": "Process_Data", "newText": "Handle_Data"},
    {"file": "/project/src/utils.adb", "line": 25, "oldText": "Process_Data", "newText": "Handle_Data"},
    {"file": "/project/src/main.adb", "line": 12, "oldText": "Process_Data", "newText": "Handle_Data"}
  ],
  "totalChanges": 3,
  "applied": false
}

ada_build

Build the project with GPRbuild.

{
  "clean": false
}

Response:

{
  "success": true,
  "exitCode": 0,
  "errors": [],
  "warnings": [],
  "buildTime": 2.5
}

ada_project_info

Get project structure information.

{}

Response:

{
  "projectFile": "/project/project.gpr",
  "projectName": "My_Project",
  "sourceDirs": ["/project/src"],
  "objectDir": "/project/obj",
  "execDir": "/project/bin",
  "mainUnits": ["main.adb"]
}

ada_call_hierarchy

Get call relationships for a subprogram.

{
  "file": "/project/src/utils.adb",
  "line": 25,
  "column": 12,
  "direction": "both"
}

Response:

{
  "symbol": "Process_Data",
  "kind": "procedure",
  "incoming": [
    {"name": "Main", "file": "/project/src/main.adb", "line": 12}
  ],
  "outgoing": [
    {"name": "Validate_Input", "file": "/project/src/validators.ads", "line": 8}
  ]
}

---

AI Agent Usage Guide

Recommended Workflow

1. UNDERSTAND CONTEXT
   └─→ ada_document_symbols - Get file structure
   └─→ ada_project_info - Understand project layout
   └─→ ada_diagnostics - Check current errors

2. NAVIGATE CODE
   └─→ ada_goto_definition - Find where symbol is defined
   └─→ ada_find_references - Find all usages
   └─→ ada_type_definition - Find type declaration
   └─→ ada_implementation - Find body/implementation

3. UNDERSTAND SYMBOLS
   └─→ ada_hover - Get type info and documentation
   └─→ ada_signature_help - Get subprogram signatures
   └─→ ada_call_hierarchy - See who calls what

4. MAKE CHANGES
   └─→ ada_completions - Get context-aware suggestions
   └─→ ada_rename_symbol - Safely rename across project
   └─→ ada_format_file - Format code consistently

5. VERIFY CHANGES
   └─→ ada_diagnostics - Confirm no new errors
   └─→ ada_build - Full compilation check

Tool Selection Guidelines

AI Agent Task	Recommended Tools
"What type is this variable?"	ada_hover
"Where is this defined?"	ada_goto_definition
"Where is this used?"	ada_find_references
"Show me the structure of this file"	ada_document_symbols
"Find all symbols named X"	ada_workspace_symbols
"Are there any errors?"	ada_diagnostics
"Rename this safely"	ada_rename_symbol
"What can I type here?"	ada_completions
"Show the spec for this body"	ada_get_spec
"Show the body for this spec"	ada_implementation
"What calls this procedure?"	ada_call_hierarchy

Best Practices

1. Always check diagnostics after editing - Ada is strongly typed; verify your changes compile
2. Use hover before making assumptions - Get accurate type information
3. Use find_references before refactoring - Understand the full impact
4. Use document_symbols for orientation - Understand file structure before diving in
5. Prefer rename_symbol over find-replace - It handles all usages correctly

---

Configuration

Environment Variables

Variable	Default	Description
ALS_PATH	ada_language_server	Path to ALS executable
ADA_PROJECT_FILE	Auto-detect	GPR project file path
ADA_PROJECT_ROOT	Current directory	Project root directory
ADA_MCP_LOG_LEVEL	INFO	Logging verbosity (DEBUG, INFO, WARNING, ERROR)
ADA_MCP_TIMEOUT	30	Request timeout in seconds
ADA_MCP_CACHE_TTL	5	Cache time-to-live in seconds

Logging

Set ADA_MCP_LOG_LEVEL to adjust verbosity:

# Debug mode (verbose)
export ADA_MCP_LOG_LEVEL=DEBUG

# Production mode (errors only)
export ADA_MCP_LOG_LEVEL=ERROR

---

Architecture

┌─────────────────┐     MCP/JSON-RPC      ┌─────────────────┐
│   AI Agent      │ ◄──────────────────► │  Ada MCP Server │
│ (Copilot, etc.) │     (NDJSON/stdio)    │    (Python)     │
└─────────────────┘                       └────────┬────────┘
                                                   │
                                                   │ LSP/JSON-RPC
                                                   │ (stdio)
                                                   ▼
                                          ┌─────────────────┐
                                          │ Ada Language    │
                                          │ Server (ALS)    │
                                          └────────┬────────┘
                                                   │
                                                   ▼
                                          ┌─────────────────┐
                                          │ Ada Project     │
                                          │ (.gpr, .ads,    │
                                          │  .adb files)    │
                                          └─────────────────┘

Reliability Features

• Auto-restart: If ALS crashes, the server automatically restarts it with exponential backoff
• Health monitoring: Background task monitors ALS process health
• Response caching: TTL-based caching reduces redundant ALS queries

---

Development

# Clone repository
git clone https://github.com/ada-mcp/ada-mcp-server
cd ada-mcp-server

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linter
ruff check src/

# Format code
ruff format src/

# Type checking
mypy src/

Project Structure

ada-mcp-server/
├── src/ada_mcp/
│   ├── __main__.py      # Entry point
│   ├── server.py        # MCP server setup
│   ├── als/             # ALS communication
│   │   ├── client.py    # LSP client
│   │   ├── process.py   # ALS lifecycle & health monitoring
│   │   └── types.py     # LSP type definitions
│   ├── tools/           # MCP tool implementations
│   │   ├── navigation.py
│   │   ├── symbols.py
│   │   ├── diagnostics.py
│   │   ├── project.py
│   │   ├── refactoring.py
│   │   └── build.py
│   └── utils/           # Utilities
│       ├── cache.py     # Response caching
│       ├── position.py  # Line/column conversions
│       └── uri.py       # File URI handling
├── tests/               # Unit tests
└── scripts/             # Integration test scripts

Testing

Unit Tests (CI)

Unit tests with mocked ALS run in GitHub Actions:

pytest tests/ -v

Integration Tests (Local Only)

Integration tests require the actual Ada Language Server:

# Set ALS path
export ALS_PATH=/path/to/ada_language_server

# Run integration tests
python scripts/test_phase1_integration.py

---

Troubleshooting

ALS not found

Error: FileNotFoundError: ada_language_server

Solution: Set ALS_PATH to the full path of the ALS executable:

export ALS_PATH=/home/user/.local/bin/ada_language_server

No GPR file found

Warning: No GPR project file found. Disabling ALS indexing...

Solution: Set ADA_PROJECT_FILE or ensure your project has a .gpr file:

export ADA_PROJECT_FILE=my_project.gpr

ALS crashes repeatedly

The server will attempt to restart ALS with exponential backoff (up to 5 attempts). Check:

1. ALS version compatibility (use ALS 24.x or newer)
2. GPR file validity
3. Available system memory

Slow responses

Try reducing cache TTL for fresher results:

export ADA_MCP_CACHE_TTL=2

Or increase it for better performance on stable codebases:

export ADA_MCP_CACHE_TTL=30

Debug logging

Enable debug logging for troubleshooting:

export ADA_MCP_LOG_LEVEL=DEBUG
ada-mcp 2>&1 | tee mcp-debug.log

---

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass (pytest)
5. Submit a pull request

License

MIT License - see LICENSE for details.

Related Projects

• Ada Language Server - The underlying LSP server
• MCP Specification - Model Context Protocol documentation
• Alire - Ada package manager