Getting started with Trento MCP Server

This document provides a comprehensive guide to get started with Trento MCP Server development. It covers the development environment setup, project architecture, building, running, testing, and debugging the project.

Building the Project

Before starting development, ensure you have the following tools installed:

  • Go 1.24.4 or later (see Go installation guide)

  • Docker (for containerization)

  • Make (for build automation)

  • Git (for version control)

Project Overview

The Trento MCP Server is a Model Context Protocol (MCP) server implementation that enables AI tools and agents to interact with Trento infrastructure. The project automatically generates MCP tools from OpenAPI specifications, ensuring strong alignment between the API contract and implementation.

Project Structure

The project follows Go standard layout conventions:

mcp-server/
├── api/                    # OpenAPI specification
│   └── openapi.json       # API contract used for tool generation
├── bin/                    # Compiled binaries
├── cmd/                    # CLI commands and entry points
│   └── root.go            # Main command definitions and flags
├── docs/                   # Documentation
├── hack/                   # Build scripts and linters
├── helm/                   # Kubernetes/Helm deployment manifests
├── internal/               # Private application code
│   ├── server/            # Server implementation
│   │   ├── auth.go        # Authentication logic
│   │   └── server.go      # Core server functionality
│   └── utils/             # Shared utilities
│       ├── logger.go      # Logging configuration
│       └── types.go       # Common types and transport definitions
├── main.go                 # Application entry point
├── Dockerfile             # Container image definition
└── Makefile              # Build automation

Development Workflow

1. Clone and Setup

git clone https://github.com/trento-project/mcp-server.git
cd mcp-server

2. Install Dependencies

The project uses Go modules for dependency management:

go mod download

To install development tools (linters, etc.):

make install-tools

3. Building the Project

To build the project binary:

make build

The compiled binary will be located in the bin/ directory as trento-mcp-server.

Running the Project Locally

make clean

4. Running the Project Locally

To run the server locally with default settings:

make run

Building the Container Image

./bin/trento-mcp-server --port 8080 --transport sse --verbosity info

For a complete list of available flags:

./bin/trento-mcp-server --help

Testing

Running Tests

To run the full test suite:

make test

This runs all tests with coverage reporting.

To run tests for a specific package:

go test ./internal/server -v
go test ./internal/utils -v

To run tests with verbose output and coverage:

go test ./... -v -cover

Test Structure

  • Unit tests are located alongside source files with _test.go suffix

  • Test exports are defined in export_test.go files for testing internal functionality

Linting

The project includes some linters to ensure code quality:

# Run all linters
make lint

# Individual linters
make linter-asciidoc      # Documentation in AsciiDoc validation
make linter-golangci      # Go code linting
make linter-license       # License header verification
make linter-manifests     # Kubernetes manifests validation
make linter-shellcheck    # Shell script linting
make linter-yamllint      # YAML file linting

Debugging

Debug Logging

Run the server with debug logging enabled:

./bin/trento-mcp-server --verbosity debug

Log levels: * debug: Debug (most verbose) * info: Info (default) * warning: Warning * error: Error (least verbose)

Common Debugging Scenarios

  1. OpenAPI Specification Issues: Verify api/openapi.json is valid and contains operations tagged with MCP

  2. Authentication Problems: Check that the provided Trento API key is correct

  3. Transport Issues: Try switching between streamable and sse transports

  4. Port Conflicts: Use --port flag to specify a different port

Container Development

Building the Container Image

To build the container image:

make build-container

This creates a container image named ghcr.io/trento-project/trento-mcp-server:latest.

Running the Container

IMAGE=my-registry/trento-mcp-server:dev make build-container

Running the Container

To run the server in a container:

make run-container

To run with custom environment variables:

docker run -p 5000:5000 ghcr.io/trento-project/trento-mcp-server:latest --trento-url https://your-trento-instance.com

Pushing Container Images

To push the container image to a registry:

make push-container