Azure DevOps AL File Reader HTTP Server

An HTTP REST API server for reading and parsing AL (Application Language) files from Azure DevOps repositories. This server provides seamless integration with Azure DevOps Git repositories to analyze Business Central AL code through simple HTTP endpoints.

Features

• 🔍 Repository Discovery: List all repositories in your Azure DevOps organization/project
• 📁 AL File Browsing: Recursively find all AL files in any repository branch
• 📄 Content Reading: Retrieve complete AL file source code
• 🔧 AL Parsing: Extract structured metadata from AL objects (tables, codeunits, pages, etc.)
• 🔎 Code Search: Search for specific AL objects across repositories

Installation

Global Installation

npm install -g azure-devops-al-mcp-server

Local Installation

npm install azure-devops-al-mcp-server

From Source

git clone https://github.com/aptean/azure-devops-al-mcp-server.git
cd azure-devops-al-mcp-server
npm install
npm run build

Configuration

The server requires Azure DevOps authentication. Set up the following environment variables:

Required Environment Variables

export AZURE_DEVOPS_ORG="your-organization"
export AZURE_DEVOPS_PAT="your-personal-access-token"

Optional Environment Variables

export AZURE_DEVOPS_PROJECT="your-default-project"  # Optional: default project

Creating a Personal Access Token (PAT)

1. Go to https://dev.azure.com/{your-org}/_usersSettings/tokens
2. Click "New Token"
3. Give it a descriptive name
4. Select Code (read) permissions
5. Set appropriate expiration
6. Copy the generated token

Usage

Running the Server

Global Installation

azure-devops-al-mcp
# Server will start on http://localhost:3000

Local Installation

npx azure-devops-al-mcp-server

With Environment Variables

AZURE_DEVOPS_ORG="myorg" AZURE_DEVOPS_PAT="pat_token" PORT=8080 azure-devops-al-mcp

With Docker

docker build -t azure-devops-al-server .
docker run -p 3000:3000 -e AZURE_DEVOPS_ORG="myorg" -e AZURE_DEVOPS_PAT="pat_token" azure-devops-al-server

HTTP API Endpoints

The server exposes the following REST endpoints:

Health Check

GET /health

Server Information

GET /

List Repositories

GET /repositories?project=MyProject

List AL Files

GET /repositories/{repo-id}/al-files?branch=main&path=/src

Get File Content

GET /repositories/{repo-id}/files/src/MyTable.Table.al?branch=main

Parse AL File

GET /repositories/{repo-id}/parse/src/MyTable.Table.al?branch=main

Search AL Objects

GET /repositories/{repo-id}/search?objectType=table&searchPattern=customer&branch=main

API Documentation

Authentication

Optional API key authentication via x-api-key header:

curl -H "x-api-key: your-api-key" http://localhost:3000/repositories

Endpoints

1. List Repositories

GET /repositories?project=ProjectName

Response:

{
  "content": [
    {
      "type": "text",
      "text": "[{\"id\":\"repo-id\",\"name\":\"repo-name\",\"project\":\"project-name\",\"url\":\"repo-url\"}]"
    }
  ]
}

2. List AL Files

GET /repositories/{repo-id}/al-files?path=/src&branch=main

Response:

{
  "content": [
    {
      "type": "text", 
      "text": "[{\"path\":\"/src/MyTable.Table.al\",\"objectId\":\"abc123\",\"url\":\"file-url\"}]"
    }
  ]
}

3. Get File Content

GET /repositories/{repo-id}/files/src/MyTable.Table.al?branch=main

Response:

{
  "content": [
    {
      "type": "text",
      "text": "table 50100 MyTable { ... }"
    }
  ]
}

4. Parse AL File

GET /repositories/{repo-id}/parse/src/MyTable.Table.al?branch=main

Response:

{
  "content": [
    {
      "type": "text",
      "text": "[{\"type\":\"table\",\"id\":50100,\"name\":\"MyTable\",\"properties\":{},\"procedures\":[],\"fields\":[]}]"
    }
  ]
}

5. Search AL Objects

GET /repositories/{repo-id}/search?objectType=table&searchPattern=customer&branch=main

Response:

{
  "content": [
    {
      "type": "text",
      "text": "[{\"file\":\"/src/Customer.Table.al\",\"type\":\"table\",\"id\":18,\"name\":\"Customer\"}]"
    }
  ]
}

Examples

Starting the Server

# Set environment variables
export AZURE_DEVOPS_ORG="myorg"
export AZURE_DEVOPS_PAT="your_pat_token"
export AZURE_DEVOPS_PROJECT="MyProject"

# Start the server
azure-devops-al-mcp

# Output:
# 🚀 Azure DevOps AL File Reader HTTP Server running on http://0.0.0.0:3000
# 📋 Available endpoints:
#    GET  /              - Server info
#    GET  /health        - Health check  
#    GET  /repositories  - List repositories
#    ...

Using the API

# Check server health
curl http://localhost:3000/health

# List repositories
curl http://localhost:3000/repositories

# List AL files in a repository
curl "http://localhost:3000/repositories/my-repo-id/al-files?branch=main"

# Get file content
curl "http://localhost:3000/repositories/my-repo-id/files/src/MyTable.Table.al"

# Parse an AL file
curl "http://localhost:3000/repositories/my-repo-id/parse/src/MyTable.Table.al"

# Search for table objects
curl "http://localhost:3000/repositories/my-repo-id/search?objectType=table"

JavaScript/TypeScript Usage

const baseUrl = 'http://localhost:3000';

// List repositories
const repos = await fetch(`${baseUrl}/repositories`).then(r => r.json());

// Get AL files  
const alFiles = await fetch(`${baseUrl}/repositories/my-repo/al-files`).then(r => r.json());

// Parse an AL file
const parsed = await fetch(`${baseUrl}/repositories/my-repo/parse/src/MyTable.Table.al`).then(r => r.json());

Development

Building from Source

git clone https://github.com/aptean/azure-devops-al-mcp-server.git
cd azure-devops-al-mcp-server
npm install
npm run build

Development Mode

npm run watch  # Watch for TypeScript changes

Testing

npm test

Supported AL Objects

The parser recognizes and extracts metadata from:

• ✅ Tables
• ✅ Table Extensions
• ✅ Pages
• ✅ Page Extensions
• ✅ Codeunits
• ✅ Reports
• ✅ Queries
• ✅ XMLPorts
• ✅ Enums
• ✅ Enum Extensions
• ✅ Interfaces
• ✅ Control Add-ins
• ✅ Profiles
• ✅ Permission Sets

Requirements

• Node.js: >= 18.0.0
• Azure DevOps: Access to organization with Code (read) permissions
• HTTP Client: Any HTTP client (curl, Postman, browser, etc.)

Troubleshooting

Common Issues

1. Authentication Errors

   • Verify your PAT has "Code (read)" permissions
   • Check that the PAT hasn't expired
   • Ensure the organization name is correct

2. Repository Not Found

   • Verify repository name/ID is correct
   • Check that you have access to the repository
   • Ensure the project name is correct if specified

3. File Not Found

   • Check the file path is correct (case-sensitive)
   • Verify the branch exists
   • Ensure the file has a .al extension

Debug Mode

Set debug environment variable for verbose logging:

DEBUG=azure-devops-al* azure-devops-al-mcp

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📚 Documentation: GitHub Wiki

Made with ❤️ by Aptean for the Business Central community.