Business Central MCP Server

A lightweight MCP (Model Context Protocol) server that enables AI-powered IDEs like Cursor to work with Business Central AL extensions. Upload your .app files and query AL object symbols through a standardized JSON-RPC interface.

Features

• Project Management: Register projects and get API keys for secure access
• Version Control: Automatic semantic version checking to prevent duplicate uploads
• App File Processing: Upload and extract symbols from Business Central .app files
• Advanced Symbol Search: Search AL objects with fuzzy search, exact name matching, object ID search, and type filtering
• Symbol Querying: Get AL source code for tables, pages, codeunits, and other objects using symbol IDs
• Reference Finding: Search for symbol usage across your extensions
• Helper Scripts: Automated upload scripts to handle large base64 files efficiently

Quick Start

1. Install and Start Server

# Clone and setup
git clone <repository-url>
cd bc-mcp
npm install
npm run build

# Start the server
npm start

2. Configure Cursor MCP

Add to your ~/.cursor/mcp.json:

{
  "mcpServers": {
    "bc-mcp": {
      "command": "node",
      "args": ["/path/to/bc-mcp/dist/index.js"],
      "env": {}
    }
  }
}

3. Register Your Project

Use Cursor's MCP integration to call:

Tool: register_project
Parameters: { "projectName": "MyBCProject" }

This returns:

• Your API key
• A ready-to-use upload helper script
• Setup instructions

4. Save the Upload Helper Script

The registration response includes a complete Node.js script. Save it as upload-app.js in your project root or .alpackages folder.

5. Upload Your Apps

Instead of handling large base64 strings in Cursor, use the workflow:

1. Check if upload is needed (recommended):

   Tool: check_app_version
   Parameters: { 
     "apiKey": "your-api-key",
     "fileName": "Publisher.AppName_1.0.0.0.app"
   }
   

2. If upload is needed, run the helper script:

   node upload-app.js .alpackages/Publisher.AppName_1.0.0.0.app

3. Then use the upload tool with the parameters shown by the script:

   Tool: upload_app
   Parameters: {
     "apiKey": "your-api-key", 
     "fileName": "Publisher.AppName_1.0.0.0.app",
     "appFile": "[base64-content-from-script]"
   }
   

Available MCP Tools

register_project

Register a new Business Central project and get your API key plus upload helper script.

Parameters:

• projectName (string): Name of your project

Returns: API key, instructions, and ready-to-use upload script

check_app_version

Check if an app version needs to be uploaded by comparing with existing versions.

Parameters:

• apiKey (string): Your project API key
• fileName (string): Name of the .app file (e.g., "Publisher.App_1.0.0.0.app")

Returns: Upload recommendation, version comparison, and existing versions list

upload_app

Upload a Business Central .app file from the .alpackages folder.

Parameters:

• apiKey (string): Your project API key
• fileName (string): Name of the .app file
• appFile (string): Base64 encoded .app file content

Returns: Upload confirmation with app details

list_apps

List all uploaded apps for your project.

Parameters:

• apiKey (string): Your project API key

Returns: Array of apps with versions and upload dates

search_symbols

Search for AL objects across all apps in your project with advanced filtering options.

Parameters:

• apiKey (string): Your project API key
• query (string, optional): Search query for object names and types (fuzzy search). Optional if objectId is provided
• objectType (string, optional): Filter by object type (table, page, codeunit, tableextension, pageextension, etc.)
• objectId (string, optional): Search for a specific object ID (e.g., "50000", "18")
• exactName (boolean, optional): If true, search for exact name match (case-insensitive) instead of fuzzy search. Requires query parameter

Returns: Array of matching symbols with their IDs, names, types, object IDs, app info, and file paths

Examples:

# Fuzzy search for customer-related objects
{ "apiKey": "key", "query": "customer" }

# Search for exact table name
{ "apiKey": "key", "query": "Customer", "exactName": true }

# Find all objects with ID 18
{ "apiKey": "key", "objectId": "18" }

# Find all tables containing "item"
{ "apiKey": "key", "query": "item", "objectType": "table" }

get_symbol_content

Get the full AL source code of a specific symbol using its unique ID from search results.

Parameters:

• apiKey (string): Your project API key
• symbolId (string): Unique ID of the symbol (obtained from search_symbols results)

