{"_id":"@eliasnvx/hytale-mcp","_rev":"2-83f781e56be4569142b947424d456edc","name":"@eliasnvx/hytale-mcp","dist-tags":{"latest":"1.1.0"},"versions":{"0.1.2":{"name":"@eliasnvx/hytale-mcp","version":"0.1.2","_id":"@eliasnvx/hytale-mcp@0.1.2","maintainers":[{"name":"eliasnvx","email":"elias.nevx@gmail.com"}],"homepage":"https://github.com/eliasnvx/hytale-mcp#readme","bugs":{"url":"https://github.com/eliasnvx/hytale-mcp/issues"},"bin":{"hytale-mcp":"dist/index.js"},"dist":{"shasum":"73a2ad1ca466b419fa9f1bb6c84d48799e758337","tarball":"https://registry.npmjs.org/@eliasnvx/hytale-mcp/-/hytale-mcp-0.1.2.tgz","fileCount":78,"integrity":"sha512-nMo7m56kjCuv7zyxd/bj/kDqBSc/Ex0tt1HNOW27vtPBCqqo4lswp0OXk3wq+mpTjNzROrAYpa+VeGqIQ+fcdQ==","signatures":[{"sig":"MEUCIQCTjF2cOD3Gy8ILOsi3FIHY30S3XhO21QMQwTtn96GLYgIgeJ2MneeVQzPyoChR9gUufgF29O1t3wOg3TBMBPrPMY8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@eliasnvx%2fhytale-mcp@0.1.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":130486},"type":"module","gitHead":"45f2eab271ea1e0a104c5a3476e2c47c437ddd5a","scripts":{"dev":"tsx watch src/index.ts","lint":"eslint src/","test":"vitest run","build":"tsc","inspect":"npx @modelcontextprotocol/inspector dist/index.js","typecheck":"tsc --noEmit","test:watch":"vitest","cache:build":"tsx scripts/build-cache.ts","validate:data":"tsx scripts/validate-data.ts"},"_npmUser":{"name":"eliasnvx","email":"elias.nevx@gmail.com"},"repository":{"url":"git+https://github.com/eliasnvx/hytale-mcp.git","type":"git"},"_npmVersion":"10.9.8","description":"MCP server for Hytale mod development. Provides docs search, Java API reference, event/entity/block lookup, plugin and pack scaffolding, and manifest validation to AI coding assistants over the Model Context Protocol.","directories":{},"_nodeVersion":"22.23.1","dependencies":{"zod":"^4.4.3","lunr":"^2.3.9","mustache":"^4.2.0","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.22.5","eslint":"^10.6.0","vitest":"^4.1.9","typescript":"^6.0.3","@types/lunr":"^2.3.7","@types/node":"^26.1.0","@types/mustache":"^4.2.6","@vitest/coverage-v8":"^4.1.9","@typescript-eslint/parser":"^8.62.1","@typescript-eslint/eslint-plugin":"^8.62.1"},"_npmOperationalInternal":{"tmp":"tmp/hytale-mcp_0.1.2_1783085134542_0.17240340741024318","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@eliasnvx/hytale-mcp","version":"1.1.0","type":"module","repository":{"type":"git","url":"git+https://github.com/eliasnvx/hytale-mcp.git"},"bin":{"hytale-mcp":"dist/index.js"},"scripts":{"build":"tsc","dev":"tsx watch src/index.ts","test":"vitest run","test:watch":"vitest","lint":"eslint src/","typecheck":"tsc --noEmit","cache:build":"tsx scripts/build-cache.ts","validate:data":"tsx scripts/validate-data.ts","inspect":"npx @modelcontextprotocol/inspector dist/index.js"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","lunr":"^2.3.9","mustache":"^4.2.0","zod":"^4.4.3"},"devDependencies":{"@types/lunr":"^2.3.7","@types/mustache":"^4.2.6","@types/node":"^26.1.0","@typescript-eslint/eslint-plugin":"^8.62.1","@typescript-eslint/parser":"^8.62.1","@vitest/coverage-v8":"^4.1.9","eslint":"^10.6.0","tsx":"^4.22.5","typescript":"^6.0.3","vitest":"^4.1.9"},"_id":"@eliasnvx/hytale-mcp@1.1.0","gitHead":"9f06bd675b1c739064a375c81dcfcc912e179e01","description":"MCP server for Hytale mod development. Provides docs search, Java API reference, event/entity/block lookup, plugin and pack scaffolding, and manifest validation to AI coding assistants over the Model Context Protocol.","bugs":{"url":"https://github.com/eliasnvx/hytale-mcp/issues"},"homepage":"https://github.com/eliasnvx/hytale-mcp#readme","_nodeVersion":"22.23.1","_npmVersion":"10.9.8","dist":{"integrity":"sha512-w2GU6dYO8VDyg1vIlZ5YrtYbeG1QZK0EE8lQrkwJhtZsTGSUu07zDVEiR1/e8XjpAAtSst66A7epeSeO5UHhmg==","shasum":"ab127e1d7487471e4800dc9ee96bd79f8eada8e0","tarball":"https://registry.npmjs.org/@eliasnvx/hytale-mcp/-/hytale-mcp-1.1.0.tgz","fileCount":88,"unpackedSize":169308,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@eliasnvx%2fhytale-mcp@1.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCpgSO+WQ7Ppyep2PnRpvrJUAzWNXgX62nxkqWtjJosIAIgc9jtGfVyqCpnIdu479HUdmkzK80wlh8jMUNlwr5rPSM="}]},"_npmUser":{"name":"eliasnvx","email":"elias.nevx@gmail.com"},"directories":{},"maintainers":[{"name":"eliasnvx","email":"elias.nevx@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/hytale-mcp_1.1.0_1783093063764_0.033337963334926224"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-03T13:25:34.412Z","modified":"2026-07-03T15:37:44.204Z","0.1.2":"2026-07-03T13:25:34.700Z","1.1.0":"2026-07-03T15:37:43.933Z"},"bugs":{"url":"https://github.com/eliasnvx/hytale-mcp/issues"},"homepage":"https://github.com/eliasnvx/hytale-mcp#readme","repository":{"type":"git","url":"git+https://github.com/eliasnvx/hytale-mcp.git"},"description":"MCP server for Hytale mod development. Provides docs search, Java API reference, event/entity/block lookup, plugin and pack scaffolding, and manifest validation to AI coding assistants over the Model Context Protocol.","maintainers":[{"name":"eliasnvx","email":"elias.nevx@gmail.com"}],"readme":"# hytale-mcp\n\nMCP server for Hytale mod development. Provides docs search, Java API reference,\nevent/entity/block lookup, plugin and pack scaffolding, and manifest validation to\nAI coding assistants over the Model Context Protocol.\n\nWorks with Claude Code, Claude Desktop, Antigravity, Cursor, Windsurf, Codex, and any\nMCP-compatible client.\n\n[![CI](https://github.com/eliasnvx/hytale-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/eliasnvx/hytale-mcp/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/@eliasnvx/hytale-mcp.svg)](https://www.npmjs.com/package/@eliasnvx/hytale-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Node](https://img.shields.io/node/v/@eliasnvx/hytale-mcp.svg)](package.json)\n\n## Why\n\nHytale entered Early Access in January 2026 with modding built into the platform from\nday one. Documentation is spread across the official site, a community GitBook, and\nseveral GitHub organizations. This server consolidates all of it into a single set of\ntools so an AI assistant can answer Hytale modding questions and generate boilerplate\nwithout the developer switching tabs.\n\n## Install\n\nNo installation step is required. Add the server to your MCP client configuration and\nit runs via `npx` on demand.\n\n### Claude Desktop\n\nEdit the config file for your OS:\n\n| OS | Path |\n|---|---|\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Linux | `~/.config/Claude/claude_desktop_config.json` |\n\n```json\n{\n  \"mcpServers\": {\n    \"hytale-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@eliasnvx/hytale-mcp\"]\n    }\n  }\n}\n```\n\nRestart Claude Desktop completely (quit, not just close the window) after saving.\n\n### Claude Code\n\n```bash\nclaude mcp add hytale-mcp -- npx -y @eliasnvx/hytale-mcp\n```\n\n### Antigravity, Cursor, Windsurf\n\nAdd the same `mcpServers` block shown above to the client's MCP configuration file or\nthrough its built-in connector UI.\n\n### Codex CLI\n\n```bash\ncodex mcp add hytale-mcp -- npx -y @eliasnvx/hytale-mcp\n```\n\n## Tools\n\n| Tool | Inputs | Description |\n|---|---|---|\n| `search_docs` | `query: string, limit?: number` | Full-text search across all cached Hytale modding documentation |\n| `get_api_reference` | `className: string` | Java class and method reference from the server API |\n| `list_events` | `type?: \"sync\"\\|\"async\"\\|\"ecs\", query?: string` | Browse all events, optionally filtered by type |\n| `get_entities` | `category?: \"hostile\"\\|\"passive\"\\|\"neutral\"\\|\"boss\", query?: string` | NPC and entity registry, optionally filtered by category |\n| `search_blocks` | `query: string, category?: string` | Block and item registry search |\n| `scaffold_plugin` | `name: string, packageName: string, features: (\"events\"\\|\"commands\"\\|\"config\"\\|\"scheduler\"\\|\"entities\")[]` | Generate a plugin skeleton (manifest, main class, Gradle build) |\n| `scaffold_pack` | `name: string, type: \"block\"\\|\"item\"\\|\"entity\"\\|\"world\", description?: string` | Generate a pack skeleton |\n| `get_examples` | `topic: string` | Code examples by topic, sourced from community repositories |\n| `validate_manifest` | `json: string, type?: \"plugin\"\\|\"pack\"` | Validate a `plugin.json` or pack manifest against required fields |\n| `get_sounds` | `query?: string, category?: string` | Sound key registry, optionally filtered by category |\n| `get_changelog` | `since?: string` | Recent Hytale server API changes |\n| `analyze_error` | `log: string` | Analyze a stack trace against known engine errors |\n| `get_lore` | `query?: string, type?: string, faction?: string` | Search Hytale lore (mobs, items, stats) |\n\n## Example\n\nOnce connected, ask your AI assistant something like:\n\n> What events fire when a player breaks a block, and show me a plugin that logs it.\n\nThe assistant calls `search_docs` and `list_events` to find `BlockBreakEvent`, then\n`scaffold_plugin` to generate a working plugin skeleton with an event listener wired in.\n\n## Architecture & Documentation\n\nAll data is pre-fetched at build time and cached to `data/*.json`. Tool handlers never make network calls — they read from the committed cache, so responses are fast and the server has no runtime dependency on upstream sites being reachable.\n\n```\n[upstream sources] --build time--> scripts/build-cache.ts --> data/*.json\n                                                                     |\n                                                         src/tools/*.ts --> MCP response\n```\n\nFor detailed codebase breakdown, developer setup, a step-by-step tutorial on adding tools, and CI/CD pipelines, check out the **[Developer & Architecture Guide](docs/architecture.md)**.\n\n## Development\n\n```bash\ngit clone https://github.com/eliasnvx/hytale-mcp.git\ncd hytale-mcp\nnpm install\n\nnpm run dev          # start with hot reload\nnpm run test          # run the test suite\nnpm run typecheck     # type-check without emitting\nnpm run lint           # lint src/\nnpm run inspect        # open MCP Inspector against the built server\nnpm run cache:build    # rebuild data/ from upstream sources\n```\n\nRequires Node.js 22 or later.\n\n### Adding a tool\n\n1. Create `src/tools/<name>.ts` with a zod input schema and an async handler\n2. Add a test in `src/tools/__tests__/<name>.test.ts`\n3. Register the tool in `src/index.ts`\n4. Update the tool table in this README and in `AGENTS.md`\n\nSee [CLAUDE.md](CLAUDE.md) and [AGENTS.md](AGENTS.md) for the full rule set followed by\nAI assistants contributing to this repository.\n\n## Data sources\n\n- [hytalemodding.dev](https://hytalemodding.dev) — events, entities, interactions, sounds\n- [Britakee Studios GitBook](https://britakee-studios.gitbook.io/hytale-modding-documentation) — plugin and pack tutorials\n- [github.com/HytaleModding](https://github.com/HytaleModding) — plugin template, decompiled source browser\n- [hytale-docs.com](https://hytale-docs.com) — community API reference\n\nThis project is not affiliated with Hypixel Studios. Data is derived from community\ndocumentation and may lag behind the latest Early Access build.\n\n## Contributing\n\nIssues and pull requests are welcome. Please run `npm run typecheck && npm run test`\nbefore opening a PR — CI enforces both on every push.\n\n## License\n\n[MIT](LICENSE)\n\n## Author\n\n[@eliasnvx](https://github.com/eliasnvx) — [vyxro.dev](https://vyxro.dev)","readmeFilename":"README.md"}