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

MCP Tools

Related MCP server: CHECK-MODULE MCP Server

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:

Expression syntax:

Modifiers:

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

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)