para

use v6.d;

#| Tool registration helpers and builder DSL
unit module MCP::Server::Tool;



head

MCP::Server::Tool - Tool registration helpers


Provides a builder-style DSL and wrapper class for registering MCP tools.


Create a new tool builder. Chain methods to define the tool, then call
C<.build> to produce a C<RegisteredTool>.


my $t = tool()
    .name('add')
    .description('Add two numbers')
    .number-param('a', description => 'First', :required)
    .number-param('b', description => 'Second', :required)
    .handler(-> :%params { %params<a> + %params<b> })
    .build;


Validate that a tool name matches the MCP spec pattern:
C<^[a-zA-Z0-9_-]{1,64}$>. Dies on invalid names.


Fluent builder for tool definitions. Available chain methods:


item

Wrapper holding a C<Tool> definition and its handler.



use MCP::Types;

#| Validate tool name matches MCP spec pattern: ^[a-zA-Z0-9_-]{1,64}$
our sub validate-tool-name(Str $name) is export {
    unless $name ~~ /^ <[a..zA..Z0..9_\-]> ** 1..64 $/ {
        die "Invalid tool name '$name': must match ^[a-zA-Z0-9_-]\{1,64\}\$ (letters, digits, underscores, hyphens; 1-64 characters)";
    }
}

#| Wrapper class for a registered tool with its handler
class RegisteredTool is export {
    has Str $.name is required;
    has Str $.description;
    has Str $.title;
    has @.icons;
    has Hash $.inputSchema;
    has Hash $.outputSchema;
    has MCP::Types::ToolAnnotations $.annotations;
    has MCP::Types::TaskExecution $.execution;
    has &.handler is required;

    #| Get the Tool definition for listing
    method to-tool(--> MCP::Types::Tool) {
        MCP::Types::Tool.new(
            :$!name,
            :$!description,
            :$!title,
            :@!icons,
            :$!inputSchema,
            :$!outputSchema,
            :$!annotations,
            :$!execution,
        )
    }

    #| Call the tool with given arguments
    method call(%arguments --> MCP::Types::CallToolResult) {
        my $result =
            (try &!handler(:params(%arguments)))
            // (try &!handler(|%arguments))
            // (try &!handler(%arguments))
            // &!handler();

        # Normalize result to CallToolResult
        given $result {
            when MCP::Types::CallToolResult {
                return $result;
            }
            when MCP::Types::Content {
                return MCP::Types::CallToolResult.new(content => [$result]);
            }
            when Hash {
                # If tool has outputSchema, treat Hash as structuredContent
                if $!outputSchema {
                    return MCP::Types::CallToolResult.new(
                        structuredContent => $result,
                        content => [MCP::Types::TextContent.new(text => $result.raku)],
                    );
                }
                return MCP::Types::CallToolResult.new(
                    content => [MCP::Types::TextContent.new(text => $result.Str)]
                );
            }
            when Str {
                return MCP::Types::CallToolResult.new(
                    content => [MCP::Types::TextContent.new(text => $result)]
                );
            }
            when Positional {
                return MCP::Types::CallToolResult.new(content => $result.Array);
            }
            default {
                return MCP::Types::CallToolResult.new(
                    content => [MCP::Types::TextContent.new(text => $result.Str)]
                );
            }
        }
    }
}

#| Builder for creating tool definitions
class ToolBuilder is export {
    has Str $.name;
    has Str $.description;
    has Str $.title;
    has @.icons;
    has Hash $.inputSchema = { type => 'object', properties => {}, required => [] };
    has Hash $.outputSchema;
    has MCP::Types::ToolAnnotations $.annotations;
    has MCP::Types::TaskExecution $.execution;
    has &.handler;

    method name(Str $!name --> ToolBuilder) { self }

    method description(Str $!description --> ToolBuilder) { self }

    method title(Str $!title --> ToolBuilder) { self }

    method icon(Str $src, Str :$mimeType, :@sizes --> ToolBuilder) {
        @!icons.push(MCP::Types::IconDefinition.new(:$src, :$mimeType, :@sizes));
        self
    }

    method schema(Hash $!inputSchema --> ToolBuilder) { self }

    method input-schema(Hash $!inputSchema --> ToolBuilder) { self }

    method output-schema(Hash $!outputSchema --> ToolBuilder) { self }

    #| Add a string parameter
    method string-param(Str $name, Str :$description, Bool :$required --> ToolBuilder) {
        $!inputSchema<properties>{$name} = {
            type => 'string',
            ($description ?? (description => $description) !! Empty)
        };
        $!inputSchema<required>.push($name) if $required;
        self
    }

    #| Add a number parameter
    method number-param(Str $name, Str :$description, Bool :$required --> ToolBuilder) {
        $!inputSchema<properties>{$name} = {
            type => 'number',
            ($description ?? (description => $description) !! Empty)
        };
        $!inputSchema<required>.push($name) if $required;
        self
    }

    #| Add an integer parameter
    method integer-param(Str $name, Str :$description, Bool :$required --> ToolBuilder) {
        $!inputSchema<properties>{$name} = {
            type => 'integer',
            ($description ?? (description => $description) !! Empty)
        };
        $!inputSchema<required>.push($name) if $required;
        self
    }

    #| Add a boolean parameter
    method boolean-param(Str $name, Str :$description, Bool :$required --> ToolBuilder) {
        $!inputSchema<properties>{$name} = {
            type => 'boolean',
            ($description ?? (description => $description) !! Empty)
        };
        $!inputSchema<required>.push($name) if $required;
        self
    }

