English | 中文

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:

1. Hierarchy: inheritance chain from the class up to root (-> separated)
2. 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

1. On first search for a given CNPC version, the server fetches JavaDoc HTML from kodevelopment.nl or GitHub Pages
2. It parses class pages using version-specific HTML parsers (6 profile names routing to 3 parser implementations)
3. Methods and fields are extracted with JVM descriptors and stored as CSV cache
4. Class hierarchy is extracted and stored as JSON cache
5. 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)