aiogram-mcp 0.1.0__tar.gz

aiogram_mcp-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Report a defect or regression
+title: "[Bug] "
+labels: bug
+assignees: ""
+---
+
+## Summary
+
+Describe the bug clearly.
+
+## Environment
+
+- Python version:
+- aiogram version:
+- aiogram-mcp version:
+- MCP client:
+
+## Reproduction
+
+1. 
+2. 
+3. 
+
+## Expected behavior
+
+What should have happened?
+
+## Actual behavior
+
+What happened instead?
+
+## Logs or traceback
+
+```text
+paste logs here
+```

aiogram_mcp-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

aiogram_mcp-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature request
+about: Suggest a capability or API improvement
+title: "[Feature] "
+labels: enhancement
+assignees: ""
+---
+
+## Problem
+
+What user or developer problem does this solve?
+
+## Proposed solution
+
+Describe the API or behavior you want.
+
+## Alternatives considered
+
+List any alternatives or workarounds.
+
+## Additional context
+
+Anything else maintainers should know.

aiogram_mcp-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,12 @@
+## Summary
+
+Describe the change.
+
+## Checklist
+
+- [ ] I ran `ruff check aiogram_mcp tests examples`
+- [ ] I ran `mypy aiogram_mcp`
+- [ ] I ran `pytest -v`
+- [ ] I updated tests if behavior changed
+- [ ] I updated docs or examples if public behavior changed
+- [ ] I updated `CHANGELOG.md` for user-visible changes

aiogram_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install dependencies
+        run: uv pip install -e ".[dev]" --system
+
+      - name: Lint with ruff
+        run: ruff check aiogram_mcp tests examples
+
+      - name: Type check with mypy
+        run: mypy aiogram_mcp
+
+      - name: Run tests
+        run: pytest -v --tb=short

aiogram_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade build
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

aiogram_mcp-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/

aiogram_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0
+
+- Initial public package structure.
+- Added MCP server core, middleware, tool registry, tests, and examples.
+- Added GitHub workflows, issue templates, PR template, and release docs.
+- Replaced the private-domain example with a generic incident alerting example.

aiogram_mcp-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,23 @@
+# Code of Conduct
+
+## Our Standard
+
+This project expects respectful, direct, and professional collaboration.
+
+Examples of acceptable behavior:
+
+- giving constructive technical feedback
+- assuming good intent
+- keeping discussions focused on the code and product
+
+Examples of unacceptable behavior:
+
+- personal attacks
+- harassment
+- discriminatory language or behavior
+- publishing private information without consent
+
+## Enforcement
+
+Project maintainers may remove comments, issues, pull requests, or contributors
+that violate this code of conduct.

aiogram_mcp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing
+
+Thanks for contributing to `aiogram-mcp`.
+
+## Development Setup
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+On Windows PowerShell:
+
+```powershell
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+pip install -e ".[dev]"
+```
+
+## Local Checks
+
+Run these before opening a pull request:
+
+```bash
+ruff check aiogram_mcp tests examples
+mypy aiogram_mcp
+pytest -v
+```
+
+## Pull Request Guidelines
+
+- Keep PRs focused.
+- Add or update tests when behavior changes.
+- Update `README.md` when public APIs or examples change.
+- Update `CHANGELOG.md` for user-visible changes.
+
+## Release Expectations
+
+- Public API changes should be documented.
+- New MCP tools must have basic tests and safety notes.
+- Examples should be generic and safe to publish.

aiogram_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Py2755
+
+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.

