mcp-server-endstone

<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 ```bash uvx mcp-server-endstone ``` ### From Source ```bash git clone https://github.com/Mcayear/mcp-server-endstone cd mcp-server-endstone pip install -e . # Start after installation mcp-server-endstone ``` ### Unit Tests ```bash python -m tests.test_server ``` ## Usage ### Start the Server Directly ```bash 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): ```json { "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 ```python 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 ```python 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. 2. **Debugging Errors**: The server's log level is set to INFO. Check the logs to diagnose problems. 3. **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](https://github.com/EndstoneMC/endstone) - The `reference` content is based on `endstone/docs/reference` and `endstone/docs/tutorials`. ## License MIT License