Endfield MCP Server

Language / 语言： English | 中文

English

An MCP Server for Arknights: Endfield fan creation. It gives any MCP-compatible client — Claude Desktop, Claude Code, Chatbox, and more — live access to Endfield lore, character info, and world-building entries via the Endfield Talos Wiki.

This is the sibling project of PRTS-MCP (for the original Arknights). Same architecture philosophy, modernized to a single TypeScript implementation on Bun — one codebase covers both the local stdio transport (Claude Desktop) and the remote Streamable HTTP transport (shared servers).

Current Status (0.3.1)

15 tools across three domains — 6 Wiki, 5 Character, 4 Story — all end-to-end working and verified. GameData (characters, story) is served from a self-hosted mirror with auto-sync + bundled offline fallback.

Wiki content is in English (the wiki's primary language). Tool descriptions are in Chinese. The calling LLM bridges the content language as needed.

Data Sources

• Endfield Talos Wiki (https://endfield.wiki.gg/api.php) — lore articles, faction info, world-building entries. Live HTTP requests with browser-style headers (the wiki's WAF blocks bare bots).
• Self-hosted GameData mirror (planned for 0.2.0, repository TBD) — text-only JSON tables (characters, items, stages, enemies) mirrored from Variante/endfield_research_kit exports. Hosted on a private domain; no binary assets redistributed.

Why these sources

During v0.1 planning we evaluated every candidate Endfield wiki / data source and selected on technical merit:

The selection rationale is documented so future contributors don't re-litigate it. If you're proposing a new source, read this table first.

Quick Start

Prerequisites: Bun ≥ 1.2.

git clone https://github.com/3aKHP/Endfield-MCP.git
cd Endfield-MCP/ts
bun install

Local stdio (Claude Desktop / Claude Code):

bun run src/server.ts

Or add to your MCP client config (paths use forward slashes on all platforms; on Windows you can also use backslashes):

{
  "mcpServers": {
    "endfield": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/Endfield-MCP/ts/src/server.ts"]
    }
  }
}

Remote HTTP server:

EF_TRANSPORT=http PORT=3000 bun run src/server.ts
# MCP endpoint: http://localhost:3000/mcp  (POST only, stateless)
# Health check:  http://localhost:3000/health

Configuration (Environment Variables)

Verification

cd ts
bun run typecheck                          # TypeScript zero errors
bun test                                   # unit tests (no network)
bun run scripts/smoke-live.ts              # live WAF-bypass check (hits the real wiki — run manually, not in CI)

Or use the all-in-one audit:

.\scripts\check-runtime.ps1 -Full          # Windows
./scripts/check-runtime.sh --full          # Unix

Related Projects

• PRTS-MCP — sibling MCP Server for the original Arknights. Architecture blueprint for this project.
• Variante/endfield_research_kit — local Endfield data export toolkit. Defines the schema our GameData mirror will follow.
• Endfield Talos Wiki — primary wiki data source.

中文

面向《明日方舟：终末地》同人创作的 MCP Server。为 MCP 客户端（Claude Desktop、Claude Code、Chatbox 等）提供终末地世界观、角色资料和阵营设定的实时检索能力。

本项目是 PRTS-MCP（明日方舟本体的姊妹项目）的兄弟项目。相同的架构哲学，但简化为基于 Bun 的单 TypeScript 实现——一套代码同时覆盖本地 stdio 传输（Claude Desktop）和远程 Streamable HTTP 传输（共享服务器）。

当前状态（0.3.1）

15 个工具覆盖三个域——6 个 Wiki、5 个角色、4 个剧情——全部端到端跑通并验证。GameData（角色 / 剧情）由自建镜像提供，支持自动同步 + bundled 离线兜底。

Wiki 内容以英文为主（站点的主语言），工具描述使用中文。内容由调用方 LLM 负责桥接语言。

数据源

• Endfield Talos Wiki（https://endfield.wiki.gg/api.php）—— 世界观词条、阵营设定、剧情线索。实时 HTTP 请求，需带浏览器风格请求头（站点 WAF 会拦截裸 bot）。
• 自建 GameData 镜像（计划 0.2.0，仓库 TBD）—— 纯文本 JSON 表格（角色、物品、关卡、敌人），参照 Variante/endfield_research_kit 的导出契约镜像，托管在私有域名，不发布二进制资产。

为什么选这些源

v0.1 规划阶段我们评估了每个候选的终末地 wiki / 数据源，按技术可行性筛选：

选型理由记录在此，避免未来贡献者重复讨论。如果你要提议新数据源，请先读这张表。

快速开始

前置条件： Bun ≥ 1.2。

git clone https://github.com/3aKHP/Endfield-MCP.git
cd Endfield-MCP/ts
bun install

本地 stdio（Claude Desktop / Claude Code）：

bun run src/server.ts

或添加到 MCP 客户端配置（路径在所有平台上都用正斜杠；Windows 上也可以用反斜杠）：

{
  "mcpServers": {
    "endfield": {
      "command": "bun",
      "args": ["run", "/绝对路径/Endfield-MCP/ts/src/server.ts"]
    }
  }
}

远程 HTTP 服务：

EF_TRANSPORT=http PORT=3000 bun run src/server.ts
# MCP 端点：http://localhost:3000/mcp  （仅 POST，无状态）
# 健康检查：http://localhost:3000/health

配置（环境变量）

验证

cd ts
bun run typecheck                          # TypeScript 零错误
bun test                                   # 单元测试（无网络）
bun run scripts/smoke-live.ts              # 实测 WAF 绕过（真实访问 Wiki——手动运行，不进 CI）

或用一键审计脚本：

.\scripts\check-runtime.ps1 -Full          # Windows
./scripts/check-runtime.sh --full          # Unix

相关项目

• PRTS-MCP —— 明日方舟本体的姊妹 MCP Server，本项目架构蓝本。
• Variante/endfield_research_kit —— 终末地本地数据导出工具包，定义了我们 GameData 镜像将遵循的 schema。
• Endfield Talos Wiki —— 本项目 Wiki 数据来源。

开发文档

• AGENTS.md —— AI 协作者启动手册（运行时环境、启动准则、已知陷阱）
• docs/dev/WORKFLOW.md —— 开发工作流（分支模型、迭代循环、独立 CR、版本同步）
• docs/dev/STYLE.md —— 代码规范与架构硬原则
• STATUS.md —— 项目现状与工具清单
• ROADMAP.md —— 路线图与版本规划

License

MIT