Metadata-Version: 2.4
Name: telegram-managed-bot-factory
Version: 0.1.2
Summary: A secure MCP control plane for Telegram Managed Bots
Project-URL: Homepage, https://github.com/laser54/telegram-managed-bot-factory
Project-URL: Source, https://github.com/laser54/telegram-managed-bot-factory
Project-URL: Issues, https://github.com/laser54/telegram-managed-bot-factory/issues
Project-URL: Changelog, https://github.com/laser54/telegram-managed-bot-factory/blob/main/CHANGELOG.md
Project-URL: Security, https://github.com/laser54/telegram-managed-bot-factory/security/policy
Author: laser54
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.11
Requires-Dist: aiogram<4,>=3.30
Requires-Dist: cryptography<51,>=49
Requires-Dist: httpx<1,>=0.28
Requires-Dist: mcp<3,>=2
Requires-Dist: platformdirs<5,>=4.3
Requires-Dist: pydantic<3,>=2.12
Description-Content-Type: text/markdown

# Telegram Managed Bot Factory

[![PyPI version](https://img.shields.io/pypi/v/telegram-managed-bot-factory.svg)](https://pypi.org/project/telegram-managed-bot-factory/)

<!-- mcp-name: io.github.laser54/bot-factory -->

A self-hosted MCP control plane that turns one user-owned Telegram manager bot
into isolated, useful child bots. Ask Hermes for a supported bot, confirm that
specific creation in Telegram, and the persistent Factory worker retrieves and
contains the child credential without exposing it to the model or MCP.

Public alpha `0.1.2` is published on [PyPI](https://pypi.org/project/telegram-managed-bot-factory/0.1.2/).
Each PyPI version is immutable; install the current release below.

## Install

Requires Linux with `systemd --user`, Python 3.11–3.14, [uv](https://docs.astral.sh/uv/),
Hermes 0.18, and a separate Telegram bot with Bot Management Mode enabled.

```bash
uvx --from telegram-managed-bot-factory==0.1.2 bot-factory install-hermes
```

The local installer securely prompts once for the manager credential, enrolls
the owner, installs the persistent user service, registers the six-tool stdio
server with Hermes, and verifies discovery. It creates no child bot.

## How it works

```text
You → Hermes → Factory MCP ──durable request──▶ persistent worker
                  ▲                                │
                  │ safe status                    │ Bot API
                  │                                ▼
                  └──── Telegram confirmation ◀─ manager bot
                                                   │ child credential
                                                   ▼
                                         isolated child runtime
```

Hermes and MCP are the non-secret control plane. The persistent worker alone
polls the manager bot and retrieves credentials. Each child receives only its
own credential and uses instance-local state.

## Useful profiles

| Profile | Use it for |
|---|---|
| `quick_faq` | A public menu of 3–8 local plain-text answers and contact text. |
| `lead_inbox` | A privacy-noticed message form with owner notification and confirmed export/purge. |
| `link_inbox` | Owner-only URLs and notes with `/list` and `/done`; URLs are never fetched. |

`owner_echo` is also included as an owner-only isolation and health smoke test.
Profiles cannot provide arbitrary code, executables, filesystem paths, HTML,
agent tools, or remote fetches.

## 60–90 second demo

After installation, ask Hermes:

> Create a quick FAQ bot named “Studio FAQ” with username `studio_faq_bot`.
> Welcome: “Choose a question.” Add pricing, turnaround, and contact FAQs.

Hermes returns the Telegram creation link. Open it, approve once, then open the
new child and send `/start`, `/faq 1`, and `/health`. If provisioning is still
in progress, ask Hermes for the request status. For the other profiles, submit
one test lead and try owner-only `/export confirm` then `/purge confirm`, or
save a URL in `link_inbox`, inspect `/list`, and use `/done 1`.

## Platform and boundaries

- Supported runtime: Linux with `systemd --user`; Ubuntu and WSL2 are tested.
- Supported clients: Hermes 0.18 legacy stdio and tested MCP `2026-07-28` paths.
- Not supported: Windows/macOS installation, hosted multi-tenancy, arbitrary
  child code, automatic bot-account deletion, or bypassing Telegram approval.
- The manager bot is user-owned and separate from the Hermes gateway bot.
- Every child creation requires Telegram confirmation; this is not “one-click.”
- The Official MCP Registry listing is metadata, not a security certification.

## Security highlights

- Tokens never enter MCP arguments/results, chat, CLI arguments, YAML, SQLite,
  manifests, logs, traces, fixtures, or Git.
- Secret directories are `0700`, files are `0600`, and child credentials travel
  through an inherited anonymous file descriptor rather than argv or environment.
- Child inbound update IDs and offsets are durable. Completed collisions are
  no-ops; a crash-ambiguous side effect is quarantined for reconciliation, not
  silently retried. External effects are not claimed to be exactly once.
- Inputs are bounded and validated; profiles cannot execute or fetch supplied content.

See the [security policy](SECURITY.md) and [architecture](docs/ARCHITECTURE.md)
for the full boundary model.

## Documentation and source

- [Source and issues](https://github.com/laser54/telegram-managed-bot-factory)
- [Specification](docs/SPECIFICATION.md) · [acceptance](docs/ACCEPTANCE.md) ·
  [status](docs/STATUS.md) · [publication evidence](docs/evidence/RELEASE_0.1.0_2026-08-09.md)
- [Changelog](CHANGELOG.md) · [contributing](CONTRIBUTING.md) · [security](SECURITY.md)
- [Telegram Managed Bots](https://core.telegram.org/bots/features#managed-bots) ·
  [Official MCP Registry entry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.laser54%2Fbot-factory)

## Troubleshooting and removal

Check the worker and Hermes registration without sharing unreviewed journal output:

```bash
systemctl --user status bot-factory-manager.service
hermes mcp test bot-factory
```

On WSL2, PID 1 must be `systemd`, and the distribution must remain running.
Uninstalling the service/package does not delete Factory data or revoke Telegram
bots; review local XDG `bot-factory` directories and BotFather controls separately.