    #| Add an array parameter
    method array-param(Str $name, Str :$description, Hash :$items, Bool :$required --> ToolBuilder) {
        $!inputSchema<properties>{$name} = {
            type => 'array',
            ($description ?? (description => $description) !! Empty),
            ($items ?? (items => $items) !! Empty)
        };
        $!inputSchema<required>.push($name) if $required;
        self
    }

    #| Set annotations (supports both short names and spec names with Hint suffix)
    method annotations(
        Str :$title,
        Bool :$readOnly,
        Bool :$readOnlyHint,
        Bool :$destructive,
        Bool :$destructiveHint,
        Bool :$idempotent,
        Bool :$idempotentHint,
        Bool :$openWorld,
        Bool :$openWorldHint
    --> ToolBuilder) {
        $!annotations = MCP::Types::ToolAnnotations.new(
            title => $title,
            readOnlyHint => $readOnly // $readOnlyHint,
            destructiveHint => $destructive // $destructiveHint,
            idempotentHint => $idempotent // $idempotentHint,
            openWorldHint => $openWorld // $openWorldHint,
        );
        self
    }

    #| Set task support level (forbidden, optional, required)
    method task-support(Str $level --> ToolBuilder) {
        my $ts = do given $level {
            when 'forbidden' { MCP::Types::TaskForbidden }
            when 'optional'  { MCP::Types::TaskOptional }
            when 'required'  { MCP::Types::TaskRequired }
            default          { MCP::Types::TaskOptional }
        };
        $!execution = MCP::Types::TaskExecution.new(taskSupport => $ts);
        self
    }

    method handler(&!handler --> ToolBuilder) { self }

    method build(--> RegisteredTool) {
        die "Tool name is required" unless $!name;
        validate-tool-name($!name);
        die "Tool handler is required" unless &!handler;

        RegisteredTool.new(
            :$!name,
            :$!description,
            :$!title,
            :@!icons,
            :$!inputSchema,
            :$!outputSchema,
            :$!annotations,
            :$!execution,
            :&!handler,
        )
    }
}

#| Convenience function to create a tool builder
our sub tool(--> ToolBuilder) is export {
    ToolBuilder.new
}


root

Server

Resource

React

=begin React :component<HeaderCol> :id<menu> 
=para L<Documentation|/doc/introduction>
=para L<Modules| /mods>
=para L<Examples| file:../examples/index.podlite>
=para L<AI|file:../mcp/index.podlite>
=para L<Download |file:../download/index.podlite>
=para L<About|file:../about/index.podlite>
=para 🔍 K<⌘K>/K<ctrl-K>
=end React


=begin React :component<HeaderCol> :id<footer>  
=begin nested :!nested
=item1 B<Language>
    =item2 L<Get started|file:../getting-started/getting-started.podlite>
    =item2 L<Why Raku?|/doc/language/faq#Why-should-I-learn-Raku-What's-so-great-about-it>
    =item2 L<Try Raku|https://glot.io/new/raku>
    =item2 L<Download | file:../download/index.podlite>
    =item2 L<Raku cheat sheet|https://github.com/Raku/mu/blob/master/docs/Perl6/Cheatsheet/cheatsheet.txt>
    =item2 L<Raku on Exercism|https://exercism.org/tracks/raku>
    =item2 L<Wikipedia|https://en.wikipedia.org/wiki/Raku_(programming_language)>

=end nested
=begin nested :!nested

=item1 B<L<Documentation|/doc>>
    =item2 L<Getting started, Migration guides from other languages, & Tutorials | file:../doc/introduction.podlite>
    =item2 L<Language References|file:../doc/reference.podlite>
    =item2 L<Type Reference| file:../doc/types.podlite>
    =item2 L<Miscellaneous| file:../doc/miscellaneous.podlite>
    =item2 L<FAQs (Frequently Asked Questions)|/doc/language/faq>
    =item2 L<Community|/doc/language/community>
    =item2 L<The list of all documents|file:../doc/index.podlite>
    =item2 L<Hand these documents to an AI assistant|file:../mcp/index.podlite>

=end nested
=begin nested :!nested
=item1 B<Learning>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Wikibook |https://en.wikibooks.org/wiki/Raku_Programming>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>
    =item2 L<Learn Raku in Y minutes|https://learnxinyminutes.com/docs/raku/>
    =item2 L<Golfing |https://github.com/AlexDaniel/raku-golf-cheatsheet>
=end nested
=begin nested :!nested

=item1 B<Explore>
    =item2 L<Raku Blog Aggregator|https://planet.raku.org/>
    =item2 L<Rakudo Weekly|https://rakudoweekly.blog/>
    =item2 L<The Weekly Challenge |https://perlweeklychallenge.org/>
    =item2 L<Raku Advent Calendar|https://raku-advent.blog/>

=end nested
=end React


Built with L<Podlite|https://podlite.org> — the markup and publishing tools behind this site.


=begin React :component<CookieConsent> :id<CookieConsent> :buttonCaption("Got it!")
=para
This website uses cookies for analytics.
=end React


Tool

NAME

DESCRIPTION

FUNCTIONS

sub tool(--> ToolBuilder)

sub validate-tool-name(Str $name)

CLASSES

ToolBuilder

RegisteredTool

MCP v0.33.6

Authors

License

Dependencies

Test Dependencies

Provides

Documentation