Developer Documentation

This document contains technical information for developers who want to contribute to the Kusto MCP Server project, build from source, or understand the implementation details.

Prerequisites

Node.js 16.x or higher
npm 8.x or higher
Access to an Azure Data Explorer (Kusto) cluster
Azure CLI or Azure Identity for authentication

Development Setup

Building from Source

Clone the repository:

git clone https://github.com/johnib/kusto-mcp
cd kusto-mcp

Install dependencies:
```
npm install
```
Build the project:
```
npm run build
```

Running in Development Mode

Start the server in development mode with auto-restart:

npm run dev

For production:

npm start

Testing

End-to-End Tests

The project includes comprehensive E2E tests that run against a real Kusto cluster:

# Run all E2E tests
npm run test:e2e

# Run with debug output
npm run test:e2e:debug

# Run in watch mode
npm run test:e2e:watch

The E2E tests:

Test against https://help.kusto.windows.net/ContosoSales
Run the MCP server as a subprocess
Verify MCP protocol compliance
Test all tool operations with real data
Validate error handling scenarios

For detailed testing documentation, see tests/e2e/README.md.

Unit Tests

Run unit tests:

npm test

Run with coverage:

npm run test:unit:coverage

Project Structure

kusto-mcp/
├── src/
│   ├── index.ts           # Entry point
│   ├── server.ts          # MCP server implementation
│   ├── auth/              # Authentication handlers
│   │   └── token-credentials.ts
│   ├── common/            # Common utilities
│   │   ├── errors.ts      # Error handling
│   │   ├── markdown-formatter.ts # Response formatting
│   │   ├── response-limiter.ts   # Response size limiting
│   │   └── utils.ts       # Utility functions
│   ├── operations/        # Kusto operations
│   │   └── kusto/
│   │       ├── connection.ts
│   │       ├── tables.ts
│   │       ├── queries.ts
│   │       └── index.ts
│   └── types/             # TypeScript type definitions
│       ├── config.ts
│       └── kusto-interfaces.ts
├── tests/                 # Test files
│   ├── e2e/              # End-to-end tests
│   └── unit/             # Unit tests
├── docs/                  # Documentation
├── dist/                  # Compiled JavaScript
├── .env.example           # Example environment variables
├── package.json           # Project manifest
└── tsconfig.json          # TypeScript configuration

Adding New Operations

To add a new Kusto operation:

Create a new file in src/operations/kusto/ or extend an existing one
Define the operation function
Export the function from src/operations/kusto/index.ts
Add the tool to the server in src/server.ts

Example:

// src/operations/kusto/new-operation.ts
export async function newOperation(client: KustoClient, params: NewOperationParams) {
  // Implementation
}

// src/operations/kusto/index.ts
export { newOperation } from './new-operation.js';

// src/server.ts
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === 'new-operation') {
    // Handle the new operation
  }
});

MCP Tools Reference

The server provides the following MCP tools:

initialize-connection

Creates a connection to an ADX cluster

Parameters:

cluster_url (string): The URL of the Kusto cluster
database (string): The database to connect to

show-tables

Lists tables in the given database

Parameters: None

show-table

Shows the table schema columns

Parameters:

tableName (string): The name of the table to get the schema for

execute-query

Runs KQL queries and returns results with automatic result limiting

Parameters:

query (string): The query to execute
limit (number, optional): Maximum number of rows to return (default: 20)

Features:

Automatically limits results to prevent context window overflow
Detects when results are partial and provides guidance
Returns metadata indicating if more results are available
Suggests using aggregations or filters for large datasets

show-functions

Lists all functions in the given database

Parameters: None

show-function

Provides detailed information on a given function, including its source code

Parameters:

functionName (string): The name of the function to get information about

CI/CD

This project uses GitHub Actions for automated testing, building, and publishing to NPM.

Automated Publishing

The project is configured with semantic release for automated versioning and publishing:

On push to main: Automatically runs tests, builds, and publishes to NPM based on conventional commit messages
Version bumping: Uses semantic versioning based on commit message types:
- fix: → Patch version (1.1.1 → 1.1.2)
- feat: → Minor version (1.1.1 → 1.2.0)
- BREAKING CHANGE: → Major version (1.1.1 → 2.0.0)
Skip publishing: Add [skip ci] to commit message to skip publishing (useful for docs/config changes)
Automatic changelog: Generates release notes from commit messages

