fix(mcp): Allow several tool groups in btw_mcp_server() (#221)

* fix(mcp): Allow several tool groups in btw_mcp_server()

The R file detection chained `is.character(tools) && file.exists(tools)`,
which errors under R >= 4.3 when `tools` names more than one tool group.
Use `is_string()` so the file branch only considers a single path.

Fixes #206

* test(mcp): assert flattened tools and R-script passthrough  Capture the `tools` argument passed to mcptools::mcp_server() and check that a character vector of tool groups is flattened to tools from those groups, and that a path to an .R script is passed through unflattened.  Follows up on #206, PR #221.

* docs(mcp): recommend tools.R script and document script-path semantics

---------

Co-authored-by: Garrick Aden-Buie <garrick@adenbuie.com>

Author: taekop

NEWS.md

@@ -4,6 +4,8 @@
 
 * Package tests now support a compact reporter that shows per-file progress, timing, warning and failure details, and final counts. `btw pkg test` uses it by default, while `btw_tool_pkg_test()` defaults to concise output for non-streaming clients; both accept other testthat reporter names (#220).
 
+* `btw_mcp_server()` no longer errors when `tools` is a character vector naming more than one tool group, e.g. `btw_mcp_server(c("docs", "env", "sessioninfo"))` (@taekop, #206).
+
 # btw 1.5.0
 
 ## New features

R/mcp.R

@@ -43,6 +43,36 @@
 #' See [btw_tools()] for a complete list of available tool groups and their
 #' contents.
 #'
+#' To combine btw's tools with your own custom tools, we recommend writing a
+#' small R script that returns the combined list of tools and passing its path
+#' to `btw_mcp_server()`.
+#'
+#' MCP servers are usually launched by your coding harness, e.g. via
+#' `Rscript -e "btw::btw_mcp_server(...)"` in a client configuration file.
+#' Composing the tool list in an R script is much easier to read and maintain
+#' than cramming the same code into an inline `Rscript` command. The script
+#' below combines btw's tools with your own custom tools:
+#'
+#' ```r
+#' # tools.R
+#' my_custom_tool <- ellmer::tool(
+#'   function() R.version.string,
+#'   "Report the version of R running the MCP server"
+#' )
+#'
+#' c(btw_tools("docs", "pkg"), list(my_custom_tool))
+#' ```
+#'
+#' The script is responsible for the complete list of tools, so include
+#' [btw_tools()] calls in the script to pull in btw's tools.
+#'
+#' Use an absolute path to the script in most cases, e.g.
+#' `btw_mcp_server("/path/to/tools.R")`. Relative paths are resolved against
+#' the working directory of the process launched by the coding harness, which
+#' is usually the project directory but isn't guaranteed. A project-specific
+#' tools script in the project directory is a reasonable use of a relative
+#' path, but absolute paths are the safest choice otherwise.
+#'
 #' @section Configuration:
 #' To configure this server with MCP clients, use the command `Rscript` and the
 #' args `-e "btw::btw_mcp_server()"`. We recommend customizing the tool set as
@@ -155,7 +185,9 @@
 #'   to the tools provided by [btw_tools()]. Use [btw_tools()] to subset to
 #'   specific list of \pkg{btw} tools that can be augmented with additional
 #'   tools. Alternatively, you can pass a path to an R script that returns a
-#'   list of tools as supported by [mcptools::mcp_server()].
+#'   list of tools as supported by [mcptools::mcp_server()]. In that case the
+#'   script provides the complete set of tools -- btw's tools are not included
+#'   unless the script itself adds them with [btw_tools()].
 #'
 #' @return Returns the result of [mcptools::mcp_server()] or
 #'   [mcptools::mcp_session()].
@@ -165,7 +197,7 @@
 btw_mcp_server <- function(tools = NULL) {
   # If given a path to an R script, we'll pass it on to mcp_server()
   is_likely_r_file <-
-    is.character(tools) &&
+    is_string(tools) &&
     file.exists(tools) &&
     grepl("[.]r$", tools, ignore.case = TRUE)
 
@@ -194,4 +226,4 @@ btw_mcp_tools <- function() {
     function(tool) !identical(tool@annotations$btw_group, "skills"),
     all_tools
   )
-}
+}

man/mcp.Rd

@@ -12,6 +12,51 @@ test_that("btw_mcp_server errors informatively with bad `tools`", {
   )
 })
 
+test_that("btw_mcp_server works with a character vector of multiple tool groups", {
+  local_enable_tools()
+
+  captured <- new.env(parent = emptyenv())
+  local_mocked_bindings(
+    mcp_server = function(tools, ...) {
+      captured$tools <- tools
+      "mocked"
+    },
+    .package = "mcptools"
+  )
+
+  expect_equal(btw_mcp_server(tools = c("docs", "env")), "mocked")
+
+  groups <- unique(vapply(
+    captured$tools,
+    function(tool) tool@annotations$btw_group,
+    character(1)
+  ))
+  expect_setequal(groups, c("docs", "env"))
+})
+
+test_that("btw_mcp_server passes an R script path through to mcptools", {
+  local_enable_tools()
+
+  # The script is sourced by mcptools::mcp_server(), not by btw_mcp_server(),
+  # so here we only assert that the path is handed over unflattened.
+  path_tools <- withr::local_tempfile(
+    lines = "btw::btw_tools('docs')",
+    fileext = ".R"
+  )
+
+  captured <- new.env(parent = emptyenv())
+  local_mocked_bindings(
+    mcp_server = function(tools, ...) {
+      captured$tools <- tools
+      "mocked"
+    },
+    .package = "mcptools"
+  )
+
+  expect_equal(btw_mcp_server(tools = path_tools), "mocked")
+  expect_equal(captured$tools, path_tools)
+})
+
 test_that("btw_mcp_tools() excludes skills group by default", {
   local_enable_tools()
   tools <- btw_mcp_tools()