MCP ragnar server (#123)

* add `mcp_serve_store`

* opt-out of r session tools

Companion to posit-dev/mcptools#68

* update docs + small tweaks

* Change the default tool name prefix to `search_store_`

* add NEWS

* add `mcptools` to Suggests

* add `mcp_serve_store` to pkgdown

Author: t-kalinowski

DESCRIPTION

@@ -35,6 +35,7 @@ Imports:
     duckdb (>= 1.3.1),
     glue,
     httr2,
+    jsonlite,
     methods,
     reticulate (>= 1.42.0),
     rlang (>= 1.1.0),
@@ -51,13 +52,14 @@ Suggests:
     gargle,
     knitr,
     lifecycle,
+    mcptools,
     pandoc,
     paws.common,
     rmarkdown,
     shiny,
     stringr,
-    tibble,
-    testthat (>= 3.0.0)
+    testthat (>= 3.0.0),
+    tibble
 VignetteBuilder:
     knitr
 Config/Needs/website: tidyverse/tidytemplate, rmarkdown

NAMESPACE

@@ -14,6 +14,7 @@ export(embed_openai)
 export(markdown_chunk)
 export(markdown_frame)
 export(markdown_segment)
+export(mcp_serve_store)
 export(ragnar_chunk)
 export(ragnar_chunk_segments)
 export(ragnar_chunks_view)

NEWS.md

@@ -1,5 +1,11 @@
 # ragnar (development version)
 
+* New function `mcp_serve_store()` which supports letting a local MCP client
+  like Codex CLI or Claude Code search a `RagnarStore` (#123).
+
+* The default tool name prefix registered by `ragnar_register_tool_retrive()` has
+  changed from `rag_retrieve_from_` to `search_store_`.
+
 * Store Inspector updated with keyboard shortcuts, a draggable divider,
   improved preview linkification and metadata display,
   visual tweaks and general bug fixes (#120).

R/ellmer.R

@@ -39,12 +39,38 @@ ragnar_register_tool_retrieve <- function(
   check_string(name, allow_null = TRUE)
   check_string(title, allow_null = TRUE)
 
-  name <- name %||% glue::glue("rag_retrieve_from_{store@name}")
+  tool_def <- ragnar_tool_retrieve(
+    store = store,
+    store_description = store_description,
+    ...,
+    name = name,
+    title = title
+  )
+
+  chat$register_tool(tool_def)
+  invisible(chat)
+}
+
+# Internal: build an ellmer tool for retrieving from a Ragnar store
+ragnar_tool_retrieve <- function(
+  store,
+  store_description = "the knowledge store",
+  ...,
+  name = NULL,
+  title = NULL
+) {
+  rlang::check_installed("ellmer")
+
+  check_string(name, allow_null = TRUE)
+  check_string(title, allow_null = TRUE)
+
+  name <- name %||% glue::glue("search_store_{store@name}")
   title <- title %||% store@title
 
   previously_retrieved_chunk_ids <- integer()
+  list(...) # force
 
-  tool_def <- ellmer::tool(
+  ellmer::tool(
     function(text) {
       chunks <- ragnar_retrieve(
         store,
@@ -54,7 +80,14 @@ ragnar_register_tool_retrieve <- function(
       )
       previously_retrieved_chunk_ids <<-
         unique(unlist(c(chunks$chunk_id, previously_retrieved_chunk_ids)))
-      chunks
+      jsonlite::toJSON(
+        chunks,
+        pretty = TRUE,
+        auto_unbox = TRUE,
+        null = "null",
+        na = "null",
+        rownames = FALSE
+      )
     },
     name = name,
     description = glue::glue(
@@ -71,7 +104,78 @@ ragnar_register_tool_retrieve <- function(
       open_world_hint = FALSE
     )
   )
+}
 
-  chat$register_tool(tool_def)
-  invisible(chat)
+#' Serve a Ragnar store over MCP
+#'
+#' Launches an MCP server (via [mcptools::mcp_server()]) that exposes a
+#' retrieval tool backed by a Ragnar store. This lets MCP-enabled clients (e.g.,
+#' Codex CLI, Claude Code) call into your store to retrieve relevant
+#' excerpts.
+#'
+#' @param store A `RagnarStore` object or a file path to a Ragnar DuckDB store.
+#'   If a character path is supplied, it is opened with
+#'   [ragnar_store_connect()].
+#' @param store_description Optional string used in the tool description
+#'   presented to clients.
+#' @inheritParams ragnar_register_tool_retrieve
+# ' @param ... Additional arguments forwarded to [ragnar_retrieve()].
+# ' @param name,title Optional identifiers for the tool. By default, derives from
+# '   `store@name` and `store@title` when available.
+#' @param extra_tools Optional additional tools (list of `ellmer::tool()`
+#'   objects) to serve alongside the retrieval tool.
+#'
+#' @return This function blocks the current R process by running an MCP server.
+#'   It is intended for non-interactive use. Called primarily for side-effects.
+#'
+#' @details
+#'
+#' To use this function with [Codex CLI](https://developers.openai.com/codex/cli/), add something like this
+#' to `~/.codex/config.toml`
+#'
+#' ```toml
+#' [mcp_servers.quartohelp]
+#' command = "Rscript"
+#' args = [
+#'   "-e",
+#'   "ragnar::mcp_serve_store(quartohelp:::quartohelp_ragnar_store(), top_k=10)"
+#' ]
+#' ```
+#'
+#' You can confirm the agent can search the ragnar store by inspecting the
+#' output from the `/mcp` command, or by asking it "What tools do you have
+#' available?".
+#'
+#'
+#' @export
+mcp_serve_store <- function(
+  store,
+  store_description = "the knowledge store",
+  ...,
+  name = NULL,
+  title = NULL,
+  extra_tools = NULL
+) {
+  rlang::check_installed("mcptools")
+  rlang::check_installed("ellmer")
+
+  if (is.character(store)) {
+    store <- ragnar_store_connect(store)
+  }
+
+  retrieve_tool <- ragnar_tool_retrieve(
+    store = store,
+    store_description = store_description,
+    ...,
+    name = name,
+    title = title,
+    as_json = TRUE
+  )
+
+  tools <- c(list(retrieve_tool), extra_tools)
+  if (rlang::is_installed("mcptools", version = "0.1.1.9001")) {
+    mcptools::mcp_server(tools, include_session_tools = FALSE)
+  } else {
+    mcptools::mcp_server(tools)
+  }
 }

_pkgdown.yml

@@ -59,4 +59,5 @@ reference:
     contents:
       - starts_with("ragnar_retrieve")
       - ragnar_register_tool_retrieve
+      - mcp_serve_store
       - chunks_deoverlap