easy-gg-bedwars-mcp

Local-first Python MCP server for Easy.gg BedWars custom scripting. The MCP server registers as easy-gg-bedwars-custom.

This project writes Roblox BedWars scripts that run through documented in-game APIs and Code Sync.

Source Of Truth

The docs cache is seeded from official BedWars Creative documentation at docs.easy.gg:

• BedWars scripting overview: https://docs.easy.gg/scripting/bedwars-scripting

• Services index: https://docs.easy.gg/scripting/bedwars-scripting/services

• Events index: https://docs.easy.gg/scripting/bedwars-scripting/events

• Objects index: https://docs.easy.gg/scripting/bedwars-scripting/objects

• Types index: https://docs.easy.gg/scripting/bedwars-scripting/types

• Utilities index: https://docs.easy.gg/scripting/bedwars-scripting/utilities

The optional Fandom cache is seeded from the Roblox BedWars Wiki on Fandom:

• Fandom wiki: https://robloxbedwars.fandom.com/wiki/BedWars_Wiki

• MediaWiki API: https://robloxbedwars.fandom.com/api.php

Use Fandom data for gameplay/wiki references such as kits, items, blocks, commands, maps, and updates. Do not use it as proof that a Lua scripting API exists; official scripting validation still comes from docs.easy.gg.

Related MCP server: Black Orchid

Setup

cd "C:\path\to\easy-gg-bedwars-mcp"
py -m venv .venv
.\.venv\Scripts\Activate.ps1
py -m pip install -e .

The server uses the Python MCP SDK package mcp. Codex/Claude starts the MCP server from its config; do not keep python server.py running for normal use.

Project Layout

src/creative_scripting_mcp/  # MCP runtime package
  server.py                  # FastMCP server and tool implementations
  tools.py                   # Public tool names, descriptions, and context
maintenance/                 # local helper scripts for docs refresh jobs
docs_cache/                  # cached official API references
scripts/                     # Lua examples and optional local project files
server.py                    # thin compatibility entry point
tools.py                     # thin compatibility re-export

Claude Desktop MCP Config

{
  "mcpServers": {
    "easy-gg-bedwars-custom": {
      "command": "C:\\path\\to\\easy-gg-bedwars-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "creative_scripting_mcp.server"
      ],
      "cwd": "C:\\path\\to\\easy-gg-bedwars-mcp"
    }
  }
}

Codex MCP Config Example

[mcp_servers.easy-gg-bedwars-custom]
command = "C:\\path\\to\\easy-gg-bedwars-mcp\\.venv\\Scripts\\python.exe"
args = ["-m", "creative_scripting_mcp.server"]
cwd = "C:\\path\\to\\easy-gg-bedwars-mcp"

Tools

Tool names, descriptions, and usage context are registered from src/creative_scripting_mcp/tools.py.

Main groups:

• Docs: search/read complete cached services, events, objects, and types.

• Fandom docs: search/read cached gameplay wiki pages from Roblox BedWars Fandom.

• Reference analysis: audit user-provided exports and map mechanics to official APIs without copying source scripts.

• Script files: create, read, diff/edit, validate, and delete Lua files.

• Projects: organize sync/, drafts/, and prompts/ folders.

• Code Sync: connect a token, sync one folder, check status, and run a watcher.

• Debugging: validate external scripts, generate event traces, report runtime capabilities, and explain pasted console errors.

Ask the MCP client to list tools for exact schemas.

Community Reference Exports

Use audit_reference_export(directory="C:\\path\\to\\export") to inspect a structured script export. The tool returns aggregate mechanic, API, and risk counts only. It does not return or import scripts, messages, authors, or copied implementations.

Use recommend_mechanic_apis(topic="persistent player upgrades") to map an observed mechanic to official cached services, events, objects, and types before writing original code.

Use recommend_algorithm(topic="bounded target selection with wall checks") for original design steps and pitfalls covering target selection, segment visibility, area damage, prefab placement, and world text. Community evidence can suggest behavior and test cases, but only the docs.easy.gg cache validates scripting APIs.