aiogram_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: aiogram-mcp
+Version: 0.1.0
+Summary: MCP server middleware for aiogram Telegram bots — expose your bot to AI agents via the Model Context Protocol
+Project-URL: Homepage, https://github.com/Py2755/aiogram-mcp
+Project-URL: Repository, https://github.com/Py2755/aiogram-mcp
+Project-URL: Issues, https://github.com/Py2755/aiogram-mcp/issues
+Project-URL: Changelog, https://github.com/Py2755/aiogram-mcp/blob/main/CHANGELOG.md
+Author: Py2755
+License: MIT
+License-File: LICENSE
+Keywords: ai,aiogram,anthropic,bot,claude,mcp,model-context-protocol,telegram
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: aiogram>=3.20.0
+Requires-Dist: fastmcp>=2.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# aiogram-mcp
+
+[![CI](https://github.com/Py2755/aiogram-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Py2755/aiogram-mcp/actions/workflows/ci.yml)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![PyPI version](https://img.shields.io/pypi/v/aiogram-mcp.svg)](https://pypi.org/project/aiogram-mcp/)
+
+MCP server middleware for aiogram Telegram bots.
+
+`aiogram-mcp` lets you expose an existing [aiogram](https://github.com/aiogram/aiogram) bot to [MCP](https://modelcontextprotocol.io/) clients such as Claude Desktop without rewriting handlers, routers, or business logic.
+
+## Status
+
+**Beta** — the core API is stable but may change before 1.0.
+
+## Installation
+
+```bash
+pip install aiogram-mcp
+```
+
+Requirements:
+
+- Python 3.10+
+- aiogram 3.20+
+
+## Quickstart
+
+```python
+from aiogram import Bot, Dispatcher
+from aiogram_mcp import AiogramMCP
+
+bot = Bot(token="YOUR_BOT_TOKEN")
+dp = Dispatcher()
+
+# Register your normal handlers here.
+
+mcp = AiogramMCP(bot=bot, dp=dp)
+await mcp.run_alongside_bot(transport="stdio")
+```
+
+Available transports:
+
+- `stdio` for Claude Desktop and local MCP clients
+- `sse` for remote HTTP-based MCP connections
+
+## Built-in Tools
+
+Messaging:
+
+- `send_message`
+- `send_photo`
+- `forward_message`
+- `delete_message`
+- `pin_message`
+
+Users:
+
+- `get_bot_info`
+- `get_chat_member_info`
+- `get_user_profile_photos`
+
+Chats:
+
+- `get_chat_info`
+- `get_chat_members_count`
+- `ban_user`
+- `unban_user`
+- `set_chat_title`
+- `set_chat_description`
+
+Broadcast:
+
+- `broadcast` when `enable_broadcast=True`
+
+## Safety Controls
+
+```python
+mcp = AiogramMCP(
+    bot=bot,
+    dp=dp,
+    name="my-bot",
+    allowed_chat_ids=[123456789, -1001234567890],
+    enable_broadcast=True,
+    max_broadcast_recipients=500,
+)
+```
+
+Use `MCPMiddleware` to track recent chats and build recipient lists:
+
+```python
+from aiogram_mcp import AiogramMCP, MCPMiddleware
+
+tracker = MCPMiddleware()
+dp.message.middleware(tracker)
+
+mcp = AiogramMCP(bot=bot, dp=dp, enable_broadcast=True)
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check aiogram_mcp tests examples
+mypy aiogram_mcp
+pytest -v
+```
+
+Project layout:
+
+- `aiogram_mcp/` package source
+- `tests/` unit tests
+- `examples/` runnable usage examples
+- `.github/workflows/ci.yml` GitHub Actions pipeline
+
+## Examples
+
+- [basic_bot.py](examples/basic_bot.py)
+- [incident_alert_bot.py](examples/incident_alert_bot.py)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

aiogram_mcp-0.1.0/README.md

@@ -0,0 +1,123 @@
+# aiogram-mcp
+
+[![CI](https://github.com/Py2755/aiogram-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Py2755/aiogram-mcp/actions/workflows/ci.yml)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![PyPI version](https://img.shields.io/pypi/v/aiogram-mcp.svg)](https://pypi.org/project/aiogram-mcp/)
+
+MCP server middleware for aiogram Telegram bots.
+
+`aiogram-mcp` lets you expose an existing [aiogram](https://github.com/aiogram/aiogram) bot to [MCP](https://modelcontextprotocol.io/) clients such as Claude Desktop without rewriting handlers, routers, or business logic.
+
+## Status
+
+**Beta** — the core API is stable but may change before 1.0.
+
+## Installation
+
+```bash
+pip install aiogram-mcp
+```
+
+Requirements:
+
+- Python 3.10+
+- aiogram 3.20+
+
+## Quickstart
+
+```python
+from aiogram import Bot, Dispatcher
+from aiogram_mcp import AiogramMCP
+
+bot = Bot(token="YOUR_BOT_TOKEN")
+dp = Dispatcher()
+
+# Register your normal handlers here.
+
+mcp = AiogramMCP(bot=bot, dp=dp)
+await mcp.run_alongside_bot(transport="stdio")
+```
+
+Available transports:
+
+- `stdio` for Claude Desktop and local MCP clients
+- `sse` for remote HTTP-based MCP connections
+
+## Built-in Tools
+
+Messaging:
+
+- `send_message`
+- `send_photo`
+- `forward_message`
+- `delete_message`
+- `pin_message`
+
+Users:
+
+- `get_bot_info`
+- `get_chat_member_info`
+- `get_user_profile_photos`
+
+Chats:
+
+- `get_chat_info`
+- `get_chat_members_count`
+- `ban_user`
+- `unban_user`
+- `set_chat_title`
+- `set_chat_description`
+
+Broadcast:
+
+- `broadcast` when `enable_broadcast=True`
+
+## Safety Controls
+
+```python
+mcp = AiogramMCP(
+    bot=bot,
+    dp=dp,
+    name="my-bot",
+    allowed_chat_ids=[123456789, -1001234567890],
+    enable_broadcast=True,
+    max_broadcast_recipients=500,
+)
+```
+
+Use `MCPMiddleware` to track recent chats and build recipient lists:
+
+```python
+from aiogram_mcp import AiogramMCP, MCPMiddleware
+
+tracker = MCPMiddleware()
+dp.message.middleware(tracker)
+
+mcp = AiogramMCP(bot=bot, dp=dp, enable_broadcast=True)
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check aiogram_mcp tests examples
+mypy aiogram_mcp
+pytest -v
+```
+
+Project layout:
+
+- `aiogram_mcp/` package source
+- `tests/` unit tests
+- `examples/` runnable usage examples
+- `.github/workflows/ci.yml` GitHub Actions pipeline
+
+## Examples
+
+- [basic_bot.py](examples/basic_bot.py)
+- [incident_alert_bot.py](examples/incident_alert_bot.py)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

aiogram_mcp-0.1.0/RELEASE.md

@@ -0,0 +1,40 @@
+# Release Process
+
+## Before Tagging
+
+1. Update `CHANGELOG.md`.
+2. Run:
+
+```bash
+ruff check aiogram_mcp tests examples
+mypy aiogram_mcp
+pytest -v
+```
+
+3. Verify at least one real bot can start with:
+
+```bash
+python examples/basic_bot.py
+```
+
+4. Verify one MCP client can connect over the intended transport.
+5. Confirm package metadata and README are current.
+
+## Create a Release
+
+1. Bump the version in `pyproject.toml`.
+2. Commit the release changes.
+3. Create and push a tag:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+4. Confirm GitHub Actions completed successfully.
+5. Publish GitHub release notes from the changelog.
+
+## After Release
+
+1. Smoke test the published package in a clean virtual environment.
+2. Open a follow-up issue for anything deferred from the release.

aiogram_mcp-0.1.0/SECURITY.md

@@ -0,0 +1,17 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Do not open a public GitHub issue for security-sensitive problems.
+
+Instead:
+
+1. Report via [GitHub Security Advisories](https://github.com/Py2755/aiogram-mcp/security/advisories/new).
+2. Include a clear reproduction or proof of concept.
+3. Include impact, affected versions, and suggested mitigations if known.
+
+We will respond within 7 days of your report.
+
+## Supported Versions
+
+Security fixes are expected for the latest release line only until the project has multiple maintained versions.

aiogram_mcp-0.1.0/aiogram_mcp/__init__.py

@@ -0,0 +1,16 @@
+"""Public package exports for aiogram-mcp."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .context import BotContext
+from .middleware import MCPMiddleware
+from .server import AiogramMCP
+
+try:
+    __version__ = version("aiogram-mcp")
+except PackageNotFoundError:
+    __version__ = "0.1.0"
+
+__all__ = ["AiogramMCP", "BotContext", "MCPMiddleware", "__version__"]

aiogram_mcp-0.1.0/aiogram_mcp/context.py

@@ -0,0 +1,22 @@
+"""Shared runtime context for MCP tools."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from aiogram import Bot, Dispatcher
+
+
+@dataclass(slots=True)
+class BotContext:
+    """Dependencies shared by all tool handlers."""
+
+    bot: Bot
+    dp: Dispatcher
+    allowed_chat_ids: list[int] | None = None
+
+    def is_chat_allowed(self, chat_id: int) -> bool:
+        """Return whether the MCP server may act on a chat."""
+        if self.allowed_chat_ids is None:
+            return True
+        return chat_id in self.allowed_chat_ids

aiogram_mcp-0.1.0/aiogram_mcp/middleware.py

@@ -0,0 +1,33 @@
+"""Middleware utilities exposed by the package."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from aiogram import BaseMiddleware
+from aiogram.types import TelegramObject
+
+
+class MCPMiddleware(BaseMiddleware):
+    """Track active chats and users for later MCP-driven broadcasts."""
+
+    def __init__(self) -> None:
+        self.active_chat_ids: set[int] = set()
+        self.active_user_ids: set[int] = set()
+
+    async def __call__(
+        self,
+        handler: Callable[[TelegramObject, dict[str, Any]], Awaitable[Any]],
+        event: TelegramObject,
+        data: dict[str, Any],
+    ) -> Any:
+        chat = getattr(event, "chat", None)
+        if chat is not None and getattr(chat, "id", None) is not None:
+            self.active_chat_ids.add(chat.id)
+
+        user = getattr(event, "from_user", None)
+        if user is not None and getattr(user, "id", None) is not None:
+            self.active_user_ids.add(user.id)
+
+        return await handler(event, data)

aiogram_mcp-0.1.0/aiogram_mcp/py.typed

@@ -0,0 +1 @@
+