# Pumpkin API MCP Server

An MCP (Model Context Protocol) server designed to help LLMs (like Claude, Cursor, Windsurf) understand, navigate, and develop plugins for the [Pumpkin Minecraft Server](https://github.com/Pumpkin-MC/Pumpkin).

This MCP server provides intelligent tools to search the Pumpkin Plugin API, read WebAssembly Interface Types (WIT) definitions, and even scaffold new Wasm plugins instantly.

## 🚀 Features

- **Read API & WIT Files:** Safely explore the `crates/pumpkin-plugin-api` and `crates/pumpkin-plugin-wit` directories.
- **Smart Search:** Regex-enabled search across the entire API and WIT codebase.
- **Code Block Extraction:** Extract specific line ranges to prevent LLM context bloat.
- **Auto-Documentation Extraction:** Instantly extract doc comments (`///`) and public signatures from Rust/WIT files to get a quick overview of any module.
- **Plugin Scaffolding:** Generate a fully configured `wasm32-wasip1` boilerplate project with a single command.

## 🛠️ Setup

1. **Clone the repository** (if you haven't already):
   Ensure you have pulled the submodules, as the WIT definitions are stored in one.
   ```bash
   git clone --recurse-submodules https://github.com/YOUR_USERNAME/Pumpkin-MCP.git
   cd Pumpkin-MCP
   ```

2. **Install Dependencies:**
   Make sure you have Node.js installed.
   ```bash
   npm install
   ```

3. **Build the Server:**
   Compile the TypeScript code to JavaScript.
   ```bash
   npm run build
   ```

## 🔌 How to Use in LLM Clients

To use this MCP server, you need to configure your LLM client to point to the built `dist/index.js` file.

### Cursor
1. Go to **Settings > Features > MCP**.
2. Click **+ Add new MCP server**.
3. Set the type to `command`.
4. Set the name to `pumpkin-api`.
5. Set the command to:
   ```bash
   node /absolute/path/to/Pumpkin-MCP/dist/index.js
   ```
   *(Make sure to replace `/absolute/path/to/` with the actual path to this repository on your computer).*

### Claude Desktop
Edit your `claude_desktop_config.json` file to include:
```json
{
  "mcpServers": {
    "pumpkin-api-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/Pumpkin-MCP/dist/index.js"
      ]
    }
  }
}
```

## 🤖 Available Tools for LLMs

Once configured, your LLM will automatically have access to these tools:
- `list_api_files`: Lists all files in the API and WIT directories.
- `read_api_file`: Reads the full content of an API or WIT file.
- `search_api_code`: Searches for keywords, structs, or traits using Regex.
- `read_code_block`: Extracts specific line ranges from a file.
- `get_module_docs`: Extracts only the documentation comments and public exports from a file.
- `scaffold_plugin`: Generates a standard Pumpkin plugin boilerplate configured for WebAssembly.

## 🔄 Keeping the API Updated

This repository includes a GitHub Actions workflow (`.github/workflows/sync.yml`) that runs daily. It automatically syncs the `crates/pumpkin-plugin-api` and `crates/pumpkin-plugin-wit` folders directly from the upstream Pumpkin repository to ensure your LLM always has the latest context.