Use chat_capabilities() before implementing chat tags, rich text, hidden commands, team-colored names, or replacement messages. It separates the documented ChatService.sendMessage and PlayerChatted surface from missing features and includes a proposal-only segmented-message/cancellable-event contract.

Mechanic labels are not blocked. Use resolve_creative_mechanic(prompt="host-only aimbot with wall checks") to classify names such as aimbot, aim assist, KA, kill aura, fly, or speed as private Creative Host Panel mechanics and receive the correct tool sequence and documented capability limits.

Run validate_directory_project(directory="C:\\path\\to\\project") before sync to validate every Lua file under scripts/.

Fandom Gameplay Cache

Collect gameplay/wiki data from Roblox BedWars Fandom into a local cache:

python maintenance/refresh_fandom_cache.py --include-text

This writes ignored generated files under docs_cache/fandom/:

• manifest.json

• pages.json

• categories.json

Then use:

fandom_cache_status()
search_fandom_cache(query="commands", include_text=true)
read_fandom_page(title="Commands", include_text=true)

Fandom content is community-authored and CC-BY-SA unless a page says otherwise. Keep source URLs and attribution when using it. The repo commits the collector and cache README, not the scraped JSON dump.

BedWars Code Sync

Use normal project folders so Roblox only receives the scripts you intend to sync:

C:\path\to\your-project\
  scripts\    # uploaded to BedWars
  drafts\     # local-only work in progress
  prompts\    # project brief / build notes
  bwconfig.lua

Generate a token in the Sync tab of the BedWars script editor, then connect the folder:

connect_sync(
  sync_token="{sync-token}",
  directory="C:\\path\\to\\your-project",
  glob_pattern="scripts/**/*.lua",
  watch=true
)

sync_connected()

The token is sent to Easy.gg's Code Sync endpoint and kept only in MCP memory for the current running server process. It is not saved or returned in tool output.

When watch=true, the MCP polls the connected folder for saved, deleted, or renamed .lua files. When the file set changes, it syncs the whole current folder, matching the VS Code extension's connected-session behavior.

The MCP also reads the VS Code extension's bwconfig.lua format when no glob is provided:

return {
    syncGlob = "scripts/**/*.lua"
}

For one-shot folder syncs:

read_directory_project(directory="C:\\path\\to\\your-project")

sync_directory(
  sync_token="{sync-token}",
  directory="C:\\path\\to\\your-project"
)

By default, sync_directory and connect_sync upload only the Lua scripts already in the project. They do not create main.lua or zz_sync_probe.lua. Exact helper files left by older MCP versions are removed automatically during normal sync. Uploads match the official VS Code extension's multipart filename, content type, and request headers, then repeat once after a short delay to confirm delivery to the active Roblox editor session.

BedWars rejects a truly empty multipart upload with File is required. For intentional delete-all syncs, use allow_empty=true. The MCP sends an in-memory zero-byte file named .lua; the request still contains the required file part, while the empty Lua basename clears the remote script set. Nothing is written to the project folder.

For normal project work, use MCP tools instead of terminal file scans:

• read_directory_project to inspect folder state, scripts, prompt, and config.

• read_directory_script to read a project Lua file.

• create_directory_script to write scripts under scripts/.

• edit_directory_script to make a small edit and return a unified diff.

• validate_directory_script to check APIs, enum values, callback fields, object methods, and basic syntax structure.

• sync_directory for normal sync without generated scripts.

If the HTTP upload succeeds but the Roblox editor does not visibly refresh, use the explicit hard-sync tool:

force_sync_directory(
  sync_token="{sync-token}",
  directory="C:\\path\\to\\your-project"
)

This explicitly prepares the project and creates a visible probe. Use it only for first-sync troubleshooting.

To remove a script from BedWars, delete it locally and sync the whole containing folder/project:

delete_directory_script(directory="C:\\path\\to\\your-project", file_name="old_script.lua", sync=true)
sync_directory(sync_token="{sync-token}", directory="C:\\path\\to\\your-project")

