yelin-sticker-mcp
README.md
# yelin-sticker-mcp
[中文](#中文) | [English](#english)
---
## 中文
一个 stdio MCP 服务:让 AI 助手按"想表达的意思"找表情包、发表情包,还能把聊天里收到的图收进你自己的表情库。
走标准输入输出,不开网络服务;除非你配置了 webhook 或运行下载脚本,否则不联网。
仓库里**不带任何图片**。图从哪来见下面的[导入自己的表情](#导入自己的表情)和[动态 Emoji](#动态-emoji可选)。
### 先看你需要哪个
- **你的聊天窗会显示工具结果里的图片**(有的 MCP 聊天客户端会,比如 Kelivo;能接 MCP 不等于会显示,以你用的版本为准):只装这一个就够了。AI 用 `sticker_send` 发表情时,图放在工具结果里,由聊天窗显示。动图会不会动、显示多大,由客户端决定。
- **你的聊天窗不显示工具图片,或者表情要送到另一个页面**(比如 AI 在服务器上跑,你在自己做的网页或 App 里聊天):有两种做法。一是用本插头自带的 webhook(格式见下面"webhook 收到什么");二是再装同一个作者写的 `yelin-send-mcp`,它还能发 AI 自己画的图、写的歌和文件,`examples/` 里有收件端例子。不管哪种,收到以后都要自己接进页面显示;用 `yelin-send-mcp` 转发时,它要能读到这里给出的图片路径。
- **在手机上用**:本插头走 stdio,要在电脑或服务器上运行。只能连远程 MCP 的客户端,需要一个兼容的网关,并按该客户端的要求配置传输方式、HTTPS 和认证。
### 工具
| 工具 | 做什么 |
|---|---|
| `sticker_find(want, n?)` | 按意思找候选(如"抱抱""晚安""委屈""thumbs up")。回 id、分类、名字、文件路径,前几张附缩略预览。只找不发。 |
| `sticker_send(id, text?)` | 发出挑好的表情,可带一句话。**默认把表情原图放在工具结果里**(3 MiB 以内的 PNG/GIF/JPEG/WEBP;超过上限、格式认不出或读不了时,换成第一帧静态预览),能显示工具图片的客户端会显示它;配置了 `STICKER_WEBHOOK_URL` 才 POST 出去。 |
| `sticker_save(path, tags)` | 把一张本地图片(比如聊天里收到的表情)连同标签收进"自己的"库,按内容去重。 |
| `sticker_untagged(n?)` | 把导入后还没起名的图拼成一张编号的 6×6 总表(每格左上角是编号),附"编号→id"对照。 |
| `sticker_tag(id, tags)` / `sticker_tag(batch=...)` | 起名/改标签(覆盖旧标签)。id 可以写最近一张总表上的编号;batch 一行一张"编号 标签…",一次起完。 |
搜索打分:在"分类 + 名字 + 关键词"上做 BM25。中文拆成单字和相邻两字词(单字权重低),英文按词。名字完全一致的最靠前,名字/关键词包含查询词的其次;"自己的"库加权 ×1.5。多字查询只撞上单个字(比如搜"晚安"碰上"安全")不算命中。索引缓存在状态目录,图库或标签有变化会自动重建。
### 安装
需要 Python 3.10 或更新。
```bash
git clone <本仓库地址> yelin-sticker-mcp
cd yelin-sticker-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python sticker_mcp.py paths # 看看各个目录最终落在哪
```
### 配到 Claude Code
```bash
claude mcp add --transport stdio sticker -- \
/path/to/yelin-sticker-mcp/.venv/bin/python /path/to/yelin-sticker-mcp/sticker_mcp.py
```
带环境变量(`--env` 放在服务名前面):
```bash
claude mcp add --transport stdio \
--env STICKER_HOME="$HOME/stickers" \
--env STICKER_WEBHOOK_URL=https://example.com/hooks/sticker \
--env STICKER_WEBHOOK_TOKEN=your-token-here \
sticker -- /path/to/yelin-sticker-mcp/.venv/bin/python /path/to/yelin-sticker-mcp/sticker_mcp.py
```
加完在 Claude Code 里用 `/mcp` 看连上没有;删掉用 `claude mcp remove sticker`。
其他支持 MCP 的客户端,一般是这样的 JSON:
```json
{
"mcpServers": {
"sticker": {
"command": "/path/to/yelin-sticker-mcp/.venv/bin/python",
"args": ["/path/to/yelin-sticker-mcp/sticker_mcp.py"],
"env": { "STICKER_HOME": "~/stickers" }
}
}
}
```
### 环境变量与配置文件
优先级:环境变量 > 配置文件 > 默认值。配置文件是 JSON,格式见 `config.example.json`;路径可以用 `~`。
| 环境变量 | 配置文件键 | 默认值 | 说明 |
|---|---|---|---|
| `STICKER_CONFIG` | — | `~/.config/yelin-sticker-mcp/config.json`(遵循 `XDG_CONFIG_HOME`) | 配置文件位置 |
| `STICKER_HOME` | `home` | `~/.local/share/yelin-sticker-mcp`(遵循 `XDG_DATA_HOME`) | 下面各目录的默认根 |
| `STICKER_LIBRARY_DIR` | `library_dir` | `$STICKER_HOME/library` | 图库:一级子目录名 = 分类,文件名 = 描述 |
| `STICKER_MINE_DIR` | `mine_dir` | `$STICKER_HOME/mine` | "自己的"库(图片 + `tags.json`),搜索时优先 |
| `STICKER_NOTO_DIR` | `noto_dir` | `$STICKER_HOME/noto` | `build_noto.py` 下载的动态 Emoji |
| `STICKER_THUMBS_DIR` | `thumbs_dir` | `$STICKER_HOME/thumbs` | 160px webp 缩略图 |
| `STICKER_STATE_DIR` | `state_dir` | `$STICKER_HOME/state` | 索引缓存、编号总表、发送记录 `sent.jsonl` |
| `STICKER_WEBHOOK_URL` | `webhook_url` | 空 | 设了才往外发(必须是 `https://`) |
| `STICKER_WEBHOOK_TOKEN` | 不支持 | 空 | webhook 令牌,**只从环境变量读**,不写进配置文件 |
| `STICKER_WEBHOOK_HEADER` | `webhook_header` | `Authorization` | 令牌放在哪个请求头;是 `Authorization` 时自动加 `Bearer ` 前缀,其他头原样放 |
| `STICKER_WEBHOOK_EMBED` | `webhook_embed` | 关 | `1`/`true`:把图片 base64 一起发(接收方不在本机时用) |
| `STICKER_WEBHOOK_ALLOW_HTTP` | `webhook_allow_http` | 关 | `1`/`true`:放行 `http://` 地址,只给本机调试用(令牌会明文发出) |
### webhook 收到什么
`sticker_send` 在配置了 `STICKER_WEBHOOK_URL` 时发一个 `POST`,`Content-Type: application/json`:
```json
{
"event": "sticker",
"ts": "2026-01-01T12:00:00+00:00",
"id": "n1a2b3c4d5",
"kind": "noto",
"category": "动态·亲亲爱你",
"name": "抱抱",
"char": "🤗",
"path": "/本机/上的/原图路径.webp",
"thumb": "/本机/上的/缩略图.webp",
"text": "随表情一起说的话",
"mime": "image/webp",
"data": "<base64,只在 STICKER_WEBHOOK_EMBED 打开时有>"
}
```
返回任何 2xx 都算成功;4xx/5xx 或连不上会作为工具错误返回给助手。`kind` 是 `library`、`noto` 或 `mine`。
**不跟随重定向**:webhook 返回 3xx 一律当失败,不重发、不带令牌去 `Location` 指的地址(不管是别的域名还是从 https 降到 http)。请把 `STICKER_WEBHOOK_URL` 直接填成最终地址。
### 导入自己的表情
1. **直接放进图库**:`library/<分类>/<描述>.gif`。文件名就是搜索用的描述,一级目录名是分类(开头的数字序号会去掉,`01_开心` → `开心`);更深的子目录名也会当关键词。以 `.` 开头的文件和目录会跳过。放进去下次搜索就会自动重建索引。
2. **一次导一批,让助手看图起名**:
```bash
.venv/bin/python sticker_mcp.py import ~/Pictures/stickers more.gif
```
图片进"自己的"库,标签先空着(按文件头认 PNG/JPG/GIF/WEBP,按内容哈希去重,打不开的会撤回,HEIC 请先转成 JPG/PNG)。然后在对话里让助手调 `sticker_untagged` 看编号总表,再用 `sticker_tag(batch="1 抱抱 撒娇\n2 晚安 困了")` 一次起完。**没起名的图不会出现在搜索结果里。**
3. **聊天里收到的图**:让助手用 `sticker_save(path, tags)` 收进"自己的"库。
### 动态 Emoji(可选)
想要会动的 Emoji,自己运行下载脚本(从官方地址下载到你本机,约 600 个,约 250MB;已下载的会跳过,可以随时重跑补缺):
```bash
.venv/bin/python build_noto.py # 下载到 STICKER_NOTO_DIR;也可以 --dir 指定
.venv/bin/python make_thumbs.py --all # 可选:提前把缩略图都做好
```
脚本下载谷歌 Noto Emoji Animation 的官方 512px 动态 webp(不收肤色变体),同时用 Unicode CLDR 的中文注释生成中文名和关键词,补了一些聊天常用叫法("晚安""比心""么么哒"等),并按 Unicode 子分组归成十几个中文大类,写成 `catalog.json`;同目录会写 `ATTRIBUTION.txt`(逐个文件写明出处和许可)和 `LICENSE-UNICODE.txt`(Unicode License v3 的完整版权与许可告示,随 Unicode 数据一起保留)。
### 测试
```bash
.venv/bin/pip install pytest
.venv/bin/python -m pytest -q
```
测试全部在临时目录里跑,不碰你真实的图库和配置,也不联网(webhook 走 urllib 真实的处理链,只把最底层的 http/https 收发换成假的,重定向也在里面测)。
### 出处与许可
- 本仓库代码:MIT,见 `LICENSE`。
- 仓库里不带任何表情图片。
- 动态 Emoji:**Noto Emoji Animation** by Google,许可 **CC BY 4.0**(<https://googlefonts.github.io/noto-emoji-animation/>,<https://creativecommons.org/licenses/by/4.0/>)。由 `build_noto.py` 从官方地址下载到你本机;如果你再分发这些图,需要保留署名。
- 中文名与关键词:**Unicode CLDR** annotations,分类来自 Unicode `emoji-test.txt`,© Unicode, Inc.,许可 **Unicode License v3**(<https://github.com/unicode-org/cldr>,<https://www.unicode.org/license.txt>)。`build_noto.py` 会把完整告示写进下载目录的 `LICENSE-UNICODE.txt`;本仓库的 MIT 许可不覆盖这些下载数据。
- 你自己放进图库或"自己的"库的图,版权归各自的权利人;请只放你有权使用的图。
---
## English
A stdio MCP server that lets an AI assistant find stickers by what it wants to express, send them, and keep a
personal sticker library built from images it receives in chat. It talks over stdin/stdout and opens no network
service; it only goes online if you configure a webhook or run the download script.
**No images ship with this repository.** See [Importing your own stickers](#importing-your-own-stickers) and
[Animated emoji](#animated-emoji-optional).
### Which one do you need
- **Your chat window shows images from tool results** (some MCP chat clients do, Kelivo for example; speaking MCP does not mean it shows them, so check the version you use): this plug alone is enough. When the AI calls `sticker_send`, the image is in the tool result and the chat window shows it. Whether animations play, and how big it looks, is up to the client.
- **Your chat window does not show tool images, or stickers have to reach another page** (say the AI runs on a server and you chat in your own web page or app): two ways. Use this plug's own webhook (its JSON payload is shown under "webhook 收到什么" in the Chinese section; the field names are English), or also install `yelin-send-mcp` (same author), which can send pictures the AI made, songs and files too, and whose `examples/` has receivers. Either way you still wire what arrives into your page; when `yelin-send-mcp` forwards a sticker it must be able to read the image path this plug returns.
- **On a phone**: this plug speaks stdio and runs on a computer or a server. Clients that only take remote MCP servers need a compatible gateway set up the way that client requires (transport, HTTPS, authentication).
### Tools
| Tool | What it does |
|---|---|
| `sticker_find(want, n?)` | Find candidates by meaning ("抱抱", "晚安", "thumbs up"...). Returns id, category, name, file path, with previews of the first few. Search only. |
| `sticker_send(id, text?)` | Send a picked sticker, optionally with a line of text. **By default the tool result carries the sticker itself** (PNG/GIF/JPEG/WEBP up to 3 MiB; over the cap, in another format or unreadable, a still first-frame preview instead), which clients that show tool images can show; it POSTs only when `STICKER_WEBHOOK_URL` is set. |
| `sticker_save(path, tags)` | Copy a local image (e.g. a sticker received in chat) into your own library with tags; deduplicated by content. |
| `sticker_untagged(n?)` | Render imported-but-untagged images as a numbered 6x6 contact sheet, with a number -> id map. |
| `sticker_tag(id, tags)` / `sticker_tag(batch=...)` | Set tags (replaces old ones). `id` may be a number from the latest sheet; `batch` is one "number tags" per line. |
Ranking: BM25 over "category + name + keywords". Chinese text is split into single characters (low weight) and
two-character words; latin text into words. Exact name matches rank first, names/keywords containing the query
next; your own library gets a x1.5 boost. A multi-character query that only shares single characters with a
sticker (e.g. "晚安" vs "安全") is not a match. The index is cached and rebuilt automatically when files or tags change.
### Install
Python 3.10+.
```bash
git clone <this repository> yelin-sticker-mcp
cd yelin-sticker-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python sticker_mcp.py paths # show the resolved directories
```
### Use with Claude Code
```bash
claude mcp add --transport stdio sticker -- \
/path/to/yelin-sticker-mcp/.venv/bin/python /path/to/yelin-sticker-mcp/sticker_mcp.py
```
With environment variables (`--env` goes before the server name):
```bash
claude mcp add --transport stdio \
--env STICKER_HOME="$HOME/stickers" \
--env STICKER_WEBHOOK_URL=https://example.com/hooks/sticker \
--env STICKER_WEBHOOK_TOKEN=your-token-here \
sticker -- /path/to/yelin-sticker-mcp/.venv/bin/python /path/to/yelin-sticker-mcp/sticker_mcp.py
```
Check it with `/mcp` inside Claude Code; remove it with `claude mcp remove sticker`. Other MCP clients usually take
the same `command` / `args` / `env` JSON shown in the Chinese section above.
### Environment variables and config file
Precedence: environment > config file > defaults. The config file is JSON (see `config.example.json`); `~` is expanded.
| Variable | Config key | Default | Meaning |
|---|---|---|---|
| `STICKER_CONFIG` | — | `~/.config/yelin-sticker-mcp/config.json` (honours `XDG_CONFIG_HOME`) | config file location |
| `STICKER_HOME` | `home` | `~/.local/share/yelin-sticker-mcp` (honours `XDG_DATA_HOME`) | default root of the folders below |
| `STICKER_LIBRARY_DIR` | `library_dir` | `$STICKER_HOME/library` | image library: top-level folder = category, file name = description |
| `STICKER_MINE_DIR` | `mine_dir` | `$STICKER_HOME/mine` | your own library (images + `tags.json`), ranked first |
| `STICKER_NOTO_DIR` | `noto_dir` | `$STICKER_HOME/noto` | animated emoji downloaded by `build_noto.py` |
| `STICKER_THUMBS_DIR` | `thumbs_dir` | `$STICKER_HOME/thumbs` | 160px webp thumbnails |
| `STICKER_STATE_DIR` | `state_dir` | `$STICKER_HOME/state` | index cache, contact sheets, send log `sent.jsonl` |
| `STICKER_WEBHOOK_URL` | `webhook_url` | empty | POST target; nothing is sent unless set (must be `https://`) |
| `STICKER_WEBHOOK_TOKEN` | not supported | empty | webhook token, **environment only**, never read from the config file |
| `STICKER_WEBHOOK_HEADER` | `webhook_header` | `Authorization` | header carrying the token; `Authorization` gets a `Bearer ` prefix, other headers get the raw value |
| `STICKER_WEBHOOK_EMBED` | `webhook_embed` | off | `1`/`true`: include the image as base64 (for receivers on another machine) |
| `STICKER_WEBHOOK_ALLOW_HTTP` | `webhook_allow_http` | off | `1`/`true`: accept an `http://` URL, for local debugging only (the token is sent in clear text) |
The webhook body is the JSON shown in the Chinese section (`event`, `ts`, `id`, `kind`, `category`, `name`,
`char`, `path`, `thumb`, `text`, plus `mime`/`data` when embedding). Any 2xx response counts as success; errors are
returned to the assistant as tool errors.
**Redirects are never followed**: any 3xx is a failure. The request is not retried and the token is never sent to the
`Location` target (another host, or https downgraded to http). Set `STICKER_WEBHOOK_URL` to the final address.
### Importing your own stickers
1. **Drop files into the library**: `library/<category>/<description>.gif`. The file name is the searchable
description and the top-level folder is the category (a leading number like `01_` is stripped); deeper folder
names become keywords. Dot-files and dot-folders are skipped. The index rebuilds on the next search.
2. **Import a batch and let the assistant name them**:
```bash
.venv/bin/python sticker_mcp.py import ~/Pictures/stickers more.gif
```
Images go into your own library untagged (format detected from the file header: PNG/JPG/GIF/WEBP; deduplicated
by content; unreadable files are rolled back; convert HEIC first). Then ask the assistant to call
`sticker_untagged` and name them with `sticker_tag(batch=...)`. **Untagged images never show up in search.**
3. **Images received in chat**: the assistant saves them with `sticker_save(path, tags)`.
### Animated emoji (optional)
Run the download script yourself (it fetches from the official sources to your machine: about 600 files, ~250 MB;
files already present are skipped, so it is safe to re-run):
```bash
.venv/bin/python build_noto.py # into STICKER_NOTO_DIR, or pass --dir
.venv/bin/python make_thumbs.py --all # optional: pre-build thumbnails
```
It downloads the official 512px animated webp files of Google's Noto Emoji Animation (skin-tone variants skipped),
builds Chinese names and keywords from the Unicode CLDR zh annotations plus a few everyday chat aliases, groups
emoji into about 15 Chinese categories from the Unicode subgroups, and writes `catalog.json`, an `ATTRIBUTION.txt`
(source and license of every file) and `LICENSE-UNICODE.txt` (the full Unicode License v3 copyright and permission
notice, which has to stay with the Unicode data).
### Tests
```bash
.venv/bin/pip install pytest
.venv/bin/python -m pytest -q
```
Tests run in temporary directories only: no real library, no real config, no network (the webhook goes through
urllib's real handler chain with only the bottom http/https layer faked, redirects included).
### Credits and licenses
- Code in this repository: MIT, see `LICENSE`.
- No sticker images are included.
- Animated emoji: **Noto Emoji Animation** by Google, licensed under **CC BY 4.0**
(<https://googlefonts.github.io/noto-emoji-animation/>, <https://creativecommons.org/licenses/by/4.0/>).
`build_noto.py` downloads them from the official source to your machine; keep the attribution if you redistribute them.
- Chinese names and keywords: **Unicode CLDR** annotations; categories from Unicode `emoji-test.txt`.
© Unicode, Inc., licensed under the **Unicode License v3** (<https://github.com/unicode-org/cldr>,
<https://www.unicode.org/license.txt>). `build_noto.py` writes the full notice to `LICENSE-UNICODE.txt` in the
download folder; the MIT license of this repository does not cover the downloaded data.
- Images you add to the library or your own collection belong to their respective rights holders; only add images
you are allowed to use.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessOutdated data