lumio-admin-mcp

MCP server (stdio) that exposes Lumio 诗文库 / 词库 / 字库 admin APIs to hosts such as Cursor and Grok Bot, authenticated with a long-lived Bot Token.

PyPI: lumio-admin-mcp
源码： mcp/lumio-admin

设计规格：

• 一期诗文：docs/superpowers/specs/2026-10-22-lumio-classic-bot-mcp-design.md
• 二期词库/字库：docs/superpowers/specs/2026-10-23-lumio-mcp-words-hanzi.md

Requirements

• Python 3.11+
• uv（推荐用 uvx 直接跑）
• 可达的 Lumio API（LUMIO_API_BASE_URL）
• Bot Token（scopes：classic / words / hanzi）

1. Create a Bot Token

在 monorepo 的 backend 目录：

cd backend && ../.venv/bin/python -m scripts.create_bot_token --name grok-bot

默认 scopes：classic,words,hanzi。仅诗文时可：

../.venv/bin/python -m scripts.create_bot_token --name classic-only --scopes classic

stdout 仅打印一次：

BOT_TOKEN=lumio_bot_…

2. Cursor / Grok Bot MCP（推荐：PyPI + uvx）

发布到 PyPI 后，无需本地 checkout：

{
  "mcpServers": {
    "lumio-admin": {
      "command": "uvx",
      "args": ["lumio-admin-mcp"],
      "env": {
        "LUMIO_API_BASE_URL": "https://your-lumio-host",
        "LUMIO_BOT_TOKEN": "lumio_bot_…"
      }
    }
  }
}

固定版本示例："args": ["lumio-admin-mcp==0.1.0"]。

本地开发（未发布 / 改源码时）

{
  "mcpServers": {
    "lumio-admin": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABS/PATH/mcp/lumio-admin",
        "run",
        "lumio-admin-mcp"
      ],
      "env": {
        "LUMIO_API_BASE_URL": "http://127.0.0.1:7061",
        "LUMIO_BOT_TOKEN": "lumio_bot_…"
      }
    }
  }
}

3. Publish to PyPI（维护者）

1. 在 PyPI 创建账号，Account settings → API tokens → 生成 token（pypi-…）。
2. 在本目录构建并发布：

cd mcp/lumio-admin
uv build
uv publish

uv publish 会提示输入用户名（可用 __token__）与 password（粘贴 API token）。也可用环境变量：

export UV_PUBLISH_TOKEN=pypi-…
uv publish

发版前请 bump pyproject.toml 的 version，再 uv build && uv publish。

4. Local install / debug

cd mcp/lumio-admin
uv sync
export LUMIO_API_BASE_URL=http://127.0.0.1:7061
export LUMIO_BOT_TOKEN=lumio_bot_…
uv run lumio-admin-mcp

stdio：等待 MCP host；缺环境变量时 stderr 提示并以 code 1 退出。

5. Example prompts

• 「列出 online 古诗」
• 「给静夜思加注释 床=井栏边 并上线」
• 「在采实每日背诵词库新建分组 Unit 3-2，批量写入这些短语」
• 「列出字库，往某某字库的某分组批量加汉字」

6. Tools

诗文库（classic）

词库（words）

字库（hanzi）

7. Security

• Never commit LUMIO_BOT_TOKEN / PyPI token。
• Bot Token 按 scopes 限制路径前缀。
• 吊销：cd backend && ../.venv/bin/python -m scripts.revoke_bot_token --id <id>