Astral Bridge

Astral Bridge connects QQ, through NapCat's OneBot v11 reverse WebSocket, and optionally Telegram, through the Telegram Bot API, to one fixed Astral Code app-server session. It also exposes MCP tools so the agent can reply back to chat platforms, send files, mention people, recall/delete messages, and fetch recent conversation context when needed.

This project is intended for self-hosted personal or team automation. It is not affiliated with QQ, Tencent, NapCat, OneBot, Telegram, or Astral Code.

Features

• Receive QQ private and group messages from NapCat over OneBot v11.

• Receive Telegram private, group, supergroup, and channel-post messages through long polling.

• Route every accepted message into one configured Astral app-server thread.

• Trigger group messages only when the bot is mentioned, replied to, or the chat is configured as always-trigger.

• Trigger every message from configured private QQ or Telegram users/chats.

• Store allowed conversation history locally in SQLite for later MCP lookups.

• Include compact inbound context: platform, chat/group name/id, sender id, nickname, username/card, message id, reply id, trigger kind, unread count, and attachment metadata.

• Support app-server turn/steer when the fixed Astral thread already has an active turn.

• Expose Streamable HTTP or stdio MCP tools for QQ and Telegram replies, history, media, files, mentions, and replies to specific message ids.

• Accept generic external event webhooks and forward them into the fixed Astral session.

• Expose a read-only Web UI for connection status, routing, recent messages, recent conversations, and recent bridge logs.

• Add a random 3-5 second delay before outbound QQ send actions.

Related MCP server: @chatmaid/mcp

Requirements

• Node.js 26 or newer. The bridge uses node:sqlite.

• pnpm 10 or newer.

• A running Astral Code app-server.

• NapCat configured with OneBot v11 reverse WebSocket.

• Optional: a Telegram bot token from BotFather if Telegram support is enabled.

Quick Start

pnpm install
cp examples/config.example.json config.json
pnpm dev -- --config ./config.json

Build for production:

pnpm build
pnpm start -- --config ./config.json

Point NapCat's OneBot v11 reverse WebSocket to:

ws://127.0.0.1:6701/onebot/v11/ws

If the bridge is running in Docker or on another host, replace the host and port with the address reachable from NapCat, for example:

ws://bridge:6701/onebot/v11/ws

Configuration

Start from examples/config.example.json:

{
  "onebot": {
    "host": "127.0.0.1",
    "port": 6701,
    "path": "/onebot/v11/ws",
    "accessToken": null,
    "actionTimeoutMs": 10000
  },
  "mcp": {
    "transport": "stdio",
    "host": "127.0.0.1",
    "port": 6710,
    "path": "/mcp"
  },
  "astral": {
    "appServerUrl": "ws://127.0.0.1:4222",
    "authToken": null,
    "threadId": "REPLACE_WITH_FIXED_ASTRAL_THREAD_ID",
    "cwd": null,
    "modelProvider": null,
    "model": null,
    "includeImageInputs": false
  },
  "qq": {
    "botUserId": "REPLACE_WITH_BOT_QQ",
    "allowedGroupIds": ["REPLACE_GROUP_ID"],
    "alwaysTriggerGroupIds": [],
    "allowedPrivateUserIds": ["REPLACE_USER_ID"],
    "triggerKeywords": ["astral", "bot"],
    "recordUntriggered": true
  },
  "telegram": {
    "enabled": false,
    "botToken": "REPLACE_WITH_TELEGRAM_BOT_TOKEN",
    "botUsername": "REPLACE_WITH_TELEGRAM_BOT_USERNAME",
    "allowedChatIds": ["REPLACE_TELEGRAM_CHAT_ID"],
    "alwaysTriggerChatIds": [],
    "triggerKeywords": ["astral", "bot"],
    "recordUntriggered": true,
    "pollTimeoutSeconds": 25,
    "pollIntervalMs": 1000,
    "apiBaseUrl": "https://api.telegram.org"
  },
  "tts": {
    "enabled": false,
    "apiKey": "REPLACE_WITH_TTS_API_KEY",
    "baseUrl": "https://api.xiaomimimo.com/v1",
    "model": "mimo-v2.5-tts",
    "voice": "mimo_default",
    "format": "wav",
    "timeoutMs": 60000
  },
  "externalEvents": {
    "enabled": true,
    "path": "/api/events",
    "authToken": "REPLACE_WITH_EVENT_API_TOKEN",
    "maxBodyBytes": 65536,
    "debounceMs": 2000,
    "maxBatchEvents": 20,
    "maxBatchBodyChars": 6000
  },
  "storage": {
    "dbPath": "./data/astral-bridge.db",
    "mediaDir": "./media",
    "downloadMedia": false
  }
}

