### Install Dependencies and Build Project

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/README.md

Standard commands to clone the repository, install Node.js dependencies, and build the project from source.

```bash
git clone https://github.com/MCDxAI/minecraft-dev-mcp.git
cd minecraft-dev-mcp
npm install
npm run build
```

--------------------------------

### Verify Java Installation

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/README.md

Command to check the installed Java version, ensuring it meets the 17+ requirement.

```bash
java -version
```

--------------------------------

### MCP Server Configuration Example

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/README.md

This JSON snippet shows how to configure an MCP server, including setting a custom cache directory and log level.

```json
{
  "mcpServers": {
    "minecraft-dev": {
      "command": "minecraft-dev-mcp",
      "env": {
        "CACHE_DIR": "/custom/cache/path",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}
```

--------------------------------

### Start Minecraft Dev MCP in HTTP Mode

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/README.md

Use the `--http` flag to start the server with the Streamable HTTP transport. The `--port` flag specifies the listening port, defaulting to 3000. This mode is for clients or editors connecting over HTTP.

```bash
minecraft-dev-mcp --http --port 3000
```

--------------------------------

### Run Integration Tests

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/CLAUDE.md

Executes all integration tests for the project. Ensure npm is installed and the project dependencies are set up.

```bash
npm test
```

--------------------------------

### Decompile Mod JAR Example

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/CLAUDE.md

An example of how to use the `decompile_mod_jar` tool with a specified JAR path and mapping type.

```typescript
decompile_mod_jar({ jarPath: "C:/mods/meteor-remapped-yarn.jar", mapping: "yarn" })
```

--------------------------------

### NPM Installation Configuration for MCP Server

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/README.md

Use this JSON configuration in your Claude Desktop or Claude Code settings when installing the MCP server via NPM. Ensure Node.js 18+ is installed.

```json
{
  "mcpServers": {
    "minecraft-dev": {
      "command": "minecraft-dev-mcp"
    }
  }
}
```

--------------------------------

### Search Mod Code Example

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/CLAUDE.md

Demonstrates searching for methods named 'onTick' within a specific mod version using the `search_mod_code` tool.

```typescript
search_mod_code({ modId: "meteor-client", modVersion: "0.5.8", query: "onTick", searchType: "method", mapping: "yarn" })
```

--------------------------------

### NPX Installation Configuration for MCP Server

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/README.md

Configure your Claude Desktop or Claude Code settings to use the MCP server with NPX for a no-installation approach. This requires Node.js 18+.

```json
{
  "mcpServers": {
    "minecraft-dev": {
      "command": "npx",
      "args": ["-y", "@mcdxai/minecraft-dev-mcp"]
    }
  }
}
```

--------------------------------

### Search Mod Indexed Example

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/CLAUDE.md

An example of using `search_mod_indexed` to find occurrences of 'packet AND send' within a specific mod, filtered by class, method, and field types.

```typescript
search_mod_indexed({ query: "packet AND send", modId: "meteor-client", modVersion: "0.5.8", mapping: "yarn" })
```

--------------------------------

### Invoke a Tool with Flags using Minecraft Dev CLI

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/README.md

Invoke specific tools using their flags. For example, `get_minecraft_source` requires `--version`, `--className`, and `--mapping`. Boolean, numeric, and JSON values are automatically coerced.

```bash
minecraft-dev-cli get_minecraft_source --version 1.21.10 --className net.minecraft.world.entity.Entity --mapping yarn
```

--------------------------------

### Run All Tests (Default + Manual)

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/__tests__/manual/README.md

Execute all tests, including both the default CI suite and the manual tests.

```bash
npm run test:all
```

--------------------------------

### Run All Manual Tests

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/__tests__/manual/README.md

Execute all manual tests, including service-level version compatibility and MCP transport suites.

```bash
npm run test:manual
```

--------------------------------

### Run Manual Patched-JAR Suite

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/CLAUDE.md

