KotorMCP

Model Context Protocol server for Knights of the Old Republic game resources

A Model Context Protocol (MCP) server that exposes context-rich tools for AI agents to interact with Knights of the Old Republic (KOTOR) and Knights of the Old Republic II: The Sith Lords (TSL) game installations. This server provides intelligent resource discovery, installation management, and game data inspection capabilities tailored for automated analysis and debugging workflows.

Features

Installation Detection & Management
- Automatic detection of KOTOR 1 and KOTOR 2 installations
- Environment variable support (K1_PATH, K2_PATH, TSL_PATH, etc.)
- Default path discovery (Windows registry, common install locations)
- Installation caching for performance
Resource Discovery & Inspection
- List resources from all locations (override, modules, chitin, streams)
- Filter by resource type, name patterns, and module scope
- Deep resource summarization (GFF structures, 2DA tables, TLK strings)
- Resource metadata extraction (size, location, type)
Journal & Plot Analysis
- Comprehensive journal entry overview (global.jrl)
- Plot category organization
- Quest entry enumeration
- Cross-references with game scripts and dialogs
AI-Optimized Workflows
- Context-rich responses designed for LLM consumption
- Structured JSON output for programmatic access
- Efficient resource scanning with configurable limits
- Installation-aware resource resolution

Installation Guide

Prerequisites

Python 3.8+
A valid KOTOR 1 or KOTOR 2 installation
MCP-compatible client (Claude Desktop, Cursor, etc.)

Quick Start

Using uv (Recommended)

# End users: run with --refresh for latest (no install needed)
uvx --refresh kotormcp

# Developers: run from local source with --with-editable
uvx --with-editable Libraries/PyKotor --with-editable Tools/KotorMCP kotormcp
uv run --directory Tools/KotorMCP/src --module kotormcp

# Or install editable
uv pip install -e Tools/KotorMCP

Using pip

pip install kotormcp
# Or from source: pip install -e Tools/KotorMCP

Configuration

Claude Desktop

Add the following to your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "kotormcp": {
      "command": "uvx",
      "args": [
        "--refresh",
        "--from",
        "kotormcp @ git+https://github.com/th3w1zard1/KotorMCP.git",
        "kotormcp"
      ],
      "env": {
        "K1_PATH": "C:\\Program Files\\steamapps\\common\\swkotor",
        "K2_PATH": "C:\\Program Files\\steamapps\\common\\Knights of the Old Republic II"
      }
    }
  }
}

Cursor / VS Code (Claude Dev Extension)

Add to your MCP configuration:

{
  "mcpServers": {
    "kotormcp": {
      "command": "uvx",
      "args": [
        "--refresh",
        "--from",
        "kotormcp @ git+https://github.com/th3w1zard1/KotorMCP.git",
        "kotormcp"
      ],
      "env": {
        "K1_PATH": "C:\\Program Files\\steamapps\\common\\swkotor",
        "K2_PATH": "C:\\Program Files\\steamapps\\common\\Knights of the Old Republic II"
      }
    }
  }
}

Environment Variables

The server automatically detects installations using these environment variables (in order of precedence):

KOTOR 1:

K1_PATH
KOTOR_PATH
KOTOR1_PATH

KOTOR 2:

K2_PATH
TSL_PATH
KOTOR2_PATH
K1_PATH (fallback)

If environment variables are not set, the server will attempt to find installations using default paths (Windows registry, common install locations).

Usage Guide

The server provides five main tools for interacting with KOTOR installations:

1. `detectInstallations`

Detect available KOTOR installations and their paths.

Parameters: None

Response:

{
  "K1": [
    {
      "path": "C:\\Program Files\\LucasArts\\SWKotOR",
      "exists": true,
      "label": "default"
    }
  ],
  "K2": [
    {
      "path": "C:\\Program Files\\LucasArts\\SWKotOR2",
      "exists": true,
      "label": "env"
    }
  ]
}

Example:

use_mcp_tool({
  server_name: "kotormcp",
  tool_name: "detectInstallations",
  arguments: {}
})

2. `loadInstallation`

Load and cache a KOTOR installation for subsequent operations.

Parameters:

game (string, required): Game identifier ("k1", "k2", "tsl", "kotori", "kotor2")
path (string, optional): Explicit installation path (overrides environment variables)

Response:

{
  "game": "K1",
  "path": "C:\\Program Files\\LucasArts\\SWKotOR"
}

Example:

use_mcp_tool({
  server_name: "kotormcp",
  tool_name: "loadInstallation",
  arguments: {
    game: "k1",
    path: "C:\\Program Files\\LucasArts\\SWKotOR"
  }
})

3. `listResources`

List resources from the active installation with filtering options.

Parameters:

game (string, required): Game identifier
location (string, optional): Resource location filter ("all", "override", "modules", "chitin", "streams") - default: "all"
moduleFilter (string, optional): Filter by module name (e.g., "001ebo")
resourceTypes (string, optional): Comma-separated resource type extensions (e.g., "gff,dlg,jrl")
resrefQuery (string, optional): Filter resources by name pattern (case-insensitive)
limit (number, optional): Maximum number of results (default: 50)

Response:

{
  "count": 25,
  "items": [
    {
      "resref": "global",
      "restype": "JRL",
      "source": "override",
      "size": 12345,
      "module": null
    }
  ],
  "truncated": false
}

Example:

use_mcp_tool({
  server_name: "kotormcp",
  tool_name: "listResources",
  arguments: {
    game: "k1",
    location: "override",
    resourceTypes: "jrl,gff",
    resrefQuery: "global",
    limit: 10
  }
})

