Skip to main content
Glama
3113y

isaac-wiki-mcp

by 3113y
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Isaac Wiki MCP

面向《以撒的结合：忏悔》模组开发的 MCP 文档服务器。它将 API 文档作为本地 Markdown 知识库提供给支持 MCP 的编码助手，便于在 Vibe Coding 时查证类、方法、枚举与教程，减少凭空编造 API 的情况。

项目采用 llmwiki 风格：文档是可审阅、可版本控制的 Markdown 页面，并保留 [[wikilinks]] 交叉引用；检索为纯 Python 全文搜索，不依赖向量数据库或模型服务。

当前内容与适用范围

  • 内置锁定版本的 Isaac API Edition 中英文 Markdown 快照。

  • 通过请求配置选择基础游戏 API：rep 或 rep+。

  • 可启用 rgon 注入型 API 覆盖层；未启用时，RGON 标记区块会从返回内容中移除。

  • language 支持 en、zh 与 auto。auto 会根据查询文本保守地判断中英文；需要稳定结果时应显式指定语言。

  • 每次配置了 game、dependencies 或非 auto 的 language，检索都会使用版本化双语快照；不传这些参数时保持旧版 wiki/ 查询行为，以兼容既有调用方。

当前 MCP 对外支持的依赖只有 rgon。快照构建过程会记录 RGON 与 RGON+ 的上游来源，但 RGON+、EID、curlib 等尚不是可选择的 MCP 依赖配置；请不要将它们视为本版本的兼容性承诺。

当前快照记录：中英文各 468 篇 Markdown 文档，API Edition 快照修订为 77199a65ab2ebd789ecefb88a66220811855a238。可调用 wiki_sources 读取机器可用的完整来源、页面数和上游修订信息。

Related MCP server: godot-mcp-docs

安装

要求 Python 3.11 或更高版本。使用 uv 的本地开发安装：

git clone https://github.com/3113y/isaac-wiki-mcp.git
cd isaac-wiki-mcp
uv sync --extra dev

也可以使用 pip：

pip install -e ".[dev]"

配置为 MCP 服务器

服务器通过标准输入输出传输 JSON-RPC，日志只写入标准错误。以本地克隆目录为例，在 MCP 客户端配置中加入：

{
  "mcpServers": {
    "isaac-wiki": {
      "command": "uv",
      "args": ["run", "isaac-wiki-mcp"],
      "cwd": "/absolute/path/to/isaac-wiki-mcp"
    }
  }
}

也可在已激活的 Python 环境中将 command 改为 isaac-wiki-mcp。配置完成后，让编码助手先调用 wiki_search 找到页面，再用 wiki_read 取得完整上下文。

MCP 工具

工具

用途

主要参数

wiki_search

全文搜索并返回匹配页面的完整内容

query、top_k（1–10）、category、环境参数

wiki_read

按页面名或路径读取完整页面

page、环境参数

wiki_list

列出页面元数据，不返回正文

category、环境参数

wiki_stats

返回本地索引的基础统计（分类计数基于历史 wiki 目录）

无

wiki_sources

返回快照仓库、支持的配置和锁定修订

无

category 可取 classes、enums、tutorials 或 reference。它用于历史 wiki/ 目录的分类过滤；版本化快照沿用 API Edition 的原始目录层级，当前不会再按该参数二次过滤。环境参数在 wiki_search、wiki_read 与 wiki_list 中一致：

参数

取值

说明

game

rep、rep+

基础 API 版本；省略时配置记录为 rep

dependencies

[] 或 ["rgon"]

要启用的 API 覆盖层

language

en、zh、auto

返回文档语言；auto 根据查询或页面名判断

wiki_search 与 wiki_read 还接受 include_incompatible。该字段目前会随结果回显，用于未来的条目级兼容性筛选；当前版本不应把它当作已完成的跨配置过滤功能。

调用示例

查询 REP 的英文页面：

{
  "query": "player health",
  "game": "rep",
  "language": "en"
}

读取 REP+ 的中文 EntityPlayer 页面：

{
  "page": "EntityPlayer",
  "game": "rep+",
  "language": "zh"
}

在 REP 环境中检索 RGON 覆盖层内容：

{
  "query": "knockback",
  "game": "rep",
  "dependencies": ["rgon"],
  "language": "auto"
}

建议调用方始终传入实际开发环境的 game、dependencies 和 language，并将工具返回的 profile 视作本次查询采用的环境记录。

命令行

isaac-wiki 可用于本地检查知识库：

# 搜索并以 JSON 返回
uv run isaac-wiki search "player health" --game rep --language en --format json

# 读取中文版页面
uv run isaac-wiki read EntityPlayer --game rep+ --language zh

# 使用 RGON 覆盖层列出版本化页面
uv run isaac-wiki list --game rep --dependency rgon --language zh --format json

# 查看本地索引统计
uv run isaac-wiki stats --format json

常用命令：

isaac-wiki search QUERY [--top-k N] [--category CATEGORY]
isaac-wiki read PAGE
isaac-wiki list [--category CATEGORY]
isaac-wiki stats
isaac-wiki build
isaac-wiki sync-reference SOURCE_ROOT [--output wiki/reference]

search 和 read 支持 --include-incompatible；环境选项为 --game rep|rep+、可重复的 --dependency rgon，以及 --language en|zh|auto。

数据来源与更新

版本化快照位于 wiki/reference/en 和 wiki/reference/zh，其来源清单为 wiki/reference/source-release.json。更新 API Edition 后，可在完整的本地 isaac-api-edition 检出目录中重新生成并打包快照：

uv run isaac-wiki sync-reference /path/to/isaac-api-edition

