RimSearcher

一个基于 MCP 的 RimWorld 源码检索与分析服务。它把本地 RimWorld C# / XML 数据建立为可查询索引，让 AI 助手能在真实源码上定位、追踪、阅读和解释逻辑，减少“幻觉式回答”。

采用 Roslyn + XML 继承解析，支持高并发只读查询。

MCP 协议版本: 2025-11-25

---

1. 核心特性

精准 C# 解析（Roslyn）

• 单次解析提取类型继承和成员索引（方法/属性/字段/事件）
• 支持类大纲、成员体提取、继承链追踪
• 支持方法、属性、构造器、索引器、运算符级别读取

XML Def 继承合并

• 递归解析 ParentName 链路
• 合并父子节点并处理列表容器/覆盖逻辑
• 输出可直接阅读的“最终 Def 结果”

C# 与 XML 语义桥接

• 从 Def 自动提取关联 C# 类型（如 thingClass / compClass / workerClass）
• 在 inspect 中同时展示 Def 信息与关联代码路径

面向查询性能优化

• 预建索引 + N-gram 候选筛选
• 启动后冻结索引（FrozenDictionary）优化只读查询吞吐
• 搜索结果带上限控制，避免超长输出拖慢上下文

低 Token 消耗（LLM 友好）

• 采用先定位再深入的查询链路（locate → inspect/trace → read_code），避免一次返回大段无关文本
• locate / trace / search_regex 工具采用结果上限与预览截断，控制上下文体积并保持关键信息密度
• read_code 支持按 methodName/extractClass 精确读取代码，未指定成员时再按小范围行号读取，避免一次返回整个文件

运行模型与边界

• 本地运行，核心检索不依赖网络
• 网络请求仅用于版本更新提示（可关闭）

---

2. 六大工具

以下为实际注册的 MCP 工具名与能力说明。

rimworld-searcher__locate

全局模糊定位入口。

支持内容

• C# 类型、成员（方法/属性/字段）、XML Def、文件名
• 过滤语法：type: method: field: def:
• CamelCase 缩写与拼写容错（如 JDW）

示例查询

def:Apparel_ShieldBelt
type:CompShield
method:CompTick
field:energy

---

rimworld-searcher__inspect

深度分析单个 Def 或 C# 类型。

Def 模式

• 展示 Def 类型、来源文件
• 返回继承合并后的 XML
• 提取关联 C# 类型并尝试映射到索引文件

C# 模式

• 返回继承关系图
• 返回类成员大纲（字段/属性/方法签名）

示例

Apparel_ShieldBelt
RimWorld.CompShield

---

rimworld-searcher__trace

交叉引用追踪工具。

模式

• inheritors：列出某基类/接口的子类
• usages：查找符号文本引用（C# + XML），带行号预览

示例

symbol: ThingComp, mode: inheritors
symbol: CompShield, mode: usages

---

rimworld-searcher__read_code

精确读取 C# 代码片段。

支持读取方式

• 指定成员：methodName（支持方法/属性/构造器/索引器/运算符）
• 指定类型：extractClass
• 指定行区间：startLine + lineCount

路径支持

• 绝对路径
• 已索引文件名（如 CompShield.cs）
• 文件基名（如 CompShield）

示例

path: CompShield.cs, methodName: CompTick

---

rimworld-searcher__search_regex

全局正则检索（C# + XML）。

特性

• 可选 fileFilter（如 .cs / .xml）
• 结果按文件分组，显示行号预览
• 内置输出截断提示，避免超大响应

示例

pattern: class.*:.*ThingComp
fileFilter: .cs

---

rimworld-searcher__list_directory

目录浏览工具。

特性

• 列出目录下文件与子目录（子目录以 / 结尾）
• 支持 limit 分页提示
• 受 PathSecurity 白名单约束（除非显式关闭）

---

2.5 系统架构

RimSearcher Architecture (Narrow)

