AstrBot MCP (Node/TypeScript)

MCP server for operating AstrBot through:

• AstrBot REST Gateway (astrbot_plugin_mcp_tools) at http://127.0.0.1:6324

This project is a full rewrite in Node + TypeScript.

Install

npm install
npm run build

Run

node dist/src/index.js

or in development:

npm run dev

MCP config example

{
  "mcpServers": {
    "astrbot-mcp": {
      "command": "node",
      "args": ["D:/绋嬪簭/astrbotmcp/dist/src/index.js"],
      "env": {
        "ASTRBOT_GATEWAY_URL": "http://127.0.0.1:6324",
        "ASTRBOT_GATEWAY_TOKEN": "iaushdqwuikdwq78ui"
      }
    }
  }
}

Environment variables

Required:

• ASTRBOT_GATEWAY_TOKEN

Optional:

• ASTRBOT_GATEWAY_URL (default: http://127.0.0.1:6324)

• ASTRBOT_GATEWAY_TIMEOUT (default: 30000, milliseconds)

• ASTRBOT_CAPABILITY_MODE (search | readonly | minimize | full, default: full)

• ASTRBOT_ENABLE_SEARCH_TOOLS (false by default)

• ASTRBOT_LOG_VIEW (compact by default, or raw)

• ASTRBOT_ENABLE_LOG_NOISE_FILTERING (true by default)

• ASTRBOT_GITHUB_ACCELERATION (optional GitHub acceleration base URL override for plugin repo install/update; use off to disable MCP auto acceleration)

Tool groups

• system: status, compact logs, logs by id, restart

• platforms: list, stats, details

• providers: list, current, details

• configs: inspect core/plugin, search, patch core/plugin

• plugins: list/details/config read+replace/install/set-enabled/reload/update/uninstall

• messages: trigger replies, recent sessions, history

• astrbot_tools: list/details/invoke/task/stream

• mcp_servers: list/register/update/uninstall/test

• personas: list/details/upsert/delete

• skills: list/install/toggle/delete

• subagents: list/config inspect/config update

• cron: list/upsert/delete

• discovery: search_tools (only when ASTRBOT_ENABLE_SEARCH_TOOLS=true)

Safety defaults

• capabilityMode=full by default (as requested)

• search_tools is disabled by default

• logs return compact/noise-filtered output by default

• restart and logs use the gateway only; no separate dashboard auth is required

Scripts

• npm run check - type check

• npm run build - build to dist/

• npm run dev - run directly from TypeScript

Message semantics

• trigger_message_reply: injects an inbound message through /events/injections/message, optionally overrides the target LLM provider/model/streaming flags, waits for the event to settle, and by default returns only the bot reply text. Internal metadata is hidden unless include_debug=true.

• trigger_message_reply: session_id can be caller-created for tests. Reuse the same id to continue one synthetic conversation; use a fresh id to start an isolated test session. For GroupMessage, session_id is usually the real group id.

• trigger_message_reply accepts include_logs=false when you want a low-context response but still keep the send-and-wait behavior.

• get_message_history: for webchat, use conversation_id or target_id; do not pass the sender id as user_id. conversation_id may also be a synthetic id you created earlier during injection tests.

Internal tool semantics

• list_astrbot_tools: compact list of AstrBot internal tools. This is the clearest discovery entry for LLMs.

• list_internal_tools: same compact list, kept for backward compatibility.

• get_internal_tool_details: compact tool metadata by default, with full parameter schema controlled by include_parameters.

• invoke_internal_tool: compact invoke result by default. It returns the tool parameter schema only on the first call for the same tool within the current MCP process, then hides it on later calls to reduce context use.

• invoke_internal_tool: now defaults to wait_for_completion=true. If AstrBot returns a background task_id, MCP will keep polling /tools/tasks/{task_id} until the task is terminal or wait_timeout_seconds is reached.

• invoke_internal_tool: when a tool only returns a background acceptance message, MCP now puts that text into accepted_reply instead of pretending it is the final reply.

• invoke_internal_tool: include_logs=true appends simplified task logs to the JSON result; default is false to keep the response short.

• invoke_internal_tool: include_image_content=true makes MCP return completed image attachments as real MCP image content blocks in addition to compact JSON metadata.

• invoke_internal_tool: use show_parameters=true to force showing the tool parameter schema, show_parameters=false to hide it, show_arguments=true to echo the actual call arguments, and show_debug=true to include debug payloads.

• get_internal_tool_task: compact query for one internal tool task by task_id.

• stream_internal_tool_task: collects compact SSE task events from /tools/tasks/{task_id}/stream and returns the latest task snapshot plus streamed events.

Plugin workflow

• list_plugins: compact plugin list for discovery only. It no longer returns full handlers/config noise.

• get_plugin_details: compact metadata plus command list for one plugin. Config is intentionally separated.

• get_plugin_config_file: fetch the full editable plugin config object. This is the main read step before changing a plugin config.

• replace_plugin_config_file: replace the full plugin config object and auto-reload the plugin.

• Normal plugin config workflow: get_plugin_details -> get_plugin_config_file -> edit the returned config object -> replace_plugin_config_file.

• patch_plugin_config: only for small path-level edits. Prefer the full read-edit-save flow above for normal configuration work.

• install_plugin / update_plugin: for GitHub repos, MCP now auto-detects a reachable GitHub acceleration prefix and uses it by default.

• install_plugin / update_plugin: prefer github_acceleration; proxy is kept only as a deprecated alias for backward compatibility.

• Recommended flow: install_plugin -> get_plugin_details -> get_plugin_config_file -> replace_plugin_config_file -> uninstall_plugin when needed.