Environment overrides:

recordUntriggered controls whether non-triggering messages from allowed conversations are stored. Keeping it enabled lets the agent fetch surrounding context without forwarding every group message into Astral.

Telegram uses long polling. On startup the bridge calls deleteWebhook so Telegram will allow getUpdates. Send /chatid to the bot in a private chat, group, supergroup, or topic to get the exact chat_id; this command works even before the chat is allowlisted. All other Telegram interaction requires the chat id to be present in telegram.allowedChatIds or telegram.alwaysTriggerChatIds.

Web UI

When HTTP MCP is enabled, open:

GET /ui

The dashboard polls GET /api/dashboard/state and shows NapCat/Astral connection status, the active Astral turn id when one is running, configured routing, external event API status, recent conversations, recent stored messages, and recent bridge logs.

Astral MCP Setup

For stdio MCP, build first and point Astral at the compiled entrypoint:

[mcp_servers.qq]
command = "node"
args = ["/path/to/astral-bridge/dist/index.js", "--config", "/path/to/astral-bridge/config.json"]

[mcp_servers.telegram]
command = "node"
args = ["/path/to/astral-bridge/dist/index.js", "--config", "/path/to/astral-bridge/config.json"]

Use node directly instead of a package-manager wrapper. stdio MCP requires stdout to contain only JSON-RPC messages.

For container or multi-process deployments, run HTTP MCP:

{
  "mcp": {
    "transport": "http",
    "host": "0.0.0.0",
    "port": 6710,
    "path": "/mcp"
  }
}

Then configure Astral:

[mcp_servers.qq]
url = "http://bridge:6710/mcp"

[mcp_servers.telegram]
url = "http://bridge:6710/mcp"

The bridge exposes both QQ and Telegram tools from the same MCP endpoint. Registering the endpoint under both qq and telegram gives the agent natural tool names such as mcp__qq__qq_send_group_message and mcp__telegram__telegram_send_message.

MCP Tools

Group Administration

Group administration tools are grouped to keep the MCP tool list small. Call qq_group_admin_help to discover action names and required fields. Disbanding groups is intentionally not implemented; leave_group only makes the bot leave the group.

All group-specific administration tools reject group_id values outside qq.allowedGroupIds when that allowlist is configured. Actions that mutate group state require confirm: true; use that only after the user explicitly asks for the operation.

Mentions, Images, and Replies

Use parts when a group message needs exact ordering of text, mentions, and images:

[
  { "type": "text", "text": "请 " },
  { "type": "at", "user_id": "TARGET_QQ" },
  { "type": "text", "text": " 看一下 " },
  { "type": "image", "file": "/workspace/result.png" }
]

Reply to a specific QQ message by passing reply_to_message_id with the OneBot message_id from the inbound prompt or one of the history tools.

Images in outbound messages use OneBot image segments. Non-image files use NapCat-compatible upload_group_file and upload_private_file actions.

Telegram text messages use ordered parts for mentions:

[
  { "type": "text", "text": "请 " },
  { "type": "mention", "username": "alice" },
  { "type": "text", "text": " 看一下；也同步给 " },
  { "type": "mention", "user_id": "123456789", "text": "Bob" }
]

Use telegram_send_rich_message when a Telegram reply needs structured formatting such as headings, lists, tables, collapsible details, code blocks, or formulas. Pass exactly one of html or markdown:

{
  "chat_id": "-1001234567890",
  "html": "<h2>Summary</h2><ul><li>Done</li><li>Next step</li></ul>",
  "reply_to_message_id": "123",
  "message_thread_id": "456"
}

For Telegram files, call telegram_send_file for images and non-images alike. This sends through Telegram sendDocument, preserving the original file quality. Telegram rich message media blocks are intended for HTTP/HTTPS URLs; local /workspace and /app/media files should still be sent with telegram_send_file:

{
  "chat_id": "-1001234567890",
  "file": "/workspace/result.png",
  "caption": "结果图",
  "reply_to_message_id": "123",
  "message_thread_id": "456"
}

Message Routing

