mcp-telegram: Instructions file for Codex

AGENTS.md

Guidance for coding agents working in this repository. User-facing docs live in README.md; this file only covers what isn't obvious from the code.

What this is

A Go MCP server for Telegram, built on gotd/td. It is primarily a read-heavy research/summarisation assistant (search, extraction, context loading); admin and posting features are secondary. Two transports:

• stdio — single local account;
• streamable HTTP — embedded OAuth 2.1 server, per-user QR login, multi-user, deployable to Cloud Run (deploy/).

Layout

• main.go → internal/app.go — CLI entry (run, login, logout, config).
• internal/tools — MCP tools, one file per tool (Handler with Register).
• internal/tgdata, internal/messages — Telegram data access and message formatting shared by tools.
• internal/server, internal/authsrv — HTTP transport and OAuth.
• internal/tgclient, internal/sessionstore, internal/secret, internal/config — Telegram client and credential/session storage: macOS Keychain on darwin, file store in *_other.go (//go:build !darwin).
• internal/keyring — the MCP_AUTH_TOKEN_KEYS master keys shared by the token sealer and the session cipher; internal/keyedlimit — per-key token-bucket limiter (auth endpoints, user pool); internal/xdg — state directory, atomic file writes and the file-backed gotd session.
• internal/tgid, internal/presentation, internal/logging, internal/flags — shared id type, MCP-facing formats, the slog handler, CLI flags.
• internal/summarize, internal/prompts, internal/resources, internal/completion.
• internal/testutil/telegram — the scripted Telegram RPC fake for tests.
• test/ — integration tests (build tag integration).

Adding a tool

1. New file in internal/tools: an input struct (descriptions go in jsonschema tags; closed value sets via inputSchemaWithEnums) and a Register method.
2. Register with tools.AddTool — never plain mcp.AddTool: it keeps error results from reaching the client as an empty structured output. Use tools.AddContentTool only for tools with no typed output (e.g. GetMedia).
3. A tool that takes a chat ID takes the assembly's *tgclient.Resolver and wraps the RPC that uses the peer in tgclient.WithPeer (WithPeers, WithPeersFrom for several or for @usernames mixed with IDs): that is where a stale access hash is dropped from the cache and the call retried.
4. Return ErrResult only for input validation. Return every other failure as the handler's Go error via failed(op, err) / failedHint: the registration helpers classify it (dead session, a stopped client, flood wait, a problem with the chat named — tgclient.IsPeerSpecific), render the text the model sees, which the request log records under the tool's name. Anything else worth an operator's attention goes to slog (MCP client logging is deprecated and not used). They also give the call its flood-wait budget (tgclient.WithWaitBudget). A call that got part of its work done is no failure: its output embeds partialOutcome and says what it lacks with warn / warnCause, which AddTool flags for the request log.
5. Add the handler to buildHandlers in internal/server/server.go: research for read-only tools, mutating for anything that changes state. The split drives the server variants (see README "Server Variants").
6. Make the first sentence of Description self-contained: the compact and research variants keep only that sentence.
7. Update the tool list and tool counts in README.md.