该命令需要上游目录具备基础中英文文档、RGON/RGON+ 文档以及 scripts/build_overlay_docs.py。它会重建 wiki/reference 并更新来源修订记录；运行前请确认上游检出内容完整。提交快照更新时应同时检查 source-release.json，让使用者能够追溯文档版本。

API 文档的错误或改进建议欢迎通过 Issue 或 Pull Request 提交。请提供页面路径、原文来源、适用的 game / dependencies 配置，以及可验证的修改依据；这能避免将不同版本或前置依赖的行为混入同一条说明。

项目结构

src/isaac_wiki/
  server.py          MCP stdio JSON-RPC 服务器
  facade.py          统一查询接口与环境解析
  wiki_engine.py     Markdown 索引、搜索、读取与 RGON 内容过滤
  snapshot.py        API Edition 快照构建与来源记录
  cli.py             命令行入口
wiki/
  reference/en/      版本化英文 API Edition 快照
  reference/zh/      版本化中文 API Edition 快照
  reference/source-release.json
data/                旧版页面生成所用数据
tests/               自动化测试

开发与验证

uv run --extra dev pytest tests -q

项目以 MIT License 发布。

Available Tools

4 tools
wiki_listA

List all wiki pages, optionally filtered by category. Returns metadata (title, method_count, DLC versions) for each page — no full content.

ParametersJSON Schema
NameRequiredDescriptionDefault
categoryNoFilter by category.

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It clearly states what the tool returns (title, method_count, DLC versions) and what it does not return (full content). It also notes the optional filtering behavior. This is substantial transparency for a read-only list tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence, front-loaded with the main action, and includes only essential details about the return value. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one optional parameter and no output schema, the description is complete enough: it explains what is returned and what is omitted. It does not mention pagination or limits, but that is not critical for a straightforward list endpoint. The metadata fields are enumerated, which adds clarity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already covers the only parameter 'category' with a description and enum values. The tool description adds 'optionally filtered' and lists the enum values, but this mostly repeats schema info. With 100% schema coverage, the description does not need to add much, and any addition is marginal.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and resource ('wiki pages'), and clearly distinguishes from siblings by stating it returns metadata for all pages, not full content. This differentiates it from wiki_read (reading a specific page) and wiki_search (searching).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when you need a list of wiki pages with metadata, optionally filtered by category. However, it does not explicitly mention alternatives or when not to use this tool. The sibling tools exist but no exclusions are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

wiki_readA

Read a complete Isaac API wiki page by name. Returns the full page with all methods, descriptions, DLC compatibility badges, and [[wikilinks]] to related classes. Use wiki_search first to find the right page name.

ParametersJSON Schema
NameRequiredDescriptionDefault
pageYesPage name or path. Examples: 'EntityPlayer', 'Game', 'enums/EntityType'.

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description explains the return content (methods, descriptions, DLC badges, wikilinks), giving the agent an idea of what to expect. However, it does not disclose error behavior for missing pages or any potential side effects, though the tool is clearly a read operation. The description carries most of the burden but leaves some edge cases uncovered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: first states the primary action and resource, second lists the return contents and gives a usage hint. No redundant or filler text. Information is front-loaded and every sentence contributes value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has a single parameter and no output schema, but the description explains the return value (full page with methods, descriptions, DLC badges, wikilinks) and provides usage context. It omits details about failure modes but for a simple read tool, the description is sufficiently complete for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with examples, so the schema already documents the 'page' parameter well. The description reinforces that the tool reads 'by name', but adds no additional semantic detail beyond what the schema provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Read' with a clear resource ('Isaac API wiki page by name'), stating exactly what the tool does. It distinguishes from sibling tools by emphasizing full page retrieval, whereas wiki_search, wiki_list, and wiki_stats serve different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance to 'Use wiki_search first to find the right page name', which clarifies the intended workflow. It does not explicitly exclude scenarios or mention alternatives, but the sequencing hint is strong actionable context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

wiki_statsA

Get statistics about the wiki knowledge base (page count, method count, categories).

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that the tool returns page count, method count, and categories, which gives some insight into output, but does not address side effects, authentication, or error behavior. For a simple read-only stats tool this is adequate but not thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, focused sentence that immediately states the purpose and provides concrete examples. It has no unnecessary words or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a statistics tool with no parameters and no output schema, the description gives a clear idea of the return content (page count, method count, categories). It leaves minor ambiguity about whether categories are counts or lists, but overall it is sufficiently complete for its simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and an empty schema, so there is nothing to document. The description does not need to add parameter details, and the baseline for 0 parameters is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves statistics about the wiki knowledge base, with specific examples (page count, method count, categories). This distinguishes it from siblings like wiki_read and wiki_search, which focus on content retrieval or searching.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no explicit guidance on when to choose this tool over alternatives. It does not mention any exclusions, prerequisites, or comparison to sibling tools, leaving the usage context inferred but not stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.2.0
    • First observedwiki_list
    • First observedwiki_read
    • First observedwiki_search
    • First observedwiki_stats
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: read a specific page, search across pages, list pages, and get stats. The descriptions explicitly guide when to use each, so there is no overlap or ambiguity.

Naming Consistency5/5

All tools follow a consistent `wiki_verb` pattern (read, search, list, stats). The naming is predictable and uniform, with the only minor deviation being `wiki_stats` using a noun instead of a verb, but this is a common exception for a statistics operation.

Tool Count5/5

Four tools is a well-scoped count for a wiki MCP server. Each tool covers a distinct aspect of wiki interaction without being redundant or overly expansive.

Completeness5/5

The tool surface fully covers the expected operations for a read-only wiki knowledge base: searching, reading, listing, and getting stats. There are no missing critical operations or dead ends for the described purpose.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers