last9-mcp-server: Instructions file for Codex

last9-mcp-server — agent instructions

Canonical agent guidance for this repo. CLAUDE.md is a compatibility shim that includes this file — edit here, not there.

This is a public repo. Never put internal backend paths, handler or route names, customer names, or infrastructure identifiers in code, comments, docs, commits, or PRs.

Orientation

An MCP server in Go (module last9-mcp) that exposes Last9 observability as tools, prompts, and resources.

Root files

file	role
main.go	startup, config, subcommands, stdio/HTTP transport
tools.go	every tool registration
resources.go	reference resources (last9://reference/...)
dump.go	dump-tools / dump-prompts — builds a server without credentials
http_server.go	--http mode

internal/

package	role
last9api	the single door for HTTP calls to the Last9 API
apm, alerting, dashboards, telemetry, change_events, suggest	tool handlers
prompts	embedded tool descriptions and reference manuals
workflows	MCP prompts
toolsets	which tools belong to which --toolsets domain
models, constants, utils, auth, deeplink, otelids	shared plumbing

Commands

go build .
go test -race ./...          # integration tests skip without TEST_REFRESH_TOKEN
go run . dump-tools          # served tools/list, name-sorted, plus instructions; no credentials
go run . dump-prompts        # served prompts/list
./scripts/start-local.sh     # run against a local .env
./scripts/eval-r10.sh        # eval suites against a fresh build of this checkout

Adding a tool, end to end

1. New API endpoint? Add internal/last9api/<area>/<endpoint>.go — see Calling the Last9 API. Skip if the endpoint already exists.
2. Description — write internal/prompts/descriptions/<tool_name>.md and embed it in internal/prompts/prompts.go as <Tool>Description — see Tool descriptions.
3. Tool — create <package>/<tool_name>.go with its Args struct, its New<Tool>Handler, and its private helpers — see Go conventions.
4. Register — add to tools.go via registerIfAllowed (registerWriteTool for a tool that changes state), and add the tool name to its domain in internal/toolsets/toolsets.go — see Registration.
5. Test — <tool_name>_test.go using httptest.NewServer; run go test -race ./....
6. Verify — go run . dump-tools shows the tool with the intended description and schema.
7. CHANGELOG — one bullet at the top of its section in [Unreleased].