Package eu.mrapik.minecraftservermcp.api

Interface MinecraftServerMcp

All Known Implementing Classes:
MinecraftServerMcpImpl
public interface MinecraftServerMcp
Public extension point for registering MCP tools from other Bukkit plugins.

The MCP plugin exposes an implementation of this interface through Bukkit's ServicesManager. Obtain it after the MCP plugin has enabled, for example: Bukkit.getServicesManager().load(MinecraftServerMcp.class).

Built-in tools (e.g. fs_write, console command, logs) are registered like third-party tools via registerTool(McpToolDefinition). Built-in filesystem and player data are MCP resources registered at startup (see plugin sources); they use the same access.*.tools.* keys for policy.

Every registered tool is wrapped so that each tools/call runs only after the HTTP bearer token has been resolved to an access profile and the per-tool policy in config.yml has been applied (see McpToolInvocation).

  • Method Details

    • registerTool

      @NotNull @NotNull reactor.core.publisher.Mono<Void> registerTool(@NotNull @NotNull McpToolDefinition definition)
      Adds a tool to the MCP server, or replaces an existing tool with the same MCP tool name.

      The definition's McpToolDefinition.id() must equal McpSchema.Tool.name(). Configuration for that tool is read from access.&lt;profile&gt;.tools.&lt;id&gt; for each token profile.

      Parameters:
      definition - tool metadata and handler; not null
      Returns:
      completes when the tool is visible to MCP clients (may notify list changes)

    • unregisterTool

      @NotNull @NotNull reactor.core.publisher.Mono<Void> unregisterTool(@NotNull @NotNull String toolId)
      Removes a tool from the MCP server by its advertised MCP name.

      This is unconditional (operator/trusted caller). Plugins that registered a tool should prefer unregisterToolAs(String, Plugin) so only the owning plugin can remove it.

      Parameters:
      toolId - same string as McpToolDefinition.id() / McpSchema.Tool.name()
      Returns:
      completes when the tool has been removed

    • unregisterToolAs

      @NotNull @NotNull reactor.core.publisher.Mono<Void> unregisterToolAs(@NotNull @NotNull String toolId, @NotNull @NotNull Plugin caller)
      Removes a tool only if caller's name matches the plugin that registered it (see toolOwningPlugin(String)).
      Parameters:
      toolId - MCP tool name
      caller - plugin that must own the tool
      Returns:
      completes when removed, or errors if the tool is unknown or not owned by caller

    • toolOwningPlugin

      @Nullable @Nullable String toolOwningPlugin(@NotNull @NotNull String toolId)
      Returns which Bukkit plugin registered the given MCP tool name, for ownership checks in unregisterToolAs(java.lang.String, org.bukkit.plugin.Plugin).
      Parameters:
      toolId - MCP tool name (same as McpToolDefinition.id())
      Returns:
      the registering plugin's name, or null if no such tool is registered

    • reloadConfiguration

      void reloadConfiguration()
      Reloads this plugin's config.yml from disk and replaces the in-memory PluginSettings. Already-registered tools stay registered; subsequent tool invocations use the new token and policy values.

    • mcpServer

      @NotNull @NotNull io.modelcontextprotocol.server.McpAsyncServer mcpServer()
      Direct access to the underlying Model Context Protocol async server.

      Use this for advanced integration (sessions, capabilities) if you need more than registerTool(eu.mrapik.minecraftservermcp.api.McpToolDefinition). Typical plugin code only needs registerTool(eu.mrapik.minecraftservermcp.api.McpToolDefinition) and unregisterTool(java.lang.String).

      Returns:
      the non-null MCP server instance used by this plugin