module MCP::Tools

Included Modules

• Utils::Paths

Defined in:

Constant Summary

Log = ::Log.for("mcp")

NAME_REGEX = /^([a-zA-Z0-9_-]+|hashtag#[a-zA-Z0-9_-]+|mention@[[email protected]]+)$/

TOOL_DEFINITIONS = [{name: "paginate_collection", description: "Paginate through collections of ActivityPub objects, activities, and actors. Use this tool when you want to inspect the contents of a collection.", properties: [{name: "name", type: "string", description: "Name of the collection to paginate", required: true, matches: NAME_REGEX}, {name: "page", type: "integer", description: "Page number (optional, defaults to 1)", minimum: 1, default: 1}, {name: "size", type: "integer", description: "Number of items per page (optional, defaults to 10, maximum 1000)", minimum: 1, maximum: 20, default: 10}]}, {name: "count_collection_since", description: "Count items in ActivityPub collections since a given time. Use this tool when you want to know if new items have been added in the last day/week/month.", properties: [{name: "name", type: "string", description: "Name of the collection to count", required: true, matches: NAME_REGEX}, {name: "since", type: "time", description: "Time (RFC3339) to count from", required: true}]}, {name: "get_thread", description: "Retrieve thread structure, metadata, and summary data. Large threads may have hundreds of objects, so this tool supports pagination. This tool retrieves the entire thread for the given `object_id` starting at the root, not only the subthread.\n\n**Two Modes of Operation:**\n\n1. **Initial Query Mode**: Provide `object_id` (plus optional `projection` and `page_size`) to start traversing a thread.\n Returns summary data and the first page of objects. If there are more pages, includes a `cursor`.\n\n2. **Pagination Mode**: Provide only `cursor` (from a previous response) to fetch the next page.\n Returns the next page of objects. If there are more pages, includes a `cursor`.\n Do not include `object_id`, `projection`, or `page_size`.\n\n**Usage Examples:**\n- Start: `{\"object_id\": 123, \"projection\": \"metadata\", \"page_size\": 20}`\n- Continue: `{\"cursor\": \"eyJwYWdlcl9pZ...\"}`\n\n**Important:** You must provide EITHER `object_id` OR `cursor`, but not both.", properties: [{name: "object_id", type: "integer", description: "Database ID of any object in the thread. Required for initial query, omit when using cursor.", required: false, minimum: 1}, {name: "projection", type: "string", description: "Data fields to include: 'minimal' (IDs and structure only) or 'metadata' (adds authors, timestamps). Only used with object_id.", required: false, enum: ["minimal", "metadata"], default: "metadata"}, {name: "page_size", type: "integer", description: "Number of objects per page. Only used with object_id.", required: false, minimum: 1, maximum: 100, default: 25}, {name: "cursor", type: "string", description: "Opaque pagination cursor from previous get_thread response. Use ONLY this parameter to fetch next page.", required: false}]}, {name: "analyze_thread", description: "Analyze thread structure and identify key participants and notable branches. Use this before reading thread content to understand the conversation landscape and identify which posts are most relevant to examine. This is especially useful with large threads.\n\n**Returns:**\n- Basic statistics (total posts, unique authors, max depth, analysis duration)\n- Key participants (original poster + top 5 most active posters with their posts)\n- Notable branches (conversation subtrees with ≥5 posts)\n- Timeline histogram (temporal distribution of posts)", properties: [{name: "object_id", type: "integer", description: "Database ID of any object in the thread", required: true, minimum: 1}]}, {name: "read_resources", description: "Read one or more resources by URI (format \"ktistec://{resource}/{id*}\"). Supports all resource types including templated resources (actors, objects) and static resources (information, users). Supports batched reads (comma-separated IDs of resources of the same type). Use this tool as a universal fallback when resources are not supported by an MCP client.", properties: [{name: "uris", type: "array", description: "Resource URIs to read (e.g., ['ktistec://actors/123,456', 'ktistec://objects/456,789'])", required: true, items: "string"}]}] of ToolDefinition

Class Method Summary

• .handle_tool_analyze_thread(params : JSON::Any, account : Account) : JSON::Any
• .handle_tool_count_collection_since(params : JSON::Any, account : Account) : JSON::Any
• .handle_tool_get_thread(params : JSON::Any, account : Account) : JSON::Any
• .handle_tool_paginate_collection(params : JSON::Any, account : Account) : JSON::Any
• .handle_tool_read_resources(params : JSON::Any, account : Account) : JSON::Any
• .handle_tools_call(request : JSON::RPC::Request, account : Account) : JSON::Any
• .handle_tools_list(request : JSON::RPC::Request) : JSON::Any
• .result_pager
• .result_pager=(result_pager)

Macro Summary

• def_tool(name, description, properties = [] of ToolPropertyDefinition, &block)

  Defines an MCP tool.

Class Method Detail

Macro Detail