<p align="right"> <img src="https://flagicons.lipis.dev/flags/4x3/gb.svg" width="30" height="24"> </p>

Endstone MCP Server

<p align="center"> <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"> <img src="https://img.shields.io/badge/version-0.1.4-blue" alt="Version"> <img src="https://img.shields.io/badge/Python-%3E=3.8-blue?logo=python" alt="Python version"> </p>

A Model Context Protocol (MCP) server designed to support EndstoneMC development.

<p align="center"> <a href="README_CN.md"> <img src="https://flagicons.lipis.dev/flags/4x3/cn.svg" width="30" height="24"> </a> </p>

Features

• Module Information Query: Retrieve detailed information and exports for Endstone modules.
• Code Search: Search for classes, functions, and constants across all Endstone modules.
• Plugin Template Generation: Generate basic plugin templates based on specified requirements.
• Event Handling Guidance: Provide detailed information and examples for event handling.
• Development Tutorials: Built-in guides for plugin development, event handling, and command creation.

Installation or Startup

Using uvx

uvx mcp-server-endstone

From Source

git clone https://github.com/Mcayear/mcp-server-endstone
cd mcp-server-endstone
pip install -e .

# Start after installation
mcp-server-endstone

Unit Tests

python -m tests.test_server

Usage

Start the Server Directly

mcp-server-endstone [--reference <path_to_reference_files>]

Integrate with an MCP Client

Add the following to your MCP client configuration:

Example (compatible with clients like cursor, trae):

{
  "mcpServers": {
    "endstone": {
      "command": "uvx",
      "args": [
        "mcp-server-endstone"
      ]
    }
  }
}

Available Tools

1. get_module_info

Get information about a specific Endstone module.

Parameters:

• module_name: The name of the module (e.g., 'endstone.event', 'endstone.plugin').

Example:

Tool: get_module_info
Parameters: {"module_name": "endstone.event"}

2. search_exports

Search for specific exports across all modules.

Parameters:

• query: The search term (class name, function name, etc.).

Example:

Tool: search_exports
Parameters: {"query": "Player"}

3. get_symbol_info

Get the detailed definition of a specific symbol (like a class or event) in Endstone, including its documentation, attributes, and methods.

Parameters:

• symbol_name: The name of the symbol (e.g., 'PlayerInteractEvent', 'Plugin').

Example:

Tool: get_symbol_info
Parameters: {"symbol_name": "PlayerInteractEvent"}

4. generate_plugin_template

Generate a basic plugin template with specified features.

Parameters:

• plugin_name: The name of the plugin (must end with '_plugin').
• features: A list of features to include (optional: 'commands', 'events', 'permissions').

Example:

Tool: generate_plugin_template
Parameters: {
  "plugin_name": "example_plugin",
  "features": ["events", "commands"]
}

5. get_event_info

Get information about events. If event_type is provided, it returns the detailed definition (attributes, docs) and usage examples for that event. Otherwise, it lists all available events.

Parameters:

• event_type: A specific event type (optional).

Example:

Tool: get_event_info
Parameters: {"event_type": "PlayerJoinEvent"}

6. read_tutorials

Get content for a tutorial. If no tutorial name is specified, it lists all available tutorials.

Parameters:

• query: The name of the tutorial (optional).

Example:

Tool: read_tutorials
Parameters: {"query": "register-commands"}

Supported Endstone Modules

• endstone - Core module
• endstone.actor - Actor-related
• endstone.ban - Ban system
• endstone.block - Block operations
• endstone.boss - Boss bar
• endstone.command - Command system
• endstone.damage - Damage system
• endstone.enchantments - Enchantments
• endstone.event - Event system
• endstone.form - Form UI
• endstone.inventory - Inventory
• endstone.lang - Language localization
• endstone.level - World/Dimension
• endstone.map - Map
• endstone.permissions - Permission system
• endstone.plugin - Plugin basics
• endstone.scheduler - Task scheduler
• endstone.scoreboard - Scoreboard
• endstone.util - Utilities

Development Examples

Basic Plugin Structure

from endstone.plugin import Plugin
from endstone import Logger

class MyPlugin(Plugin):
    name = "MyPlugin"
    version = "1.0.0"
    api_version = "0.5"
    
    def on_enable(self) -> None:
        self.logger.info(f"{self.name} v{self.version} enabled!")
    
    def on_disable(self) -> None:
        self.logger.info(f"{self.name} disabled!")

Event Handling

from endstone.event import event_handler, PlayerJoinEvent

@event_handler
def on_player_join(self, event: PlayerJoinEvent):
    player = event.player
    self.logger.info(f"Welcome {player.name}!")
    player.send_message("Welcome to the server!")

Project Structure

mcp-server-endstone/
├── reference/         # Required reference resources
│   ├── endstone/
│   └── tutorials/
├── src/
│   └── mcp_server_endstone/
│       ├── __init__.py
│       ├── server.py  # Core server logic
│       ├── cli.py     # Command-line entry point
│       └── reference/ # Reference files
├── tests/
│   ├── __init__.py
│   └── test_server.py
├── pyproject.toml
└── README.md

Troubleshooting

1. Reference File Path Issues: The server first attempts to load reference files from the reference directory within the package, then from the current working directory. If neither exists, some features may be unavailable. Use the --reference argument to specify the path.

1. Debugging Errors: The server's log level is set to INFO. Check the logs to diagnose problems.

1. Dependency Issues: Ensure all dependencies are correctly installed: mcp>=0.1.0

Contributing

Contributions are welcome! Please feel free to submit Issues and Pull Requests to improve this MCP server.

Credits

EndstoneMC - The reference content is based on endstone/docs/reference and endstone/docs/tutorials.

License

MIT License