lfx-mcp copilot-instructions.md

Copilot Instructions — LFX MCP Server

What This Repository Does

This is the LFX MCP Server — a Model Context Protocol (MCP) implementation in Go that exposes the Linux Foundation's LFX platform as MCP tools for AI agents. It uses the official MCP Go SDK and supports JSON-RPC 2.0 over stdio (dev) and Streamable HTTP (production) transports.

Key facts: ~25 Go source files, single binary, no database, stateless HTTP mode. Go and MCP SDK versions are pinned in go.mod. Built with ko for container images. Deployed to Kubernetes via Helm.

---

CI Rules (what breaks the build)

Two workflows run on every PR (.github/workflows/):

1. license-header-check.yml — tracked source/config files (Go, YAML, shell, Makefile, etc.) must begin with the license header.
2. mega-linter.yml — MegaLinter Go flavor v9 (config: .mega-linter.yml).

Requirements for new/modified files

License header — always include as the first lines:

// Copyright The Linux Foundation and contributors.
// SPDX-License-Identifier: MIT

For YAML, shell, and Makefile use # comment syntax. Missing headers are the #1 cause of CI failure.

Package doc comment — every non-test .go file must have // Package <name> ... immediately above the package declaration. The GO_REVIVE linter enforces the package-comments rule. _test.go files are exempt.

YAML formatting — keep lines ≤120 characters (config: .yamllint); this is a warning, not a build failure. Helm templates in charts/lfx-mcp/templates/ are excluded from YAML linting.

Other MegaLinter checks: the Go flavor bundles a full set of Go and common scripting/CI linters (shell, Docker, GitHub Actions, Helm, Markdown, secrets, etc.) and runs them all by default. .mega-linter.yml is the single source of truth for what's disabled or downgraded to error-only — check it rather than relying on any list here.

---

Project Layout

cmd/lfx-mcp-server/main.go    — Entry point, config, flag parsing, tool registration
internal/tools/                — All MCP tool implementations (one file per tool/domain)
internal/tools/scopes.go       — Scope constants (ScopeRead, ScopeManage)
internal/tools/helpers.go      — Shared utilities for tool handlers
internal/auth/                 — JWT verification, API-key verification
internal/lfxv2/                — LFX V2 API client (token exchange, slug resolver, access checks)
internal/serviceapi/           — Generic HTTP client for downstream service APIs
internal/otel/                 — OpenTelemetry initialization
charts/lfx-mcp/               — Helm chart (deployment, ingress, service, PDB)
Makefile                       — Build automation (targets: build, test, check, clean, etc.)
.mega-linter.yml               — MegaLinter config
.yamllint                      — YAML lint rules (max line length: 120)
.ko.yaml                       — ko builder config with ldflags
Dockerfile                     — Multi-stage build (Chainguard base images)
AGENTS.md                      — Detailed developer guide (canonical; CLAUDE.md is a symlink)
ARCHITECTURE.md                — System architecture with Mermaid diagrams