Metadata-Version: 2.5
Name: lumio-admin-mcp
Version: 0.1.1
Summary: MCP server for Lumio admin APIs via Bot Token
Project-URL: Homepage, https://github.com/cyetstar/lumio
Project-URL: Repository, https://github.com/cyetstar/lumio
Project-URL: Documentation, https://github.com/cyetstar/lumio/tree/main/mcp/lumio-admin
Project-URL: Issues, https://github.com/cyetstar/lumio/issues
Author: cyetstar
License-Expression: MIT
License-File: LICENSE
Keywords: admin,bot,lumio,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.9.0
Requires-Dist: pydantic>=2.0
Description-Content-Type: text/markdown

# 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`](https://pypi.org/project/lumio-admin-mcp/)  
**源码：** [`mcp/lumio-admin`](https://github.com/cyetstar/lumio/tree/main/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](https://docs.astral.sh/uv/)（推荐用 `uvx` 直接跑）
- 可达的 Lumio API（`LUMIO_API_BASE_URL`）
- Bot Token（scopes：`classic` / `words` / `hanzi`）

## 1. Create a Bot Token

在 monorepo 的 `backend` 目录：

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

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

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

stdout 仅打印一次：

```text
BOT_TOKEN=lumio_bot_…
```

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

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

```json
{
  "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"]`。

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

```json
{
  "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](https://pypi.org) 创建账号，Account settings → API tokens → 生成 token（`pypi-…`）。
2. 在本目录构建并发布：

```bash
cd mcp/lumio-admin
uv build
uv publish
```

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

```bash
export UV_PUBLISH_TOKEN=pypi-…
uv publish
```

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

## 4. Local install / debug

```bash
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）

| Tool | HTTP | Notes |
|------|------|--------|
| `list_works` | GET `/api/admin/classic/works` | `kind`, `q`, `status`, `page`, `page_size` |
| `get_work` | GET `.../works/{id}` | |
| `create_work` | POST `.../works` | may set `status=online`；可选 `appreciation`（文章赏析） |
| `update_work` | PATCH `.../works/{id}` | 可选 `appreciation` |
| `delete_work` | DELETE `.../works/{id}` | single work only |
| `list_glosses` | GET `.../works/{id}/glosses` | |
| `create_gloss` | POST `.../works/{id}/glosses` | |
| `update_gloss` | PATCH `.../glosses/{id}` | |
| `delete_gloss` | DELETE `.../glosses/{id}` | |

### 词库（words）

| Tool | HTTP | Notes |
|------|------|--------|
| `list_word_libraries` | GET `/api/admin/word-libraries` | |
| `list_word_groups` | GET `.../{library_id}/groups` | |
| `create_word_group` | POST `.../{library_id}/groups` | 不新建词库 |
| `batch_add_words` | POST `.../groups/{group_id}/words/batch` | |

### 字库（hanzi）

| Tool | HTTP | Notes |
|------|------|--------|
| `list_hanzi_libraries` | GET `/api/admin/hanzi-libraries` | |
| `list_hanzi_groups` | GET `.../{library_id}/groups` | |
| `create_hanzi_group` | POST `.../{library_id}/groups` | 不新建字库 |
| `batch_add_hanzis` | POST `.../groups/{group_id}/hanzis/batch` | |

## 7. Security

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