Build and Package

This guide is for developers who want to build the MCP server from source and create packages.

Prerequisites

Node.js 20+ installed
npm or yarn package manager
TypeScript knowledge (for development)

Project Structure

mcp/
├── src/
│   ├── index.ts              # MCP server implementation
│   ├── banyandb-client.ts    # BanyanDB HTTP client
│   ├── query-generator.ts    # Natural language to BydbQL translator
│   ├── llm-prompt.ts         # LLM prompt generation
│   └── logger.ts             # Logging utilities
├── tools/
│   └── checkversion.js        # Version checking utility
├── dist/                     # Compiled JavaScript (generated)
├── banyandb-data/            # BanyanDB data directory (runtime)
├── Dockerfile                # Multi-stage Docker build file
├── docker-compose.yml        # Docker Compose configuration
├── eslint.config.mjs         # ESLint configuration
├── tsconfig.json             # TypeScript configuration
├── package.json              # Node.js dependencies and scripts
├── package-lock.json         # Dependency lock file
├── example-config.json       # Example MCP configuration
├── inspector-config.json     # MCP Inspector configuration
├── LICENSE                   # License file
├── LICENSE.tpl               # License template
├── Makefile                  # Build automation
└── README.md                 # Project documentation

Building from Source

1. Install Dependencies

cd mcp
npm install

2. Build

npm run build

This compiles TypeScript to JavaScript in the dist/ directory.

3. Verify Build

node dist/index.js --help

Development Mode

For development, you can use tsx to run TypeScript directly without compilation:

npm run dev

This runs src/index.ts directly using tsx, which is faster for iterative development.

Development Workflow

1. Make Changes

Edit files in the src/ directory.

2. Format and Lint

Before testing, format your code and check for linting issues:

npm run format
npm run lint

3. Test Changes

Use development mode for quick testing:

npm run dev

Or build and test:

npm run build
node dist/index.js

3. Test with Inspector

Use MCP Inspector to test your changes:

# Build first
npm run build

# Run Inspector
npx @modelcontextprotocol/inspector --config inspector-config.json

Debugging

VS Code Debug Configuration

Create .vscode/launch.json in the mcp directory:

{
  "version": "0.1.0",
  "configurations": [
    {
      "name": "Debug with MCP Inspector",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "npx",
      "runtimeArgs": [
        "@modelcontextprotocol/inspector",
        "--config",
        "${workspaceFolder}/inspector-config.json"
      ],
      "env": {
        "BANYANDB_ADDRESS": "localhost:17900",
        "LLM_API_KEY": "${env:LLM_API_KEY}",
        "LLM_BASE_URL": "${env:LLM_BASE_URL}"
      },
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen",
      "skipFiles": ["<node_internals>/**"],
      "sourceMaps": true,
      "outputCapture": "std"
    }
  ]
}

Debugging Steps

Set breakpoints in TypeScript files
Select “Debug with MCP Inspector” from the debug dropdown
Press F5 to start debugging
Inspector UI opens at http://localhost:6274
Test queries through the Inspector UI - breakpoints will trigger

Packaging

Create Distribution Package

The build process creates a dist/ directory with compiled JavaScript files. To create a distributable package:

# Build
npm run build

# Create package (includes dist/ and package.json)
tar -czf banyandb-mcp.tar.gz dist/ package.json

Docker Image

The project includes a production-ready Dockerfile that uses a multi-stage build for optimal image size and security.

Build Docker Image

To build a Docker image:

cd mcp

# Build the image
docker build -t apache/skywalking-banyandb-mcp:latest .

Or using the Makefile:

# From the project root
make -C mcp docker

# Or from the mcp directory
cd mcp
make docker

Dockerfile Features

The Dockerfile includes:

Multi-stage build: Separate build and production stages for smaller final image
Security: Runs as non-root user (appuser) for better security
Optimization: Only production dependencies in final image
Alpine-based: Uses node:20-alpine for minimal image size

Build Arguments

The Dockerfile supports standard Docker build arguments. You can customize the build:

docker build \
  --build-arg NODE_ENV=production \
  -t apache/skywalking-banyandb-mcp:latest .

Testing the Docker Image

After building, test the image:

# Run the container
docker run --rm \
  -e BANYANDB_ADDRESS=localhost:17900 \
  -e LLM_API_KEY=your-api-key \
  -e LLM_BASE_URL=your-api-key \
  apache/skywalking-banyandb-mcp:latest

Publishing Docker Image

To publish the image to a registry:

# Tag the image
docker tag apache/skywalking-banyandb-mcp:latest \
  ghcr.io/apache/skywalking-banyandb-mcp:v1.0.0

# Push to registry
docker push ghcr.io/apache/skywalking-banyandb-mcp:v1.0.0

Integration with Main Makefile

The MCP server is already integrated into the main project Makefile. The mcp/Makefile includes:

Build targets: build, all, docker
Clean targets: clean-build
Install targets: install
License targets: license-check, license-fix, license-dep
Version checking: check-version

Common Makefile Commands

# Build the project (includes format check, lint, and TypeScript compilation)
make -C mcp build

# Build Docker image
make -C mcp docker

# Install dependencies
make -C mcp install

# Clean build artifacts
make -C mcp clean-build

# Check license headers
make -C mcp license-check

# Fix license headers
make -C mcp license-fix

The Makefile automatically handles:

Code formatting checks (format:check)
Code linting (lint)
Dependency installation
TypeScript compilation
Docker image building (with proper tagging)
Version management

Testing

Integration Tests

Test with real BanyanDB instance:

Start BanyanDB:
```
docker-compose up -d
```

Run MCP Inspector:

npm run build
npx @modelcontextprotocol/inspector --config inspector-config.json

Test various queries through the Inspector UI

Code Quality

Linting

The project includes ESLint for code quality checks. Run linting:

npm run lint

This will check all TypeScript files in the src/ directory for code quality issues.

Formatting

The project uses Prettier for code formatting. Format your code:

npm run format

Check formatting without making changes (useful for CI):

npm run format:check

Both linting and formatting are integrated into the build process via the Makefile.

Release Process

Update version in package.json
Format code: npm run format
Lint code: npm run lint
Build the project: npm run build (or make build which includes lint/format checks)
Test with Inspector
Create package or Docker image
Tag the release in git
Publish Docker image (if applicable)

Troubleshooting

Build fails:

Check Node.js version: node --version (should be 20+)
Clear node_modules and reinstall: rm -rf node_modules && npm install
Check TypeScript version compatibility

Type errors:

Run npm run build to see all TypeScript errors
Check tsconfig.json configuration

Runtime errors:

Verify all dependencies are installed: npm install
Check environment variables are set correctly
Verify BanyanDB is accessible

Resources

Edit this page