NeoForge Dev MCP

NeoForge mod development MCP (Model Context Protocol) toolkit for Minecraft 1.21.1, providing AI assistants with documentation search, code examples, API references, and MDK templates.

Overview

This MCP server provides tools for NeoForge 1.21.1 mod development:

• 🔍 Documentation Search - Search official NeoForge documentation
• 📚 Code Examples - Get working code snippets for common patterns
• 📖 Concept Explanations - Understand NeoForge concepts and APIs
• 🔄 Migration Guides - Forge to NeoForge migration patterns
• 📦 MDK Templates - Ready-to-use template code

Skill vs MCP Responsibilities

This repository works together with neoforge-dev-1.21.1-skill:

Aspect	MCP (This Repo)	Skill Repository
Code Examples	✅ Real-time from docs	❌
MDK Templates	✅ Structured templates	❌
Documentation	✅ Searchable index	❌
Development Workflow	❌	✅ Process orchestration
Code Standards	❌	✅ Style guides & best practices
Debugging Guides	❌	✅ Troubleshooting & diagnostics
Release Workflow	❌	✅ Build & publish process

When to Use Which?

• Use MCP when you need: code examples, API docs, templates, migration patterns
• Use Skill when you need: workflow guidance, code review, debugging, release process

Repository Structure

neoforge-dev-1.21.1-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── db-versioning.ts      # Database version management
│   ├── indexer/              # Indexer modules
│   │   ├── store.ts          # SQLite data storage
│   │   ├── crawler.ts        # Documentation crawler
│   │   ├── chunker.ts        # Document chunking
│   │   ├── embeddings.ts     # Vector embeddings
│   │   ├── sitemap.ts        # Sitemap parser
│   │   └── types.ts          # Type definitions
│   ├── services/             # Service layer
│   │   ├── search-service.ts # Search service
│   │   └── concept-service.ts# Concept service
│   └── tools/                # MCP tools
│       ├── searchDocs.ts     # Document search
│       ├── getExample.ts     # Get examples
│       └── explainConcept.ts # Concept explanation
├── scripts/
│   └── index-docs.ts         # Document indexing script
├── data/                     # Data storage directory
├── package.json
├── tsconfig.json
└── README.md

Installation

From GitHub Packages

# Configure authentication (one-time)
echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN" >> ~/.npmrc

# Install
npm install @3453890470/neoforge-dev

From Source

git clone https://github.com/3453890470/neoforge-dev-1.21.1-mcp.git
cd neoforge-dev-1.21.1-mcp
npm install
npm run build

Usage

As MCP Server

Add to your MCP client configuration:

{
  "mcpServers": {
    "neoforge-mcp": {
      "command": "npx",
      "args": ["-y", "@3453890470/neoforge-dev"]
    }
  }
}

Development

# Run in development mode
npm run dev

# Build
npm run build

# Start server
npm start

Tool List

Tool	Description	Parameters
search_neoforge_docs	Search NeoForge documentation	query, category?, limit?
get_neoforge_example	Get code examples	topic, category?
explain_neoforge_concept	Explain NeoForge concepts	concept
get_forge_to_neoforge	Forge to NeoForge migration	forgeApi
get_mdk_template	Get MDK templates	feature
list_forge_migrations	List available migrations	category?

Supported Categories

• getting-started - Introduction and setup
• blocks - Block registration and customization
• items - Item registration and customization
• entities - Entity system
• gui - GUI and containers
• networking - Network communication
• data - Data components and attachments
• worldgen - World generation
• events - NeoForge event system
• capabilities - NeoForge capabilities
• registries - Registry system
• migrations - Migration guides
• advanced - Advanced topics

Version Matrix

Component	Version
Minecraft	1.21.1
NeoForge	21.1.x
Java	21+
Node.js	18+

Integration

OpenCode

{
  "mcpServers": {
    "neoforge-mcp": {
      "command": "npx",
      "args": ["-y", "@3453890470/neoforge-dev"]
    }
  }
}

Claude Desktop

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "neoforge-mcp": {
      "command": "npx",
      "args": ["-y", "@3453890470/neoforge-dev"]
    }
  }
}

Cursor IDE

// .cursor/config.json
{
  "mcp": {
    "servers": {
      "neoforge-mcp": {
        "command": "npx",
        "args": ["-y", "@3453890470/neoforge-dev"]
      }
    }
  }
}

Continue.dev

// ~/.continue/config.json
{
  "mcpServers": {
    "neoforge-mcp": {
      "command": "npx",
      "args": ["-y", "@3453890470/neoforge-dev"]
    }
  }
}

License

MIT License - see LICENSE for details.

Related Projects

• neoforge-dev-1.21.1-skill - Workflow & standards skill
• forge-dev-1.20.1-mcp - Forge 1.20.1 MCP
• forge-dev-1.20.1-skill - Forge 1.20.1 skill