{"id":35357585,"url":"https://github.com/ogmatrix/mcmodding-mcp","last_synced_at":"2026-01-13T23:01:31.195Z","repository":{"id":328629760,"uuid":"1113883126","full_name":"OGMatrix/mcmodding-mcp","owner":"OGMatrix","description":"mcmodding-mcp is a Model Context Protocol (MCP) server that gives AI assistants like Claude direct access to Minecraft modding documentation. Instead of relying on potentially outdated training data, your AI assistant can search real documentation, find code examples, and explain concepts accurately.","archived":false,"fork":false,"pushed_at":"2026-01-01T21:27:25.000Z","size":717,"stargazers_count":6,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"dev","last_synced_at":"2026-01-07T07:23:40.467Z","etag":null,"topics":["mc","mcp","minecraft","modding"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/mcmodding-mcp/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OGMatrix.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-10T15:42:27.000Z","updated_at":"2026-01-01T21:17:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/OGMatrix/mcmodding-mcp","commit_stats":null,"previous_names":["ogmatrix/mcmodding-mcp"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/OGMatrix/mcmodding-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OGMatrix%2Fmcmodding-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OGMatrix%2Fmcmodding-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OGMatrix%2Fmcmodding-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OGMatrix%2Fmcmodding-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OGMatrix","download_url":"https://codeload.github.com/OGMatrix/mcmodding-mcp/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OGMatrix%2Fmcmodding-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28405148,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T21:51:37.118Z","status":"ssl_error","status_checked_at":"2026-01-13T21:45:14.585Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mc","mcp","minecraft","modding"],"created_at":"2026-01-01T23:30:46.711Z","updated_at":"2026-01-13T23:01:31.190Z","avatar_url":"https://github.com/OGMatrix.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"docs/logo.png\" alt=\"MCModding-MCP Logo\" width=\"180\" /\u003e\n\n# MCModding-MCP\n\n### 🤖 AI-Powered Minecraft Modding Documentation Server\n\n_Give your AI assistant real-time access to Fabric \u0026 NeoForge documentation_\n\n\u003cbr /\u003e\n\n[![npm version](https://img.shields.io/npm/v/mcmodding-mcp?style=for-the-badge\u0026logo=npm\u0026logoColor=white\u0026color=CB3837)](https://www.npmjs.com/package/mcmodding-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/mcmodding-mcp?style=for-the-badge\u0026logo=npm\u0026logoColor=white\u0026color=blue)](https://www.npmjs.com/package/mcmodding-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green?style=for-the-badge\u0026logo=opensourceinitiative\u0026logoColor=white)](https://opensource.org/licenses/MIT)\n[![CI](https://img.shields.io/github/actions/workflow/status/OGMatrix/mcmodding-mcp/ci.yml?style=for-the-badge\u0026logo=github\u0026label=CI)](https://github.com/OGMatrix/mcmodding-mcp/actions/workflows/ci.yml)\n\n\u003cbr /\u003e\n\n[![GitHub stars](https://img.shields.io/github/stars/OGMatrix/mcmodding-mcp?style=flat-square\u0026logo=github\u0026label=Stars)](https://github.com/OGMatrix/mcmodding-mcp/stargazers)\n[![GitHub issues](https://img.shields.io/github/issues/OGMatrix/mcmodding-mcp?style=flat-square\u0026logo=github\u0026label=Issues)](https://github.com/OGMatrix/mcmodding-mcp/issues)\n[![GitHub last commit](https://img.shields.io/github/last-commit/OGMatrix/mcmodding-mcp?style=flat-square\u0026logo=github\u0026label=Last%20Commit)](https://github.com/OGMatrix/mcmodding-mcp/commits)\n[![Node.js](https://img.shields.io/badge/Node.js-≥20.0.0-339933?style=flat-square\u0026logo=node.js\u0026logoColor=white)](https://nodejs.org/)\n\n\u003cbr /\u003e\n\n[📖 Documentation](#available-tools) • [🚀 Quick Start](#quick-start) • [💡 Features](#features) • [🤝 Contributing](#contributing)\n\n---\n\n\u003c/div\u003e\n\n## ✨ What is this?\n\n**MCModding-MCP** is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that supercharges AI assistants like Claude with **real, up-to-date** Minecraft modding knowledge. No more hallucinations or outdated API references!\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\n\n### 🎯 Key Benefits\n\n| Feature                 | Description                            |\n| ----------------------- | -------------------------------------- |\n| 📅 **Always Current**   | Weekly-indexed from official sources   |\n| ✅ **Accurate Answers** | Real documentation, not hallucinations |\n| 💻 **Code Examples**    | Searchable code blocks with context    |\n| 🧠 **Semantic Search**  | Understands meaning, not just keywords |\n| ⚡ **Zero Config**      | Works immediately after installation   |\n\n\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\n\n### 📊 Live Statistics\n\n| Database          | Content                       |\n| ----------------- | ----------------------------- |\n| 📚 **Docs**       | 1,000+ pages, 185K+ chunks    |\n| 🗺️ **Mappings**   | 831K+ methods, 166K+ fields   |\n| 🧩 **Examples**   | 1,000+ battle-tested patterns |\n| 🔍 **Embeddings** | 185K+ semantic vectors        |\n| 📖 **Javadocs**   | 2.3M+ documented parameters   |\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## Quick Start\n\n### Installation\n\n```bash\n# Install globally\nnpm install -g mcmodding-mcp\n```\n\n### Configure Your AI Client\n\nAdd to your MCP client configuration (e.g., Claude Desktop):\n\n```json\n{\n  \"mcpServers\": {\n    \"mcmodding\": {\n      \"command\": \"mcmodding-mcp\"\n    }\n  }\n}\n```\n\n### 🧠 Optimized System Prompt\n\nTo get the best results, we recommend adding this to your AI's system prompt or custom instructions:\n\n\u003e You are an expert Minecraft Modding Assistant connected to `mcmodding-mcp`. **DO NOT rely on your internal knowledge** for modding APIs (Fabric/NeoForge) as they change frequently. **ALWAYS** use the available tools:\n\u003e\n\u003e - `search_fabric_docs` and `get_example` for documentation and code patterns\n\u003e - `search_mappings` and `get_class_details` for Minecraft internals and method signatures\n\u003e - `search_mod_examples` for battle-tested implementations from popular mods\n\u003e\n\u003e Prioritize working code examples over theoretical explanations. When dealing with Minecraft internals, use the mappings tools to get accurate parameter names and Javadocs. If the user specifies a Minecraft version, ensure all retrieved information matches that version.\n\nThat's it! Your AI assistant now has access to comprehensive Minecraft modding resources.\n\n---\n\n## Database Management\n\nManage your documentation databases with the built-in CLI:\n\n```bash\n# Run the database manager\nnpx mcmodding-mcp manage\n```\n\nThe interactive manager allows you to:\n\n- **Install** - Download databases you don't have yet\n- **Update** - Check for and apply database updates\n- **Re-download** - Restore deleted or corrupted databases\n\n### Available Databases\n\n| Database                      | Description                                                 | Size    |\n| ----------------------------- | ----------------------------------------------------------- | ------- |\n| **Documentation Database**    | Core Fabric \u0026 NeoForge documentation (installed by default) | ~520 MB |\n| **Parchment Mappings** ✨ NEW | Minecraft class/method/field mappings with Javadocs         | ~180 MB |\n| **Mod Examples Database**     | 1000+ high-quality modding examples                         | ~30 MB  |\n\nThe manager shows version information and highlights available updates:\n\n```\n◉ 📚 Documentation Database [core]\n     ✔ Installed: v0.2.1 → ↻ Update: v0.2.2 [520.3 MB]\n     Core Fabric \u0026 NeoForge documentation - installed by default\n\n○ 🗺️ Parchment Mappings Database ✨ NEW\n     ⚠ Not installed → Available: v0.1.0 [178.5 MB]\n     Minecraft class/method/field names with parameter names and Javadocs\n\n○ 🧩 Mod Examples Database\n     ⚠ Not installed → Available: v0.1.0 [28.1 MB]\n     1000+ high-quality modding examples for Fabric \u0026 NeoForge\n```\n\n---\n\n## Available Tools\n\nThe MCP server provides powerful tools across three categories:\n\n### 📖 Documentation Tools\n\n#### `search_fabric_docs`\n\nSearch documentation with smart filtering.\n\n```typescript\n// Example: Find information about item registration\n{\n  query: \"how to register custom items\",\n  category: \"items\",           // Optional filter\n  loader: \"fabric\",            // fabric | neoforge\n  minecraft_version: \"1.21.10\"  // Optional version filter\n}\n```\n\n#### `get_example`\n\nGet working code examples for any topic.\n\n```typescript\n// Example: Get block registration code\n{\n  topic: \"custom block with block entity\",\n  language: \"java\",\n  loader: \"fabric\"\n}\n```\n\n#### `explain_fabric_concept`\n\nGet detailed explanations of modding concepts with related resources.\n\n```typescript\n// Example: Understand mixins\n{\n  concept: 'mixins';\n}\n```\n\n#### `get_minecraft_version`\n\nGet current Minecraft version information.\n\n```typescript\n// Get latest version\n{\n  type: 'latest';\n}\n\n// Get all indexed versions\n{\n  type: 'all';\n}\n```\n\n---\n\n### 🗺️ Parchment Mappings Tools ✨ NEW\n\n_Requires Parchment Mappings database - install via `npx mcmodding-mcp manage`_\n\n#### `search_mappings`\n\nSearch Minecraft class, method, and field mappings with parameter names and Javadocs.\n\n```typescript\n// Example: Find block-related classes and methods\n{\n  query: \"BlockEntity\",\n  type: \"class\",              // class | method | field | all\n  minecraft_version: \"1.21.10\",\n  include_javadoc: true\n}\n```\n\n#### `get_class_details`\n\nGet comprehensive information about a Minecraft class including all methods and fields.\n\n```typescript\n// Example: Explore the Block class\n{\n  class_name: \"net.minecraft.world.level.block.Block\",\n  include_methods: true,\n  include_fields: true\n}\n```\n\n#### `lookup_obfuscated`\n\nLook up deobfuscated names from obfuscated identifiers (useful for crash logs).\n\n```typescript\n// Example: Decode an obfuscated method name\n{\n  obfuscated_name: 'm_46859_';\n}\n```\n\n#### `get_method_signature`\n\nGet the full signature of a method including all parameter names and types.\n\n```typescript\n// Example: Get method details\n{\n  class_name: \"Block\",\n  method_name: \"onPlace\"\n}\n```\n\n#### `browse_package`\n\nDiscover classes in a Minecraft package.\n\n```typescript\n// Example: Browse block package\n{\n  package_name: 'net.minecraft.world.level.block';\n}\n```\n\n---\n\n### 🧩 Mod Examples Tools\n\n_Requires Mod Examples database - install via `npx mcmodding-mcp manage`_\n\n#### `search_mod_examples`\n\nSearch battle-tested code from popular mods like Create, Botania, and Applied Energistics 2.\n\n```typescript\n// Example: Find block entity implementations\n{\n  query: \"block entity tick\",\n  mod: \"Create\",              // Optional: filter by mod\n  category: \"tile-entities\",\n  complexity: \"intermediate\"\n}\n```\n\n#### `get_mod_example`\n\nGet detailed information about a specific example with full code and explanations.\n\n```typescript\n// Example: Get full details for an example\n{\n  id: 42,\n  include_related: true\n}\n```\n\n#### `list_canonical_mods`\n\nDiscover all indexed mods and their available examples.\n\n#### `list_mod_categories`\n\nBrowse available example categories (blocks, entities, rendering, etc.).\n\n---\n\n## Features\n\n### Hybrid Search Engine\n\nCombines multiple search strategies for best results:\n\n| Strategy                | Purpose                                 |\n| ----------------------- | --------------------------------------- |\n| **FTS5 Full-Text**      | Fast keyword matching with ranking      |\n| **Semantic Embeddings** | Understanding meaning and context       |\n| **Section Search**      | Finding relevant documentation sections |\n| **Code Search**         | Locating specific code patterns         |\n\n### Auto-Updates\n\nThe database automatically checks for updates on startup:\n\n- Compares local version with GitHub releases\n- Downloads new versions with hash verification\n- Creates backups before updating\n- Non-blocking - server starts immediately\n\n### Documentation Sources\n\nCurrently indexes:\n\n- [wiki.fabricmc.net](https://wiki.fabricmc.net) - Fabric Wiki (226+ pages)\n- [docs.fabricmc.net](https://docs.fabricmc.net) - Official Fabric Docs (266+ pages)\n- [docs.neoforged.net](https://docs.neoforged.net) - NeoForge Docs (512+ pages)\n\n---\n\n## For Developers\n\n### Development Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/OGMatrix/mcmodding-mcp.git\ncd mcmodding-mcp\n\n# Install dependencies\nnpm install\n\n# Run in development mode\nnpm run dev\n```\n\n### Build Commands\n\n```bash\n# Development\nnpm run dev              # Watch mode with hot reload\nnpm run typecheck        # TypeScript type checking\nnpm run lint             # ESLint\nnpm run test             # Run tests\nnpm run format           # Prettier formatting\n\n# Production\nnpm run build            # Build TypeScript\nnpm run build:prod       # Build with fresh documentation index\nnpm run index-docs       # Index documentation with embeddings\n\n# Database Management\nnpx mcmodding-mcp manage # Interactive database installer/updater\n```\n\n### Project Structure\n\n```\nmcmodding-mcp/\n├── src/\n│   ├── index.ts              # MCP server entry point\n│   ├── db-versioning.ts      # Auto-update system\n│   ├── indexer/\n│   │   ├── crawler.ts        # Documentation crawler\n│   │   ├── chunker.ts        # Text chunking\n│   │   ├── embeddings.ts     # Semantic embeddings\n│   │   ├── store.ts          # SQLite database\n│   │   └── sitemap.ts        # Sitemap parsing\n│   ├── services/\n│   │   ├── search-service.ts # Search logic\n│   │   └── concept-service.ts # Concept explanations\n│   └── tools/\n│       ├── searchDocs.ts     # search_fabric_docs handler\n│       ├── getExample.ts     # get_example handler\n│       └── explainConcept.ts # explain_fabric_concept handler\n├── scripts/\n│   └── index-docs.ts         # Documentation indexing script\n├── data/\n│   ├── mcmodding-docs.db     # SQLite database\n│   └── db-manifest.json      # Version manifest\n└── dist/                     # Compiled JavaScript\n```\n\n### Database Schema\n\n```sql\n-- Documents: Full documentation pages\nCREATE TABLE documents (\n  id INTEGER PRIMARY KEY,\n  url TEXT UNIQUE NOT NULL,\n  title TEXT NOT NULL,\n  content TEXT NOT NULL,\n  category TEXT NOT NULL,\n  loader TEXT NOT NULL,          -- fabric | neoforge | shared\n  minecraft_version TEXT,\n  hash TEXT NOT NULL             -- For change detection\n);\n\n-- Chunks: Searchable content units\nCREATE TABLE chunks (\n  id TEXT PRIMARY KEY,\n  document_id INTEGER NOT NULL,\n  chunk_type TEXT NOT NULL,      -- title | section | code | full\n  content TEXT NOT NULL,\n  section_heading TEXT,\n  code_language TEXT,\n  word_count INTEGER,\n  has_code BOOLEAN\n);\n\n-- Embeddings: Semantic search vectors\nCREATE TABLE embeddings (\n  chunk_id TEXT PRIMARY KEY,\n  embedding BLOB NOT NULL,       -- 384-dim Float32Array\n  dimension INTEGER NOT NULL,\n  model TEXT NOT NULL            -- Xenova/all-MiniLM-L6-v2\n);\n\n-- FTS5 indexes for fast text search\nCREATE VIRTUAL TABLE documents_fts USING fts5(...);\nCREATE VIRTUAL TABLE chunks_fts USING fts5(...);\n```\n\n---\n\n## Release Workflow\n\nThis project uses [release-please](https://github.com/googleapis/release-please) for automated releases.\n\n### Branch Strategy\n\n| Branch | Purpose             |\n| ------ | ------------------- |\n| `dev`  | Active development  |\n| `prod` | Production releases |\n\n### How It Works\n\n1. Push commits to `dev` using [conventional commits](https://www.conventionalcommits.org/)\n2. Release-please maintains a Release PR (`dev` → `prod`)\n3. When merged, automatic release: npm publish + GitHub release + database upload\n4. Changes sync back to `dev`\n\nSee [RELEASE_WORKFLOW.md](RELEASE_WORKFLOW.md) for complete details.\n\n---\n\n## Configuration\n\n### Environment Variables\n\n| Variable          | Description             | Default                    |\n| ----------------- | ----------------------- | -------------------------- |\n| `DB_PATH`         | Custom database path    | `./data/mcmodding-docs.db` |\n| `GITHUB_REPO_URL` | Custom repo for updates | Auto-detected              |\n| `MCP_DEBUG`       | Enable debug logging    | `false`                    |\n\n### Disabling Auto-Updates\n\nSet `DB_PATH` to a custom location to manage updates manually:\n\n```bash\nDB_PATH=/path/to/my/database.db mcmodding-mcp\n```\n\n---\n\n## 💡 Share Your Ideas!\n\nWe're actively developing mcmodding-mcp and want to hear from you!\n\n### Have an Idea?\n\n- **Feature requests** - What tools would make your modding easier?\n- **New documentation sources** - Know a great modding resource we should index?\n- **Workflow improvements** - How could the tools work better for your use case?\n\n👉 [Open a Feature Request](https://github.com/OGMatrix/mcmodding-mcp/issues/new?template=feature_request.yml)\n\n### Found a Bug?\n\n- Incorrect search results?\n- Missing or outdated documentation?\n- Tool not working as expected?\n\n👉 [Report a Bug](https://github.com/OGMatrix/mcmodding-mcp/issues/new?template=bug_report.yml)\n\n### Share Your Experience\n\nUsing mcmodding-mcp for a cool project? We'd love to hear about it! Share your story in [Discussions](https://github.com/OGMatrix/mcmodding-mcp/discussions).\n\n---\n\n## Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Quick Contribution Guide\n\n1. Fork the repository\n2. Create a feature branch from `dev`\n3. Make changes with conventional commits\n4. Submit a PR to `dev`\n\n---\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes and releases.\n\n---\n\n## Acknowledgments\n\n- [Fabric Documentation](https://docs.fabricmc.net/) - Official Fabric documentation\n- [Fabric Wiki](https://wiki.fabricmc.net/) - Community wiki\n- [NeoForge Documentation](https://docs.neoforged.net/) - Official NeoForge documentation\n- [ParchmentMC](https://parchmentmc.org/) - Parameter names and Javadoc mappings\n- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification\n- [Transformers.js](https://huggingface.co/docs/transformers.js) - Local ML embeddings\n- [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) - Fast SQLite bindings\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cbr /\u003e\n\n**🎮 Built with ❤️ for the Minecraft modding community**\n\n\u003cbr /\u003e\n\n[![Made with TypeScript](https://img.shields.io/badge/Made%20with-TypeScript-3178C6?style=for-the-badge\u0026logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![Powered by SQLite](https://img.shields.io/badge/Powered%20by-SQLite-003B57?style=for-the-badge\u0026logo=sqlite\u0026logoColor=white)](https://www.sqlite.org/)\n[![Uses MCP](https://img.shields.io/badge/Uses-Model%20Context%20Protocol-8B5CF6?style=for-the-badge)](https://modelcontextprotocol.io/)\n\n\u003cbr /\u003e\n\nIf you find this project useful, please consider giving it a ⭐!\n\n[⬆️ Back to Top](#mcmodding-mcp)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fogmatrix%2Fmcmodding-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fogmatrix%2Fmcmodding-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fogmatrix%2Fmcmodding-mcp/lists"}