tools: Skill for Claude Code

MCP Server Skill

Expose functionality over the Model Context Protocol using mcp-common, the shared scaffolding behind all three servers here (data uniqueness, code/context, adopt). Transport, registration and error handling are already solved — a new tool writes none of that.

The SPI — a tool never mentions the MCP SDK

public class MyTool implements McpTool {   // Function<Map<String,Object>, ToolResult>

    @Override
    public ToolDefinition getToolDefinition() {
        return new ToolDefinition("my_tool", "What it does, for the model.",
                Map.of("type", "object",
                       "properties", Map.of("path", Map.of("type", "string")),
                       "required", List.of("path")));
    }

    @Override
    public ToolResult apply(Map<String, Object> arguments) {
        String path = ToolArguments.requiredString(arguments, "path");
        return ToolResult.success(answer);          // or ToolResult.error(message)
    }
}

• ToolDefinition (name, description, JSON-schema map) and ToolResult (success / error) are the SPI's own transport-neutral types; AbstractMcpConfiguration translates them into the SDK's Tool and CallToolResult. Do not import io.modelcontextprotocol from a tool.
• Parse arguments with ToolArguments: requiredString, requiredInt, optionalString, optionalBoolean, optionalInt, optionalBoundedInt — don't hand-roll casts out of the map.
• Don't catch-and-wrap for the protocol's sake. AbstractMcpConfiguration turns any thrown RuntimeException into an error ToolResult naming the tool, so a bad argument reaches the client as an actionable tool error. Throw a clear exception; return ToolResult.error when the failure is expected.
• The failure path masks both channels (FailureMessage): the arguments it logs lose their credentials, and the message the client reads loses both those and any absolute path, keeping only the file's name. Write exception messages that stay useful under that — name what was wrong with the argument, not where on the server's disk it resolved to.