|
| 1 | +#' @keywords internal |
| 2 | +"_PACKAGE" |
| 3 | + |
| 4 | +#' plumber2mcp: Add Model Context Protocol Support to Plumber APIs |
| 5 | +#' |
| 6 | +#' @description |
| 7 | +#' The plumber2mcp package extends Plumber APIs with Model Context Protocol (MCP) |
| 8 | +#' support, enabling AI assistants (like Claude, ChatGPT, etc.) to discover and |
| 9 | +#' interact with your R functions through three key MCP primitives: |
| 10 | +#' |
| 11 | +#' \itemize{ |
| 12 | +#' \item \strong{Tools}: AI assistants can call your API endpoints directly |
| 13 | +#' \item \strong{Resources}: AI assistants can read documentation, data, and analysis results |
| 14 | +#' \item \strong{Prompts}: AI assistants can use pre-defined templates to guide interactions |
| 15 | +#' } |
| 16 | +#' |
| 17 | +#' @section Main Functions: |
| 18 | +#' |
| 19 | +#' \strong{Core MCP Setup:} |
| 20 | +#' \itemize{ |
| 21 | +#' \item \code{\link{pr_mcp}}: Add MCP support to a Plumber router (main function) |
| 22 | +#' \item \code{\link{pr_mcp_http}}: Add MCP support with HTTP transport |
| 23 | +#' \item \code{\link{pr_mcp_stdio}}: Add MCP support with stdio transport |
| 24 | +#' } |
| 25 | +#' |
| 26 | +#' \strong{Resources:} |
| 27 | +#' \itemize{ |
| 28 | +#' \item \code{\link{pr_mcp_resource}}: Add a custom resource |
| 29 | +#' \item \code{\link{pr_mcp_help_resources}}: Add built-in R help resources |
| 30 | +#' } |
| 31 | +#' |
| 32 | +#' \strong{Prompts:} |
| 33 | +#' \itemize{ |
| 34 | +#' \item \code{\link{pr_mcp_prompt}}: Add a prompt template |
| 35 | +#' } |
| 36 | +#' |
| 37 | +#' @section Quick Start: |
| 38 | +#' |
| 39 | +#' \strong{HTTP Transport (for testing):} |
| 40 | +#' \preformatted{ |
| 41 | +#' library(plumber) |
| 42 | +#' library(plumber2mcp) |
| 43 | +#' |
| 44 | +#' pr("plumber.R") \%>\% |
| 45 | +#' pr_mcp(transport = "http") \%>\% |
| 46 | +#' pr_run(port = 8000) |
| 47 | +#' } |
| 48 | +#' |
| 49 | +#' \strong{Stdio Transport (for MCP clients):} |
| 50 | +#' \preformatted{ |
| 51 | +#' library(plumber) |
| 52 | +#' library(plumber2mcp) |
| 53 | +#' |
| 54 | +#' pr("plumber.R") \%>\% |
| 55 | +#' pr_mcp(transport = "stdio") |
| 56 | +#' } |
| 57 | +#' |
| 58 | +#' @section Adding Features: |
| 59 | +#' |
| 60 | +#' \strong{Add a Resource:} |
| 61 | +#' \preformatted{ |
| 62 | +#' pr \%>\% |
| 63 | +#' pr_mcp(transport = "stdio") \%>\% |
| 64 | +#' pr_mcp_resource( |
| 65 | +#' uri = "/data/summary", |
| 66 | +#' func = function() summary(mtcars), |
| 67 | +#' name = "Dataset Summary" |
| 68 | +#' ) |
| 69 | +#' } |
| 70 | +#' |
| 71 | +#' \strong{Add a Prompt:} |
| 72 | +#' \preformatted{ |
| 73 | +#' pr \%>\% |
| 74 | +#' pr_mcp(transport = "stdio") \%>\% |
| 75 | +#' pr_mcp_prompt( |
| 76 | +#' name = "analyze-data", |
| 77 | +#' description = "Guide for data analysis", |
| 78 | +#' arguments = list( |
| 79 | +#' list(name = "dataset", description = "Dataset name", required = TRUE) |
| 80 | +#' ), |
| 81 | +#' func = function(dataset) { |
| 82 | +#' paste("Please analyze the", dataset, "dataset") |
| 83 | +#' } |
| 84 | +#' ) |
| 85 | +#' } |
| 86 | +#' |
| 87 | +#' @section MCP Protocol: |
| 88 | +#' |
| 89 | +#' This package implements the Model Context Protocol (MCP) specification version |
| 90 | +#' 2024-11-05. It provides: |
| 91 | +#' |
| 92 | +#' \itemize{ |
| 93 | +#' \item \strong{Automatic endpoint discovery}: Scans your Plumber API and converts endpoints to MCP tools |
| 94 | +#' \item \strong{Rich schema generation}: Creates detailed JSON schemas from roxygen documentation |
| 95 | +#' \item \strong{JSON-RPC 2.0}: Handles all MCP communication via JSON-RPC |
| 96 | +#' \item \strong{Multiple transports}: HTTP (for testing) and stdio (for MCP clients) |
| 97 | +#' \item \strong{Enhanced documentation}: Extracts parameter descriptions, types, and defaults |
| 98 | +#' } |
| 99 | +#' |
| 100 | +#' @section Supported MCP Methods: |
| 101 | +#' |
| 102 | +#' \strong{Core Protocol:} |
| 103 | +#' \itemize{ |
| 104 | +#' \item \code{initialize}: Server initialization and capability negotiation |
| 105 | +#' \item \code{ping}: Health check |
| 106 | +#' } |
| 107 | +#' |
| 108 | +#' \strong{Tools:} |
| 109 | +#' \itemize{ |
| 110 | +#' \item \code{tools/list}: List available API endpoints |
| 111 | +#' \item \code{tools/call}: Execute an API endpoint |
| 112 | +#' } |
| 113 | +#' |
| 114 | +#' \strong{Resources:} |
| 115 | +#' \itemize{ |
| 116 | +#' \item \code{resources/list}: List available resources |
| 117 | +#' \item \code{resources/read}: Read a specific resource |
| 118 | +#' \item \code{resources/templates/list}: List resource templates |
| 119 | +#' } |
| 120 | +#' |
| 121 | +#' \strong{Prompts:} |
| 122 | +#' \itemize{ |
| 123 | +#' \item \code{prompts/list}: List available prompt templates |
| 124 | +#' \item \code{prompts/get}: Get a specific prompt with arguments |
| 125 | +#' } |
| 126 | +#' |
| 127 | +#' @section Configuration: |
| 128 | +#' |
| 129 | +#' Customize your MCP server with: |
| 130 | +#' \itemize{ |
| 131 | +#' \item \code{path}: Custom mount path (default: "/mcp") |
| 132 | +#' \item \code{include_endpoints}: Whitelist specific endpoints |
| 133 | +#' \item \code{exclude_endpoints}: Blacklist specific endpoints |
| 134 | +#' \item \code{server_name}: Custom server name |
| 135 | +#' \item \code{server_version}: Custom server version |
| 136 | +#' \item \code{debug}: Enable debug logging (stdio only) |
| 137 | +#' } |
| 138 | +#' |
| 139 | +#' @section Learn More: |
| 140 | +#' |
| 141 | +#' \itemize{ |
| 142 | +#' \item MCP Specification: \url{https://modelcontextprotocol.io} |
| 143 | +#' \item GitHub Repository: \url{https://github.com/armish/plumber2mcp} |
| 144 | +#' \item Plumber Documentation: \url{https://www.rplumber.io} |
| 145 | +#' } |
| 146 | +#' |
| 147 | +#' @examples |
| 148 | +#' \dontrun{ |
| 149 | +#' # Basic HTTP server |
| 150 | +#' library(plumber) |
| 151 | +#' library(plumber2mcp) |
| 152 | +#' |
| 153 | +#' pr <- plumber::pr() |
| 154 | +#' pr$handle("GET", "/echo", function(msg = "hello") { |
| 155 | +#' list(message = msg) |
| 156 | +#' }) |
| 157 | +#' |
| 158 | +#' pr %>% |
| 159 | +#' pr_mcp(transport = "http") %>% |
| 160 | +#' pr_run(port = 8000) |
| 161 | +#' |
| 162 | +#' # Full-featured stdio server |
| 163 | +#' pr %>% |
| 164 | +#' pr_mcp(transport = "stdio") %>% |
| 165 | +#' pr_mcp_resource( |
| 166 | +#' uri = "/docs/api", |
| 167 | +#' func = function() "API Documentation", |
| 168 | +#' name = "API Docs" |
| 169 | +#' ) %>% |
| 170 | +#' pr_mcp_prompt( |
| 171 | +#' name = "help", |
| 172 | +#' description = "Get help with the API", |
| 173 | +#' func = function() "How can I help you use this API?" |
| 174 | +#' ) |
| 175 | +#' } |
| 176 | +#' |
| 177 | +#' @docType package |
| 178 | +#' @name plumber2mcp-package |
| 179 | +NULL |
0 commit comments