npm package: @praveen1718/azure-devops-al-mcp
Description: MCP server for reading and parsing AL (Application Language) files from Azure DevOps repositories
Author: Aptean
Latest version: 1.3.0

# 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

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

### Local Installation

```bash
npm install azure-devops-al-mcp-server
```

### From Source

```bash
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

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

### Optional Environment Variables

```bash
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
```bash
azure-devops-al-mcp
# Server will start on http://localhost:3000
```

#### Local Installation
```bash
npx azure-devops-al-mcp-server
```

#### With Environment Variables
```bash
AZURE_DEVOPS_ORG="myorg" AZURE_DEVOPS_PAT="pat_token" PORT=8080 azure-devops-al-mcp
```

#### With Docker
```bash
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
```bash
GET /health
```

#### Server Information
```bash
GET /
```

#### List Repositories
```bash
GET /repositories?project=MyProject
```

#### List AL Files
```bash
GET /repositories/{repo-id}/al-files?branch=main&path=/src
```

#### Get File Content
```bash
GET /repositories/{repo-id}/files/src/MyTable.Table.al?branch=main
```

#### Parse AL File
```bash
GET /repositories/{repo-id}/parse/src/MyTable.Table.al?branch=main
```

#### Search AL Objects
```bash
GET /repositories/{repo-id}/search?objectType=table&searchPattern=customer&branch=main
```

## API Documentation

### Authentication

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

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

### Endpoints

#### 1. List Repositories
```
GET /repositories?project=ProjectName
```

**Response:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "content": [
    {
      "type": "text",
      "text": "table 50100 MyTable { ... }"
    }
  ]
}
```

#### 4. Parse AL File
```
GET /repositories/{repo-id}/parse/src/MyTable.Table.al?branch=main
```

**Response:**
```json
{
  "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:**
```json
{
  "content": [
    {
      "type": "text",
      "text": "[{\"file\":\"/src/Customer.Table.al\",\"type\":\"table\",\"id\":18,\"name\":\"Customer\"}]"
    }
  ]
}
```

## Examples

### Starting the Server

```bash
# 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

```bash
# 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

```javascript
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

```bash
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

```bash
npm run watch  # Watch for TypeScript changes
```

### Testing

```bash
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:

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

## License

MIT License - see [LICENSE](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: support@aptean.com
- 🐛 Issues: [GitHub Issues](https://github.com/aptean/azure-devops-al-mcp-server/issues)
- 📚 Documentation: [GitHub Wiki](https://github.com/aptean/azure-devops-al-mcp-server/wiki)

---

Made with ❤️ by [Aptean](https://www.aptean.com) for the Business Central community.