Returns: Full AL source code with object details and metadata

find_references

Find all references to a symbol across all apps in your project.

Parameters:

• apiKey (string): Your project API key
• symbolName (string): Name of the symbol to find references for

Returns: List of files and locations where the symbol is referenced across all apps

Solving the Base64 Overflow Issue

Problem: Large .app files (>10MB) cause issues when Cursor tries to generate base64 content directly, leading to memory overflow or stuck execution.

Solution: The upload helper script approach:

1. Register project → Get helper script with embedded API key
2. Run helper script → Handles file reading and base64 encoding locally
3. Use script output → Provides clean parameters for MCP tools
4. Check version first → Avoid unnecessary uploads

This workflow keeps large binary data out of the LLM context while providing a smooth developer experience.

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Start in development mode
npm run dev

# Run tests
npm test

Architecture

• FastMCP: JSON-RPC server framework
• SQLite: Local database for projects, apps, and symbols
• JSZip: .app file extraction and processing
• TypeScript: Type-safe development
• Zod: Runtime validation

Security

• API keys for project access control
• File validation (only .app files from .alpackages folders)
• Size limits and security warnings
• Local-only operation (no external network calls)

Troubleshooting

Cursor Shows Red MCP Status

1. Check that the server path in mcp.json is correct
2. Ensure the server builds without errors: npm run build
3. Test server manually: echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js
4. Check Cursor's MCP logs for specific error messages

Large File Upload Issues

Use the helper script workflow instead of direct base64 encoding in Cursor. The script handles large files efficiently and provides clear instructions.

Version Conflicts

Use check_app_version before uploading to see if a newer version already exists. The server enforces semantic versioning and rejects non-incremental uploads.

Cursor Rules

When working with this Business Central MCP Server in Cursor, follow these guidelines for optimal AI assistance:

For Cursor AI Integration (.cursorrules)

Add this to your .cursorrules file in your Business Central project:

# Business Central Development with MCP Server

## Context
This project uses the Business Central MCP Server for AL development. The server provides tools to manage and query Business Central extensions.

## Available MCP Tools

### Core Workflow
1. Use `register_project` to set up a new project and get API key
2. Use `check_app_version` before uploading to avoid conflicts
3. Upload .app files via HTTP endpoint (not MCP tool due to file size)
4. Use `search_symbols` to find AL objects across all apps
5. Use `get_symbol_content` to view full AL source code
6. Use `find_references` to track symbol usage

### Search Capabilities
- **Fuzzy Search**: Default behavior, partial matching
- **Exact Name Search**: Use `exactName: true` for precise matches
- **Object ID Search**: Search by AL object ID (e.g., table 18, page 50000)
- **Type Filtering**: Filter by objectType (table, page, codeunit, etc.)

### Best Practices
- Always search for symbols first using `search_symbols` to get symbol IDs
- Use symbol IDs from search results with `get_symbol_content` for source code
- Check app versions before uploading to prevent conflicts
- Process only .app files from .alpackages directories
- Use the provided upload helper script for large files

### Security
- Each project has unique API keys for access control
- Only .app files are processed, with validation
- All operations are local-only, no external network calls

## AL Development Guidelines
- Follow Microsoft AL coding standards
- Use proper error handling in AL code
- Implement appropriate permissions and security
- Test extensions thoroughly before deployment
- Document custom objects and procedures

## When suggesting code changes:
- Always check existing AL objects first using the search tools
- Understand the object structure before making modifications
- Consider dependencies when suggesting changes
- Ensure compatibility with Business Central versions

Typical Workflow in Cursor

1. Start a new BC project:

   • Ask AI to register project: "Register a new BC project called 'MyExtension'"
   • Save the API key and upload script provided

2. Upload your extensions:

   • "Check if MyExtension_1.0.0.0.app needs to be uploaded"
   • If needed, run the upload script and then upload via MCP

3. Explore and understand code:

   • "Search for all Customer-related tables"
   • "Find the exact Customer table definition"
   • "Show me all references to the Customer table"

4. Development assistance:

   • "Find table 18 and show me its structure"
   • "Search for all page extensions in the system"
   • "Help me understand how Item table is used across extensions"

License

MIT License - see LICENSE file for details.