agentleFS
qelphyboxqelphybox/tg-mcp/CLAUDE.md

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

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
  1. Distinctive:

    Never log message content, Tokens, Session keys or Telegram sessions.

    line 19
  2. Very specific:

    Read tools are read-only (readOnlyHint: true).

    line 20
  3. Very specific:

    Default vocabulary: needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix.

    line 35

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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 to https://connector.tgmcp.dev. Setup, rollback and what a deploy loses: docs/deploy.md.
  • Landing page: site/ (static files, no build) → GitHub Pages at https://tgmcp.dev on push to main (.github/workflows/pages.yml). Check it with node 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.Z matching Cargo.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_WAIT is 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.