ombi-mcp/AGENTS.md

AGENTS.md

Project overview

ombi-mcp is a Model Context Protocol (MCP) server that exposes Ombi functionality (media requests, search, availability, issues) to MCP clients such as AI assistants.

This is a distributable product: it must work against any self-hosted Ombi instance, configured via OMBI_URL / OMBI_API_KEY. Do not hardcode instance-specific values.

Our local development environment points at https://ombi.i3omb.com — that URL is environment-specific config only (e.g. a local .env), never a default or test fixture others would see.

Remote repo: https://git.i3omb.com/gronod/ombi-mcp.git

Repository layout

Update as the project grows.

• cmd/ombi-mcp/ — server entrypoint (main.go)
• internal/config/ — environment/config loading
• internal/ombi/ — Ombi API client, auth, and wire types
• internal/mcpserver/ — MCP server setup
• internal/transport/ — HTTP/SSE transport (mux, CORS, graceful shutdown); stdio stays in the entrypoint
• internal/tools/ — MCP tool registry, argument, and result types
• internal/translate/ — enum/terminology translation layer
• internal/integration_test/ — build-tagged (//go:build integration) end-to-end suite: spawns the compiled binary and speaks raw MCP JSON-RPC over stdio against a mock Ombi, or a live instance when OMBI_* env vars are set
• docs/ — schema and planning docs
• .gitea/workflows/ — cross-platform CI builds and Gitea container publishing
• Dockerfile / .dockerignore — static multi-platform container packaging
• docs/ci.md — runner setup, registry secrets, artifacts, and Docker usage
• AGENTS.md — this file

Development

Toolchain: Go (module ombi-mcp). Build with CGO_ENABLED=0 — the server ships as a statically linked binary with no CGO dependencies.

Prerequisites

• Go 1.27+
• An Ombi instance URL and API key for integration testing. Keep credentials in a local .env file — never commit secrets.

Commands

• Install dependencies: go mod tidy (or go get <pkg> to add one)
• Build: CGO_ENABLED=0 go build ./...
• Build binary: CGO_ENABLED=0 go build -o ombi-mcp ./cmd/ombi-mcp
• Run dev server: go run ./cmd/ombi-mcp
• Run tests: go test ./...
• Run integration tests (mock Ombi, no credentials needed): go test -tags integration ./internal/integration_test/
• Run live integration tests: set OMBI_* vars (e.g. set -a; . ./.env; set +a) then the same command — live tests skip when OMBI_URL is unset
• Lint / typecheck: go vet ./... (and gofmt -l . for formatting)

Conventions

• Follow the conventions of the chosen language/toolchain; match existing code style.
• All Ombi API access should go through a single client module — do not scatter HTTP calls across tools.
• MCP tool names should be snake_case and encode effect via prefix: read_* for read-only tools (e.g. read_search), write_* for state-mutating tools (e.g. write_request_create).
• Validate and sanitize all tool inputs; never interpolate user input into URLs without escaping.

Environment variables

• OMBI_URL — base URL of the Ombi instance
• OMBI_AUTH_MODE — upstream credential mechanism: jwt (primary) or api_key
• OMBI_USERNAME / OMBI_PASSWORD — JWT login credentials (jwt mode)
• OMBI_API_KEY — Ombi API key (api_key mode)
• OMBI_USER_NAME — optional Ombi username bound via UserName header (api_key mode)
• MCP_TRANSPORT — client-facing transport: stdio (default) or sse
• MCP_PORT — listen port for sse transport (default 8080; routes: GET /sse opens a session stream, clients POST JSON-RPC to the advertised ?sessionid= endpoint, also served at /messages; permissive CORS)

Git

• Commit small, focused changes with messages explaining the why.
• Do not commit secrets, .env files, or generated artifacts.