Executes the manual patched-JAR suite for end-to-end testing of the patched-MC pipeline. Requires setting environment variables for the patched JAR path and version information.

```bash
PATCHED_JAR_PATH=/path/to/patched.jar \
PATCHED_VERSION=1.21.1-neoforge-21.1.72 \
PATCHED_MC_VERSION=1.21.1 \
PATCHED_LOADER=neoforge \
npm run test:manual:patched
```

--------------------------------

### Run Specific Service-Level Suites

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/__tests__/manual/README.md

Execute specific service-level version compatibility suites for Yarn and Mojmap.

```bash
npm run test:manual:1.21.10
npm run test:manual:1.20.1
npm run test:manual:1.19.4
npm run test:manual:mojmap
```

--------------------------------

### List Available Tools with Minecraft Dev CLI

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/README.md

The `minecraft-dev-cli` provides a standalone command-line interface to invoke tools directly. Use `list-tools` to see all available tools and their parameters. Arguments are flags-only.

```bash
minecraft-dev-cli list-tools
```

--------------------------------

### Run Manual Patched JAR Test

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/__tests__/fixtures/forge-1.20.1/README.md

Use this command to run the patched-JAR test suite locally. Ensure you have the necessary environment variables set, including the path to your patched JAR file.

```bash
PATCHED_JAR_PATH=/path/to/your/patched.jar \
PATCHED_VERSION=1.20.1-forge-47.4.0 \
PATCHED_MC_VERSION=1.20.1 \
PATCHED_LOADER=forge \
npm run test:manual:patched
```

--------------------------------

### Run MCP Transport Quick Smoke Tests

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/__tests__/manual/README.md

Execute a quick smoke test of the MCP transport matrix.

```bash
npm run test:manual:mcp:smoke
```

--------------------------------

### Analyze Mod JAR with Minecraft Dev CLI

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/README.md

Use the `analyze_mod_jar` tool to analyze a mod JAR file. Provide the `--jarPath` and optionally `--includeAllClasses` as a boolean value. Output is always JSON.

```bash
minecraft-dev-cli analyze_mod_jar --jarPath C:\mods\example.jar --includeAllClasses true
```

--------------------------------

### Select MCP Matrix Versions

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/__tests__/manual/README.md

Specify custom versions for the MCP end-to-end matrix tests using the MCP_E2E_VERSIONS environment variable.

```bash
cross-env MCP_E2E_VERSIONS=1.21.11,1.20.1,26.1-snapshot-1,26.1-snapshot-9 npm run test:manual:mcp
```

--------------------------------

### Generate Registry Data with Server JAR

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/CLAUDE.md

Use the server JAR for registry extraction, especially for MC 1.18+ which requires a bundler format. Ensure the server JAR is not remapped.

```typescript
// Get SERVER JAR (not client!)
const serverJarPath = await this.versionManager.getServerJar(version);

// Run data generator with version-specific format
const registriesFile = await this.dataGen.generateRegistryData(
  serverJarPath,
  registryDir,
  version // Used to detect if bundler format needed
);
```

--------------------------------

### Run Specific Mojmap Version Tests

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/__tests__/manual/README.md

Execute Mojmap remap/decompile tests for a specific Minecraft version.

```bash
npm run test:manual:mojmap:1.21.11
npm run test:manual:mojmap:1.21.10
npm run test:manual:mojmap:1.20.1
npm run test:manual:mojmap:1.19.4
```

--------------------------------

### index_mod Tool

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/CLAUDE.md

Creates a full-text search index for decompiled mod source code using SQLite FTS5. This enables significantly faster searching with the `search_mod_indexed` tool. Indexing can be forced to re-index existing data.

