[English](README.md) | [中文](README_zh-CN.md)

# CNPC JavaDoc MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 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](https://github.com/SaltfishSheep/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

```bash
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`):

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

**OpenCode** (`opencode.json`):

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

**Cursor** (`.cursor/mcp.json`):

```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](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)