flowchart LR
    U[用户] --> A[AstrBot<br/>Agent]
    A -->|原生 MCP 或插件桥接| S[astrbot-mcp<br/>MCP Server]
    S --> H[HTTP / REST]
    S --> W[网页搜索 / 抓取]
    S --> P[天气 / 时间 / 汇率]
    S --> F[文件沙箱]
    S --> D[(SQLite)]
    S --> G[GitHub]
    S --> M[SMTP / IMAP]
    S --> C[日历 .ics]
    S --> K[(知识库<br/>FTS5 + 可选向量)]

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

cp config.example.yaml config.yaml
# 按需填写 API Key，或使用环境变量
astrbot-mcp --check-config      # 查看解析后的配置（密钥已脱敏）
astrbot-mcp --list-tools        # 查看注册了哪些工具

# stdio（由 AstrBot 等客户端拉起）
astrbot-mcp --config config.yaml

# Streamable HTTP
astrbot-mcp --config config.yaml --transport streamable-http --host 0.0.0.0 --port 8765

# 旧版 SSE
astrbot-mcp --config config.yaml --transport sse --host 0.0.0.0 --port 8765

Authorization: Bearer <token>

cp config.example.yaml config.yaml
# 修改 config.yaml 中的 auth_token / 服务开关 / API Key
docker compose up -d --build
curl http://127.0.0.1:8765/health

{
  "transport": "stdio",
  "command": "/path/to/Astrbot-MCP/.venv/bin/python",
  "args": ["-m", "astrbot_mcp", "--config", "/path/to/Astrbot-MCP/config.yaml"],
  "cwd": "/path/to/Astrbot-MCP"
}

{
  "transport": "streamable_http",
  "url": "http://127.0.0.1:8765/mcp",
  "headers": { "Authorization": "Bearer <你的 token>" }
}

# 把本仓库的 astrbot_plugin 目录复制到 AstrBot 的插件目录，并改名为插件名
cp -r astrbot_plugin /path/to/AstrBot/data/plugins/astrbot_plugin_mcp_bridge

{
  "mcpServers": {
    "astrbot-mcp": {
      "transport": "stdio",
      "command": "/path/to/Astrbot-MCP/.venv/bin/python",
      "args": ["-m", "astrbot_mcp", "--config", "/path/to/Astrbot-MCP/config.yaml"],
      "cwd": "/path/to/Astrbot-MCP"
    },
    "remote-example": {
      "transport": "streamable_http",
      "url": "http://127.0.0.1:8765/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

[
  { "name": "astrbot-mcp", "command": "python", "args": ["-m", "astrbot_mcp"] }
]

/mcp list                         查看服务器状态
/mcp tools <server>               查看工具列表
/mcp call <server> <tool> <json>  调用工具
/mcp reload                       重连并重新注册（管理员）
/mcp help                         帮助

services:
  knowledge:
    embedding:
      enabled: true
      base_url: ${EMBEDDING_BASE_URL}
      api_key: ${OPENAI_API_KEY}
      model: text-embedding-3-small
      dimensions: 0

kb_remember(content="用户偏好中文回答", tags="preference")
kb_learn_url(url="https://example.com/article", tags="docs")

{
  "auto_learn": {
    "enabled": true,
    "knowledge_server": "astrbot-mcp",
    "tool_name": "kb_remember",
    "tags": "auto-learned",
    "min_message_chars": 20,
    "max_conversation_chars": 4000,
    "learn_in_group": false
  }
}

cp .env.example .env        # docker compose 会自动读取 .env

export TAVILY_API_KEY=tvly-xxx

services:
  web_search:
    provider: tavily
    api_key: ${TAVILY_API_KEY}

services:
  files:
    root: ./data/files
    allow_write: true
    allow_delete: false
  sqlite:
    root: ./data/sqlite
    allow_write: true

services:
  mail:
    enabled: true
    smtp_host: smtp.example.com
    smtp_port: 465
    smtp_ssl: true
    username: bot@example.com
    password: ${MAIL_PASSWORD}
    from_addr: bot@example.com
    imap_host: imap.example.com
    imap_port: 993
    imap_ssl: true

security:
  allow_private_networks: true

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

pytest -q                                  # 全部单元测试（离线，不访问网络）
pytest -q --cov=astrbot_mcp --cov-report=term-missing
ruff check src astrbot_plugin tests        # Lint
ruff format --check src astrbot_plugin tests
astrbot-mcp --check-config
astrbot-mcp --list-tools

.
├── src/astrbot_mcp/
│   ├── __main__.py        # CLI 入口
│   ├── server.py          # FastMCP、HTTP 网关、鉴权、/health
│   ├── config.py          # YAML + 环境变量 + 路径解析
│   ├── net.py             # SSRF 防护与安全请求
│   ├── registry.py        # 服务注册
│   └── services/          # 各服务适配器
├── astrbot_plugin/        # AstrBot 插件（复制到 data/plugins/）
├── tests/                 # pytest 用例（conftest.py 提供离线 HTTP 夹具）
├── .github/workflows/     # CI：lint + 多版本测试
├── config.example.yaml
├── Dockerfile
└── docker-compose.yml