Metadata-Version: 2.4
Name: lingtai-telegram
Version: 0.1.0
Summary: LingTai Telegram MCP server — bot API client with LICC inbox callback.
Project-URL: Homepage, https://github.com/Lingtai-AI/lingtai-telegram
Project-URL: Repository, https://github.com/Lingtai-AI/lingtai-telegram
Project-URL: LingTai, https://lingtai.ai
Author-email: Zesen Huang <hzsbazinga@outlook.com>
License: MIT
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# lingtai-telegram

LingTai Telegram MCP server — Bot API client with multi-account support and LICC inbox callback.

This is the canonical setup, configuration, and troubleshooting doc for the `lingtai-telegram` MCP. It is fetched by LingTai agents (or anyone else) when they need to install or configure this server.

> **MCP / LICC contract spec:** see the `lingtai-anatomy` skill, `reference/mcp-protocol.md`, for the canonical specification of the catalog → registry → activation chain, environment-variable injection, and the LICC v1 inbox callback protocol. The reference client implementation is `src/lingtai_telegram/licc.py` in this repo (vendored verbatim into all first-party LingTai MCP repos — copy it if you're writing your own).

## Tools

One omnibus MCP tool: `telegram(action=...)`. Actions: `send`, `check`, `read`, `reply`, `search`, `delete`, `edit`, `contacts`, `add_contact`, `remove_contact`, `accounts`. Compound message IDs: `account_alias:chat_id:message_id`.

## Inbound messages (LICC)

Inbound Telegram updates flow into the host agent's inbox via the LingTai Inbox Callback Contract. Each new message is delivered as a LICC event with:

- `from` — username (or first_name as fallback).
- `subject` — `"telegram message from <user> via <account_alias>"`.
- `body` — a ~300 char preview of the message text (use `telegram(action="check"|"read")` to see the full conversation).
- `metadata.message_id` — compound ID for `reply`/`delete`/`edit`.
- `metadata.account` — which configured bot received it.
- `metadata.chat_id`, `metadata.has_media`, `metadata.has_callback` — routing flags.

## Install

```bash
# Into the LingTai agent's venv (typically ~/.lingtai-tui/runtime/venv/)
pip install git+https://github.com/Lingtai-AI/lingtai-telegram.git
```

After install, `python -m lingtai_telegram` (or the `lingtai-telegram` script) starts the MCP server over stdio.

## Configure

The server reads its bot config from a JSON file pointed at by `LINGTAI_TELEGRAM_CONFIG`. Recommended path: `.secrets/telegram.json` inside the agent's working directory. Plaintext only — this MCP does not support `*_env` indirection.

### Config schema

```json
{
  "accounts": [
    {
      "alias": "myagent",
      "bot_token": "1234567890:ABCdefGhIJklMNOpqRSTuvwxyz",
      "allowed_users": [123456789, 987654321],
      "poll_interval": 1.0
    }
  ]
}
```

- `alias` — human-friendly name for this account; used as the `account` parameter in tool calls.
- `bot_token` — issued by [@BotFather](https://t.me/BotFather). Format: `<bot_id>:<auth_string>`.
- `allowed_users` — optional allow-list of Telegram user IDs (integers). When set, updates from other users are silently ignored. Omit to accept any sender.
- `poll_interval` — seconds between getUpdates long-polls (default 1.0).

### Activation in LingTai

```json
{
  "addons": ["telegram"],
  "mcp": {
    "telegram": {
      "type": "stdio",
      "command": "/path/to/your/python",
      "args": ["-m", "lingtai_telegram"],
      "env": {
        "LINGTAI_TELEGRAM_CONFIG": ".secrets/telegram.json"
      }
    }
  }
}
```

Then run `system(action="refresh")` from the agent. The MCP subprocess starts, the per-account poll threads begin, and the omnibus `telegram` tool becomes available.

## Troubleshooting

- **`LINGTAI_TELEGRAM_CONFIG env var not set`** — your `init.json` `mcp.telegram.env` entry is missing the `LINGTAI_TELEGRAM_CONFIG` key.
- **`Telegram config not found`** — the path resolves but no file exists. Relative paths are resolved against `LINGTAI_AGENT_DIR`.
- **`Unauthorized: invalid token specified`** — wrong or revoked bot token. Re-issue via [@BotFather](https://t.me/BotFather) (`/mybots` → token).
- **Server boots but no inbound messages** — bot privacy mode may be on. In @BotFather: `/setprivacy` → `Disable` (allows the bot to see all messages in groups). Direct messages always work.
- **`MCP server failed to start`** — usually the `command` path in `init.json` doesn't have `lingtai_telegram` installed. Confirm with `<command> -m lingtai_telegram --help` from a shell.
- **Tool calls return `Telegram manager not initialized`** — server boot failed (most often a bad token). Check stderr for the underlying exception, fix the config, then `system(action="refresh")`.

## License

MIT.
