@zigrivers/scaffold 3.32.1 → 3.33.1

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.

package/content/knowledge/mcp-server/mcp-sdk-selection.md

@@ -0,0 +1,136 @@
+---
+name: mcp-sdk-selection
+description: TypeScript @modelcontextprotocol/sdk vs Python SDK and FastMCP — trade-offs, SDK patterns, McpServer class, decorator-based registration, and when to use each
+topics: [mcp, sdk, typescript, python, fastmcp]
+volatility: fast-moving
+last-reviewed: null
+version-pin: 'MCP spec 2025-11-25; @modelcontextprotocol/sdk 1.x; mcp[cli] Python 1.2.0+'
+sources:
+  - url: https://modelcontextprotocol.io/docs/develop/build-server
+  - url: https://github.com/modelcontextprotocol/typescript-sdk
+  - url: https://github.com/modelcontextprotocol/python-sdk
+---
+
+Three SDK options cover the majority of MCP server implementations: the official TypeScript SDK (`@modelcontextprotocol/sdk`), the official Python SDK (`mcp`), and FastMCP (a higher-level Python wrapper bundled with the Python SDK). Choose based on your team's language, the server's complexity, and how much boilerplate you want to manage.
+
+## Summary
+
+**TypeScript SDK**: use for Node.js servers, teams with TypeScript expertise, or when integrating tightly with the JS/TS ecosystem. The `McpServer` high-level API covers most use cases; the lower-level `Server` class gives full control for edge cases. **Python SDK with FastMCP**: use for Python teams; FastMCP uses decorators and type hints to auto-generate tool/resource/prompt definitions, requiring minimal boilerplate. **FastMCP** is the recommended starting point for Python — it is bundled in the official `mcp[cli]` package as `mcp.server.fastmcp`. Both SDKs handle transport setup, JSON-RPC framing, and capability negotiation automatically.
+
+## Deep Guidance
+
+### TypeScript SDK (@modelcontextprotocol/sdk)
+
+Install: `npm install @modelcontextprotocol/sdk`
+
+The TypeScript SDK offers two server APIs:
+
+**McpServer (high-level, recommended)**: Handles transport setup, capability negotiation, and message routing. Register tools, resources, and prompts with typed handler functions:
+
+```typescript
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { z } from 'zod'
+
+const server = new McpServer({
+  name: 'my-server',
+  version: '1.0.0',
+})
+
+server.tool('get_weather', 'Get current weather for a location', {
+  location: z.string().describe('City name or zip code'),
+}, async ({ location }) => {
+  // fetch weather ...
+  return {
+    content: [{ type: 'text', text: `Weather for ${location}: Sunny, 72°F` }],
+  }
+})
+
+const transport = new StdioServerTransport()
+await server.connect(transport)
+```
+
+For Streamable HTTP, use `StreamableHTTPServerTransport` from `@modelcontextprotocol/sdk/server/streamableHttp.js`.
+
+**Server (low-level)**: Use when you need fine-grained control over request handling, custom middleware, or capabilities not yet abstracted by McpServer. Requires manually registering handlers for each method (`setRequestHandler`, `setNotificationHandler`). Useful for implementing servers that proxy or aggregate other MCP servers.
+
+The TypeScript SDK uses Zod schemas for input validation — the `z.object({ ... })` schema passed to `server.tool()` becomes the JSON Schema `inputSchema` automatically.
+
+### Python SDK with FastMCP
+
+Install: `uv add "mcp[cli]"` (includes FastMCP) or `pip install "mcp[cli]"`
+
+**FastMCP** is the high-level Python API. It derives tool definitions from function signatures, type hints, and docstrings — eliminating most boilerplate:
+
+```python
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("my-server")
+
+@mcp.tool()
+async def get_weather(location: str) -> str:
+    """Get current weather for a location.
+
+    Args:
+        location: City name or zip code, e.g. 'New York' or '10001'
+    """
+    # fetch weather ...
+    return f"Weather for {location}: Sunny, 72°F"
+
+if __name__ == "__main__":
+    mcp.run()  # defaults to stdio transport
+```
+
+FastMCP generates the JSON Schema `inputSchema` from the function's type annotations. The docstring becomes the tool's `description`. Argument descriptions come from the `Args:` section of the docstring. This convention-over-configuration approach makes FastMCP the fastest way to get a Python MCP server running.
+
+For resources:
+```python
+@mcp.resource("file://config/{name}")
+async def get_config(name: str) -> str:
+    """Read a configuration file by name."""
+    return Path(f"/etc/myapp/{name}.json").read_text()
+```
+
+For prompts:
+```python
+@mcp.prompt()
+async def review_code(code: str, language: str = "Python") -> list[dict]:
+    """Generate a code review prompt."""
+    return [{"role": "user", "content": f"Review this {language} code:\n{code}"}]
+```
+
+The lower-level Python SDK (`mcp.server.Server`) exists for the same fine-grained use cases as the TypeScript `Server` class.
+
+### SDK comparison
+
+| Dimension | TypeScript SDK | Python + FastMCP |
+|-----------|---------------|------------------|
+| Boilerplate | Low (McpServer) | Minimal (decorators) |
+| Type safety | Strong (Zod + TS) | Good (type hints) |
+| Schema generation | Zod → JSON Schema | Type hints → JSON Schema |
+| Ecosystem fit | Node.js, VS Code, Electron | Data science, scripting, ML |
+| Async model | Promise/async-await | asyncio (FastMCP is async-first) |
+| Deployment | npm package or compiled JS | uvx, pip, Docker |
+| Community servers | Most reference servers in TS | Growing Python ecosystem |
+
+### Choosing between SDKs
+
+**Choose TypeScript** when: your team is primarily TypeScript/JavaScript, you're building a VS Code extension or Electron app that embeds an MCP server, you need deep integration with npm ecosystem tooling, or the official reference implementation is your guide.
+
+**Choose Python + FastMCP** when: your team is primarily Python, you're wrapping existing Python services or data science tools, you want the fastest prototyping path, or you need to integrate with Python-specific libraries (pandas, SQLAlchemy, LangChain, etc.).
+
+**Avoid rolling your own transport layer** regardless of language — the SDKs handle the nuances of JSON-RPC framing, keep-alive, session management, and error formatting correctly. The only reason to implement transport handling manually is when targeting a runtime or language for which no SDK exists yet (C#, Rust, Go all have community SDKs; check the MCP GitHub org before writing your own).
+
+### Logging caution in Python stdio servers
+
+FastMCP and the Python SDK's stdio transport are sensitive to stdout pollution. Never use `print()` in a stdio server without redirecting to stderr:
+
+```python
+import sys
+# WRONG — corrupts protocol stream:
+print("Debug: processing request")
+# CORRECT:
+print("Debug: processing request", file=sys.stderr)
+```
+
+Use Python's `logging` module configured with a `StreamHandler(sys.stderr)` — it defaults to stderr and is safe for stdio servers.

package/content/knowledge/mcp-server/mcp-testing-strategies.md

@@ -0,0 +1,127 @@
+---
+name: mcp-testing-strategies
+description: MCP server testing — MCP Inspector for interactive testing, client mocks, unit tests for handlers, protocol compliance tests, and integration testing patterns
+topics: [mcp, testing, mcp-inspector, protocol-compliance, integration-testing]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://modelcontextprotocol.io/docs/tools/inspector
+  - url: https://github.com/modelcontextprotocol/inspector
+---
+
+Testing MCP servers requires verifying two distinct layers: the protocol layer (correct JSON-RPC framing, capability negotiation, lifecycle) and the domain layer (tool logic, resource content, prompt rendering). The MCP Inspector handles the protocol layer interactively; unit and integration tests handle the domain layer.
+
+## Summary
+
+The **MCP Inspector** (`npx @modelcontextprotocol/inspector`) is the primary interactive testing tool — it connects to your server, shows all protocol messages, and lets you invoke tools, browse resources, and test prompts. For automated testing: unit-test individual tool/resource/prompt handler functions directly (no transport); write integration tests using an in-process SDK client against the server; use protocol compliance tests to verify capability negotiation and error responses. Test `isError` paths explicitly — they are easy to overlook.
+
+## Deep Guidance
+
+### MCP Inspector for interactive testing
+
+The MCP Inspector is an interactive browser-based UI that connects to an MCP server and exposes all three capability types. Run it without installation:
+
+```bash
+# Test a local stdio server
+npx @modelcontextprotocol/inspector node path/to/server/index.js
+
+# Test a server installed via npm
+npx -y @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem /tmp
+
+# Test a Python server
+npx @modelcontextprotocol/inspector uvx mcp-server-myapp --config myapp.json
+```
+
+The Inspector opens in your browser and provides:
+
+- **Connection pane**: Select transport, customize command-line arguments and environment variables.
+- **Tools tab**: Lists all declared tools, shows schemas, lets you invoke tools with custom input, displays results including `isError` responses.
+- **Resources tab**: Lists static resources and templates, shows metadata, lets you read resource content, tests subscriptions.
+- **Prompts tab**: Lists prompt templates, shows arguments, lets you invoke `prompts/get` with custom argument values, previews generated messages.
+- **Notifications pane**: Shows all server log messages and notifications in real time.
+
+**Development workflow with Inspector:**
+1. Start development → launch Inspector with your server → verify connectivity and capability negotiation.
+2. Add a tool → verify it appears in the Tools tab with the correct schema → test with valid and invalid inputs.
+3. Implement error paths → verify `isError: true` responses display correctly.
+4. Test edge cases: empty inputs, maximum-size inputs, concurrent calls, subscription behavior.
+
+Use the Inspector as your first debugging stop before writing any automated tests — it shows the full protocol exchange and makes misconfigurations immediately visible.
+
+### Unit testing handler functions
+
+The best structure for testability isolates tool/resource/prompt logic from transport concerns. Extract handler functions that take typed inputs and return typed outputs, then test them without any MCP transport:
+
+```typescript
+// handlers/weather.ts — testable in isolation
+export async function getWeatherHandler(location: string): Promise<string> {
+  const data = await fetchWeatherApi(location)
+  return formatWeatherResponse(data)
+}
+
+// weather.test.ts
+import { getWeatherHandler } from './handlers/weather.js'
+it('returns formatted weather', async () => {
+  const result = await getWeatherHandler('New York')
+  expect(result).toContain('Temperature')
+})
+```
+
+The MCP registration is a thin wrapper:
+```typescript
+server.tool('get_weather', 'Get current weather', { location: z.string() },
+  async ({ location }) => ({
+    content: [{ type: 'text', text: await getWeatherHandler(location) }],
+  })
+)
+```
+
+This pattern keeps the bulk of your logic in ordinary functions that are fast to test without spinning up a transport.
+
+### Protocol compliance tests
+
+Write tests that verify correct JSON-RPC behavior at the protocol level. Use the SDK's in-process transport (TypeScript: `InMemoryTransport`; Python: available via the SDK's testing utilities) to connect a test client directly to the server:
+
+Key protocol behaviors to test:
+- `initialize` returns declared capabilities matching what the server actually supports.
+- Calling `tools/call` with an unknown tool name returns a protocol error `-32602` (not `isError`) — the request could not be dispatched at all.
+- Calling `tools/call` with arguments that fail the tool's `inputSchema` or business validation returns `isError: true` (SEP-1303), NOT `-32602` — the tool dispatched but the inputs were invalid, so the model can self-correct.
+- Tools that fail domain-level (API errors, rate limits, resource not found) return `isError: true`, not a JSON-RPC error.
+- `resources/read` with a nonexistent URI returns `-32002`.
+- `prompts/get` with a missing required argument returns `-32602` (structural dispatch failure, not a tool execution).
+- `notifications/tools/list_changed` is sent when the tool list changes (if `listChanged: true` was declared).
+
+### Testing isError paths
+
+`isError` paths are frequently untested because they require mocking external failures. Make them explicit:
+
+```typescript
+it('returns isError when API rate limited', async () => {
+  mockWeatherApi.mockRejectedValue(new RateLimitError('rate limited'))
+  const result = await callTool(server, 'get_weather', { location: 'NYC' })
+  expect(result.isError).toBe(true)
+  expect(result.content[0].text).toContain('rate limit')
+})
+```
+
+Test both `isError: true` AND that the error message is actionable (mentions what failed, not just "error occurred").
+
+### Integration testing
+
+Integration tests connect a real client (or SDK client) to the server over the actual transport:
+
+**For stdio servers**: spawn the server process in the test, connect via stdio, run the initialization handshake, invoke tools/resources/prompts, and verify results. Tear down the process after each test suite.
+
+**For HTTP servers**: start the server on a random port, make HTTP requests using the SDK client or raw HTTP, verify both successful responses and error cases. Use `supertest` (Node.js) or `httpx` (Python) for HTTP-level assertions alongside the MCP client for protocol-level assertions.
+
+**For resource subscriptions**: test that `notifications/resources/updated` is sent when the underlying data changes, and that a subsequent `resources/read` returns the new content.
+
+### Test environment setup
+
+Avoid relying on real external APIs in unit or integration tests. Mock or stub all external calls. For testing servers that wrap external services (GitHub, databases, cloud APIs), use:
+- Test doubles (mocks) at the HTTP level (e.g., `nock` for Node.js, `responses` for Python).
+- Sandbox/test environments of the external service if a mock is too complex.
+- Recorded HTTP cassettes (e.g., VCR-style) for stable third-party APIs.
+
+Run the Inspector on your test fixtures to visually confirm that schemas, descriptions, and error messages read well from an LLM client's perspective — the Inspector is also a schema review tool.