@zigrivers/scaffold 3.32.1 → 3.33.0

package/content/knowledge/mcp-server/mcp-error-handling.md

@@ -0,0 +1,131 @@
+---
+name: mcp-error-handling
+description: MCP protocol errors (JSON-RPC error codes) vs tool execution errors (isError content), partial failures, error message design, and client recovery patterns
+topics: [mcp, error-handling, json-rpc, tool-errors, protocol-errors]
+volatility: evolving
+last-reviewed: null
+version-pin: 'MCP spec 2025-11-25'
+sources:
+  - url: https://modelcontextprotocol.io/specification/2025-11-25/server/tools
+  - url: https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle
+  - url: https://www.jsonrpc.org/specification
+---
+
+MCP has two distinct error channels. Mixing them up is one of the most common MCP server bugs: using protocol errors for domain failures causes the LLM to lose context about what went wrong; using isError for protocol failures breaks client error-handling logic.
+
+## Summary
+
+**Protocol errors** (JSON-RPC error responses) signal that a request could not be processed at all — unknown method, invalid parameters, server crash. Use standard JSON-RPC error codes. **Tool execution errors** (`isError: true` in the tool result) signal that the tool ran but the operation failed — API error, resource not found, business logic rejection. The LLM can read and react to tool errors; it cannot generally recover from protocol errors. Always prefer `isError: true` for domain-level failures that a well-behaved caller might encounter.
+
+## Deep Guidance
+
+### Protocol errors: JSON-RPC error responses
+
+A protocol error is a JSON-RPC error response object. It replaces the `result` field entirely:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "error": {
+    "code": -32602,
+    "message": "Unknown tool: invalid_tool_name"
+  }
+}
+```
+
+Use protocol errors for:
+- **Method not found** (`-32601`): the client called a method the server does not implement.
+- **Invalid params** (`-32602`): structural/wire-level request problems that prevent dispatch entirely — unknown tool name in `tools/call`, unknown method, missing required prompt arguments to `prompts/get`, invalid resource URI in `resources/read`, malformed params shape at the JSON-RPC level. **Do NOT use `-32602` for a tool that dispatched successfully but whose arguments fail the tool's own `inputSchema` or business validation** — those are tool execution errors (see `isError` below).
+- **Internal error** (`-32603`): unhandled exception or server bug. Include enough detail in `message` to diagnose, but sanitize sensitive data.
+- **Parse error** (`-32700`): malformed JSON received. The SDK handles this automatically.
+- **Invalid request** (`-32600`): request is not valid JSON-RPC 2.0 structure. Also SDK-handled.
+
+Custom server-defined error codes MUST be in the JSON-RPC server-error range `-32099` to `-32000` (most-negative to least-negative). Standard resource error code: `-32002` (resource not found).
+
+The `error` object MAY include a `data` field with additional structured context:
+```json
+{
+  "code": -32602,
+  "message": "Missing required argument",
+  "data": { "argument": "location", "required": true }
+}
+```
+
+### Tool execution errors: isError
+
+When a tool runs but the operation it performs fails, return the failure as a normal result with `isError: true`:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 4,
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "Failed to fetch weather data: API returned 429 Too Many Requests. Rate limit resets at 14:00 UTC. Suggest retrying after that time."
+      }
+    ],
+    "isError": true
+  }
+}
+```
+
+Use `isError: true` for:
+- **Tool input/schema validation failures** — when a tool dispatches but its arguments fail the tool's own `inputSchema` or business validation rules (wrong value, out-of-range number, unsupported enum value, failed cross-field constraint). Per SEP-1303 (2025-11-25), these MUST be `isError: true` so the model can self-correct, NOT `-32602`.
+- External API failures (HTTP 4xx/5xx from downstream services)
+- Resource not found in a domain sense (file doesn't exist at the path the user specified)
+- Business logic rejections (insufficient permissions in the target system, invalid state for the operation)
+- Network timeouts when calling downstream services
+- Partial failures where the overall result is a failure
+
+**Why this distinction matters**: when `isError: true`, the result is a successful JSON-RPC response — the protocol layer worked correctly. The LLM receives the content and can read the error message, decide to retry with different parameters, inform the user, or take an alternative approach. Protocol errors, on the other hand, are invisible to the LLM in most client implementations — they're handled at the transport/client layer. The 2025-11-25 spec revision (SEP-1303) explicitly directs that tool input validation errors MUST be returned as Tool Execution Errors (`isError: true`) rather than Protocol Errors (`-32602`), specifically to enable model self-correction. This applies to any argument that dispatches to a real tool but fails schema/business validation once there.
+
+### Error message quality
+
+Both protocol error messages and `isError` content messages are read by either developers (protocol errors) or LLMs (isError). Write them to be actionable:
+
+**For isError messages** (LLM-readable):
+- State what failed specifically, not just "an error occurred".
+- Include any relevant IDs, timestamps, or context the LLM can use.
+- Suggest what to do next when recovery is possible.
+- Include rate limit reset times, retry suggestions, or alternative approaches.
+
+**For protocol error messages** (developer-readable):
+- Name the specific field or method that caused the error.
+- Quote the invalid value or describe the expected format.
+- Avoid exposing internal file paths, stack traces, or secrets.
+
+### Partial failures in multi-item operations
+
+When a tool processes multiple items and some succeed while others fail:
+
+**Option A (partial success)**: Return successful results and error descriptions in the `content` array, without setting `isError: true`. Use this when partial output is useful:
+```json
+{
+  "content": [
+    { "type": "text", "text": "Processed 3 of 5 items:\n✓ item1: success\n✓ item2: success\n✗ item3: rate limited\n✓ item4: success\n✗ item5: not found" }
+  ]
+}
+```
+
+**Option B (total failure)**: If no items succeeded or the partial result is not useful, set `isError: true` and describe the failure.
+
+Never silently drop failures — always include what failed and why, even in partial success responses.
+
+### Initialization and lifecycle errors
+
+During the `initialize` handshake, return a protocol error if:
+- The client requests a protocol version the server does not support (respond with your supported version per spec, or error if incompatible).
+- Required capabilities cannot be negotiated.
+
+After initialization, if a client calls a method whose capability was not declared (e.g., calls `tools/list` but the server did not declare `tools` capability), return `-32601` (method not found) or `-32602` (invalid params) to indicate the feature is not available.
+
+### Client-side recovery patterns
+
+MCP clients should handle these error patterns from servers:
+- **Protocol error on tool call**: log the error, surface to user if relevant, do not retry automatically (likely a programming error).
+- **`isError: true` on tool result**: pass the error content to the LLM — it can decide whether to retry, use a different tool, or report to the user.
+- **Server disconnect / connection reset**: attempt reconnection and re-run the `initialize` handshake before resuming operations. Do not silently drop in-flight requests.
+- **`notifications/tools/list_changed`**: re-issue `tools/list` before the next tool call to ensure the cached tool list is current.

package/content/knowledge/mcp-server/mcp-observability.md

@@ -0,0 +1,125 @@
+---
+name: mcp-observability
+description: MCP server structured logging, stderr discipline for stdio transport, log message notifications, request tracing, debugging with MCP Inspector, and performance monitoring
+topics: [mcp, observability, logging, tracing, debugging, monitoring]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://modelcontextprotocol.io/docs/tools/debugging
+  - url: https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/logging
+---
+
+Good observability in an MCP server means you can diagnose problems without attaching a debugger. The fundamental constraint is the stdio transport's stdout-is-protocol-only rule, which makes naive logging dangerous. Structured logging to the right channel is non-negotiable.
+
+## Summary
+
+For **stdio servers**, write all logging to **stderr** — stdout is reserved exclusively for JSON-RPC protocol messages. Any stray write to stdout corrupts the protocol stream. For **HTTP servers**, use standard structured logging to files, stdout, or an aggregator — stderr is not captured by clients. MCP also provides a protocol-level logging mechanism via `notifications/message` (usable on any transport). Always include a correlation ID per request. Use the MCP Inspector as your first debugging tool.
+
+## Deep Guidance
+
+### Stderr discipline for stdio transport
+
+The stdio transport reserves stdout entirely for JSON-RPC protocol messages. Even a single line of non-JSON output to stdout — a startup banner, a debug print, a library that logs to stdout by default — will corrupt the message stream and cause parse errors in the client. This is the most common cause of "MCP server not responding" problems.
+
+**TypeScript/Node.js**: use `process.stderr.write(...)` or a logging library configured to stderr:
+```typescript
+import { createWriteStream } from 'node:fs'
+// write to stderr or a log file — never process.stdout
+const log = (msg: string) => process.stderr.write(`[server] ${msg}\n`)
+```
+
+**Python**: use `print(..., file=sys.stderr)` or configure `logging` to use stderr:
+```python
+import logging, sys
+logging.basicConfig(
+    level=logging.INFO,
+    stream=sys.stderr,  # critical: must be stderr, not stdout
+    format='%(asctime)s %(levelname)s %(name)s: %(message)s'
+)
+```
+
+The Python SDK's FastMCP does this correctly by default. Watch for third-party libraries that configure their own logging handlers pointing at stdout.
+
+**Go**: `log.Println` writes to stderr by default — safe for stdio servers. Avoid `fmt.Println` which goes to stdout.
+
+### MCP protocol-level logging (all transports)
+
+For any transport, the server can send log messages to the client via the `notifications/message` notification. The server must declare `logging: {}` in its capabilities during initialization.
+
+Log levels follow RFC 5424: `debug`, `info`, `notice`, `warning`, `error`, `critical`, `alert`, `emergency`. Clients can set the minimum level via `logging/setLevel`.
+
+TypeScript SDK:
+```typescript
+await server.sendLoggingMessage({ level: 'info', data: 'Tool execution started', logger: 'weather-tool' })
+```
+
+Python FastMCP:
+```python
+await ctx.session.send_log_message(level="info", data="Processing request", logger="my-server")
+```
+
+Protocol-level logging is visible to the MCP client (and to the Inspector's Notifications pane), making it useful for surfacing server state to the host application without relying on stderr capture.
+
+### Structured logging format
+
+Use structured logs (JSON or key=value) rather than unstructured strings. Include:
+- `timestamp`: ISO 8601 or epoch milliseconds
+- `level`: debug/info/warning/error
+- `request_id` or `correlation_id`: unique per MCP request (use the JSON-RPC `id` field value)
+- `method`: the JSON-RPC method being handled
+- `tool_name` / `resource_uri` / `prompt_name`: the specific capability invoked
+- `duration_ms`: time taken (for completed requests)
+- `error`: error type and message (for failures)
+
+Example structured log entry:
+```json
+{
+  "timestamp": "2025-06-18T14:32:01.234Z",
+  "level": "info",
+  "request_id": "42",
+  "method": "tools/call",
+  "tool_name": "get_weather",
+  "duration_ms": 234,
+  "location": "New York"
+}
+```
+
+### Request tracing
+
+Assign a correlation ID to each incoming MCP request using the JSON-RPC `id` field (for requests) or a generated UUID (for notifications). Thread this ID through all log entries, downstream API calls, and database queries generated by that request. This makes it possible to reconstruct the full execution path for a single tool call when debugging a failure.
+
+For HTTP transport, also include the `Mcp-Session-Id` in logs to correlate all requests within a session.
+
+### Debugging with MCP Inspector
+
+The MCP Inspector is the most effective debugging tool for local development:
+
+```bash
+# Launch your server with the Inspector
+npx @modelcontextprotocol/inspector node dist/server.js
+```
+
+Inspector debugging workflow:
+1. Check the Notifications pane for server log messages and error notifications.
+2. Invoke a failing tool and inspect the raw request/response in the tool result pane.
+3. Verify capability negotiation — check that the capabilities shown in the Inspector match what your server declares.
+4. Test error paths explicitly: call tools with invalid inputs and verify `isError: true` responses display correctly.
+
+For Claude Desktop specifically, tail the MCP log files:
+```bash
+# macOS
+tail -F ~/Library/Logs/Claude/mcp*.log
+```
+
+### Performance monitoring
+
+Log operation timing for all tool calls and resource reads. Track:
+- **p50/p95/p99 latency** per tool: identify slow tools before users complain.
+- **Error rate** per tool: high error rates indicate API instability or logic bugs.
+- **Payload size**: large tool results consume LLM context; log result byte sizes to catch runaway responses.
+- **Downstream API latency**: separately log time spent waiting for external APIs vs. server-side processing.
+
+For HTTP-transport servers, standard HTTP middleware (Morgan, Express's req timing) captures request-level metrics. For stdio servers, implement timing within each tool handler and write to stderr/log file.
+
+Set alerts on: error rate above 5%, tool latency p99 above 5 seconds, and any `SIGTERM` not followed by clean exit within 30 seconds (hung shutdown).

package/content/knowledge/mcp-server/mcp-prompt-primitives.md

@@ -0,0 +1,119 @@
+---
+name: mcp-prompt-primitives
+description: MCP prompts as user-controlled primitives, prompts/list and prompts/get methods, arguments, message roles, and when to use prompts vs tools
+topics: [mcp, prompts, ux, slash-commands, prompt-templates]
+volatility: evolving
+last-reviewed: null
+version-pin: 'MCP spec 2025-11-25'
+sources:
+  - url: https://modelcontextprotocol.io/specification/2025-11-25/server/prompts
+---
+
+Prompts in MCP are structured, reusable message templates that users explicitly select. They are different from tools (model-controlled, automatic) and resources (application-controlled, passive context). Understanding the distinction shapes how you expose server capabilities.
+
+## Summary
+
+Servers declare prompts via `prompts/list`; clients retrieve a populated prompt via `prompts/get` with filled-in arguments. Each prompt returns a `messages` array with `role`/`content` pairs ready to inject into a conversation. Prompts are **user-controlled** — they appear as slash commands or UI-selectable templates. Declare `prompts: { listChanged: true }` if the available prompts can change at runtime. Use prompts when a user needs to explicitly invoke a repeatable interaction pattern; use tools when the LLM should autonomously execute an action.
+
+## Deep Guidance
+
+### Prompts as user-controlled primitives
+
+The defining characteristic of MCP prompts is that they are **user-initiated**, not model-initiated. The host surfaces them as discoverable, selectable commands — typically slash commands in a chat UI, menu items in an IDE, or shortcut buttons in a desktop app. The user explicitly chooses a prompt, fills in any arguments, and the resulting message sequence is injected into the conversation.
+
+This contrasts sharply with tools (which the LLM invokes automatically based on context) and resources (which the host includes in context based on application logic). Prompts are neither automatic nor passive — they are deliberate user actions.
+
+### prompts/list — discovery
+
+`prompts/list` returns available prompt templates. Each entry includes `name`, optional `title` (display name), optional `description`, and an optional `arguments` array:
+
+```json
+{
+  "prompts": [
+    {
+      "name": "code_review",
+      "title": "Request Code Review",
+      "description": "Ask the model to review code for quality, bugs, and improvements",
+      "arguments": [
+        {
+          "name": "code",
+          "description": "The source code to review",
+          "required": true
+        },
+        {
+          "name": "language",
+          "description": "Programming language, e.g. TypeScript",
+          "required": false
+        }
+      ]
+    }
+  ]
+}
+```
+
+`prompts/list` supports cursor-based pagination. If the server can add or remove prompts dynamically, declare `prompts: { listChanged: true }` and send `notifications/prompts/list_changed` when the set changes.
+
+### prompts/get — retrieval and argument injection
+
+`prompts/get` takes a `name` and an `arguments` map (matching the declared argument names to concrete values). The server returns a `messages` array — fully formed conversation messages ready to send to an LLM:
+
+```json
+{
+  "method": "prompts/get",
+  "params": {
+    "name": "code_review",
+    "arguments": {
+      "code": "function add(a, b) { return a + b }",
+      "language": "JavaScript"
+    }
+  }
+}
+```
+
+Response:
+```json
+{
+  "result": {
+    "description": "Code review prompt for JavaScript",
+    "messages": [
+      {
+        "role": "user",
+        "content": {
+          "type": "text",
+          "text": "Please review this JavaScript code for quality, potential bugs, and improvements:\n\nfunction add(a, b) { return a + b }"
+        }
+      }
+    ]
+  }
+}
+```
+
+The server does the argument substitution and structures the messages — the client does not template-expand arguments itself. This lets the server implement sophisticated logic: injecting relevant resources, fetching live data to embed in the prompt, or constructing multi-turn conversation starters.
+
+### Message roles and content types
+
+Prompt messages support `role: "user"` and `role: "assistant"`. Use `"user"` for the human turn and `"assistant"` for pre-seeded model responses (useful for few-shot examples or to prime a specific response style).
+
+Content types within messages match tool result content types: `text`, `image`, `audio`, and `resource` (embedded resource). Use embedded resources to include relevant file contents, API data, or database records directly in the prompt without requiring a separate `resources/read` call.
+
+### When to use prompts vs tools vs resources
+
+These three primitives answer different questions:
+
+| Primitive | Controlled by | When to use |
+|-----------|--------------|-------------|
+| **Prompt** | User (explicit selection) | Repeatable interaction patterns a user deliberately invokes: code review, explain concept, generate commit message |
+| **Tool** | LLM (autonomous invocation) | Actions the LLM should take as part of its reasoning: fetch data, write file, call API |
+| **Resource** | Application (contextual inclusion) | Background context the LLM should be aware of: current file, open database schema, active configuration |
+
+A prompt for "generate a commit message" is appropriate — the user explicitly decides to invoke this pattern. A tool for "get_current_file" is appropriate — the LLM decides when fetching the current file is relevant to its task. A resource for "current_project_schema" is appropriate — the host automatically includes the schema as background context.
+
+Avoid turning every capability into a prompt. Prompts that should be tools (because the LLM should invoke them automatically) create friction. Prompts that should be resources (because they're background context) waste a user action.
+
+### Argument design
+
+Keep prompt arguments minimal. Each required argument is a burden on the user. Design prompts that work well with few arguments and use the server's access to context (active files, project config, authenticated user state) to fill in the rest.
+
+Use required arguments for inputs the server genuinely cannot infer: the code to review, the ticket ID to reference. Use optional arguments with sensible defaults for refinements: language hint, verbosity level, output format.
+
+Validate all arguments before building the messages. Return a JSON-RPC `-32602` (invalid params) error for missing required arguments or invalid values, with a clear message identifying which argument is problematic and what a valid value looks like.

package/content/knowledge/mcp-server/mcp-protocol-fundamentals.md

@@ -0,0 +1,130 @@
+---
+name: mcp-protocol-fundamentals
+description: MCP client/server model, JSON-RPC 2.0 message format, capability negotiation, initialize handshake, connection lifecycle, and host/client/server roles
+topics: [mcp, protocol, json-rpc, lifecycle, capability-negotiation]
+volatility: fast-moving
+last-reviewed: null
+version-pin: 'MCP spec 2025-11-25'
+sources:
+  - url: https://modelcontextprotocol.io/specification/2025-11-25/
+  - url: https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle
+  - url: https://www.jsonrpc.org/specification
+---
+
+The Model Context Protocol (MCP) is a JSON-RPC 2.0 based protocol that standardizes how LLM applications connect to external data sources and tools. Understanding the three-role model and the initialize handshake is prerequisite knowledge for every other MCP concept.
+
+## Summary
+
+MCP uses JSON-RPC 2.0 over a stateful transport. Three roles: **hosts** (LLM applications that initiate connections), **clients** (connectors within the host), and **servers** (services that expose capabilities). The connection lifecycle has three phases — initialization, operation, and shutdown — and always begins with an `initialize` request/response exchange followed by an `initialized` notification. Capabilities are declared during initialization; neither side may use a capability it did not declare.
+
+## Deep Guidance
+
+### Three-role model
+
+The MCP architecture separates concerns into three distinct roles:
+
+- **Host**: The LLM application (e.g., Claude Desktop, an IDE plugin) that orchestrates connections. The host owns the user interface and decides which servers to connect to.
+- **Client**: A connector embedded in the host that manages a single server connection, handles the protocol lifecycle, and mediates capability negotiation.
+- **Server**: An independent process or service that exposes tools, resources, or prompts. A server has no knowledge of other servers the client may be connected to.
+
+One host typically manages multiple client-server pairs. Each server connection is isolated — servers do not communicate with each other.
+
+### JSON-RPC 2.0 message format
+
+All MCP messages are JSON-RPC 2.0 objects, UTF-8 encoded. Three message types:
+
+**Requests** (expect a response):
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/list",
+  "params": {}
+}
+```
+
+**Responses** (reply to a request):
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": { "tools": [] }
+}
+```
+
+**Notifications** (no response expected, no `id` field):
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "notifications/initialized"
+}
+```
+
+Error responses use a standard error object with `code` (integer) and `message` (string). Standard JSON-RPC error codes apply: `-32700` (parse error), `-32600` (invalid request), `-32601` (method not found), `-32602` (invalid params), `-32603` (internal error).
+
+### The initialize handshake
+
+The `initialize` request MUST be the first message sent by the client. It carries the protocol version the client supports (should be the latest), the client's capabilities, and client implementation information. The server responds with its own protocol version, capabilities, and an optional `instructions` string for the client.
+
+After a successful response, the client MUST send an `initialized` notification (`notifications/initialized`) to signal readiness. Neither side should send substantive requests before this exchange completes — the only exception is ping messages.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "initialize",
+  "params": {
+    "protocolVersion": "2025-11-25",
+    "capabilities": {
+      "roots": { "listChanged": true },
+      "sampling": {},
+      "elicitation": {}
+    },
+    "clientInfo": { "name": "MyClient", "version": "1.0.0" }
+  }
+}
+```
+
+The server responds with its capabilities. Example server capability declaration:
+```json
+{
+  "protocolVersion": "2025-11-25",
+  "capabilities": {
+    "tools": { "listChanged": true },
+    "resources": { "subscribe": true, "listChanged": true },
+    "prompts": { "listChanged": true },
+    "logging": {}
+  },
+  "serverInfo": { "name": "MyServer", "version": "1.0.0" }
+}
+```
+
+### Version negotiation
+
+The client sends the latest protocol version it supports. If the server supports it, it echoes the same version. If the server does not support the requested version, it responds with the latest version it does support. If the client cannot handle the server's version, it should disconnect. The currently active spec version is `2025-11-25`; clients sending this should receive it back from any compliant modern server.
+
+### Capability negotiation
+
+Capabilities declared during `initialize` govern which protocol features are available for the session. Key capability categories:
+
+| Side   | Capability    | Enables                                         |
+|--------|---------------|-------------------------------------------------|
+| Server | `tools`       | `tools/list`, `tools/call`                      |
+| Server | `resources`   | `resources/list`, `resources/read`, subscriptions |
+| Server | `prompts`     | `prompts/list`, `prompts/get`                   |
+| Server | `logging`     | Log message notifications to client             |
+| Client | `sampling`    | Server-initiated LLM sampling requests          |
+| Client | `roots`       | Server can query filesystem root boundaries     |
+| Client | `elicitation` | Server can request additional info from user    |
+
+Sub-capabilities like `listChanged` (support for list-change notifications) and `subscribe` (resources only, per-resource change subscriptions) are nested within their parent capability. A server that declares `tools: { listChanged: true }` MUST send `notifications/tools/list_changed` when its tool set changes.
+
+### Lifecycle phases
+
+1. **Initialization**: `initialize` request → server response → `initialized` notification. No tool/resource/prompt calls before this completes.
+2. **Operation**: Normal message exchange. Both sides respect negotiated capabilities.
+3. **Shutdown**: For stdio, the client closes the server's stdin and waits for the process to exit (sending `SIGTERM` then `SIGKILL` if needed). For HTTP, closing connections signals shutdown. No formal shutdown request message exists — transport-level signals are used.
+
+### Timeouts and error handling
+
+Implementations should set timeouts on all sent requests to prevent hung connections. When a timeout fires, send a `CancelledNotification` for the pending request ID. Progress notifications can optionally reset a timeout clock, but a hard maximum timeout should always be enforced regardless. Protocol version mismatch, required capability negotiation failure, and request timeouts are the standard error cases to handle at startup.

package/content/knowledge/mcp-server/mcp-resource-design.md

@@ -0,0 +1,111 @@
+---
+name: mcp-resource-design
+description: MCP resource URIs, URI templates (RFC 6570), MIME types, resources/list + resources/read + resources/subscribe, listChanged notifications, annotations, pagination
+topics: [mcp, resources, uri-templates, mime-types, subscriptions]
+volatility: evolving
+last-reviewed: null
+version-pin: 'MCP spec 2025-11-25'
+sources:
+  - url: https://modelcontextprotocol.io/specification/2025-11-25/server/resources
+  - url: https://datatracker.ietf.org/doc/html/rfc6570
+  - url: https://datatracker.ietf.org/doc/html/rfc3986
+---
+
+Resources are the MCP primitive for exposing data that provides context to LLMs — files, database records, API responses, or any addressable content. Unlike tools, resources are application-driven (the host decides what to expose), not model-driven.
+
+## Summary
+
+Each resource has a `URI` as its unique identifier, a `name`, optional `description` and `mimeType`. Clients discover resources via `resources/list` and fetch content via `resources/read`. Parameterized resources use URI templates (RFC 6570) via `resources/templates/list`. Servers declare `resources: { subscribe: true }` to support `resources/subscribe` for change notifications. Both list and content endpoints support cursor-based pagination.
+
+## Deep Guidance
+
+### Resource URI design
+
+Every resource MUST have a globally unique URI conforming to RFC 3986. The URI scheme signals the resource's nature:
+
+- `file:///absolute/path/to/file.txt` — filesystem-like resources (the resource need not be a real file; use this for any content that behaves like a file).
+- `https://example.com/api/data` — web-fetchable resources. Use only when the client can fetch the URL directly; otherwise use a custom scheme.
+- `git://repo/path/to/file@main` — git-versioned content.
+- Custom schemes (e.g., `db://`, `github://`, `slack://`) — use freely for domain-specific resources. Custom schemes MUST conform to RFC 3986.
+
+Avoid embedding credentials, tokens, or session state in URIs — URIs are logged and passed between systems. Keep URIs stable across server restarts for resources that represent persistent entities.
+
+### Static resources vs URI templates
+
+**Static resources** have fully-specified URIs and appear in `resources/list`. Use for a bounded, known set of resources (a fixed set of config files, a fixed list of database tables, etc.).
+
+**URI templates** (RFC 6570) use `resources/templates/list` and allow parameterized resource access. The `uriTemplate` field contains an RFC 6570 Level 1 template:
+
+```json
+{
+  "uriTemplate": "github://repos/{owner}/{repo}/issues/{number}",
+  "name": "GitHub Issue",
+  "description": "A specific GitHub issue by owner, repo, and number",
+  "mimeType": "application/json"
+}
+```
+
+The template parameters (`owner`, `repo`, `number`) can be auto-completed by the server via the completions API if declared as server capability. Clients expand the template with concrete values and use the result as the URI in a `resources/read` request. Use templates for unbounded or large collections (user files, database rows, API records) where listing all resources statically is impractical.
+
+### resources/list and pagination
+
+`resources/list` returns available static resources. The response includes a `resources` array and an optional `nextCursor`. If `nextCursor` is present, pass it as `cursor` in the next request to get the next page. Always handle pagination — a server serving a filesystem may return thousands of entries.
+
+```json
+{
+  "method": "resources/list",
+  "params": { "cursor": "eyJwYWdlIjogMn0=" }
+}
+```
+
+Response resources include `uri`, `name`, optional `title`, optional `description`, optional `mimeType`, and optional `size` (bytes). The `mimeType` is advisory — always re-check the `mimeType` in the actual content returned by `resources/read`.
+
+### resources/read and content types
+
+`resources/read` takes a `uri` and returns a `contents` array. Each content item carries:
+
+- For text: `{ "uri": "...", "mimeType": "text/plain", "text": "..." }`
+- For binary: `{ "uri": "...", "mimeType": "image/png", "blob": "<base64>" }`
+
+A single read can return multiple content items if the URI expands to multiple files (e.g., a directory URI). The `blob` field contains standard base64-encoded binary data; the `text` field is a UTF-8 string.
+
+Standard MIME type conventions: `text/plain`, `text/markdown`, `application/json`, `application/octet-stream` for unknown binary, `image/png`, `image/jpeg`, `text/html`. Use `inode/directory` (XDG MIME) for directory resources without a standard MIME type.
+
+### Subscriptions
+
+Declare `resources: { subscribe: true }` to support per-resource change notifications. The flow:
+
+1. Client sends `resources/subscribe` with a specific `uri`.
+2. Server responds with success (empty result).
+3. When the resource changes, server sends `notifications/resources/updated` with the `uri`.
+4. Client re-fetches the resource with `resources/read`.
+
+Subscriptions are stateful — track them in the server. If a client disconnects and reconnects, subscriptions are lost and must be re-established. Implement subscriptions when resources represent live data (open files in an editor, real-time database records, live API state).
+
+### listChanged notifications
+
+If the set of available resources can change (files added/removed, database tables created/dropped), declare `resources: { listChanged: true }` and send `notifications/resources/list_changed` when the list changes. The client re-issues `resources/list` to refresh. This is separate from subscriptions: `listChanged` is for the catalog, subscriptions are for individual resource content.
+
+### Annotations
+
+Resources support optional `annotations` that hint at audience and priority:
+
+```json
+{
+  "annotations": {
+    "audience": ["assistant"],
+    "priority": 0.9,
+    "lastModified": "2025-06-18T10:00:00Z"
+  }
+}
+```
+
+- `audience`: `["user"]`, `["assistant"]`, or `["user", "assistant"]`. Use `["assistant"]` for machine-readable data the LLM should process but not display to users. Use `["user"]` for human-readable content.
+- `priority`: 0.0 to 1.0. Higher values indicate more important context to include when token budgets are limited.
+- `lastModified`: ISO 8601 timestamp. Enables clients to sort by recency or skip stale resources.
+
+Annotations appear on the resource list entry, the content item, or both. They are hints — clients may ignore them.
+
+### Error handling
+
+Standard JSON-RPC error codes for resource operations: `-32002` for resource not found, `-32603` for internal server errors. Always return a proper JSON-RPC error when a `resources/read` URI does not exist — do not return an empty `contents` array. Validate all incoming URIs for scheme and path safety before accessing the underlying data source.