Rimcp Hybrid

You can run a dedicated MCP server that connects RimWorld source code and XML definitions into a fast, queryable navigation service. It combines lexical search, semantic understanding, and graph-based relationships so an AI assistant can locate, reason about, and retrieve exact code blocks or definitions on demand.

How to use

You interact with the MCP server through a client that sends search and navigation requests and receives structured responses. Typical workflows include starting with a rough natural language query to identify candidate symbols, then asking for full source blocks or related dependencies. You can explore using downstream relationships (what a symbol uses), upstream relationships (who uses a symbol), or obtain the exact code fragment for a symbol to review its implementation. The server is designed to minimize unnecessary code blocks in responses so you can ingest focused context into your assistant.

When you query via a client, you can perform these common actions: 1) rough search to get a short list of candidate symbol names, 2) request details for a chosen symbol with get_item to retrieve the complete source snippet and metadata, 3) inspect get_uses to see what the symbol calls, and 4) inspect get_used_by to see who calls or references the symbol. Use these together to build a precise view of how RimWorld code and XML definitions relate and function.

How to install

Follow these concrete steps to set up the MCP server and its required components on your machine. The steps cover prerequisites, data preparation, building, and starting the server so you can begin interactive queries.

# 1) Prerequisites
# Install .NET 8.0 SDK
# Install Python 3.9+
# Prepare RimWorld data (Defs and C# sources)
# Copy RimWorld Def data to RimWorldData/ and export C# sources to RimWorldData/ as needed

# 2) Clone and prepare project structure
# Place RimWorld data into RimWorldData/ at the repository root
# Place embedding models into src/RimWorldCodeRag/models/ (e.g., e5-base-v2)

# 3) Setup embedding environment (one-time)
# Windows PowerShell:
.\scripts\setup-embedding-env.ps1
# Linux/macOS:
./scripts/setup-embedding-env.sh

# 4) Build the solution
dotnet build

# 5) Build the index (one-time, before service)
cd src/RimWorldCodeRag
dotnet run -- index --root "..\..\RimWorldData"

# 6) Start embedding server (in background or separate terminal)
# Windows PowerShell:
.\scripts\start-embedding-server.ps1
# Linux/macOS:
./scripts/start-embedding-server.sh

# 7) Start MCP server in a separate terminal
cd src\RimWorldCodeRag.McpServer
dotnet run

Configuration and start options

Configure the server using environment variables or a JSON config. The key settings include the index root path for the search data and the embedding server URL. You can override these in a config file if you prefer.

Environment variables
- RIMWORLD_INDEX_ROOT: Path to the index directory created during index building
- EMBEDDING_SERVER_URL: URL of the embedding service (default http://127.0.0.1:5000)

App config (optional)
{
  "McpServer": {
    "IndexRoot": "c:/path/to/RiMCP_hybrid/index",
    "EmbeddingServerUrl": "http://127.0.0.0.1:5000"
  }
}

Troubleshooting and notes

If you encounter issues, verify that the index exists at the path you set and that the embedding service is reachable at the configured URL and port. Ensure the MCP server process can access RimWorldData and the embedding models. When you modify data formats or segmentation rules, you may need to rebuild the index with a full refresh to ensure consistency.

Further considerations

For cross-platform use, you can operate with Windows PowerShell scripts or Linux/macOS shell scripts. The MCP server exposes JSON-RPC like interfaces to clients, and you can integrate it with your preferred AI assistant to run rapid searches and fetch exact code blocks or definitions as needed.

Available tools

rough_search

Performs hybrid semantic search to return candidate symbol names based on natural language queries, combining lexical similarity and semantic ranking.

get_uses

Returns downstream dependencies for a symbol, showing which code elements are called or used by the symbol.

get_used_by

Returns upstream dependents for a symbol, showing which elements reference or call the symbol.

get_item

Retrieves the complete source snippet and metadata for a selected symbol, including class definitions, method bodies, or XML definitions.