```APIDOC
## index_mod Tool

### Description
Creates a full-text search index for decompiled mod source code using SQLite FTS5. This process significantly speeds up subsequent searches performed by the `search_mod_indexed` tool.

### Method
`index_mod`

### Parameters
#### Input Parameters
- **modId** (string) - Required - The ID of the mod to index.
- **modVersion** (string) - Required - The version of the mod to index.
- **mapping** ('yarn' | 'mojmap') - Required - The mapping type used for the decompiled code.
- **force** (boolean) - Optional - If true, forces re-indexing even if an index already exists. Defaults to false.

### Request Example
```typescript
index_mod({
  modId: "meteor-client",
  modVersion: "0.5.8",
  mapping: "yarn",
  force: true
})
```

### Response
- **message** (string) - Confirmation message indicating the index creation process has started or completed.
```

--------------------------------

### Index Mod Tool Input

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/CLAUDE.md

Defines the input parameters for the `index_mod` tool, which creates a full-text search index for decompiled mod source code using SQLite FTS5. The `force` option can be used to re-index.

```typescript
{
  modId: string;
  modVersion: string;
  mapping: 'yarn' | 'mojmap';
  force?: boolean;
}
```

--------------------------------

### MCP Tools Reference

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/CLAUDE.md

Reference for MCP Tools, categorized into Phase 1 (Core), Phase 2 (Advanced Analysis), and Phase 3 (Mod Analysis).

```APIDOC
## MCP Tools Reference

### Phase 1 Tools (Core)
1. **`get_minecraft_source`** - Get decompiled source for a Minecraft class
2. **`decompile_minecraft_version`** - Trigger full decompilation of a version. Pass `jarPath` to point at a local Forge/NeoForge **patched** MC JAR (cache key convention: `<mc>-<loader>-<loaderVersion>`, e.g. `1.21.1-neoforge-21.1.72`); in this mode `mapping` must be `'mojmap'` (Forge/NeoForge dev environments are mojmap-only post-1.17). Sources JARs (no `.class` entries) are extracted directly; compiled JARs run through VineFlower. `force: true` wipes the decompiled dir, the job row, and the FTS5 index for that (version, mapping).
3. **`list_minecraft_versions`** - List available and cached versions
4. **`get_registry_data`** - Get registry data (blocks, items, entities)

### Phase 2 Tools (Advanced Analysis)
5. **`remap_mod_jar`** - Remap Fabric mod JARs to human-readable names
6. **`find_mapping`** - Lookup symbol mappings between namespaces
7. **`search_minecraft_code`** - Regex search in decompiled source
8. **`compare_versions`** - Compare classes/registries between versions
9. **`analyze_mixin`** - Analyze and validate Mixin code
10. **`validate_access_widener`** - Validate access widener files
11. **`compare_versions_detailed`** - AST-level version comparison
12. **`index_minecraft_version`** - Create full-text search index
13. **`search_indexed`** - Fast FTS5 search on indexed versions
14. **`get_documentation`** - Get documentation for a class
15. **`search_documentation`** - Search documentation

### Phase 3 Tools (Mod Analysis)
16. **`analyze_mod_jar`** - Analyze third-party mod JAR files
17. **`decompile_mod_jar`** - Decompile mod JARs to readable Java source
18. **`search_mod_code`** - Search decompiled mod source code
19. **`index_mod`** - Create full-text search index for mod source
20. **`search_mod_indexed`** - Fast FTS5 search on indexed mod source
```

--------------------------------

### Run MCP Transport Matrix Tests

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/__tests__/manual/README.md

Execute only the MCP transport end-to-end matrix tests.

```bash
npm run test:manual:mcp
```

--------------------------------

### Analyze Mod JAR with analyze_mod_jar

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/CLAUDE.md

Analyzes a mod JAR file to extract comprehensive metadata, including mod information, compatibility, dependencies, entry points, and mixin configurations. Supports Fabric, Quilt, Forge, and NeoForge mods. The `jarPath` parameter is required.

```typescript
{
  jarPath: string;
  includeAllClasses?: boolean;
  includeRawMetadata?: boolean;
}
```