The bridge only forwards messages from configured QQ targets or Telegram chat ids:

• Group messages: forwarded when the bot is at-mentioned or the message replies to a bot message.

• Keyword messages: in any allowed QQ/Telegram group or private chat, messages containing any configured trigger keyword are forwarded. Keyword matching is case-insensitive.

• Always-trigger group messages: for group ids in qq.alwaysTriggerGroupIds, every non-bot message is forwarded, even without an @mention or reply.

• Private messages: forwarded for every message from configured private users.

• Other allowed conversation messages: optionally stored when recordUntriggered is true, but not forwarded to Astral.

• Telegram /chatid: always answered directly so you can discover the current Telegram chat.id before editing the allowlist.

• Telegram group/supergroup/channel messages: forwarded when the bot is mentioned, the message replies to a bot message, or the chat id is in telegram.alwaysTriggerChatIds.

• Telegram private messages: forwarded for every message from configured private chat ids.

• /stop: in any allowed QQ/Telegram group or private chat, interrupts the active Astral turn and replies in the same conversation.

Every forwarded turn includes a conversation_unread section. unread_count is the number of stored messages in the same group/private conversation since the previous Astral prompt, including the current trigger message. The agent can call qq_get_unread_messages or telegram_get_unread_messages when that context is useful; it does not need to call it for every message.

External Event API

When HTTP MCP is enabled, the same HTTP server can accept generic external events:

GET /api/events/schema

Returns a machine-readable OpenAPI 3.1 schema with examples and curl usage.

POST /api/events
Authorization: Bearer REPLACE_WITH_EVENT_API_TOKEN
Content-Type: application/json

{
  "source": "minecraft:survival-main",
  "event_type": "player_join",
  "title": "Player joined",
  "body": "Steve joined the server",
  "actor": { "id": "uuid", "name": "Steve" },
  "metadata": { "world": "world", "x": 120, "y": 64, "z": -33 }
}

The bridge queues attention-worthy events, merges short bursts into one bounded Astral turn, and submits that merged event to the fixed Astral thread using the same queue as QQ messages. Set wants_agent_attention to false to validate and accept an event without forwarding it into Astral. Batching is controlled by externalEvents.debounceMs, externalEvents.maxBatchEvents, and externalEvents.maxBatchBodyChars.

Request fields:

Successful requests return 202 Accepted with { ok, accepted_for_astral, event }. Unauthorized requests return 401 when externalEvents.authToken is configured.

Astral App-Server Behavior

The bridge talks to Astral app-server over WebSocket and uses:

• initialize

• thread/resume

• turn/start

• turn/steer when the fixed thread already has an active turn

When starting a turn, the bridge requests approvalPolicy = "never" and sandboxPolicy = { type = "dangerFullAccess" }. If you use this mode, isolate Astral at the container, VM, or host level and only mount directories you are willing to expose.

Server approval requests for command execution and file changes are canceled by default. QQ sending should happen through the MCP tools and Astral MCP tool approval settings, not through the bridge approving arbitrary app-server actions.

Docker and OrbStack

The generic bridge image is defined by Dockerfile.

OrbStack deployment templates live under deploy/orbstack. They include:

• bridge: OneBot reverse WebSocket plus Streamable HTTP MCP.

• astral-code: an Ubuntu-based Astral app-server runtime with mapped config, binary, source, workspace, and build cache directories.

• napcat: NapCat Docker service.

Copy deploy/orbstack/.env.example to .env, fill in your local values, and read the Chinese deployment guide at deploy/orbstack/README.md before running the compose stack. It covers required QQ/Telegram/Astral settings, persistent volumes, memory storage, and the memory phase2 sandbox option.

Security Notes

• Do not commit real QQ ids, app-server tokens, API keys, NapCat WebUI tokens, SQLite databases, downloaded media, or local config files.

• Bind services to loopback unless you intentionally need LAN access.

• The app-server danger-full-access mode is powerful. Use a dedicated container or host account and mount only the workspace/config directories needed by the agent.

• Review allowed groups and private users before exposing the bot to busy chats.

Development

pnpm install
pnpm typecheck
pnpm build

Project layout:

src/                 Bridge source
examples/            Example JSON config
deploy/orbstack/     Self-hosted OrbStack deployment template
data/                Runtime SQLite state, ignored by git
media/               Runtime media cache, ignored by git

License

Licensed under the Apache License, Version 2.0. See LICENSE.