tg-mcp
CLAUDE.md2 starsChanged 10 days agoMITView on GitHub
Remote MCP server (streamable HTTP) giving AI clients access to a personal Telegram account: read access now, write tools from v0.2.0 (ADR-0005). Onboarding: claude mcp add --transport http <name> <url> → OAuth in the browser → QR login → done. Vocabulary is in GLOSSARY.md; decisions in docs/adr/. Rust (latest stable), tokio, axum, rmcp (MCP), grammers (Telegram, version pinned exactly), sqlx + SQLite. One binary, one Docker image. Matt Pocock's skills are vendored in .claude/skills/ (engineering + productivity, MIT). Start a…
- Reads credentials
In this repository28 other files it gives its agents.
- site/llms.txtllms.txt
- ask-mattSkill
- codebase-designSkill
- code-reviewSkill
- diagnosing-bugsSkill
- domain-modelingSkill
- grillingSkill
- grill-meSkill
- grill-with-docsSkill
- handoffSkill
- implementSkill
- implement-specSkill
- improve-codebase-architectureSkill
- prototypeSkill
- prSkill
- researchSkill
- retroSkill
- setup-matt-pocock-skillsSkill
- tddSkill
- teachSkill
- to-questionnaireSkill
- to-specSkill
- to-ticketsSkill
- triageSkill
- wait-whatSkill
- wayfinderSkill
- wizardSkill
- writing-for-agentsSkill
The file
We split this CLAUDE.md into the rules it gives an agent
3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 19
Never log message content, Tokens, Session keys or Telegram sessions.
- Very specific: line 20
Read tools are read-only (readOnlyHint: true).
- Very specific: line 35
Default vocabulary: needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
tg-mcp
Remote MCP server (streamable HTTP) giving AI clients access to a personal Telegram account: read access now, write tools from v0.2.0 (ADR-0005). Onboarding: claude mcp add --transport http <name> <url> → OAuth in the browser → QR login → done. Vocabulary is in GLOSSARY.md; decisions in docs/adr/.
Stack
Rust (latest stable), tokio, axum, rmcp (MCP), grammers (Telegram, version pinned exactly), sqlx + SQLite. One binary, one Docker image.
Commands
cargo fmt --all/cargo clippy --all-targets -- -D warnings/cargo test: all three must pass before a commit.cargo run: starts the server; config comes from env vars (see.env.example).- Deploy: push to
main→ Kamal rollout tohttps://connector.tgmcp.dev. Setup, rollback and what a deploy loses:docs/deploy.md. - Landing page:
site/(static files, no build) → GitHub Pages athttps://tgmcp.devon push tomain(.github/workflows/pages.yml). Check it withnode tests/site/landing-check.cjs(Playwright: widths, requests, buttons, demo, dictionary fallback, no JS);node tests/site/landing-check.cjs site /ru/for another language page. - Release (for self-hosters): tag
vX.Y.ZmatchingCargo.toml→ multi-arch image on GHCR + GitHub Release. Checklist:docs/acceptance.md.
Rules that are not visible in the code
- Never log message content, Tokens, Session keys or Telegram sessions. Log ids and sizes only.
- Read tools are read-only (
readOnlyHint: true). Write tools act only within their Scope and the Send allow-list, go through the writes budget and never forward (ADR-0005). Every tool has bounded input/output schemas and a capped response size. - Telegram's
FLOOD_WAITis honoured, never retried around. - The Session key is never persisted in plaintext (ADR-0003). Anything that would need it without a Token is a design bug.
- Repo artifacts (code, comments, issues, docs) are in English.
Agent skills
Matt Pocock's skills are vendored in .claude/skills/ (engineering + productivity, MIT). Start a change with /grill-with-docs, then /to-spec → /to-tickets → /implement (which drives /tdd and /code-review).
Issue tracker
GitHub Issues in qelphybox/tg-mcp (gh locally, GitHub MCP tools in cloud sessions). See docs/agents/issue-tracker.md.
Triage labels
Default vocabulary: needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix. See docs/agents/triage-labels.md.
Domain docs
Single-context: GLOSSARY.md + docs/adr/ at the repo root. See docs/agents/domain.md.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

