telegram-context-mcp 0.2.0__tar.gz

telegram_context_mcp-0.2.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,44 @@
+name: Bug report
+description: Report a reproducible problem with the server or its tools.
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use a minimal, synthetic example. Do not include phone numbers, login codes,
+        API keys or hashes, session files, credentials, or private Telegram dumps.
+  - type: textarea
+    id: environment
+    attributes:
+      label: Versions and environment
+      description: Include the project version or commit, Python and uv versions, OS, and MCP client when relevant.
+      placeholder: |
+        Project version or commit:
+        Python:
+        uv:
+        OS:
+        MCP client and version:
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: List the commands or tool arguments needed to reproduce the problem. Use synthetic data and omit secrets.
+      placeholder: |
+        1.
+        2.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: Include the error code and a short, sanitized diagnostic excerpt if useful.
+    validations:
+      required: true

telegram_context_mcp-0.2.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,27 @@
+name: Feature request
+description: Propose a focused improvement and explain the use case.
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Check ROADMAP.md for the current direction. Describe the need using synthetic
+        examples; do not include credentials, session files, or private Telegram content.
+  - type: textarea
+    id: use_case
+    attributes:
+      label: Use case
+      description: What task is difficult or impossible today, and who needs the improvement?
+    validations:
+      required: true
+  - type: textarea
+    id: scope
+    attributes:
+      label: Proposed behavior and scope
+      description: Describe the smallest useful change, what success looks like, and anything that should remain outside scope.
+    validations:
+      required: true
+  - type: input
+    id: roadmap
+    attributes:
+      label: Related roadmap item or issue
+      description: Link an existing issue or name a milestone, or state that this is a new direction.

telegram_context_mcp-0.2.0/.github/dependabot.yml

@@ -0,0 +1,32 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 4
+    versioning-strategy: lockfile-only
+    allow:
+      - dependency-type: all
+    commit-message:
+      prefix: chore
+      include: scope
+    groups:
+      mcp:
+        patterns: [mcp, mcp-types]
+      other-dependencies:
+        patterns: ["*"]
+        exclude-patterns: [telethon, mcp, mcp-types]
+        update-types: [minor, patch]
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 2
+    commit-message:
+      prefix: chore
+      include: scope
+    groups:
+      actions:
+        patterns: ["*"]
+        update-types: [minor, patch]

telegram_context_mcp-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,14 @@
+## Change
+
+<!-- State the problem and resulting behavior. Keep this PR to one bounded change.
+Mention any public API, configuration, or compatibility changes. -->
+
+## Validation
+
+<!-- Report the checks you ran and their results, such as `make check`.
+For documentation-only work, describe the relevant review. Identify any unverified behavior.
+Do not include credentials, session files, or private Telegram content. -->
+
+## Related work
+
+<!-- Link an issue or ROADMAP.md item when relevant. Remove this section if unnecessary. -->

