Package eu.mrapik.minecraftservermcp.api

Interface McpToolDefinition

public interface McpToolDefinition
Describes one MCP tool: a stable id, the metadata clients see in tools/list, and an asynchronous handler for tools/call.

Id and config: id() must match McpSchema.Tool.name() exactly. The same string is used as the key under access.<profile>.tools.<toolId> in config.yml, so administrators can enable or disable the tool and set allow/deny lists per token. Custom YAML keys under that section are exposed through McpToolInvocation.toolConfig().extra().

Ownership: owningPlugin() should be the plugin that registered the tool. When that plugin disables, it should call MinecraftServerMcp.unregisterTool(String) for each tool it added so clients do not keep stale entries.

Threading: Implementations return Mono; the MCP stack may invoke the handler off the main server thread. If you must touch the Bukkit API only on the main thread, schedule work accordingly (see built-in tools for examples).

  • Method Summary

    Modifier and Type
    Method
    Description
    @NotNull reactor.core.publisher.Mono<io.modelcontextprotocol.spec.McpSchema.CallToolResult>
    call(@NotNull McpToolInvocation invocation)
    Handles a single tools/call after authentication and per-token policy checks.
    @NotNull String
    id()
    Unique MCP tool name.
    @NotNull Plugin
    owningPlugin()
    Plugin that owns this tool registration (logging, lifecycle).
    io.modelcontextprotocol.spec.McpSchema.Tool
    tool()
    Metadata advertised to MCP clients.

  • Method Details

    • id

      @NotNull @NotNull String id()
      Unique MCP tool name. Must equal tool().name().
      Returns:
      the tool id, typically prefixed for third-party plugins (e.g. myplugin_action) to avoid collisions

    • owningPlugin

      @NotNull @NotNull Plugin owningPlugin()
      Plugin that owns this tool registration (logging, lifecycle).
      Returns:
      the registering plugin

    • tool

      @NotNull io.modelcontextprotocol.spec.McpSchema.Tool tool()
      Metadata advertised to MCP clients. The McpSchema.Tool.name() must equal id().
      Returns:
      tool listing entry including description and JSON Schema for arguments

    • call

      @NotNull @NotNull reactor.core.publisher.Mono<io.modelcontextprotocol.spec.McpSchema.CallToolResult> call(@NotNull @NotNull McpToolInvocation invocation)
      Handles a single tools/call after authentication and per-token policy checks.

      The McpToolInvocation includes the resolved profile, ToolAccessConfig for this tool id, server paths, and global settings (e.g. max read size for file tools).

      Parameters:
      invocation - context for this call; not null
      Returns:
      a cold Mono that emits one McpSchema.CallToolResult