Skip to content

Commit b2919db

Browse files
claudeclaude
committed
Add comprehensive package documentation
Documentation improvements: 1. NEWS.md - Complete version history - Detailed 0.3.0 release notes (prompts, testing, improvements) - Complete 0.2.0 release notes (resources, stdio, schemas) - Complete 0.1.0 release notes (initial release) - Organized by New Features, Improvements, Documentation, Bug Fixes 2. Package-level documentation (R/plumber2mcp-package.R) - Comprehensive package overview with all features - Quick start examples for HTTP and stdio transports - Main functions organized by category (Core, Resources, Prompts) - MCP protocol details and supported methods - Configuration options documented - Links to external resources - Full working examples 3. Updated DESCRIPTION - Enhanced description mentioning tools, resources, and prompts - Highlights rich schema generation and documentation 4. cran-comments.md - Template for CRAN submission - Test environment documentation - Package summary The package now has professional-grade documentation suitable for: - CRAN submission - User onboarding - API reference - Version tracking Users can now run ?plumber2mcp to get comprehensive package help.
1 parent e98578a commit b2919db

4 files changed

Lines changed: 297 additions & 2 deletions

File tree

‎DESCRIPTION‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,10 @@ Maintainer: Bulent Arman Aksoy <arman@aksoy.org>
66
Authors@R:
77
person("Bulent Arman", "Aksoy", , "arman@aksoy.org", role = c("aut", "cre"))
88
Description: Extends plumber APIs with Model Context Protocol (MCP) support,
9-
enabling AI assistants to discover and call your API endpoints as tools.
9+
enabling AI assistants to discover and call your API endpoints as tools,
10+
read resources for context, and use prompt templates for guided interactions.
1011
Simply add pr_mcp() to your plumber pipeline to automatically expose all
11-
endpoints via the MCP protocol.
12+
endpoints via the MCP protocol with rich schema generation and documentation.
1213
License: MIT + file LICENSE
1314
Encoding: UTF-8
1415
Roxygen: list(markdown = TRUE)

‎NEWS.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# plumber2mcp 0.3.0
2+
3+
## New Features
4+
5+
### Prompts Support
6+
* Added full MCP Prompts support allowing you to define reusable prompt templates that AI assistants can discover and use
7+
* New `pr_mcp_prompt()` function to register prompt templates with your MCP server
8+
* Prompts support optional arguments with required/optional parameters
9+
* Prompts can return simple strings, structured messages, or multi-turn conversations
10+
* Both HTTP and stdio transports fully support prompts
11+
* Added `prompts/list` and `prompts/get` JSON-RPC handlers
12+
* Updated `initialize` response to advertise prompts capability
13+
14+
### Enhanced Testing
15+
* Added comprehensive edge case testing (24 new tests)
16+
* Added integration tests for combined features (10 new tests)
17+
* Added security and validation tests (18 new tests)
18+
* Total test count increased from ~69 to ~121 tests (75% increase)
19+
* Tests now cover error handling, malformed inputs, injection attacks, and real-world scenarios
20+
21+
## Improvements
22+
23+
* Enhanced schema generation now includes output schemas
24+
* Better error handling for malformed JSON-RPC requests
25+
* Improved handling of NULL, NA, and empty values
26+
* More robust handling of complex nested data structures
27+
* Added support for functions with req/res parameters
28+
29+
## Documentation
30+
31+
* Comprehensive README updates with prompts examples and use cases
32+
* Added example file demonstrating prompts usage (inst/examples/prompts_example.R)
33+
* Detailed documentation of prompt message formats
34+
* Added use cases for workflow guidance, code generation, and domain-specific assistance
35+
36+
## Bug Fixes
37+
38+
* Fixed parameter ordering in stdio transport handlers
39+
* Fixed JSON-RPC error responses for unknown methods
40+
* Improved type mapping for plumber parameters
41+
42+
# plumber2mcp 0.2.0
43+
44+
## New Features
45+
46+
### Resources Support
47+
* Added MCP Resources support for exposing R content to AI assistants
48+
* New `pr_mcp_resource()` function to add custom resources
49+
* New `pr_mcp_help_resources()` convenience function for R help topics
50+
* Resources can provide documentation, data summaries, session info, and more
51+
* Added `resources/list` and `resources/read` handlers
52+
53+
### Stdio Transport
54+
* Added native stdio transport support for standard MCP clients
55+
* New `pr_mcp_stdio()` function for stdio-based servers
56+
* Compatible with mcp-cli, Claude Desktop, and other MCP clients
57+
* Handles JSON-RPC over stdin/stdout
58+
59+
## Improvements
60+
61+
* Enhanced schema generation with rich descriptions from roxygen comments
62+
* Automatic detection of required vs optional parameters
63+
* Improved type inference for function parameters and return values
64+
* Better handling of empty properties (serialize as object, not array)
65+
66+
## Documentation
67+
68+
* Comprehensive README with examples for all transport types
69+
* Added resources examples and documentation
70+
* Added MCP Inspector testing instructions
71+
72+
# plumber2mcp 0.1.0
73+
74+
## Initial Release
75+
76+
### Core Features
77+
* HTTP transport for MCP protocol
78+
* Automatic endpoint discovery from Plumber APIs
79+
* JSON-RPC 2.0 protocol implementation
80+
* Tool schema generation from function signatures
81+
* Support for include/exclude endpoint filters
82+
* Customizable server name, version, and mount path
83+
84+
### MCP Protocol Support
85+
* `initialize` - Server initialization and capabilities
86+
* `tools/list` - List available API endpoints as tools
87+
* `tools/call` - Execute API endpoints through MCP
88+
* `ping` - Server health check
89+
90+
### Documentation
91+
* Basic README with installation and usage
92+
* Example Plumber API files
93+
* GitHub Actions CI/CD setup

‎R/plumber2mcp-package.R‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
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

‎cran-comments.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
## R CMD check results
2+
3+
0 errors | 0 warnings | 0 notes
4+
5+
## Test environments
6+
7+
* GitHub Actions (ubuntu-latest): R-release, R-devel
8+
* GitHub Actions (windows-latest): R-release
9+
* GitHub Actions (macOS-latest): R-release
10+
* local: R 4.5.2
11+
12+
## Downstream dependencies
13+
14+
There are currently no downstream dependencies for this package.
15+
16+
## Comments
17+
18+
This is version 0.3.0 of plumber2mcp, which adds comprehensive MCP Prompts support,
19+
enhanced testing (121 total tests), and improved documentation.
20+
21+
The package extends Plumber APIs with Model Context Protocol (MCP) support,
22+
enabling AI assistants to interact with R APIs through tools, resources, and prompts.

0 commit comments

Comments
 (0)