vela-mcp/README.md

FastMCP Server wrapper for Vela.MCP - MCP-compatible interface to the Vela.MCP REST API

# Vela.MCP - Model Context Protocol Server for NAV/Business Central

Vela.MCP is an MCP (Model Context Protocol) server that provides Business Central/NAV codebase analysis tools directly to Claude Desktop and Claude Code. It connects to a Vela API server which manages the Qdrant vector database containing pre-ingested code analysis data.

## Quick Start

### Claude Desktop

Add this configuration to your Claude Desktop config file:
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS/Linux**: `~/.config/Claude/claude_desktop_config.json`

**For macOS/Linux:**
```json
{
  "mcpServers": {
    "vela": {
      "command": "npx",
      "args": ["-y", "vela-mcp"],
      "env": {
        "VELA_API_URL": "http://192.168.0.2:8000",
        "VELA_API_KEY": "your-api-key-here",
        "VELA_PROJECT_ID": "your-project-id-here"
      }
    }
  }
}
```

**For Windows:**
```json
{
  "mcpServers": {
    "vela": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "vela-mcp"],
      "env": {
        "VELA_API_URL": "http://192.168.0.2:8000",
        "VELA_API_KEY": "your-api-key-here",
        "VELA_PROJECT_ID": "your-project-id-here"
      }
    }
  }
}
```

Then reload MCP configuration in Claude Desktop.

### Claude Code

Add the MCP server using the `mcp add` command:

```bash
claude mcp add vela-mcp npx vela-mcp --scope user
```

Then configure the environment variables in your project's `.claude/mcp.json` or globally in `~/.claude/mcp.json`:

**For macOS/Linux:**
```json
{
  "mcpServers": {
    "vela-mcp": {
      "command": "npx",
      "args": ["-y", "vela-mcp"],
      "env": {
        "VELA_API_URL": "http://192.168.0.2:8000",
        "VELA_API_KEY": "your-api-key-here",
        "VELA_PROJECT_ID": "your-project-id-here"
      }
    }
  }
}
```

**For Windows:**
```json
{
  "mcpServers": {
    "vela-mcp": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "vela-mcp"],
      "env": {
        "VELA_API_URL": "http://192.168.0.2:8000",
        "VELA_API_KEY": "your-api-key-here",
        "VELA_PROJECT_ID": "your-project-id-here"
      }
    }
  }
}
```

### Cursor

Add this configuration to your Cursor MCP settings file (usually `~/.cursor/mcp.json` or in your project settings):

**For macOS/Linux:**
```json
{
  "mcpServers": {
    "vela": {
      "command": "npx",
      "args": ["-y", "vela-mcp"],
      "env": {
        "VELA_API_URL": "http://192.168.0.2:8000",
        "VELA_API_KEY": "your-api-key-here",
        "VELA_PROJECT_ID": "your-project-id-here"
      }
    }
  }
}
```

**For Windows:**
```json
{
  "mcpServers": {
    "vela": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "vela-mcp"],
      "env": {
        "VELA_API_URL": "http://192.168.0.2:8000",
        "VELA_API_KEY": "your-api-key-here",
        "VELA_PROJECT_ID": "your-project-id-here"
      }
    }
  }
}
```

Then restart Cursor to load the MCP server.

**How it works:**
- `npx` automatically downloads and runs the latest version from NPM
- `-y` flag auto-confirms the installation
- No manual installation or updates needed!

**Note for Windows users:**
Windows requires the `cmd /c` wrapper because `npx` is a batch file (`.cmd`) that cannot be executed directly. The `cmd /c` command tells Windows to run the batch file through the command interpreter.





## Configuration

### Environment Variables

All configuration is passed through environment variables in your MCP configuration:

| Variable | Required | Description | Example |
|----------|----------|-------------|---------|
| `VELA_API_URL` | Yes | The URL of your Vela API server | `http://192.168.0.1:8000
| `VELA_API_KEY` | Yes | Your API authentication key | `your-api-key-here` |
| `VELA_PROJECT_ID` | Yes | Project identifier (sent as `X-Project-ID` header) | `my-bc-project` |


## Available Tools

The MCP server exposes Business Central/NAV analysis tools:

### Upgrade & Compatibility Analysis
- **consolidated_upgrade_report**: Comprehensive upgrade analysis combining deprecated patterns, events, and dependencies
- **upgrade_tag_explorer**: Find upgrade/obsolete tags for objects and fields
- **deprecated_code_explorer**: Identify deprecated patterns and risky upgrade tags
- **dependency_explorer**: Analyze dependencies and validate against target version for breaking changes
- **event_flow_tracker**: Track event publisher-subscriber chains and identify breaking subscriptions
- **saas_incompatibility_explorer**: Find SaaS-incompatible code patterns

### Code Analysis
- **ask**: Ask natural language questions about the codebase with AI-powered search
- **event_publisher_explorer**: Find event publishers in objects by ID or wildcard pattern
- **procedure_lister**: List all procedures in an object with signatures
- **extension_finder**: Find table/page extensions for base objects
- **object_name_resolver**: Resolve object names to IDs with fuzzy matching

### Data & Structure Analysis
- **table_field_analyzer**: Analyze table structures with complete field definitions
- **data_model_rebuilder**: Rebuild data models and analyze table relationships

## Usage Examples

Once configured, you can ask Claude:

### Upgrade Analysis
- "Run a comprehensive upgrade analysis for Codeunit 50099"
- "What are the upgrade risks for Table 50075?"
- "Find upgrade tags for Table 36 field Amount"
- "What event subscriptions will break after upgrade in Codeunit 50036?"

### Code Analysis
- "Show me all dependencies for COD50099"
- "Find deprecated code patterns in the source version"
- "What event publishers exist in Codeunit 80?"
- "List all procedures in Codeunit 50099"

### Data Structure Analysis
- "Analyze the Customer table structure"
- "Show me complete field definitions for Table 50075"

## Development

### Build from Source

```bash
# Install dependencies
npm install

# Build TypeScript to JavaScript
npm run build

# Run locally
node dist/index.js
```

### Project Structure

```
Vela.MCP/
├── src/
│   └── index.ts              # TypeScript MCP server implementation
├── dist/                     # Compiled JavaScript (generated)
├── package.json              # NPM configuration
├── tsconfig.json            # TypeScript compiler configuration
└── README.md                # This file
```

## Troubleshooting

### Common Issues

**MCP server won't start:**
- Verify Node.js 18+ is installed: `node --version`
- Check the API server is running at the configured URL
- Review Claude Desktop logs for connection errors

**Tools returning errors:**
- Verify `VELA_API_URL` is correct and accessible
- Check `VELA_API_KEY` is valid
- Ensure the Vela API server is running and connected to Qdrant

**Can't connect to API:**
- Test the API directly: `curl http://192.168.0.178:8342/docs`
- Check firewall settings if API server is on different machine
- Verify the API server is listening on the correct port

### Manual Testing with CLI Arguments

For testing without Claude Desktop, use CLI arguments:

```bash
node dist/index.js --api-url http://192.168.0.178:8342 --api-key your-key --project-id your-project
```

## Requirements

- **Node.js 18+** (for native fetch support)
- **Running Vela API server**
- **Qdrant database** with ingested BC/NAV codebase data (managed by API server)

## License

[Your License Here]