MCP Client 
  |
  | JSON-RPC (MCP)
  v
RimSearcher.cs (runtime)
  |- request routing / concurrency / cancel / progress / logging bridge
  v
Program.cs (bootstrap)
  |- load config + PathSecurity
  |- try cache -> fallback full scan -> save cache
  |- start MCP server
  |
  +-- IndexCacheService
  |     |- .cache/index/manifest.json
  |     `- .cache/index/index.bin (compressed snapshot)
  |
  `-- UpdateChecker
        `- .cache/.update-cache (latest version + check time)

Tool Layer
  |- locate | inspect | trace | read_code | search_regex | list_directory
  |
  +-- SourceIndexer
  |     |- RoslynHelper / FuzzyMatcher / QueryParser
  |     `- Local C# source (Assembly-CSharp)
  |
  `-- DefIndexer
        |- XmlInheritanceHelper / FuzzyMatcher / QueryParser
        `- Local RimWorld XML (Data/Defs...)

启动流程

1. 读取配置（优先 RIMSEARCHER_CONFIG，未设置时回退到同目录 config.json）
2. 初始化路径安全策略
3. 自动准备缓存目录（<exe目录>/.cache/index）
4. 尝试加载索引缓存（manifest.json + index.bin）
5. 缓存未命中时扫描 C# / XML 并建索引，然后回写缓存
6. 冻结索引（读优化）
7. 注册工具并启动 MCP 服务

---

3. 典型工作流

场景：分析护盾腰带如何生效

1. locate(def:Apparel_ShieldBelt)：定位 Def
2. inspect(Apparel_ShieldBelt)：看合并后 XML 与关联 C# 类型
3. inspect(RimWorld.CompShield)：看继承链和类大纲
4. read_code(path=CompShield.cs, methodName=CompTick)：读取核心逻辑
5. trace(symbol=CompShield, mode=usages)：追踪相关引用

---

4. 性能与安全

维度	当前实现
索引策略	启动优先加载本地缓存，未命中时扫描并冻结索引（FrozenDictionary）
索引缓存	manifest.json + index.bin，默认目录 <exe目录>/.cache/index
模糊匹配	N-gram 候选过滤 + 评分排序
并发控制	MCP 请求并发上限 10
正则搜索保护	全局/单文件命中上限 + 行数上限 + regex 超时
路径安全	白名单根目录校验（SkipPathSecurity=false 时生效）

索引缓存说明

• 缓存目录：RimSearcher.Server.exe 同目录下 /.cache/index
• 缓存文件：manifest.json（元数据）+ index.bin（压缩索引快照）
• 首次启动通常会全量建索引并写缓存；二次启动通常会直接命中缓存，这能显著提升二次启动速度
• 若需要强制重建，删除 /.cache/index 后重启该程序即可
• 当前策略下，配置路径变化或缓存结构版本变化会触发自动重建

---

5. 快速开始

前置要求

运行 Release 版 RimSearcher.Server.exe 需要 .NET 10 Runtime；

若需本地编译源码，则需要安装 .NET 10 SDK。

安装步骤

1. 从 Releases 下载 RimSearcher.Server.exe。
2. 创建 config.json

配置示例：

{
  "CsharpSourcePaths": [
    "C:/Path/To/Your/RimWorld/Source"
  ],
  "XmlSourcePaths": [
    "C:/SteamLibrary/steamapps/common/RimWorld/Data"
  ],
  "SkipPathSecurity": false,
  "CheckUpdates": true
}

字段说明：

• CsharpSourcePaths: C# 源码目录（反编译源码目录，需要自己反编译导出游戏源码文件，这里不提供）
• XmlSourcePaths: RimWorld Data 目录
• SkipPathSecurity: true 时关闭路径白名单检查（仅建议本地可信环境）
• CheckUpdates: 是否启用版本更新提示

