gronod
49bc0775de
Build and publish / Test and build (windows) (push) Failing after 11s
Build and publish / Test and build (darwin) (push) Successful in 1m32s
Build and publish / Test and build (linux) (push) Canceled after 0s
Build and publish / Build and publish Docker image (push) Canceled after 0s
Network MCP clients (e.g. browser-based frontends) can't spawn stdio subprocesses, so the server now optionally serves the 2024-11-05 MCP HTTP/SSE transport via MCP_TRANSPORT=sse and MCP_PORT (default 8080), backed by the SDK's SSEHandler behind permissive CORS. stdio remains the default and is behaviourally unchanged.
72 lines
3.8 KiB
Markdown
72 lines
3.8 KiB
Markdown
# AGENTS.md
|
|
|
|
## Project overview
|
|
|
|
`ombi-mcp` is a Model Context Protocol (MCP) server that exposes [Ombi](https://ombi.io/) 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.
|