{"id":51090385,"url":"https://github.com/ellyseum/ellymud","last_synced_at":"2026-06-24T01:30:32.097Z","repository":{"id":319524070,"uuid":"953810298","full_name":"ellyseum/ellymud","owner":"ellyseum","description":"Modern Multi-User Dungeon in TypeScript. Telnet, WebSocket, React admin with drag-and-drop world builder, MCP server, JSON/SQLite/PostgreSQL storage.","archived":false,"fork":false,"pushed_at":"2026-04-27T19:13:21.000Z","size":3632,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-27T21:11:24.119Z","etag":null,"topics":["ai-integration","ansi","cli","game-server","mcp","mud","mud-server","multiplayer","nodejs","react","realtime-chat","telnet","telnet-server","terminal-emulator","terminal-game","text-adventure","typescript","web-admin","websocket","websockets-server"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ellyseum.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":".github/AGENTS.md","dco":null,"cla":null}},"created_at":"2025-03-24T05:40:26.000Z","updated_at":"2026-04-27T17:00:12.000Z","dependencies_parsed_at":null,"dependency_job_id":"9c3a6663-a687-4422-9e99-c7d656f4aeed","html_url":"https://github.com/ellyseum/ellymud","commit_stats":null,"previous_names":["ellyseum/lemud","ellyseum/ellymud"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/ellyseum/ellymud","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ellyseum%2Fellymud","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ellyseum%2Fellymud/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ellyseum%2Fellymud/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ellyseum%2Fellymud/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ellyseum","download_url":"https://codeload.github.com/ellyseum/ellymud/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ellyseum%2Fellymud/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34713789,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ai-integration","ansi","cli","game-server","mcp","mud","mud-server","multiplayer","nodejs","react","realtime-chat","telnet","telnet-server","terminal-emulator","terminal-game","text-adventure","typescript","web-admin","websocket","websockets-server"],"created_at":"2026-06-24T01:30:28.517Z","updated_at":"2026-06-24T01:30:32.090Z","avatar_url":"https://github.com/ellyseum.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EllyMUD\n\n[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-green.svg)](https://www.gnu.org/licenses/agpl-3.0)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D20.19-brightgreen)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)\n\nA modern Multi-User Dungeon written in Node.js and TypeScript. Connect over Telnet, WebSocket, or the bundled web client. Inspired by classic MUDs like MajorMUD, rebuilt on a contemporary stack.\n\n## Quick start\n\n```bash\ngit clone https://github.com/ellyseum/ellymud.git\ncd ellymud\nnpm run bootstrap\nnpm start\n```\n\nThen connect:\n- **Web**: \u003chttp://localhost:8080\u003e\n- **Telnet**: `telnet localhost 8023`\n\nFirst boot prompts for an admin password.\n\n## Game\n\n- Real-time, turn-based combat with NPCs and PvP\n- Abilities and spellcasting with mana, cooldowns, and resource management\n- Room-based world with safe zones, shops, banks, and combat areas\n- 12-slot equipment system, inventory, vendor economy, banking\n- Character progression: levels, stat training, experience\n- Status effects: poisons, stuns, roots, buffs, debuffs, heals\n- Rest and meditate to recover\n- Multi-user chat (`say`, `yell`, social emotes)\n- Snake mini-game (type `snake` and you'll see)\n\nSee [`docs/commands.md`](docs/commands.md) for the full command reference.\n\n## Stack\n\n- **Connections**: Telnet (8023), WebSocket (8080), bundled xterm.js web client\n- **Admin API**: REST + React dashboard with a drag-and-drop World Builder (port 3000)\n- **MCP server**: Model Context Protocol on port 3100 for AI integration and headless testing\n- **Storage**: pluggable JSON / SQLite / PostgreSQL via a repository factory — switch with one env var\n- **Auth**: bcrypt password hashing, RBAC, JWT for the admin panel, API keys for MCP\n- **Logging**: per-user, per-session, daily-rotated, with separate system/error/MCP streams\n- **Tests**: Jest unit + integration + E2E (3,500+ tests)\n\n## Storage backends\n\nSet `STORAGE_BACKEND` to switch. Migrate data with `npm run data:export` / `data:import`.\n\n| Backend | Use case | Setup |\n|---|---|---|\n| `json` | Dev, fast iteration | None — default |\n| `sqlite` | Single-server prod | `STORAGE_BACKEND=sqlite` |\n| `postgres` | Cluster / HA | `STORAGE_BACKEND=postgres` + `DATABASE_URL` |\n\nDetails in [`docs/storage-backends.md`](docs/storage-backends.md).\n\n## MCP server\n\nEllyMUD exposes a Model Context Protocol server on port 3100 with API-key auth, suitable for AI agents to connect, control test mode, drive virtual game sessions, or query game state. See [`docs/api-reference.md`](docs/api-reference.md).\n\n## Documentation\n\n| Topic | Path |\n|---|---|\n| Getting started | [`docs/getting-started.md`](docs/getting-started.md) |\n| Configuration | [`docs/configuration.md`](docs/configuration.md) |\n| Docker | [`docs/docker.md`](docs/docker.md) |\n| Deployment | [`docs/deployment.md`](docs/deployment.md) |\n| Commands | [`docs/commands.md`](docs/commands.md) |\n| Admin guide | [`docs/admin-guide.md`](docs/admin-guide.md) |\n| API reference | [`docs/api-reference.md`](docs/api-reference.md) |\n| Architecture | [`docs/architecture.md`](docs/architecture.md) |\n| Storage backends | [`docs/storage-backends.md`](docs/storage-backends.md) |\n| Performance | [`docs/performance.md`](docs/performance.md) |\n| Development | [`docs/development.md`](docs/development.md) |\n| Troubleshooting | [`docs/troubleshooting.md`](docs/troubleshooting.md) |\n\nFor contributor conventions, build commands, and architecture in detail, read [`AGENTS.md`](AGENTS.md).\n\n## Development\n\n```bash\nnpm run dev      # hot-reload server\nnpm test         # full test suite\nnpm run build    # tsc + vite build\nnpm run          # list all scripts\n```\n\n## License\n\nAGPL-3.0-or-later — see [`LICENSE`](LICENSE).\n\nCommercial licensing available on request via \u003chttps://github.com/ellyseum\u003e.\n\n## Issues \u0026 discussion\n\n- [GitHub Issues](https://github.com/ellyseum/ellymud/issues)\n- [GitHub Discussions](https://github.com/ellyseum/ellymud/discussions)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fellyseum%2Fellymud","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fellyseum%2Fellymud","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fellyseum%2Fellymud/lists"}