# 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).