mcp-tg: Instructions file for Claude Code

CLAUDE.md — Development Guide for mcp-tg

What is this

MCP server for Telegram Client API (MTProto, not Bot API). Uses gotd/td for protocol, exposes 80 tools + resources + prompts via MCP.

Build & Test

go build ./cmd/mcp-tg
go test -race ./...
golangci-lint run

Documentation

User-facing documentation lives in docs/, is built with MkDocs Material (mkdocs.yml) from the fully locked dependencies in requirements-docs.txt (compiled from requirements-docs.in), and follows the same shape as this owner's other docs sites: sections with their own index.md (navigation.indexes), a stylesheet, and a docs.yaml / docs-validate.yaml pair. .github/workflows/docs.yaml publishes to https://mcp-tg.lexfrei.dev on every push to master; .github/workflows/docs-validate.yaml runs markdownlint-cli2 and the same mkdocs build --strict on every PR (TestDocsGates_RunOnPullRequests). README.md is a landing page only — install, quickstart, links — and anything longer belongs on a docs page.

That PR check must be in master's required status checks, and is — today they are Lint, Test, Build (amd64), Build (arm64), Validate Documentation and Release Config. Keep it there: nothing in the workflow graph depends on Validate Documentation, so were it dropped, a PR that breaks the site would merge green, docs.yaml would fail on master, and the site would quietly stop updating with the last good build still served. The list lives in the repository's branch-protection settings, outside version control like the Pages config below, so it can drift from this paragraph with nothing red; gh api repos/lexfrei/mcp-tg/branches/master/protection --jq '.required_status_checks.contexts' is the source of truth. Relative links and anchors inside docs/ ([Peers](peers.md), ../building.md#transport-modes) are checked by that build and by nothing else — TestDocsSiteURLs_ResolveToPages reads absolute URLs only. This is why docs-validate.yaml carries no paths: filter, unlike the reference it is modelled on: GitHub leaves a skipped workflow's check Pending forever and blocks a merge on a required check that never reports, so a filtered workflow can never be required at all.