telegram_context_mcp-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,127 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  workflow_dispatch:
+  workflow_call:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    name: Formatting, lint, and types
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+        with:
+          version: "0.13.1"
+          python-version: "3.12"
+          enable-cache: true
+      - name: Install locked dependencies
+        run: uv sync --locked --group dev
+      - name: Check formatting
+        run: uv run --locked ruff format --check .
+      - name: Check lint
+        run: uv run --locked ruff check .
+      - name: Check types
+        run: uv run --locked ty check
+
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+        with:
+          version: "0.13.1"
+          python-version: "3.12"
+          enable-cache: true
+      - name: Check the lockfile
+        run: uv lock --check
+      - name: Build wheel and source distribution
+        run: uv build --no-sources
+      - name: Save distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: distributions
+          path: dist/*
+          if-no-files-found: error
+          retention-days: 14
+
+  tests:
+    name: Tests (${{ matrix.os }}, Python ${{ matrix.python }})
+    needs: build
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python: ["3.12", "3.13", "3.14", "3.15"]
+        include:
+          - os: macos-latest
+            python: "3.12"
+          - os: macos-latest
+            python: "3.15"
+          - os: windows-latest
+            python: "3.12"
+          - os: windows-latest
+            python: "3.15"
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+        with:
+          version: "0.13.1"
+          python-version: ${{ matrix.python }}
+          enable-cache: true
+      - name: Install locked dependencies
+        run: uv sync --locked --group dev
+      - name: Run autonomous tests
+        run: uv run --locked pytest
+      - name: Download distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: distributions
+          path: dist
+      - name: Smoke test fresh wheel and source installations
+        run: uv run --locked python scripts/smoke_distribution.py
+
+  checks:
+    name: checks
+    if: always()
+    needs: [quality, build, tests]
+    runs-on: ubuntu-latest
+    timeout-minutes: 1
+    steps:
+      - name: Require every check to succeed
+        env:
+          QUALITY_RESULT: ${{ needs.quality.result }}
+          BUILD_RESULT: ${{ needs.build.result }}
+          TEST_RESULT: ${{ needs.tests.result }}
+        run: |
+          test "$QUALITY_RESULT" = success
+          test "$BUILD_RESULT" = success
+          test "$TEST_RESULT" = success

telegram_context_mcp-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,93 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  validate:
+    name: Validate release metadata
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Check out the tagged commit and main history
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+        with:
+          version: "0.13.1"
+          python-version: "3.12"
+      - name: Verify tag, package version, changelog, and main ancestry
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: >-
+          uv run --no-project python scripts/check_release.py
+          --tag "$RELEASE_TAG" --notes-file release-notes.md
+      - name: Save release notes
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: release-notes
+          path: release-notes.md
+          if-no-files-found: error
+          retention-days: 14
+
+  validation:
+    name: Validate distributions
+    needs: validate
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    name: Publish to PyPI
+    needs: validation
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/project/telegram-context-mcp/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download the validated distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: distributions
+          path: dist
+      - name: Publish with PyPI Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
+
+  github-release:
+    name: Create GitHub Release
+    needs: publish
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      - name: Download the published distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: distributions
+          path: dist
+      - name: Download the validated release notes
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: release-notes
+          path: .
+      - name: Create the release with the exact PyPI artifacts
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: >-
+          gh release create "$RELEASE_TAG" dist/* --verify-tag
+          --title "$RELEASE_TAG" --notes-file release-notes.md

telegram_context_mcp-0.2.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+*.session*
+.env*
+!.env.example
+config.toml
+.DS_Store

telegram_context_mcp-0.2.0/.python-version

@@ -0,0 +1 @@
+3.12

telegram_context_mcp-0.2.0/AGENTS.md

@@ -0,0 +1,25 @@
+# Repository conventions
+
+## Language
+
+- Use English for documentation, code comments and docstrings, CLI text,
+  identifiers, test names, and commit messages.
+- Preserve multilingual source content and test fixtures when their language
+  is relevant to the behavior being tested.
+- Conversation replies may follow the user's language.
+
+## GitHub workflow
+
+- Work on a focused branch and open a pull request to `main`; avoid direct pushes to `main`.
+- Use Conventional Branch purpose prefixes: `feature/`, `bugfix/`, `hotfix/`,
+  `chore/`, or `release/`. Use lowercase kebab-case descriptions; release versions
+  may contain dots. Example: `feature/public-channel-discovery`.
+- Dependabot-generated `dependabot/` branches are the approved automation exception;
+  human-created branches must still use the Conventional Branch prefixes above.
+- Use Conventional Commits for commit messages and PR titles.
+- Run `make check`, review the diff, and wait for the GitHub `checks` job before merging.
+- Squash-merge completed PRs. Start the next branch from the updated `main`.
+- Update `ROADMAP.md` with completed work. See `CONTRIBUTING.md` for contributor guidance.
+- Review dependency-update PRs manually; do not enable automatic merging.
+- Keep public changes in `CHANGELOG.md`. Follow `docs/releasing.md` for version tags
+  and PyPI publication; do not treat a merged PR as a published release.

telegram_context_mcp-0.2.0/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+Public changes to `telegram-context-mcp`. The command name is `telegram-mcp`.
+
+A version entry describes its target artifact. Verify publication on
+[PyPI](https://pypi.org/project/telegram-context-mcp/) and
+[GitHub Releases](https://github.com/egor-fedorov/telegram-mcp/releases).
+
+## [Unreleased]
+
+No additional changes recorded.
+
+## [0.2.0] - 2026-10-21
+
+### Added
+
+- A foreground, bearer-authenticated local HTTP server at `127.0.0.1:8765/mcp`.
+- A `connect` STDIO proxy so several MCP clients can share one Telegram session,
+  read policy, and process-local cursor store.
+- `--version`, pinned installation examples, and configuration guides for Codex,
+  Claude Desktop, Claude Code, Cursor, and VS Code.
+- Package build checks, platform/Python compatibility checks, Trusted Publisher
+  release automation, and reviewed dependency-update PRs.
+
+### Changed
+
+- Session locking supports Windows as well as macOS and Linux.
+- Local files use explicit UTF-8 handling; configuration errors identify invalid
+  fields and sources without exposing their values.
+- Interactive configuration preserves existing settings on Enter and explicitly
+  prompts for `allow_all_chats`.
+- The README focuses on installation and first use; detailed usage, configuration,
+  troubleshooting, release instructions, and completed specifications have their
+  own documents.
+
+### Compatibility
+
+- `telegram-mcp serve` remains the standalone STDIO command. The same 14 tools and
+  message schemas are available through both transports.
+- Shared clients must run as one trusted local user. The HTTP process is started
+  explicitly; `connect` never starts it or falls back to opening another session.
+- Stop the session-owning process before local login, configuration, catalog, or
+  status commands. Use MCP `get_status` while the server is running.
+- Existing Telegram sessions and TOML read-policy settings remain usable.
+
+## Earlier source development
+
+M0–M2 added reliable retrieval, public-channel discovery, topic and pinned-message
+navigation, counters, reactions, polls, and bounded album retrieval. R1 separated
+domain, application, adapters, and bootstrap while preserving all tool contracts.
+See the [completed specifications](docs/specs/README.md) and
+[architecture decision](docs/architecture.md) for those implementation records.

telegram_context_mcp-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,91 @@
+# Contributing
+
+Use English for repository documentation, code comments, CLI text, commit messages,
+and pull requests. Keep multilingual fixtures when their language matters to a test.
+See [ROADMAP.md](ROADMAP.md) for current priorities, [Architecture](docs/architecture.md)
+for dependency boundaries, and [completed specifications](docs/specs/README.md) for
+the accepted M1/M2 contracts.
+
+## Local setup and checks
+
+Use Python 3.12 and [uv](https://docs.astral.sh/uv/) for the standard development
+environment. The supported runtime range is Python 3.12–3.15 on Windows, macOS, and
+Linux. From the project directory:
+
+```sh
+uv sync --locked --python 3.12
+make check
+```
+
+`make check` runs Ruff formatting checks, Ruff lint, ty, and pytest. Tests are offline:
+they do not require a Telegram account, login, or network requests to Telegram.
+Dependency installation may require network access. Add tests for changed behavior
+and keep existing MCP contracts compatible, or explain any compatibility changes.
+For documentation-only changes, check links, examples, and formatting.
+
+On Windows without Make, run the same checks directly:
+
+```sh
+uv run --locked ruff format --check .
+uv run --locked ruff check .
+uv run --locked ty check
+uv run --locked pytest
+```
+
+CI checks formatting/types, builds wheel and source distributions, and runs tests
+plus clean-install smoke checks. The matrix covers Python 3.12–3.15 on Linux and
+3.12/3.15 on macOS and Windows. The required `checks` job succeeds only when its
+dependencies succeed. No Telegram credentials or publishing secrets are needed.
+
+When changing transport behavior, cover standalone STDIO, authenticated local HTTP,
+and the STDIO proxy without a real Telegram account. Shared-client tests should
+exercise lifecycle and cursor behavior, including a client disconnecting while the
+session-owning server remains available. Preserve the recorded schemas of all 14 tools.
+
+## Branches, commits, and pull requests
+
+1. Start from the current `main` and create a branch for one bounded change. Follow
+   [Conventional Branch](https://conventionalbranch.org): use `feature/`, `bugfix/`,
+   `hotfix/`, or `chore/` with a lowercase kebab-case description, such as
+   `feature/public-channel-discovery` or `bugfix/preserve-retry-delay`.
+   Documentation-only work uses a branch such as `chore/update-docs`.
+   Release branches use `release/vX.Y.Z`, for example `release/v1.2.0`.
+   Dependabot's generated `dependabot/` branches are the approved automation exception;
+   human-created branches still use the Conventional Branch prefixes above.
+2. Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for
+   commit messages and the PR title: `<type>[optional scope]: <description>`.
+   Examples: `feat(discovery): add public channel search`,
+   `fix: preserve retry delays`, and `docs: explain discovery permissions`.
+3. Run the relevant checks and open a pull request targeting `main`. Describe the
+   problem, resulting behavior, and validation. Link a related issue or roadmap item
+   when applicable. Update documentation for public behavior or configuration changes.
+4. Address review feedback and wait for the GitHub `checks` job to pass. Use squash
+   merge after review; the final PR title becomes the squash commit message. Do not push feature work
+   directly to `main`.
+
+Keep changes focused. Propose a new direction with a feature request before expanding
+an agreed milestone. Add or update roadmap completion records only when their acceptance
+criteria are met; distinguish offline checks from any separately performed live validation.
+
+## Dependencies and releases
+
+Commit `uv.lock` alongside dependency changes. Review release notes and the lockfile
+diff, then run the appropriate compatibility checks. Dependabot opens update PRs for
+review; it does not merge them automatically. Updates to pinned GitHub Actions follow
+the same review and CI process as Python dependencies.
+
+Changes intended for users should have a concise entry in [CHANGELOG.md](CHANGELOG.md).
+Release preparation belongs in a PR; a version tag is pushed only after that PR has
+been squash-merged and checked. Follow [the release procedure](docs/releasing.md) for
+PyPI Trusted Publisher setup, artifact checks, tagging, and publication verification.
+Do not claim a PyPI release from a successful source build alone.
+
+## Reporting issues
+
+Use the bug report form for a minimal reproduction, version information, and expected
+versus actual behavior. Use the feature request form to explain the use case, proposed
+scope, and relationship to the roadmap.
+
+Never include phone numbers, login codes, API keys or hashes, session files, HTTP tokens,
+or private Telegram conversation dumps in issues, pull requests, logs, or fixtures.
+Use synthetic examples and remove sensitive data from diagnostics before sharing them.

telegram_context_mcp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Egor Fyodorov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

telegram_context_mcp-0.2.0/Makefile

@@ -0,0 +1,6 @@
+.PHONY: check
+check:
+	uv run --locked ruff format --check .
+	uv run --locked ruff check .
+	uv run --locked ty check
+	uv run --locked pytest