CNPC JavaDoc MCP Server

An MCP (Model Context Protocol) server that provides CustomNPCs (CNPC) JavaDoc API lookups. Lets AI coding agents search CNPC class methods, fields, and inheritance hierarchies across multiple Minecraft versions and forks.

What It Does

CustomNPCs is a Minecraft mod with a rich Java scripting API spanning 10+ Minecraft versions and 3 forks. This MCP server lets your AI agent:

Search CNPC JavaDoc for methods and fields with boolean expressions, column modifiers, and scoring
View class hierarchies — inheritance chains and direct subclasses
Auto-build caches on first use — fetches and parses JavaDoc HTML from kodevelopment.nl and GitHub Pages
Full interoperability with AI-MCP-NativeMinecraftAccess — identical search syntax

Use Cases

| Scenario | How This Helps | |----------|---------------| | CNPC script development | Look up method signatures, parameters, and return types | | Class hierarchy exploration | Find parent interfaces and classes for API types | | Cross-version porting | Compare API surfaces between MC versions | | Fork development | Query CustomNPC+ or Goodbird fork APIs |

MCP Tools

| Tool | Description | |------|-------------| | search | Search CNPC JavaDoc methods/fields with boolean expressions | | show-hierarchy | Display class inheritance chain and direct subclasses |

Quick Install

Prerequisites

Node.js ≥ 18

Step 1: Clone & Build

git clone https://github.com/SaltfishSheep/AI-MCP-CNPCAPIAccess.git
cd AI-MCP-CNPCAPIAccess
npm install
npm run build

Step 2: Add to Your MCP Client

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "cnpc-javadoc": {
      "command": "node",
      "args": ["/absolute/path/to/AI-MCP-CNPCAPIAccess/dist/index.js"]
    }
  }
}

OpenCode (opencode.json):

{
  "mcp": {
    "cnpc-javadoc": {
      "type": "local",
      "command": ["node", "/absolute/path/to/AI-MCP-CNPCAPIAccess/dist/index.js"],
      "enabled": true
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "cnpc-javadoc": {
      "command": "node",
      "args": ["/absolute/path/to/AI-MCP-CNPCAPIAccess/dist/index.js"]
    }
  }
}

Replace /absolute/path/to/ with the actual path where you cloned the repo.

Usage

Search Tool

search(mc_version="1.12.2", expression="ICustomNpc")
search(mc_version="1.12.2", expression="say:method")
search(mc_version="1.12.2", expression="health:field")

Example queries:

| Query | Description | |-------|-------------| | ICustomNpc | All entries mentioning ICustomNpc | | say:method | Methods with "say" in name | | health:field | Fields with "health" in name | | ICustomNpc::classname | Class name exactly "ICustomNpc" | | noppes/npcs/api/entity:package | All entries under entity package | | ()Z:desc | Methods returning boolean | | get:method&static::modifier | Static methods containing "get" | | {dialog\|quest}&get | Dialog or quest entries with "get" | | output="%class%" | Deduplicated class list |

Expression syntax:

| Syntax | Meaning | Example | |--------|---------|---------| | term | Case-insensitive substring match | npc | | term:modifier | Restrict to specific columns | say:method | | term::modifier | Strong modifier — exact match | ICustomNpc::classname | | noppes.npcs.api.ICustomNpc | Dot notation → / and $ paths | noppes.npcs.api.entity.ICustomNpc | | & | AND (higher precedence) | npc&say | | \| | OR | dialog\|quest | | {} | Grouping | {a\|b}&c |

Modifiers:

| Modifier | Searches | Description | |----------|----------|-------------| | all | class, name, desc, access, is_static | Default (excludes sideonly) | | class | class | Full class path | | classname | class name after last / | Class name only | | package | package before last / | Package only | | name | name | Method/field names | | method | name, type=method only | Methods only | | field | name, type=field only | Fields only | | desc | desc | JVM descriptors | | modifier | access, is_static | Access/static status | | side | sideonly | Always "common" for CNPC |

Show-Hierarchy Tool

show-hierarchy(mc_version="1.12.2", class="noppes/npcs/api/entity/ICustomNpc")

Example output: `` Hierarchy: ICustomNpc -> IEntityLiving -> IEntityLivingBase -> IEntity -> Object Subs: ICustomNpc ``

The tool returns two sections:

Hierarchy: inheritance chain from the class up to root (-> separated)
Subs: direct subclasses (if any)

Dot notation is also accepted: "noppes.npcs.api.entity.ICustomNpc".

Supported Versions

| Source | Versions | Parser Profile | |--------|----------|----------------| | kodevelopment.nl | 1.7.10 | kodevelopment-legacy | | kodevelopment.nl | 1.8.9, 1.9.4 | kodevelopment-old | | kodevelopment.nl | 1.10.2, 1.11.2 | kodevelopment-mid | | kodevelopment.nl | 1.12.2 | kodevelopment-modern | | kodevelopment.nl | 1.16.5, 1.18.2 | kodevelopment-latest | | CustomNPC+ (Kamkeel) | cnpc+:1.7.10 | kodevelopment-legacy | | Goodbird | 1.20.1 | goodbird | | BetaZavr | BetaZavr:1.12.2 | kodevelopment-modern | | BetaZavr | BetaZavr:1.20.1 | goodbird |

Note: CNPC has no official releases for MC 1.8–1.8.8, 1.9–1.9.3, 1.11, or 1.13–1.15.2.

Version Format

Standard: "1.12.2", "1.7.10", "1.20.1"
Fork: "cnpc+:1.7.10" (CustomNPC+), "BetaZavr:1.12.2", "BetaZavr:1.20.1"

How It Works

On first search for a given CNPC version, the server fetches JavaDoc HTML from kodevelopment.nl or GitHub Pages
It parses class pages using version-specific HTML parsers (6 profile names routing to 3 parser implementations)
Methods and fields are extracted with JVM descriptors and stored as CSV cache
Class hierarchy is extracted and stored as JSON cache
Subsequent searches use the cached data (validated against package.json version)

Project Structure

AI-MCP-CNPCAPIAccess/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts              # MCP server entry point (search + show-hierarchy)
│   ├── types.ts              # TypeScript type definitions
│   ├── util.ts               # Shared utilities (CSV parsing, package version)
│   ├── version-table.ts      # CNPC version → doc URL + parser profile mapping
│   ├── builder/
│   │   ├── index.ts          # buildJavadocCache entry point
│   │   ├── download.ts       # HTTP fetch with retry
│   │   ├── javadoc-parser.ts # 3-implementation JavaDoc HTML parser (6 profiles)
│   │   ├── descriptor.ts     # Java type → JVM descriptor converter
│   │   └── cache.ts          # CSV + hierarchy JSON cache writer
│   └── search/
│       ├── index.ts          # Re-exports
│       ├── expression.ts     # Boolean expression parser (AND/OR/braces)
│       └── csv-reader.ts     # CSV reader + search
├── dist/                     # Built JavaScript (entry: dist/index.js)
└── .javadoc-caches/          # Generated cache files (gitignored)

License

MIT License — see LICENSE.

Data Sources

kodevelopment.nl — Official CustomNPCs JavaDoc (1.7.10–1.18.2)
Kamkeel GitHub Pages — CustomNPC+ fork JavaDoc (1.7.10)
Goodbird GitHub Pages — Unofficial CNPC port JavaDoc (1.20.1)

CNPC JavaDoc MCP Server