Required Secrets

For the GitHub Actions to work, the following secrets must be configured in your GitHub repository:

NPM_TOKEN: Your NPM authentication token for publishing packages

Workflows

Release Workflow (.github/workflows/release.yml):
- Triggers on pushes to main branch
- Runs tests and builds the project
- Uses semantic-release for versioning and publishing
- Creates GitHub releases with auto-generated notes
CI Workflow (.github/workflows/ci.yml):
- Triggers on pull requests
- Runs linting, tests, and builds
- Ensures code quality before merging

Conventional Commits

To ensure proper versioning, use conventional commit messages:

# For bug fixes (patch version)
git commit -m "fix: resolve connection timeout issue"

# For new features (minor version)  
git commit -m "feat: add new query optimization tool"

# For breaking changes (major version)
git commit -m "feat: redesign authentication system

BREAKING CHANGE: authentication configuration format has changed"

# For documentation (no version bump)
git commit -m "docs: update installation instructions"

Code Quality

Linting and Formatting

The project uses ESLint and Prettier for code quality:

# Check linting
npm run lint:check

# Fix linting issues
npm run lint:fix

# Check formatting
npm run format:check

# Fix formatting
npm run format:fix

Pre-commit Hooks

The project uses Husky for pre-commit hooks that automatically:

Run ESLint with auto-fixing
Run Prettier with auto-formatting
Block commits if there are unfixable linting errors

For more details, see docs/pre-commit-hooks.md.

Implementation Notes

This TypeScript implementation mirrors the functionality of the C# version while using the appropriate Node.js libraries:

Uses azure-kusto-data and azure-kusto-ingest packages for Kusto operations
Implements Azure CLI authentication using KustoConnectionStringBuilder.withAzLoginIdentity
Provides comprehensive error handling with detailed exceptions
Includes OpenTelemetry integration for activity tracking
Implements schema caching to reduce redundant calls
Uses TypeScript for type safety and better developer experience

Authentication Implementation

Azure Identity Authentication

The server uses Azure Identity authentication by default.

Azure CLI Authentication

To use Azure CLI authentication:

Set KUSTO_AUTH_METHOD=azure-cli in your .env file
Ensure you're logged in with Azure CLI (az login)

AI Assistant Guidance

This MCP server includes detailed guidance for AI assistants on how to effectively interact with users when working with Azure Data Explorer. The guidance includes:

Workflow Guidance: Step-by-step instructions for connection setup, database exploration, query execution, best practices, and query optimization
Conversation Flow: Suggestions for how to guide users through the interaction, from initial connection to executing analytical queries
Error Handling: Common error scenarios and how to address them
ADX KQL Specifics: Best practices for writing efficient KQL queries

This guidance helps ensure that AI assistants can provide a consistent, helpful experience when helping users interact with Azure Data Explorer through this MCP server.

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Ensure all tests pass
Run linting and formatting
Submit a pull request

Please follow the conventional commit format for your commit messages.

License

MIT

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Developer Documentation

Prerequisites

Development Setup

Building from Source

Running in Development Mode

Testing

End-to-End Tests

Unit Tests

Project Structure

Adding New Operations

MCP Tools Reference

initialize-connection

show-tables

show-table

execute-query

show-functions

show-function

CI/CD

Automated Publishing

Required Secrets

Workflows

Conventional Commits

Code Quality

Linting and Formatting

Pre-commit Hooks

Implementation Notes

Authentication Implementation

Azure Identity Authentication

Azure CLI Authentication

AI Assistant Guidance

Contributing

License

FilesExpand file tree

DEVELOPER.md

Latest commit

History

DEVELOPER.md

File metadata and controls

Developer Documentation

Prerequisites

Development Setup

Building from Source

Running in Development Mode

Testing

End-to-End Tests

Unit Tests

Project Structure

Adding New Operations

MCP Tools Reference

initialize-connection

show-tables

show-table

execute-query

show-functions

show-function

CI/CD

Automated Publishing

Required Secrets

Workflows

Conventional Commits

Code Quality

Linting and Formatting

Pre-commit Hooks

Implementation Notes

Authentication Implementation

Azure Identity Authentication

Azure CLI Authentication

AI Assistant Guidance

Contributing

License