keep full plain-text spec in source

Author: simonpcouch

.Rbuildignore

@@ -13,3 +13,4 @@ inst/hex
 .claude/
 CLAUDE.md
 inst/diagrams.key
+inst/spec

CLAUDE.md

@@ -2,6 +2,8 @@
 
 The mcptools package uses nanonext for inter-process communication between the MCP server and R sessions. nanonext provides asynchronous messaging using the nanomsg/nng protocols.
 
+The full plain-text MCP specification lives in `.md` files in `inst/spec/`—tool call for it as needed.
+
 ## Key Concepts
 
 ### Asynchronous I/O (Aio)

inst/spec/authorization.md

@@ -0,0 +1,147 @@
+# Overview
+
+<div id="enable-section-numbers" />
+
+<Info>**Protocol Revision**: 2025-06-18</Info>
+
+The Model Context Protocol consists of several key components that work together:
+
+* **Base Protocol**: Core JSON-RPC message types
+* **Lifecycle Management**: Connection initialization, capability negotiation, and
+  session control
+* **Authorization**: Authentication and authorization framework for HTTP-based transports
+* **Server Features**: Resources, prompts, and tools exposed by servers
+* **Client Features**: Sampling and root directory lists provided by clients
+* **Utilities**: Cross-cutting concerns like logging and argument completion
+
+All implementations **MUST** support the base protocol and lifecycle management
+components. Other components **MAY** be implemented based on the specific needs of the
+application.
+
+These protocol layers establish clear separation of concerns while enabling rich
+interactions between clients and servers. The modular design allows implementations to
+support exactly the features they need.
+
+## Messages
+
+All messages between MCP clients and servers **MUST** follow the
+[JSON-RPC 2.0](https://www.jsonrpc.org/specification) specification. The protocol defines
+these types of messages:
+
+### Requests
+
+Requests are sent from the client to the server or vice versa, to initiate an operation.
+
+```typescript  theme={null}
+{
+  jsonrpc: "2.0";
+  id: string | number;
+  method: string;
+  params?: {
+    [key: string]: unknown;
+  };
+}
+```
+
+* Requests **MUST** include a string or integer ID.
+* Unlike base JSON-RPC, the ID **MUST NOT** be `null`.
+* The request ID **MUST NOT** have been previously used by the requestor within the same
+  session.
+
+### Responses
+
+Responses are sent in reply to requests, containing the result or error of the operation.
+
+```typescript  theme={null}
+{
+  jsonrpc: "2.0";
+  id: string | number;
+  result?: {
+    [key: string]: unknown;
+  }
+  error?: {
+    code: number;
+    message: string;
+    data?: unknown;
+  }
+}
+```
+
+* Responses **MUST** include the same ID as the request they correspond to.
+* **Responses** are further sub-categorized as either **successful results** or
+  **errors**. Either a `result` or an `error` **MUST** be set. A response **MUST NOT**
+  set both.
+* Results **MAY** follow any JSON object structure, while errors **MUST** include an
+  error code and message at minimum.
+* Error codes **MUST** be integers.
+
+### Notifications
+
+Notifications are sent from the client to the server or vice versa, as a one-way message.
+The receiver **MUST NOT** send a response.
+
+```typescript  theme={null}
+{
+  jsonrpc: "2.0";
+  method: string;
+  params?: {
+    [key: string]: unknown;
+  };
+}
+```
+
+* Notifications **MUST NOT** include an ID.
+
+## Auth
+
+MCP provides an [Authorization](/specification/2025-06-18/basic/authorization) framework for use with HTTP.
+Implementations using an HTTP-based transport **SHOULD** conform to this specification,
+whereas implementations using STDIO transport **SHOULD NOT** follow this specification,
+and instead retrieve credentials from the environment.
+
+Additionally, clients and servers **MAY** negotiate their own custom authentication and
+authorization strategies.
+
+For further discussions and contributions to the evolution of MCP’s auth mechanisms, join
+us in
+[GitHub Discussions](https://github.com/modelcontextprotocol/specification/discussions)
+to help shape the future of the protocol!
+
+## Schema
+
+The full specification of the protocol is defined as a
+[TypeScript schema](https://github.com/modelcontextprotocol/specification/blob/main/schema/2025-06-18/schema.ts).
+This is the source of truth for all protocol messages and structures.
+
+There is also a
+[JSON Schema](https://github.com/modelcontextprotocol/specification/blob/main/schema/2025-06-18/schema.json),
+which is automatically generated from the TypeScript source of truth, for use with
+various automated tooling.
+
+### General fields
+
+#### `_meta`
+
+The `_meta` property/parameter is reserved by MCP to allow clients and servers
+to attach additional metadata to their interactions.
+
+Certain key names are reserved by MCP for protocol-level metadata, as specified below;
+implementations MUST NOT make assumptions about values at these keys.
+
+Additionally, definitions in the [schema](https://github.com/modelcontextprotocol/specification/blob/main/schema/2025-06-18/schema.ts)
+may reserve particular names for purpose-specific metadata, as declared in those definitions.
+
+**Key name format:** valid `_meta` key names have two segments: an optional **prefix**, and a **name**.
+
+**Prefix:**
+
+* If specified, MUST be a series of labels separated by dots (`.`), followed by a slash (`/`).
+  * Labels MUST start with a letter and end with a letter or digit; interior characters can be letters, digits, or hyphens (`-`).
+* Any prefix beginning with zero or more valid labels, followed by `modelcontextprotocol` or `mcp`, followed by any valid label,
+  is **reserved** for MCP use.
+  * For example: `modelcontextprotocol.io/`, `mcp.dev/`, `api.modelcontextprotocol.org/`, and `tools.mcp.com/` are all reserved.
+
+**Name:**
+
+* Unless empty, MUST begin and end with an alphanumeric character (`[a-z0-9A-Z]`).
+* MAY contain hyphens (`-`), underscores (`_`), dots (`.`), and alphanumerics in between.

inst/spec/basic.md

@@ -0,0 +1,32 @@
+# The full plain-text spec is kept in inst/spec for use by coding agents.
+# Update it by calling this function.
+fetch_spec <- function(revision = "2025-06-18") {
+  base_url <- sprintf(
+    "https://modelcontextprotocol.io/specification/%s",
+    revision
+  )
+
+  files <- c(
+    "basic.md",
+    "basic/lifecycle.md",
+    "basic/transports.md",
+    "basic/authorization.md"
+  )
+
+  dest_dir <- system.file("spec", package = "mcptools")
+  if (dest_dir == "") {
+    dest_dir <- "inst/spec"
+  }
+
+  if (!dir.exists(dest_dir)) {
+    dir.create(dest_dir, recursive = TRUE)
+  }
+
+  for (file in files) {
+    url <- file.path(base_url, file)
+    dest_file <- file.path(dest_dir, basename(file))
+    download.file(url, dest_file, quiet = FALSE, mode = "wb")
+  }
+
+  invisible(dest_dir)
+}