```typescript
analyze_mod_jar({ jarPath: "C:/mods/meteor-client-1.21.10-32.jar" })
```

--------------------------------

### Search Mod Indexed Tool Input

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/CLAUDE.md

Specifies the input for the `search_mod_indexed` tool, which performs fast full-text searches using a pre-built mod index. Supports FTS5 syntax and optional type filtering. A limit can be set for results.

```typescript
{
  query: string;
  modId: string;
  modVersion: string;
  mapping: 'yarn' | 'mojmap';
  types?: Array<'class' | 'method' | 'field'>;
  limit?: number;
}
```

--------------------------------

### Decompile Mod JAR Tool Input

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/CLAUDE.md

Defines the input parameters for the `decompile_mod_jar` tool, which decompiles a mod JAR file to readable Java source code. Supports both WSL and Windows path formats.

```typescript
{
  jarPath: string;
  mapping: 'yarn' | 'mojmap';
  modId?: string;
  modVersion?: string;
}
```

--------------------------------

### search_mod_indexed Tool

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/CLAUDE.md

Performs fast full-text searches on a pre-built index of decompiled mod source code. Supports FTS5 query syntax and allows filtering by element types. Requires mod identification and mapping type.

```APIDOC
## search_mod_indexed Tool

### Description
Performs fast full-text searches using a pre-built index of decompiled mod source code. This tool leverages SQLite FTS5 syntax for powerful querying and allows for optional filtering by element types.

### Method
`search_mod_indexed`

### Parameters
#### Input Parameters
- **query** (string) - Required - The search query using FTS5 syntax (e.g., `AND`, `OR`, `NOT`, `"phrase"`, `prefix*`).
- **modId** (string) - Required - The ID of the mod whose index should be searched.
- **modVersion** (string) - Required - The version of the mod whose index should be searched.
- **mapping** ('yarn' | 'mojmap') - Required - The mapping type used for the decompiled code.
- **types** (Array<'class' | 'method' | 'field'>) - Optional - An array of element types to filter the search results (e.g., `['class', 'method']`).
- **limit** (number) - Optional - The maximum number of results to return. Defaults to 100.

### Request Example
```typescript
search_mod_indexed({
  query: "packet AND send",
  modId: "meteor-client",
  modVersion: "0.5.8",
  mapping: "yarn"
})
```

### Response
- **results** (Array<string>) - A list of strings representing the found matches based on the FTS5 query.
```

--------------------------------

### decompile_mod_jar Tool

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/CLAUDE.md

Decompiles a mod JAR file into readable Java source code. It supports automatic detection of mod metadata and utilizes caching for efficiency. The tool integrates with VineFlower for decompilation and is compatible with WSL.

```APIDOC
## decompile_mod_jar Tool

### Description
Decompiles a mod JAR file to readable Java source code. Supports both original (intermediary) and remapped JARs, with auto-detection of mod ID and version. Decompiled sources are cached for future use.

### Method
`decompile_mod_jar`

### Parameters
#### Input Parameters
- **jarPath** (string) - Required - Path to the mod JAR file (supports WSL or Windows path formats).
- **mapping** ('yarn' | 'mojmap') - Required - The type of mapping used in the JAR (e.g., 'yarn' or 'mojmap').
- **modId** (string) - Optional - The ID of the mod. If not provided, it will be auto-detected from the JAR metadata.
- **modVersion** (string) - Optional - The version of the mod. If not provided, it will be auto-detected from the JAR metadata.

### Request Example
```typescript
decompile_mod_jar({
  jarPath: "C:/mods/meteor-remapped-yarn.jar",
  mapping: "yarn"
})
```

### Response
- **decompiledSourceDirectory** (string) - Path to the directory containing the decompiled Java source code.
- **modId** (string) - The detected or provided mod ID.
- **modVersion** (string) - The detected or provided mod version.
```

--------------------------------

### search_mod_code Tool

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/CLAUDE.md

