--- title: "MCP tool schemas and example outputs" vignette: > %\VignetteIndexEntry{MCP tool schemas and example outputs} %\VignetteEngine{quarto::html} %\VignetteEncoding{UTF-8} format: html: toc: true toc-depth: 2 knitr: opts_chunk: collapse: true comment: '#>' --- This vignette shows what an MCP client can expose to an AI agent when the `rairai` server is used against this package. It prints all 21 current tool schemas and representative inputs. The 19 package-local examples run during rendering; the two CRAN examples show schemas and inputs only, without network calls or fabricated responses. Schemas and local responses come from freshly loaded package code, not hand-written snapshots. Example arguments are maintained here. Displayed JSON replaces the canonical build root with `/path/to/rairai`, including occurrences in nested values or keys. This is a publication-only redaction: runtime responses still disclose canonical absolute host paths. Source-relative locations are unchanged. ```{r} #| label: setup #| include: false knitr::opts_chunk$set(collapse = TRUE, comment = "#>") find_package_root <- function(path = getwd()) { path <- normalizePath(path, winslash = "/", mustWork = TRUE) repeat { if ( file.exists(file.path(path, "DESCRIPTION")) && dir.exists(file.path(path, "R")) ) { return(path) } parent <- dirname(path) if (identical(parent, path)) { stop("Could not find package root from ", getwd(), call. = FALSE) } path <- parent } } root <- find_package_root() knitr::opts_knit$set(root.dir = root) pkgload::load_all(root, quiet = TRUE) format_json <- function(x) { if (is.character(x) && length(x) == 1L && jsonlite::validate(x)) { x <- jsonlite::fromJSON(x, simplifyVector = FALSE) } jsonlite::toJSON( x, auto_unbox = TRUE, pretty = TRUE, null = "null", na = "null" ) |> stringr::str_replace_all(stringr::fixed(root), "/path/to/rairai") } serve_tools <- getFromNamespace("serve_tools", "rairai") PackageToolService <- getFromNamespace("PackageToolService", "rairai") service <- PackageToolService$new(root_path = root) tools <- serve_tools(service) dispatch <- getFromNamespace("dispatch_message", "mcplite") initialization <- dispatch( list( jsonrpc = "2.0", id = 1, method = "initialize", params = list( protocolVersion = "2025-11-25", capabilities = structure(list(), names = character()), clientInfo = list(name = "rairai-vignette", version = "0.0.0") ) ), getFromNamespace("new_server_state", "mcplite")(tools) ) stopifnot(identical( initialization$response$result$protocolVersion, "2025-11-25" )) state <- dispatch( list(jsonrpc = "2.0", method = "notifications/initialized"), initialization$state )$state response <- dispatch( list(jsonrpc = "2.0", id = 2, method = "tools/list"), state ) tool_definitions <- response$response$result$tools tool_names <- vapply(tool_definitions, function(tool) tool$name, character(1)) names(tools) <- tool_names names(tool_definitions) <- tool_names cran_tools <- c("cran_search", "cran_package") example_args <- list( package_overview = stats::setNames(list(), character()), package_dependencies = list(depth = 1L), package_files = list(scope = "R", include = c("lines", "size")), package_namespace = stats::setNames(list(), character()), tests_for = list(name = "serve_tools"), package_docs = list(package = "rairai", limit = 10L), help_search = list(query = "serve", package = "rairai", limit = 5L), help_page = list( topic = "serve", package = "rairai", sections = c("Description", "Usage", "Arguments", "Examples"), max_chars = 2000L ), package_vignettes = list(package = "rairai"), package_news = list(package = "rairai"), cran_search = list(query = "static analysis", n_results = 5L), cran_package = list(package_name = "treesitter"), r6_classes = stats::setNames(list(), character()), r6_class = list(name = "PackageToolService"), r6_method = list(class = "PackageToolService", method = "symbols"), r6_method_references = list( class = "PackageToolService", method = "symbols" ), symbols = list(query = "serve", kind = "Function", limit = 20L), definition = list(name = "serve", kind = "Function", exact = TRUE), references = list( name = "serve", kind = "Function", exact = TRUE, limit = 20L ), function_formals = list(name = "serve"), refactor_context = list( name = "serve", kind = "Function", exact = TRUE, limit = 20L ) ) stopifnot( length(tools) == 21L, setequal(names(example_args), tool_names) ) emit_tool_section <- function(name) { tool <- tools[[name]] schema <- tool_definitions[[name]] args <- example_args[[name]] if (is.null(args)) { stop("No example arguments configured for tool `", name, "`.", call. = FALSE) } cat("## `", name, "`\n\n", sep = "") cat(schema$description, "\n\n", sep = "") cat("### Schema visible to the MCP client\n\n") cat("```json\n") cat(format_json(schema), "\n", sep = "") cat("```\n\n") cat("### Example input\n\n") cat("```json\n") cat(format_json(args), "\n", sep = "") cat("```\n\n") if (name %in% cran_tools) { cat("Network example not run during rendering; no response is shown.\n\n") } else { result <- do.call(tool, args) cat("### Example response\n\n") cat("```json\n") cat(format_json(result), "\n", sep = "") cat("```\n\n") } } emit_tool_group <- function(title, names) { cat("# ", title, "\n\n", sep = "") stopifnot(all(names %in% tool_names)) for (name in names) { emit_tool_section(name) } } ``` ## How to read this vignette Each section below is produced from the live tool definitions in this package: - The schema comes from a `tools/list` response after negotiating MCP protocol version `2025-11-25` with `mcplite`. - The example input is a small argument list chosen to exercise the tool against this repository. - Each local response is produced by calling the tool during rendering. A failed call fails the render instead of being presented as a normal response. - CRAN inputs are illustrative and are not executed. Loading `rairai` here runs the documentation generator. The tools inspect package files and metadata statically; they do not execute inspected source to obtain facts. The 19 local schemas expose optional `package_root`; the CRAN schemas do not. See the [toolset overview](tools.html#tool-surface-and-package-roots) for root selection and filesystem access. ```{r} #| label: static-package-tools #| results: asis emit_tool_group( "Static package tools", c( "package_overview", "package_dependencies", "package_files", "package_namespace", "tests_for", "package_docs", "help_search", "help_page", "package_vignettes", "package_news" ) ) ``` ```{r} #| label: r6-tools #| results: asis emit_tool_group( "R6 structure tools", c( "r6_classes", "r6_class", "r6_method", "r6_method_references" ) ) ``` ```{r} #| label: source-workflow-tools #| results: asis emit_tool_group( "Source and workflow tools", c( "symbols", "definition", "references", "function_formals", "refactor_context" ) ) ``` ```{r} #| label: cran-tools #| results: asis emit_tool_group("CRAN metadata tools", cran_tools) ``` ## Regenerating the content Because this vignette evaluates the current package code, refreshing it is just a normal vignette render. If a tool schema changes, if a tool response shape changes, or if the package gains new tools, the generated sections above should reflect those changes after updating the `example_args` list as needed.