8d1ce4598d
- Telegram integration for customer statistics - MCP server implementation with rate limiting - Cache system for performance optimization - Multi-language support - RESTful API endpoints 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
109 lines
4.3 KiB
Markdown
109 lines
4.3 KiB
Markdown
# Funstat MCP (Go)
|
|
|
|
This project is a complete Go reimplementation of the original Funstat MCP
|
|
server. It exposes the same MCP tools wrapped around the Telegram
|
|
`@openaiw_bot`, but with a native Go runtime and HTTP transport.
|
|
|
|
## Features
|
|
|
|
- Streamable HTTP transport (`/sse` + `/messages`) compatible with MCP clients
|
|
such as Codex CLI, Cursor, and Claude Code.
|
|
- Full parity with the original nine Funstat tools (search, topchat, text,
|
|
human lookup, user info, user messages, balance, menu, start).
|
|
- Built-in rate limiting and response caching to stay within Telegram limits.
|
|
- Telegram session bootstrapping from a Telethon string session or persisted Go
|
|
session storage.
|
|
- Configurable proxy, cache TTL, and rate limit settings via environment
|
|
variables.
|
|
|
|
## Requirements
|
|
|
|
- Go 1.22 or newer (the module was developed with Go 1.24).
|
|
- A valid Telegram API ID and API hash.
|
|
- A logged-in Telegram session. The Go server expects either:
|
|
- `TELEGRAM_SESSION_STRING` (or `TELEGRAM_SESSION_STRING_FILE`) containing a
|
|
Telethon *StringSession*, which will be converted automatically into Go
|
|
session storage, **or**
|
|
- `TELEGRAM_SESSION_PATH` pointing to a Go session file created by this
|
|
service on a previous run (`~/.funstatmcp/session.json` by default).
|
|
- Network access to Telegram (configure proxies via the `FUNSTAT_PROXY_*`
|
|
variables if necessary).
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Description |
|
|
|----------|-------------|
|
|
| `TELEGRAM_API_ID` | **Required.** Telegram API ID. |
|
|
| `TELEGRAM_API_HASH` | **Required.** Telegram API hash. |
|
|
| `TELEGRAM_SESSION_STRING` | Base64 Telethon StringSession (optional if session file already exists). |
|
|
| `TELEGRAM_SESSION_STRING_FILE` | Path to a file containing the StringSession. |
|
|
| `TELEGRAM_SESSION_PATH` | Optional path for Go session storage (`.session` suffix is appended if missing). |
|
|
| `FUNSTAT_BOT_USERNAME` | Bot username (default `@openaiw_bot`). |
|
|
| `FUNSTAT_RATE_LIMIT_PER_SECOND` | Requests per second (default `18`). |
|
|
| `FUNSTAT_RATE_LIMIT_WINDOW` | Duration window, e.g. `1s` (default `1s`). |
|
|
| `FUNSTAT_CACHE_TTL` | Cache lifetime for command responses (default `1h`). |
|
|
| `FUNSTAT_PROXY_TYPE` | Proxy type (`socks5` supported). |
|
|
| `FUNSTAT_PROXY_HOST` | Proxy host. |
|
|
| `FUNSTAT_PROXY_PORT` | Proxy port. |
|
|
| `FUNSTAT_PROXY_USERNAME` / `FUNSTAT_PROXY_PASSWORD` | Optional proxy credentials. |
|
|
| `FUNSTAT_HOST` | Bind host (default `127.0.0.1`). |
|
|
| `FUNSTAT_PORT` | Bind port (default `8091`). |
|
|
| `FUNSTAT_REQUIRE_SESSION` | When `true`, enables strict session ID enforcement (not yet required by the Go transport). |
|
|
|
|
## Running the Server
|
|
|
|
```bash
|
|
export TELEGRAM_API_ID=...
|
|
export TELEGRAM_API_HASH=...
|
|
export TELEGRAM_SESSION_STRING=... # or TELEGRAM_SESSION_STRING_FILE
|
|
|
|
go run ./cmd/funstat-mcp
|
|
```
|
|
|
|
The server starts on `http://127.0.0.1:8091` by default with:
|
|
|
|
- `GET /sse` — server-sent events stream for MCP clients.
|
|
- `POST /messages` — JSON-RPC 2.0 endpoint for MCP requests.
|
|
- `GET /health` — simple health probe.
|
|
|
|
For convenience a helper script is available:
|
|
|
|
```bash
|
|
./scripts/start_server.sh
|
|
```
|
|
|
|
## Tool Coverage
|
|
|
|
The server exposes the following MCP tools (identical to the Python version):
|
|
|
|
| Tool | Description |
|
|
|------|-------------|
|
|
| `funstat_search` | 搜索 Telegram 群组/频道。 |
|
|
| `funstat_topchat` | 获取热门群组列表。 |
|
|
| `funstat_text` | 按文本搜索消息。 |
|
|
| `funstat_human` | 按姓名搜索用户。 |
|
|
| `funstat_user_info` | 查询用户详情。 |
|
|
| `funstat_user_messages` | 抓取用户聊天记录并自动翻页。 |
|
|
| `funstat_balance` | 查询积分余额。 |
|
|
| `funstat_menu` | 显示 Funstat 菜单。 |
|
|
| `funstat_start` | Funstat 欢迎信息。 |
|
|
|
|
## Session Notes
|
|
|
|
- If you already possess the Telethon `.session` SQLite file, generate a
|
|
StringSession first (e.g. via Telethon or `python -m telethon.sessions`)
|
|
and provide it through `TELEGRAM_SESSION_STRING`.
|
|
- After the first successful run the Go server stores an encrypted Go session
|
|
at `~/.funstatmcp/session.json` (unless overridden). Subsequent runs only
|
|
require the API ID/hash.
|
|
|
|
## Development
|
|
|
|
- Format code with `gofmt -w cmd internal`.
|
|
- Run `go test ./...` (no automated tests are included yet).
|
|
- Dependencies are managed via Go modules (`go mod tidy`).
|
|
|
|
## License
|
|
|
|
Follows the license of the original Funstat MCP project (MIT, if applicable).
|