Searches through decompiled mod source code for classes, methods, fields, or specific content using regular expressions or literal strings. Requires mod identification and mapping type.

```APIDOC
## search_mod_code Tool

### Description
Searches for classes, methods, fields, or content within decompiled mod source code using regex patterns or literal strings. This tool operates on decompiled code and requires specific mod identification.

### Method
`search_mod_code`

### Parameters
#### Input Parameters
- **modId** (string) - Required - The ID of the mod to search within.
- **modVersion** (string) - Required - The version of the mod to search within.
- **query** (string) - Required - The regex pattern or literal string to search for.
- **searchType** ('class' | 'method' | 'field' | 'content' | 'all') - Required - Specifies the type of element to search for (e.g., 'class', 'method', 'field', 'content', or 'all').
- **mapping** ('yarn' | 'mojmap') - Required - The mapping type used for the decompiled code.
- **limit** (number) - Optional - The maximum number of results to return. Defaults to 50.

### Request Example
```typescript
search_mod_code({
  modId: "meteor-client",
  modVersion: "0.5.8",
  query: "onTick",
  searchType: "method",
  mapping: "yarn"
})
```

### Response
- **results** (Array<string>) - A list of strings representing the found matches.
```

--------------------------------

### analyze_mod_jar

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/CLAUDE.md

Analyzes a mod JAR file to extract comprehensive metadata. Supports Fabric, Quilt, Forge, and NeoForge mods.

```APIDOC
## analyze_mod_jar

### Description
Analyzes a mod JAR file to extract comprehensive metadata. Supports Fabric, Quilt, Forge, and NeoForge mods.

### Input
```typescript
{
  jarPath: string;           // Local path to the mod JAR file
  includeAllClasses?: boolean; // Include full class list (can be large)
  includeRawMetadata?: boolean; // Include raw fabric.mod.json, mixin configs
}
```

### Output
Includes:
- **Mod metadata**: ID, version, name, description, authors, license
- **Compatibility**: Minecraft version, loader version, Java version, environment (client/server)
- **Dependencies**: Required, optional, incompatible mods with version constraints
- **Entry points**: Main, client, server initializers with class references
- **Mixins**: Config files, packages, mixin class lists (common/client/server)
- **Class analysis**: Total count, package breakdown, mixin detection via bytecode
- **Nested JARs**: Jar-in-Jar dependencies

### Example usage
```
analyze_mod_jar({ jarPath: "C:/mods/meteor-client-1.21.10-32.jar" })
```

Returns JSON with full mod analysis including detected loader type, all dependencies, entry points, and mixin configurations.
```

--------------------------------

### Search Mod Code Tool Input

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/CLAUDE.md

Specifies the input for the `search_mod_code` tool, used to find classes, methods, fields, or content within decompiled mod source code using regex. A limit can be set for the number of results.

```typescript
{
  modId: string;
  modVersion: string;
  query: string;
  searchType: 'class' | 'method' | 'field' | 'content' | 'all';
  mapping: 'yarn' | 'mojmap';
  limit?: number;
}
```

--------------------------------

### Remap Official to Intermediary JAR

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/CLAUDE.md

First step in yarn mapping remapping: remap from official obfuscated names to Fabric's stable intermediary names. This uses the tinyRemapper.

```typescript
// Step 1: official → intermediary
const intermediaryJar = await this.tinyRemapper.remap(
  inputJar,
  intermediaryPath,
  intermediateMappings,
  'official', 'intermediary'
);
```

--------------------------------

### Remap Intermediary to Yarn JAR

Source: https://github.com/mcdxai/minecraft-dev-mcp/blob/main/CLAUDE.md

Second step in yarn mapping remapping: remap from intermediary names to human-readable Yarn names. This uses the tinyRemapper.

```typescript
// Step 2: intermediary → named (yarn)
const yarnJar = await this.tinyRemapper.remap(
  intermediaryJar,
  outputPath,
  yarnMappings,
  'intermediary', 'named'
);
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.