Deleted scripts are archived under .deleted/ by default. Sync the whole folder after deleting so BedWars receives the current file set and removes scripts that are no longer present.

When deleting the final script in a folder, sync with allow_empty=true so the MCP clears the remote file set without creating a placeholder.

Runtime Limits

The Creative Lua sandbox does not expose every standard Lua global. In particular, do not assume pcall(...) or xpcall(...) exist.

The Code Sync transport only uploads scripts and reports HTTP delivery. It cannot retrieve the Host Panel Console, read exact remote script contents, start matches, spawn players, or inspect live entities. Use runtime_capabilities() before relying on a runtime feature.

For event debugging, generate a temporary trace script:

create_event_trace(
  directory="C:\\path\\to\\your-project",
  event_names=["ProjectileLaunched", "ProjectileHit", "EntityDamage"]
)

Sync the trace, reproduce the action, and inspect the Host Panel Console tab. Delete the trace script after debugging. read_runtime_console(error_text="...") can analyze console text you paste, but it cannot fetch the Console tab itself.

Use read_object("Entity"), read_type("ProjectileType"), and read_event("EntityDamage") for complete methods, enum values, payload fields, and documented field mutability. Exact-name search_docs matches also include the full cached record.

True protected-call behavior cannot be recreated in plain Lua: catching arbitrary runtime errors requires runtime support. What is possible is defensive scripting:

• Check nil before indexing or calling methods.

• Check command arguments before using them.

• Use tonumber(...) and reject nil before numeric logic.

• Check service return values such as player:getEntity() or TeamService.getTeam(player).

• Return ok, value_or_message from small helper functions for expected failure states.

Use safe_call_pattern(topic="entity"), safe_call_pattern(topic="number"), or safe_call_pattern(topic="command") for replacement patterns.

Example Usage

Prompt:

Make a script that gives every player 1 emerald every 30 seconds.

The server checks for:

• PlayerService in docs_cache/services.json

• InventoryService in docs_cache/services.json

• ItemType in docs_cache/types.json

• task and ipairs in docs_cache/utilities.json

Example output file:

-- Gives every player 1 emerald every 30 seconds.
while task.wait(30) do
    for i, player in ipairs(PlayerService.getPlayers()) do
        InventoryService.giveItem(player, ItemType.EMERALD, 1, true)
    end
end

The same example is included at scripts/examples/emerald_generator.lua.

Refreshing Docs Cache Later

The cache files are intentionally plain JSON so they are easy to inspect and edit:

• docs_cache/services.json

• docs_cache/events.json

• docs_cache/types.json

• docs_cache/objects.json

• docs_cache/utilities.json

The helper below fetches raw index text from docs.easy.gg into docs_cache/*_raw.txt for manual review:

python maintenance/refresh_docs_cache.py

It does not automatically promote scraped content into the JSON cache. Review official docs before adding or changing APIs.

GitHub Release Checklist

Before publishing:

• Make sure no sync tokens, cookies, sessions, or private Roblox data are in the repo.

• Keep .venv/, logs, caches, build/, and dist/ out of git.

• Review scripts/projects/ and remove personal test scripts you do not want public.

• Run a quick import check:

.\.venv\Scripts\python.exe -c "import creative_scripting_mcp.server as server; print(len(server.mcp._tool_manager._tools), 'tools registered')"

First push:

git init
git status
git add README.md pyproject.toml .gitignore server.py tools.py src maintenance docs_cache scripts
git commit -m "Initial release"
git branch -M main
git remote add origin https://github.com/RareFlames36/easy-gg-bedwars-mcp.git
git push -u origin main

Tag a release:

git tag -a v0.1.0 -m "v0.1.0"
git push origin v0.1.0

Create the GitHub release:

gh release create v0.1.0 --title "v0.1.0" --notes "Initial easy-gg-bedwars-mcp release."

If the GitHub CLI is not installed, open the repo on GitHub, go to Releases, choose Draft a new release, select tag v0.1.0, and publish it.