4. `describeResource`

Get detailed information about a specific resource, including structured data for GFF files, 2DA tables, and TLK files.

Parameters:

game (string, required): Game identifier
resref (string, required): Resource name (without extension)
restype (string, required): Resource type extension (e.g., "jrl", "gff", "2da", "tlk")
order (array, optional): Search location priority order (default: ["override", "custom_folders", "modules", "chitin"])

Response:

{
  "resref": "global",
  "restype": "JRL",
  "source": "override",
  "size": 12345,
  "summary": {
    "type": "JRL",
    "categories": 5,
    "entries": 42,
    "structure": "..."
  }
}

Example:

use_mcp_tool({
  server_name: "kotormcp",
  tool_name: "describeResource",
  arguments: {
    game: "k1",
    resref: "global",
    restype: "jrl"
  }
})

5. `journalOverview`

Get a comprehensive overview of journal entries and plot categories from global.jrl.

Parameters:

game (string, required): Game identifier

Response:

{
  "count": 5,
  "categories": [
    {
      "id": 0,
      "name": "Main Quest",
      "entries": [
        {
          "id": 0,
          "title": "Escape from Taris",
          "text": "You must escape from the planet Taris..."
        }
      ]
    }
  ]
}

Example:

use_mcp_tool({
  server_name: "kotormcp",
  tool_name: "journalOverview",
  arguments: {
    game: "k1"
  }
})

Common Workflows

Finding All Resources That Modify Plot Points

// 1. Load installation
await loadInstallation({ game: "k1" });

// 2. List all journal-related resources
const resources = await listResources({
  game: "k1",
  resourceTypes: "jrl,gff,dlg",
  resrefQuery: "global",
  limit: 100
});

// 3. Get journal overview
const journal = await journalOverview({ game: "k1" });

// 4. Search for scripts that reference plot points
const scripts = await listResources({
  game: "k1",
  resourceTypes: "ncs",
  resrefQuery: "plot",
  limit: 50
});

Investigating Module Structure

// 1. List all resources in a specific module
const moduleResources = await listResources({
  game: "k1",
  location: "modules",
  moduleFilter: "001ebo",
  limit: 200
});

// 2. Get detailed information about key resources
const area = await describeResource({
  game: "k1",
  resref: "001ebo",
  restype: "are"
});

const git = await describeResource({
  game: "k1",
  resref: "001ebo",
  restype: "git"
});

Debugging Missing Resources

// 1. Check all locations for a resource
const resource = await describeResource({
  game: "k1",
  resref: "missing_resource",
  restype: "gff",
  order: ["override", "modules", "chitin", "streams"]
});

// 2. List similar resources
const similar = await listResources({
  game: "k1",
  resrefQuery: "missing",
  limit: 20
});

Architecture

KotorMCP is built on the Model Context Protocol specification and uses the official Python MCP SDK. The server:

Caches installations for performance across multiple tool calls
Resolves resources using the same logic as PyKotorCLI and PyKotor's Installation class
Provides structured summaries optimized for LLM consumption
Follows established patterns from engine reimplementations (reone, xoreos, kotor.js)

Implementation Notes

Resource scanning logic mirrors scripts/investigate_module_structure.py
Journal summarization follows the structure documented in vendor/xoreos/src/engines/nwn2/journal.cpp
Resource resolution uses PyKotor's Installation class with configurable search order
GFF structure summarization provides hierarchical field overviews

Development

Building from Source

# Clone the repository
git clone https://github.com/OldRepublicDevs/PyKotor.git
cd PyKotor

# Install dependencies
uv pip install -e Tools/KotorMCP

# Run the server
python -m kotormcp.server

Project Structure

Tools/KotorMCP/
├── src/
│   └── kotormcp/
│       ├── __init__.py
│       └── server.py          # Main MCP server implementation
├── pyproject.toml             # Project metadata and dependencies
├── requirements.txt            # Pip-compatible requirements
└── README.md                  # This file

Dependencies

mcp>=0.1.1 - Model Context Protocol Python SDK
pykotor>=2.3.2 - PyKotor core library for KOTOR file format support

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

For bug reports or feature requests, please open an issue on GitHub.

License

This project is part of the PyKotor ecosystem and is licensed under the LGPL-3.0-or-later License. See the main repository LICENSE file for details.

Related Projects

PyKotor - Core library for KOTOR file formats
PyKotorCLI - Command-line interface for KOTOR resources
Holocron Toolset - GUI editor for KOTOR files

Acknowledgments

Built on the Model Context Protocol specification
Uses the PyKotor library for game file format support
Inspired by engine reimplementations: reone, xoreos, kotor.js

Made with ❤️ for the KOTOR modding community

Report Bug · Request Feature · Documentation

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.github/workflows		.github/workflows
src/kotormcp		src/kotormcp
.gitignore		.gitignore
README.md		README.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

KotorMCP

Features

Installation Guide

Prerequisites

Quick Start

Using uv (Recommended)

Using pip

Configuration

Claude Desktop

Cursor / VS Code (Claude Dev Extension)

Environment Variables

Usage Guide

1. detectInstallations

2. loadInstallation

3. listResources

4. describeResource

5. journalOverview

Common Workflows

Finding All Resources That Modify Plot Points

Investigating Module Structure

Debugging Missing Resources

Architecture

Implementation Notes

Development

Building from Source

Project Structure

Dependencies

Contributing

License

Related Projects

Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

1. `detectInstallations`

2. `loadInstallation`

3. `listResources`

4. `describeResource`

5. `journalOverview`

Packages