AniNest
AniNest is a mostly read-only MCP server for illustration search, PCR character/arena lookup, portrait identification, local memory access, service health checks, and local character-name overlay updates.
Search illustrations using Chinese or English requests, with controls for count, size, orientation, extra tags, and negative tags.
Look up characters by name, nickname, four-digit uid, or six-digit id; also rank fuzzy name matches.
Identify characters in cropped portrait images with candidate lists, similarity scores, and an unknown threshold.
Look up arena defense teams through a local service; use names/ids, region/limit filters, exclusions, and in-place replacements.
Search the local memory store and report memory row counts, scope distribution, and database size.
Probe local services and report their health/status.
Add or update characters and aliases in a local overlay file, and record corrections for wrongly matched names; these write only to local overlay data.
Provides read-only search and statistics over a local SQLite memory database, enabling querying stored memories and inspecting database size and distribution without modifying the database.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@AniNest find me a vertical swimsuit illustration of Hatsune Miku"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
AniNest · aninest-mcp
一个基于 MCP(Model Context Protocol,模型上下文协议) 的只读能力服务器,提供十个工具: 按中文描述找插画、按角色名查竞技场作业、用头像认角色、检索本地记忆、探活本机服务。
任何支持 MCP 的宿主(Claude Desktop、Cursor、自研 Agent、CI 脚本)都可以直接调用, 不需要知道背后是哪个图站、哪个本地服务、哪个游戏。
传输:
stdio(桌面客户端)与streamable-http(远端调用)协议:
2025-11-25,十个工具全部带title与annotations依赖:Python 3.10+,
mcp1.x,httpx;识图额外需要pillow+numpy
快速开始
Windows,不想碰命令行:下载 ZIP 解压 → 双击 install.cmd。脚本会建独立环境、装依赖、
自检一次握手,并打印可直接粘贴的客户端配置。
# 等价用法(加 -WriteClaudeConfig 会顺手写好 Claude Desktop 配置)
.\install.ps1 -Mirror https://pypi.tuna.tsinghua.edu.cn/simple任何系统,用命令行:
pip install "git+https://github.com/moriruruka/aninest-mcp.git"
aninest-mcp # stdio 模式,等宿主连接容器:
docker build -t aninest-mcp .
docker run --rm -p 127.0.0.1:8765:8765 -e ANINEST_MCP_TRANSPORT=streamable-http aninest-mcp本仓库不发布到 PyPI,
pip install aninest-mcp会 404;装法就是上面这几条。 装不上的排查、镜像加速、卸载、干净环境验证:安装说明。
Related MCP server: jina-mcp-server
工具
工具 | 典型请求 | 返回 |
| "来两张初音未来泳装的竖图" | 图片链接 + 用到的 tag + 是否放宽过条件 |
| "布丁、克总、真琴、纺希、莉莎这队作业" | 别人用的防守阵容(含角色名)与票数 |
| "布丁和克总分别是哪个角色" | 角色名、六位 id、四位数 uid、别名 |
| "这几张头像分别是谁" | 每张头像的候选角色与相似度 |
| "上次说的那个配色偏好还记得吗" | 记忆条目 + 打分 + 范围(本会话/全局) |
| "记忆存了多少了" | 行数、范围分布、库大小 |
| "服务都活着吗" | 五个本地端口的连通性 |
| "宫紫 是哪个角色"(表里没有) | 按名字相似度排的候选、分数、命中方式 |
| "日服刚出的新角色,加一下" | 写本地覆盖层,返回角色与别名变更 |
| "宫紫 就是宫子,记住" | 把这个词记成别名,留一条带时间的更正记录 |
阵容可以直接说人话:角色名、黑话、四位数 uid、六位 id 混着写都行(布丁 克总 100301),一队 5 人。
查不到作业时,同一次调用就能带上"排除某角色"或"把 A 换成 B"再查:
{ "defense": ["布丁", "克总", "真琴"], "exclude": ["真琴"] }
{ "defense": ["布丁", "克总", "真琴"], "replace": ["布丁->怜"], "region": 1 }读与写
前七个工具只读:不写调用方的数据、不发消息、不动账号。
character_update / character_correct 只写本地覆盖层(默认 ~/.aninest/pcr_overlay.json,
可用 ANINEST_PCR_OVERLAY 改路径),不碰随包分发的角色表、记忆库和网络。
两者在 annotations 里标了 readOnlyHint=false、destructiveHint=false,
宿主可以据此只对它们要求用户确认。
参数细节、返回字段、报错含义:使用说明。
保持角色表是新的
新角色通常先在日服上线,中文译名要过一阵才有人用。拿到日文名就先
character_update(jp="ミヤコ") 登记,character_lookup / character_match 马上能按日文名查到。
匹配错了不用新建角色:先 character_match 看候选和分数,让用户挑,再
character_correct(term, char_id) 把这个叫法记下来。两处改动都只写覆盖层,
包内 src/aninest/data/pcr_chars.json 不动,升级也不会被覆盖。
演示
一段对话,不需要任何客户端:
python demo/story.py它自己起一个示例记忆库和假作业服务,连上 server,输出一轮完整对话:
你 > 布丁、克总、真琴、纺希、莉莎这个防守,把布丁换成怜,再查一次
host > 按 1号位 怜 / 2号位 克莉丝提娜 / 3号位 真琴 / 4号位 纺希 / 5号位 莉莎 查(把 宫子 换成 怜):
找到 2 支队伍,最热门的是 优衣 / 香织(夏日) / 绫音 / 日和 / 矛依未(新年)(赞 1、踩 0)。demo/host.py 是最小宿主:一句话 → 选工具 → 把 JSON 说成人话。它故意不用大模型,
用确定性关键词路由,所以不需要 API key 就能复现。换成真模型做这两步,就是任何 MCP 客户端的日常。
一张截图 → 一套阵容(宿主侧胶水示例):
python demo/screenshot_lineup.py shot.png --grid 5x3 --rows 1流程是 截图 → 按格子裁出头像 → portrait_identify → arena_lookup。
裁图这一步故意留在宿主侧:每个宿主的截图尺寸、UI 版本、可见行数都不一样,
而 server 只回答"这张裁好的头像图是谁"。号位从右往左数(1 号位是最右边的前卫),
默认 --order rtl,也可以用 --boxes "x,y,w,h;..." 钉死矩形。
接入客户端
Claude Desktop(claude_desktop_config.json):
{
"mcpServers": {
"aninest": {
"command": "aninest-mcp",
"env": {
"ANINEST_BOORU_URL": "https://safebooru.org/index.php",
"ANINEST_MEMORY_DB": "C:/Users/you/.aninest/memory.db"
}
}
}
}通用 stdio 客户端:命令 aninest-mcp(或 python -m aninest),传输 stdio,没有必填参数。
HTTP 客户端(远端或容器):
ANINEST_MCP_TRANSPORT=streamable-http ANINEST_MCP_PORT=8765 aninest-mcp
# 然后连 http://127.0.0.1:8765/mcpDSH(DeepSeek Harness):把下面这段加进 profile 的 cordis.patch.yml,重启后工具以
mcp__aninest__art_search 这样的名字出现:
- id: mcp-aninest
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: aninest # 工具前缀,命名空间内唯一
transport: stdio
command: python
args: ['-m', 'aninest']
env:
ANINEST_MEMORY_DB: 'C:/Users/you/.aninest/memory.db'自检脚本(不需要任何客户端):
python scripts/mcp_smoke.py # 列工具 + 调 service_health
python scripts/mcp_smoke.py --call art_search --args '{"query":"初音未来 泳装","count":1}'配置
全部通过环境变量注入,仓库里没有任何凭证文件(见 .env.example)。
变量 | 默认值 | 说明 |
|
|
|
|
| 仅 HTTP/SSE 模式生效 |
|
| 任何 Gelbooru 风格 JSON API |
|
| 秒 |
|
| 图站要求可识别的 UA |
|
| 作业查询服务(见下文"本机依赖") |
|
| 只读打开 |
|
| 健康探测目标 |
| (空) | 头像目录 |
|
| 两个写工具落盘的位置 |
本机依赖与替身
十个工具里,只有 arena_lookup 依赖一个不在本仓库内的本机服务(持登录态的浏览器进程),
其余工具都能独立验证。没有那个服务时,用仓库自带的替身跑同一套契约:
工具 | 依赖 | 没有依赖时怎么验证 |
| 公网图站(默认 safebooru) | 直接可用;离线评测覆盖 tag 编译 |
| 无(角色表随包分发) | 直接可用 |
| 无(只写覆盖层) | 直接可用;把 |
| 头像包 + |
|
| 一个 SQLite 文件 |
|
|
|
|
| 无 | 五个端口全 down 也是合法结果 |
两分钟复现:
# 1) 记忆工具:造一个示例库再查
python scripts/make_demo_db.py --out demo_memory.db
ANINEST_MEMORY_DB=./demo_memory.db python scripts/mcp_smoke.py --call memory_stats
# 2) 作业查询:起假服务,再走真实 MCP stdio 调用
python scripts/fake_arena.py --port 6192 &
ANINEST_ARENA_URL=http://127.0.0.1:6192 python scripts/mcp_smoke.py --call arena_lookup \
--args '{"defense":["布丁","克总","真琴"],"limit":2}'
# 3) 识图:造几张合成头像,指着它跑
python scripts/make_demo_avatars.py --out demo_avatars
ANINEST_PCR_AVATARS=./demo_avatars python scripts/mcp_smoke.py --call portrait_identify \
--args '{"images":["demo_avatars/100101.png"]}'测试
pip install -e ".[dev]"
ruff check src tests eval scripts demo # 风格与静态检查
python -m unittest discover -s tests # 单元 + 契约测试
python eval/run_eval.py # 离线评测(tag 编译,26 条 golden case)
python eval/run_eval.py --network # 联网端到端(成功率 / p50 / p95)
python scripts/live_check.py # 对着正在跑的本地服务逐个调工具当前结果(Windows 11 / Python 3.13 / 本机直连,2026-10-29):
指标 | 结果 |
单元 + 契约测试 | 172 passed |
离线评测(26 条 golden case) | 26/26,tag recall 1.000,precision 1.000,字段准确率 1.000 |
联网端到端(18 条真实请求) | 18/18 成功,p50 1.67 s,p95 1.99 s |
CI 矩阵 | 3.10 / 3.12 / 3.13 × Ubuntu / Windows + Docker 镜像构建,7 job 全绿 |
每一层能证明什么、不能证明什么,见 测试说明。
架构
flowchart LR
H["MCP 宿主<br/>Claude Desktop / DSH / 编辑器插件"] -- "MCP(stdio / HTTP)" --> S
S["aninest-mcp<br/>10 tools + 1 resource + 1 prompt"]
S --> B["插画站(booru)"]
S --> C["作业查询服务<br/>登录态留在那边"]
S --> D["本地 SQLite 记忆库(只读)"]
S --> E["本机服务端口探活"]
S --> F["本地覆盖层<br/>(唯一写入点)"]代码结构、模块职责、改哪里看什么:架构说明。 设计取舍(为什么这样分层、为什么不上向量库等):DECISIONS。
安全与隐私
只读优先:十个工具里七个只读;写入只落本地覆盖层,原子写、可随时删。
零凭证:
arena_lookup走本机服务,登录态存在浏览器 profile 里,不进代码、不进仓库。只放行确定安全的图:分级归一化(
s/safe/g/general→ safe,q/e丢弃)。不编造:网络错误、非 JSON 响应、空结果分别报错,不返回假数据。
可审计:返回里带
relaxed/attempt/score/rating等结构化字段。
数据边界见 PRIVACY,攻击面与信任边界见 THREAT_MODEL, 与 MCP 规范的对照见 COMPLIANCE。
文档
内容 | 文件 |
安装、卸载、故障排查 | |
工具参数、返回、报错 | |
代码结构与改动指引 | |
五层验证与"能证明什么" | |
数据边界与隐私 | |
威胁模型 | |
MCP 规范符合度 | |
设计取舍(ADR) | |
变更记录 |
常见问题
装完客户端看不到工具? 先跑 python scripts/mcp_smoke.py;能看到工具就说明 server 正常,
问题在客户端配置路径或 command 写错。
portrait_identify 报"没有头像包"? 它需要 ANINEST_PCR_AVATARS 指向一个目录,
里面是 <六位 id>.webp|png|jpg。没有素材时用 scripts/make_demo_avatars.py 造几张练手。
arena_lookup 报连不上? 它只对接本机服务;没有的话用 scripts/fake_arena.py 起替身,
或把 ANINEST_ARENA_URL 指到任何实现 POST /search 的服务。
装到 3.10 上崩了? CI 覆盖 3.10/3.12/3.13,遇到问题请附 python -V 与完整 traceback。
Roadmap
按角色名 / 黑话 / uid 查阵容
裁好的头像 → 角色
角色表本地覆盖层(新角色、纠错别名)
整页截图的一体化入口(需要宿主侧的版面适配)
检索层可插拔(当前是确定性关键词,可选接入向量检索)
致谢
作业查询依赖他人维护的公开服务与数据,特此致谢:
pcrdfans.com(作者 Peter Li,@peterli110)—— 竞技场作业数据、
/battle查询页与/units单位表均来自该站点,本项目仅调用其公开接口与页面, 未复制其代码。站点前端源码开源于 peterli110/pcrdfans.com。esterTion/redive_master_db_diff—— 解包的游戏数据;头像 CDN
redive.estertion.win亦由 esterTion 维护。
License
MIT。
Available Tools
10 toolsarena_lookupArena lineup lookupARead-only
Look up defence teams for a lineup via the local arena browser service.
Args: defense: the lineup by name — "布丁", "克总", "真琴" … (names, aliases or ids). def_ids: the same thing as six-digit ids, if you already have them. region: arena region id, 1 = mainland, 2 = overseas, 0 = no filtering. limit: how many teams to summarise, 1-6 (display cap, not a game rule). exclude: names to drop before searching ("先排除一个再查"). replace: in-place swaps such as ["宫子->真琴"]; positions are preserved.
Inputs: limit, region, def_ids, defense, +2 more. Returns: result
art_searchIllustration searchARead-only
Search an illustration for a Chinese or English request.
Args: query: free-form request, e.g. "初音未来 泳装 竖图"; tags/count/orientation are parsed. count: number of images, 1-10. size: "compressed" for a smaller preview, "original" for the full-size file. orientation: optional "landscape", "portrait" or "square" filter. extra_tags: additional canonical booru tags to include. negative: tags to exclude, sent to the board as "-tag".
Inputs: query (required), size, count, negative, +2 more. Returns: result
character_correctCharacter name correctionAIdempotent
Teach the table that term refers to a character.
This is the manual fix for a wrong match: the term is stored as an alias of the chosen character and the correction is logged with a timestamp.
Args: term: what the user actually typed, e.g. "宫紫". char_id: the character it should resolve to (id or any known name). note: optional free text kept with the correction.
Inputs: term (required), char_id (required), note. Returns: result
character_lookupCharacter lookupARead-onlyIdempotent
Map a character name, nickname, four-digit uid or six-digit id to an arena id.
Args: query: what the player said — "布丁", "克总", "猫拳", "1001", "100101". limit: how many candidates to return, 1-10.
Inputs: query (required), limit. Returns: result
character_matchCharacter name matchARead-onlyIdempotent
Rank characters by how close their names are to a query.
Use this when a lookup fails because the name is not in the table: the score
and matched_on say whether the candidate is trustworthy, so the host can
ask the user instead of guessing.
Args: query: a name in any form, e.g. "宫紫", "ミヤコ", "miyako". top_k: how many candidates to return, 1-20. threshold: minimum score, 0-1; below it nothing is returned.
Inputs: query (required), top_k, threshold. Returns: result
character_updateCharacter updateAIdempotent
Add a character or extend its aliases in the local overlay file.
New characters are usually published in Japan first and arrive with a
Japanese name before any Chinese alias exists; pass jp so lookups by the
Japanese name work immediately. The packaged table is never modified.
Args: char_id: six-digit arena id, e.g. 100701. name: Chinese name; required when creating a character that is not known. aliases: extra names to accept, e.g. ["布丁新皮", "miyako"]. jp: Japanese name, e.g. "ミヤコ". servers: servers the character exists on, e.g. ["jp", "cn"]. remove_aliases: aliases to drop (a wrong alias is worse than a missing one).
Inputs: char_id (required), jp, name, aliases, +2 more. Returns: result
memory_searchMemory searchARead-onlyIdempotent
Search the assistant's local memory store (read-only).
Args: query: keywords or a sentence to look for. limit: maximum hits, 1-20. scope: "all", "session" or "global".
Inputs: query (required), limit, scope. Returns: result
memory_statsMemory store statsARead-onlyIdempotent
Report row counts and database size of the local memory store.
Inputs: no named parameters. Returns: result
portrait_identifyPortrait identificationARead-onlyIdempotent
Identify which characters are in cropped portrait images.
Args: images: one entry per portrait — a file path, raw bytes as base64, or a data URI. top_k: candidates per portrait, 1-10. min_score: similarity floor below which the portrait counts as unknown, 0-1.
Inputs: images (required), top_k, min_score. Returns: result
service_healthService healthARead-onlyIdempotent
Probe the local services of the assistant stack and report their status.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Most tools target clearly distinct resources: image identification, art search, arena defence lookup, memory search/stats, and service health. Two pairs blur at the edges — character_lookup vs character_match (exact-ish resolution vs fuzzy fallback ranking) and character_update vs character_correct (both can install a new alias) — but the descriptions explicitly frame one as the fallback/manual fix for the other, so an agent can choose correctly.
Every tool follows the same snake_case noun_verb pattern (portrait_identify, art_search, character_lookup, arena_lookup, memory_search, character_update...). The shared character_/memory_ prefixes also make the groupings immediately legible.
Ten tools is well within the sweet spot and each one maps to a concrete operation in the assistant stack. No filler tools and no obviously missing sibling that would force a merge.
Character resolution has a full lifecycle (lookup, fuzzy match, create/extend, manual correction with alias removal), and identification, art search, arena, memory and health probes cover the surrounding workflows. Minor gaps remain: no way to delete a character entirely or list/browse the table, and the memory surface is explicitly read-only with no write path inside this server.
Maintenance
Related MCP Connectors
Remote MCP utilities for agents: structured data, commerce checks, and x402 paid API discovery.
Search, vet & assemble MCP servers from your agent: verified tools, risk labels, and trust scores.
Read-only MCP tools for AI agent discovery, structured resources, and NIULAI information.
Scan MCP tool definitions for poisoning, look up server history, count tool-list tokens. Free.
Related MCP Servers
- AlicenseBqualityCmaintenanceExposes ACR's memory, skill, web, and GitHub search tools to any MCP client, enabling task execution and tool access via the MCP protocol.64MIT
- AlicenseNot gradedqualityNot gradedmaintenanceEnables remote MCP access to tools for URL-to-markdown conversion, web and image search, academic search, embeddings, reranking, classification, deduplication, and PDF extraction.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to query a running KanColle game client's live state and integrated resources—fleets, quests, battle history, and id lookups—through read-only tools.MIT
- AlicenseAqualityCmaintenanceEnables MCP-capable clients to query a locally captured Discord archive through structured tools such as recent messages, substring search, status, server/channel listings, media retrieval, and sandboxed jsonl/markdown export. It also exposes browser-driven capture and media re-download operations that run as serialized background jobs.9AGPL 3.0