1. 在 MCP 客户端中把 RimSearcher.Server.exe 注册为 stdio MCP Server，并设置环境变量 RIMSEARCHER_CONFIG 指向上一步的 config.json。

兼容模式说明：

• 若设置了 RIMSEARCHER_CONFIG，优先读取该路径。
• 若未设置，则回退到 RimSearcher.Server.exe 同目录下的 config.json。

安装到 AI 助手（不同客户端配置差异）

通用 MCP 客户端（Claude Desktop / Gemini CLI / Cursor 等）

{
  "mcpServers": {
    "RimSearcher": {
      "command": "D:/Tools/RimSearcher/RimSearcher.Server.exe",
      "args": [],
      "env": {
        "RIMSEARCHER_CONFIG": "D:/your/custom/path/config.json"
      }
    }
  }
}

GitHub Copilot（servers 结构）

{
  "servers": {
    "RimSearcher": {
      "command": "D:/Tools/RimSearcher/RimSearcher.Server.exe",
      "args": [],
      "env": {
        "RIMSEARCHER_CONFIG": "D:/your/custom/path/config.json"
      }
    }
  }
}

OpenCode（mcp 结构）

{
  "mcp": {
    "RimSearcher": {
      "type": "local",
      "command": ["D:/Tools/RimSearcher/RimSearcher.Server.exe"],
      "enabled": true,
      "environment": {
        "RIMSEARCHER_CONFIG": "D:/your/custom/path/config.json"
      }
    }
  }
}

常见注意事项：

• command 使用 RimSearcher.Server.exe 的绝对路径。
• 推荐始终配置 RIMSEARCHER_CONFIG 指向明确路径，避免多环境切换时误读配置。
• 若不设置 RIMSEARCHER_CONFIG，才要求 config.json 与 exe 在同一目录。
• 修改客户端 MCP 配置后，重启客户端或重载 MCP 服务。
• 若客户端有工具白名单/权限开关，确保已允许 RimSearcher。

本地验证

手动验证时：

• 方式 A：设置环境变量 RIMSEARCHER_CONFIG 指向目标 config.json。
• 方式 B：不设置环境变量，把 config.json 放到 RimSearcher.Server.exe 同目录。

然后运行 RimSearcher.Server.exe，若最后一条看到类似的JSON-RPC2.0日志即表示启动成功（不同版本可能看到的日志不同，但只要看到RimSearcher MCP server started都可视为成功启动）：

• 首次构建：Program: Cache unavailable, rebuilding index -> Program: Index build completed ... -> Program: Index cache saved
• 缓存命中：Program: Index loaded from cache
• 服务就绪：RimSearcher MCP server started

快速检查是否接入成功：

• 客户端工具列表中能看到 rimworld-searcher__locate、rimworld-searcher__inspect 等 6 个工具。
• 执行一次 locate（例如 def:Apparel_ShieldBelt）能返回结果。

---

6. 更新提示说明

• 更新检查为非阻塞后台任务，不影响核心检索服务。
• 仅在 CheckUpdates=true 时启用。
• 若遇到 GitHub 匿名限流，更新检查会静默失败，不影响工具功能。
• 更新信息默认通过日志通道输出；若 MCP 客户端不展示日志，则可能看不到该提示。
• 更新检查缓存文件路径：<exe目录>/.cache/.update-cache（与 index 文件夹同级）。

---

免责声明

• 本项目为第三方开源工具，与 Ludeon Studios 及 RimWorld 官方无隶属、赞助或背书关系。
• 本工具仅对用户本地提供的源码/XML进行索引与检索，不内置或分发任何游戏原始资源。
• 检索与分析结果仅供学习、调试与研究参考。
• 使用者应自行确保其数据来源、反编译行为与使用方式符合当地法律法规、RimWorld 相关协议及各 Mod 许可证要求。
• 因使用本工具造成的任何直接或间接损失，项目作者与贡献者不承担责任。

---

License

MIT

如果这个项目对你有帮助，欢迎点个 Star⭐。