Metadata-Version: 2.4
Name: agentforge-telegram-gateway
Version: 3.1.0
Summary: Telegram bridge and MCP gateway for user-owned AI agents
Author: AgentForge Labs
License: AGPL-3.0-only
Project-URL: Homepage, https://github.com/AgentForge-Labs/shared-telegram-notifier
Project-URL: Repository, https://github.com/AgentForge-Labs/shared-telegram-notifier
Project-URL: Issues, https://github.com/AgentForge-Labs/shared-telegram-notifier/issues
Keywords: telegram,mcp,ai-agents,chatgpt,claude,codex,qwen
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Provides-Extra: dev
Requires-Dist: build>=1; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# AgentForge Telegram Gateway

Connect user-owned AI agents to people through Telegram for notifications, conversations and file exchange.

**Community Edition · MVP/Beta · GNU AGPL v3 (`AGPL-3.0-only`)**

[Quickstart](#quickstart) · [Features](#features) · [MCP](#mcp-access) · [Security](#security) · [Architecture](docs/ARCHITECTURE.md) · [Contributing](CONTRIBUTING.md)

AgentForge Telegram Gateway is for developers and operators who want a small, self-hosted bridge between Telegram and local or remote AI-agent workflows. Pair a Telegram chat once, provision a source-scoped agent identity, then exchange text, documents and photos without putting a Telegram chat ID or bot token into agent prompts.

It works with MCP-capable clients and agent workflows such as ChatGPT, Codex, Claude and Qwen. The gateway is provider-independent: provider-account authentication remains with the provider's own tooling.

## Quickstart

### 1. Install

```bash
git clone https://github.com/AgentForge-Labs/shared-telegram-notifier.git
cd shared-telegram-notifier
python3 -m venv .venv
. .venv/bin/activate
python -m pip install .
```

This installs four commands:

```text
agentforge-telegram          inbox, reply, file and notification CLI
agentforge-telegram-mcp      MCP diagnostics and tool access
agentforge-telegram-admin    bot setup, source provisioning and pairing
agentforge-telegram-gateway  gateway server
```

### 2. Create a Telegram bot

Create a bot with Telegram's `@BotFather`, then store the token through the protected setup flow:

```bash
sudo agentforge-telegram-admin telegram-setup
sudo agentforge-telegram-admin telegram-doctor
```

The bot token is entered through a hidden prompt and stored outside the repository. Do not commit bot tokens, chat IDs or generated source credentials.

### 3. Provision and pair an agent source

```bash
sudo agentforge-telegram-admin provision my-agent \
  --output /var/lib/my-agent/telegram-gateway-key \
  --owner my-agent:my-agent

sudo agentforge-telegram-admin pair my-agent
```

Open the generated Telegram deep link. The pairing flow learns the authorized Telegram identity from Telegram itself; users do not need to copy a numeric chat ID.

### 4. Run the gateway

A hardened systemd unit is included at [`deploy/telegram-notifier.service`](deploy/telegram-notifier.service). After installing the service and configuration paths for your host:

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now telegram-notifier
curl http://127.0.0.1:8818/health
```

The gateway defaults to loopback. Put a TLS reverse proxy in front of it if an MCP client must connect remotely.

## Features

- one-time Telegram pairing links — no manual chat-ID discovery;
- bidirectional text messages;
- inbound and outbound documents/photos;
- per-source `receive`, `send` and `files` permissions;
- multiple agent sources with isolated credentials and bindings;
- Telegram commands such as `/agents`, `/use`, `/status` and `/help`;
- REST/agent CLI for inbox, replies, files and proactive notifications;
- Streamable HTTP-style MCP endpoint;
- Bearer authentication for header-capable MCP clients;
- URL-secret mode for clients that cannot send custom authorization headers;
- OAuth 2.1 Authorization Code + PKCE for OAuth-capable MCP clients;
- source-scoped authorization so one agent credential cannot impersonate another source;
- loopback-first deployment and protected file-based secrets.

## MCP access

The MCP gateway exposes the Telegram bridge to MCP-capable clients while preserving source isolation.

### Bearer

Use the normal MCP endpoint with the source credential:

```text
POST https://telegram.example.com/mcp
Authorization: Bearer <source-secret>
```

### URL secret

For clients that cannot attach an authorization header:

```text
https://telegram.example.com/client/<source-secret>/mcp
```

Treat that URL as a credential. Configure reverse-proxy access logs so the secret-bearing path is never recorded verbatim.

### OAuth + PKCE

OAuth-capable MCP clients can use the gateway's protected-resource and authorization-server discovery endpoints with Authorization Code + PKCE S256. Configure OAuth with protected secret files; do not place client secrets directly in committed service files.

See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the authentication and trust boundaries.

## Generate an MCP connection file

The admin CLI can write a protected client configuration without printing the source secret to standard output:

```bash
sudo agentforge-telegram-admin mcp-config my-agent \
  --provider qwen \
  --base-url https://telegram.example.com \
  --key-file /var/lib/my-agent/telegram-gateway-key \
  --output /var/lib/my-agent/telegram-mcp.json \
  --owner my-agent:my-agent
```

Use the provider value that matches the client you are configuring. Generated connection files are credentials and should remain outside the repository.

## Agent CLI examples

Check the authenticated inbox:

```bash
agentforge-telegram --help
```

The CLI supports receiving events, replying, retrieving inbound files and sending notifications. Run `--help` for the current command surface rather than copying credentials into shell history.

### Python SDKs

The REST client is importable directly after installing the PyPI package:

```python
from agent_client import TelegramAgentClient

client = TelegramAgentClient.from_key_file(
    "my-agent", "/var/lib/my-agent/telegram-gateway-key"
)
events = client.inbox(limit=10)
```

For MCP transport diagnostics and arbitrary tool calls, use
`mcp_client.TelegramMcpClient` or the matching CLI command:

```bash
agentforge-telegram-mcp --base-url https://telegram.example.com \
  --auth bearer --key-file /var/lib/my-agent/telegram-gateway-key call \
  telegram_inbox --arguments '{"limit":10}'
```

## Security

The project is designed around a simple rule: **Telegram identity, gateway identity and model-provider identity are separate trust boundaries.**

Key defaults and protections include:

- gateway TCP bind defaults to `127.0.0.1:8818`;
- the bot token lives in a protected file outside the repository;
- source credentials are generated per agent/source;
- persistent registries store credential digests rather than plaintext source keys;
- pairing codes are short-lived and one-use;
- OAuth uses exact redirect-URI matching and PKCE S256;
- OAuth authorization/access/refresh state is stored as digests where applicable;
- URL-secret application logs are redacted;
- audit metadata excludes message text, file contents and raw credentials;
- group chats are disabled by default.

Example configuration lives in [`.env.example`](.env.example) and contains placeholders/file paths only. Never commit a real bot token, numeric personal chat/user identifier, real conversation fixture, private webhook URL or generated agent credential.

For trust boundaries and protocol flow, see [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). For vulnerability reporting, see [`SECURITY.md`](SECURITY.md).

## Deployment notes

The included systemd unit is a reference for Linux hosts. Review service user/group ownership and paths before enabling it on your system. Remote MCP access should use HTTPS at the reverse proxy; do not expose the loopback HTTP listener directly to the public internet.

Useful diagnostics:

```bash
agentforge-telegram-admin telegram-doctor
agentforge-telegram-mcp --help
agentforge-telegram-gateway --check
```

## What this project is — and is not

This repository is the focused Telegram communication bridge. It does not contain the AgentForge cloud control plane, private AgentScope backend, enterprise infrastructure orchestration or production credentials.

For broader AgentForge projects and public releases, visit [AgentForge Labs on GitHub](https://github.com/AgentForge-Labs).

Within the AgentForge product family:

- **AgentScope** is the natural next step when you need observability and operations around agent runs;
- **AgentForge Runtime** is the commercial expansion when you need controlled infrastructure access and enterprise runtime capabilities.

No private repository is required to use this Community Edition.

## Contributing

See [`CONTRIBUTING.md`](CONTRIBUTING.md). Please keep examples synthetic and never include real Telegram credentials, personal chat/user IDs or customer messages in issues, fixtures or pull requests.

## License

AgentForge Telegram Gateway Community Edition is licensed under the **GNU Affero General Public License v3.0 only** (`AGPL-3.0-only`). See [`LICENSE`](LICENSE).

## Maintainers

Maintained by [AgentForge Labs](https://github.com/AgentForge-Labs).

## Commercial web application

The private commercial repository includes a separate Next.js marketing and checkout app in `web/`.

```bash
cd web
npm ci
npm run validate
npm run dev
```

Payment credentials and provider product/variant IDs are documented in `web/.env.example`. They are server-side only.
