@zigrivers/scaffold 3.32.1 → 3.33.0

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.

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

@@ -0,0 +1,125 @@
+---
+name: mcp-tool-design
+description: MCP tool naming conventions, JSON Schema inputSchema design, idempotency, output content blocks, isError for tool-level errors, outputSchema, and annotations
+topics: [mcp, tools, json-schema, tool-design, error-handling]
+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://json-schema.org/draft/2020-12/schema
+---
+
+Tools are the primary mechanism by which MCP servers expose executable capabilities to LLM clients. A well-designed tool is discoverable, predictable, safe to retry, and explicit about its failure modes.
+
+## Summary
+
+Each MCP tool has a `name`, optional `description`, a JSON Schema `inputSchema`, and an optional `outputSchema`. Tool calls use `tools/call`; results carry a `content` array of typed content blocks and an optional `isError` boolean. Use `isError: true` to report expected tool-level failures (API errors, invalid business inputs) as structured results rather than JSON-RPC protocol errors. Tools should be idempotent where possible, and side-effect-bearing tools should be explicitly documented as such via annotations.
+
+## Deep Guidance
+
+### Tool naming conventions
+
+Tool names must be unique within a server. Use `snake_case` for tool names — the 2025-11-25 spec revision (SEP-986) formally reinforces this convention. Names should be short verb-noun phrases that describe what the tool does: `get_weather`, `create_issue`, `search_documents`. Avoid generic names like `execute` or `run` that give the LLM no signal about the tool's purpose.
+
+The `description` field is critical — it is the primary signal the LLM uses to decide when to invoke a tool. Be specific about what the tool does, what inputs it expects, and when it should be used. A poor description leads to misuse. A good description includes the domain, the action, any preconditions, and the output shape in plain English.
+
+### JSON Schema inputSchema
+
+Every tool MUST declare an `inputSchema` as a valid JSON Schema object. MCP uses **JSON Schema 2020-12** as its default schema dialect (established in the 2025-11-25 revision). The schema serves two purposes: runtime validation and LLM guidance. Best practices:
+
+- Use `type: "object"` at the root with named `properties`.
+- List required parameters in the `required` array. Do not list optional parameters there.
+- Add a `description` to every property — the LLM reads these to understand each argument.
+- Use the most specific type possible: prefer `"type": "integer"` over `"type": "number"` when only integers make sense.
+- Use `enum` for fixed sets of valid values.
+- Use `format` hints (`"format": "uri"`, `"format": "date"`) where applicable.
+
+Example of a well-specified inputSchema:
+```json
+{
+  "type": "object",
+  "properties": {
+    "repo": {
+      "type": "string",
+      "description": "GitHub repository in owner/name format, e.g. 'acme/backend'"
+    },
+    "state": {
+      "type": "string",
+      "enum": ["open", "closed", "all"],
+      "description": "Filter issues by state. Defaults to 'open'."
+    },
+    "limit": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 100,
+      "description": "Maximum number of issues to return. Defaults to 20."
+    }
+  },
+  "required": ["repo"]
+}
+```
+
+Always validate inputs against the inputSchema in the server implementation before executing any side effects. The spec requires it, and doing so prevents malformed or injected arguments from reaching downstream systems.
+
+### Idempotency and side effects
+
+MCP tools should be designed with idempotency in mind wherever the underlying operation supports it. Read-only tools (queries, lookups) are naturally idempotent and carry the lowest risk. Mutating tools (writes, deletes, API calls with side effects) should document their non-idempotency explicitly.
+
+The `annotations` field on a tool definition carries hints for clients:
+
+```json
+{
+  "annotations": {
+    "readOnlyHint": true,
+    "idempotentHint": true,
+    "openWorldHint": false
+  }
+}
+```
+
+`readOnlyHint: true` means the tool does not modify any state. `idempotentHint: true` means calling it multiple times with the same arguments produces the same result. `openWorldHint: true` means the tool interacts with external systems beyond the local environment. Clients treat these as untrusted hints — they assist the LLM in deciding whether user confirmation is needed, but do not replace host-side confirmation flows for destructive operations.
+
+### Output content blocks
+
+Tool results return a `content` array containing one or more typed content blocks:
+
+- **TextContent**: `{ "type": "text", "text": "..." }` — the most common type; use for plain text, JSON strings, or structured prose.
+- **ImageContent**: `{ "type": "image", "data": "<base64>", "mimeType": "image/png" }` — for screenshots, charts, or generated images.
+- **AudioContent**: `{ "type": "audio", "data": "<base64>", "mimeType": "audio/wav" }` — for audio responses.
+- **ResourceLink**: `{ "type": "resource_link", "uri": "...", "name": "...", "mimeType": "..." }` — reference a resource the client can fetch separately.
+- **EmbeddedResource**: `{ "type": "resource", "resource": { "uri": "...", "mimeType": "...", "text": "..." } }` — inline resource content.
+
+Tools can return multiple content blocks in one result (e.g., a text summary plus an image). The `content` array is always present, even for empty results — return an empty array rather than null.
+
+If the tool declares an `outputSchema`, it MUST also provide structured content in a `structuredContent` field matching that schema, and SHOULD also include the serialized JSON as a TextContent block for backwards compatibility.
+
+### isError: tool errors vs protocol errors
+
+MCP distinguishes two error reporting paths:
+
+**Protocol errors** (JSON-RPC errors) are for structural/wire-level failures where the call could not be dispatched at all: unknown tool name in `tools/call`, malformed JSON-RPC structure, server crashes. These return a JSON-RPC error response with a negative integer `code`. The LLM cannot generally recover from protocol errors.
+
+**Tool execution errors** use `isError: true` in the result. Use this for any failure that occurs after the tool dispatches — including tool `inputSchema` validation failures, business validation rejections, API rate limits, resource not found, and network timeouts. Per the 2025-11-25 spec (SEP-1303), tool input validation failures MUST use `isError: true` (not `-32602`) so the model can read the error and self-correct. Return `isError: true` with a descriptive TextContent explaining what went wrong and, when possible, what the caller should do differently.
+
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "GitHub API rate limit exceeded. Resets at 2025-06-18T14:00:00Z. Retry after that time."
+    }
+  ],
+  "isError": true
+}
+```
+
+Never raise a JSON-RPC protocol error for domain-level failures that a well-behaved caller might encounter. Reserve protocol errors for structural dispatch failures (wrong method name, unknown tool). When in doubt, use `isError: true` — it keeps the LLM in the loop about what went wrong.
+
+### Partial failures
+
+When a tool processes multiple items and some fail, report partial results in the `content` array with a summary, and set `isError: true` only if the overall operation should be treated as failed. For best-effort multi-item tools, return results for successful items and error descriptions for failed ones, without setting `isError: true`, so the LLM can use the partial output.
+
+### List change notifications
+
+If the server's tool set can change at runtime (e.g., tools are dynamically registered), declare `tools: { listChanged: true }` in capabilities and send `notifications/tools/list_changed` when the set changes. The client will re-issue `tools/list` to refresh its cache. This is important for servers where available tools depend on user configuration or authentication state.

package/content/knowledge/mcp-server/mcp-transport-patterns.md

@@ -0,0 +1,122 @@
+---
+name: mcp-transport-patterns
+description: MCP stdio and Streamable HTTP transports, deprecated HTTP+SSE migration, session management, MCP-Protocol-Version header, and transport selection guidance
+topics: [mcp, transport, stdio, http, sse, session-management]
+volatility: fast-moving
+last-reviewed: null
+version-pin: 'MCP spec 2025-11-25'
+sources:
+  - url: https://modelcontextprotocol.io/specification/2025-11-25/basic/transports
+---
+
+MCP defines two standard transports: **stdio** (local subprocess) and **Streamable HTTP** (network-accessible). The old HTTP+SSE transport from spec version 2024-11-05 is deprecated. Transport choice is a deployment decision that shapes your server's authentication model, scalability, and operational complexity.
+
+## Summary
+
+**stdio**: client launches server as subprocess, communicates over stdin/stdout, logs go to stderr. Best for local tools installed alongside the client. **Streamable HTTP**: server runs independently at an HTTP endpoint, clients POST JSON-RPC messages, server optionally streams responses via SSE. Best for shared/remote servers. The deprecated HTTP+SSE transport used separate GET (SSE stream) and POST (messages) endpoints — migrate to Streamable HTTP. The `MCP-Protocol-Version` header MUST be sent on all HTTP requests after initialization.
+
+## Deep Guidance
+
+### stdio transport
+
+In the stdio transport, the MCP client launches the server as a child process. All JSON-RPC messages flow over the process's standard streams:
+
+- Client writes JSON-RPC messages to server's **stdin**, one message per line, no embedded newlines.
+- Server writes JSON-RPC messages to its **stdout**, one message per line, no embedded newlines.
+- Server writes diagnostic/logging output to **stderr** only — stdout is reserved strictly for JSON-RPC protocol messages.
+
+```
+Client Process
+  ├── spawns → Server Process
+  │                ├── stdin  ← JSON-RPC messages from client
+  │                ├── stdout → JSON-RPC messages to client
+  │                └── stderr → logs (captured by client, not protocol)
+```
+
+**Key rules for stdio servers:**
+- NEVER write anything to stdout except valid JSON-RPC messages. Any stray output (debug prints, startup banners, library log messages) will corrupt the protocol stream and cause parse errors. This is the most common stdio bug.
+- Redirect all application logging to stderr (or a file). In Python: `print("msg", file=sys.stderr)`. In Node.js: `process.stderr.write(...)`. In Go: `fmt.Fprintln(os.Stderr, ...)`.
+- The server process's working directory may be undefined (could be `/` on macOS) when launched by a client. Use absolute paths for any file access or configuration loading.
+
+Shutdown: the client closes the server's stdin stream, waits for the process to exit, then sends SIGTERM after a timeout, then SIGKILL.
+
+### Streamable HTTP transport
+
+The Streamable HTTP transport runs the server as an independent HTTP service. A single MCP endpoint (e.g., `https://example.com/mcp`) handles both GET and POST:
+
+**Client → Server (POST)**: Every JSON-RPC message from client to server is a new HTTP POST. The client MUST include `Accept: application/json, text/event-stream` headers. The server responds either with `Content-Type: application/json` (single response) or `Content-Type: text/event-stream` (SSE stream for streaming/multiple messages).
+
+**Server → Client (GET)**: The client MAY open a GET SSE stream to receive server-initiated messages (notifications, server-to-client requests) without first sending a POST. The server returns `Content-Type: text/event-stream` or `405 Method Not Allowed` if not supported.
+
+**Session management**: The server MAY assign a session ID in the `Mcp-Session-Id` response header during initialization. If issued, the client MUST include `Mcp-Session-Id: <id>` on all subsequent requests. Sessions are terminated via HTTP DELETE to the MCP endpoint with the session ID header.
+
+**Security requirements**:
+- Validate the `Origin` header on all incoming connections to prevent DNS rebinding attacks.
+- Bind to localhost only (127.0.0.1) when running locally; never 0.0.0.0 for local-only servers.
+- Implement authentication for all connections (see `mcp-authentication.md`).
+
+### MCP-Protocol-Version header
+
+After initialization, HTTP clients MUST include `MCP-Protocol-Version: <negotiated-version>` on all requests. Example: `MCP-Protocol-Version: 2025-11-25`. If a server receives no version header, it SHOULD assume `2025-03-26` for backwards compatibility. Servers MUST reject requests with unsupported versions with `400 Bad Request`. As of 2025-11-25, servers MUST also respond with HTTP 403 Forbidden when an incoming connection carries an invalid `Origin` header (previously the response code was not specified).
+
+### Deprecated HTTP+SSE transport
+
+The HTTP+SSE transport (from spec version 2024-11-05) used two separate endpoints:
+- A GET endpoint that opened a persistent SSE stream, returning an `endpoint` event with a POST URL.
+- A POST endpoint for client messages.
+
+This is **deprecated** as of spec 2025-03-26 and replaced by Streamable HTTP. For backwards compatibility:
+
+**Servers** wanting to support both old and new clients: keep the old SSE GET endpoint and old POST endpoint running alongside the new Streamable HTTP endpoint.
+
+**Clients** detecting transport version: POST an `initialize` request. If the server responds with success, it supports Streamable HTTP. If the server returns 4xx (405 or 404), issue a GET instead — if it returns an SSE stream with an `endpoint` event, it's an old HTTP+SSE server. Support both paths during a migration window.
+
+### Transport selection guidance
+
+| Scenario | Recommended transport |
+|----------|----------------------|
+| Local tool (installed alongside client) | stdio |
+| Developer machine tool (file access, CLI wrappers) | stdio |
+| Shared team server (hosted, multi-user) | Streamable HTTP |
+| Cloud-hosted integration (SaaS backend) | Streamable HTTP |
+| Containerized/serverless deployment | Streamable HTTP |
+| Mobile or browser-based host | Streamable HTTP |
+
+**Choose stdio when**: the server must run on the user's machine, the tool accesses local files or processes, you want zero-config deployment (install package, configure path), or you want the simplest possible security model (OS process isolation, no network auth needed).
+
+**Choose Streamable HTTP when**: the server is shared across multiple clients or users, you need centralized deployment and updates, the server integrates with remote APIs or databases, or you need to run the server independently of any specific client lifecycle.
+
+Custom transports are allowed by the spec — any bidirectional communication channel that preserves JSON-RPC message format and lifecycle requirements can be used. Document custom transports thoroughly.
+
+### Connection lifecycle and error handling
+
+Both transports follow the same JSON-RPC 2.0 lifecycle:
+
+1. **Initialize**: client sends `initialize` request with protocol version and capabilities; server responds with its own capabilities.
+2. **Initialized notification**: client sends `notifications/initialized` to signal readiness.
+3. **Normal operation**: bidirectional request/response and notifications.
+4. **Shutdown**: client sends `notifications/cancelled` for in-flight requests, then closes the transport.
+
+**Common transport errors and remediation**:
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| Parse errors on stdio | Non-JSON written to stdout (e.g., debug prints) | Redirect all non-protocol output to stderr |
+| `400 Bad Request` on HTTP | Missing or invalid `MCP-Protocol-Version` header | Ensure client sends the header after initialization |
+| `404` on HTTP | Client using old HTTP+SSE transport path | Detect and support both paths during migration |
+| Session `410 Gone` | Session expired or server restarted | Client should re-initialize and re-establish session |
+
+### Testing transport behavior
+
+```typescript
+// Test stdio transport with in-process transport for unit tests
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+
+const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+const client = new Client({ name: "test-client", version: "1.0.0" });
+await client.connect(clientTransport);
+// server connects to serverTransport in parallel
+```
+
+For HTTP transport integration tests, use a real HTTP server bound to a random port (`listen(0)`) and tear it down after each test. Never share server state between tests.

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

@@ -0,0 +1,115 @@
+---
+name: mcp-versioning
+description: MCP protocol version negotiation, MCP-Protocol-Version HTTP header, capability-based feature detection, server versioning strategy, and backwards compatibility
+topics: [mcp, versioning, protocol-version, backwards-compatibility, capability-negotiation]
+volatility: stable
+last-reviewed: null
+version-pin: 'MCP spec 2025-11-25'
+sources:
+  - url: https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle
+  - url: https://modelcontextprotocol.io/specification/2025-11-25/basic/transports
+---
+
+MCP uses calendar-versioned protocol strings and capability-based feature detection. Understand both mechanisms to build servers that work with current clients and remain compatible as the spec evolves.
+
+## Summary
+
+Protocol versions are date strings (e.g., `2025-11-25`). The client proposes a version in `initialize`; the server echoes it or responds with its preferred version. If versions are incompatible, the client disconnects. HTTP clients MUST include `MCP-Protocol-Version: <negotiated-version>` on all subsequent requests. Feature availability is determined by capability negotiation, not version numbers alone. For your server's own versioning, use semantic versioning; keep the `serverInfo.version` field current and stable across protocol version changes.
+
+## Deep Guidance
+
+### Protocol version strings
+
+MCP protocol versions are ISO 8601 calendar dates: `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`. Current production version is `2025-11-25`. Always send the latest version you support in the `initialize` request — the server will downgrade if needed.
+
+Version negotiation in the `initialize` handshake:
+1. Client sends `"protocolVersion": "2025-11-25"` (its latest supported version).
+2. If the server supports `2025-11-25`, it responds with `"protocolVersion": "2025-11-25"`.
+3. If the server only supports `2025-03-26`, it responds with `"protocolVersion": "2025-03-26"`.
+4. The client checks if it supports the server's response version. If not, it disconnects.
+
+This ensures both sides agree on a common protocol dialect before any other messages are exchanged.
+
+### MCP-Protocol-Version HTTP header
+
+After initialization, HTTP clients MUST send `MCP-Protocol-Version: <negotiated-version>` on every subsequent request:
+
+```
+POST /mcp HTTP/1.1
+Host: mcp.example.com
+Content-Type: application/json
+Accept: application/json, text/event-stream
+MCP-Protocol-Version: 2025-11-25
+Mcp-Session-Id: abc123
+```
+
+Servers use this header to handle requests differently based on protocol version when supporting multiple versions simultaneously. If a server receives no `MCP-Protocol-Version` header, the spec says to assume `2025-03-26` for backwards compatibility. Servers MUST return `400 Bad Request` for unsupported or invalid version header values.
+
+### Capability-based feature detection
+
+Do not version-gate features solely on protocol version numbers. Use capability negotiation instead. A server supporting `2025-11-25` may not declare the `prompts` capability — that means prompts are not available regardless of protocol version.
+
+The correct pattern for clients: check whether the server declared the capability before calling the corresponding methods. A client that calls `tools/list` without checking whether the server declared `tools` capability will receive a protocol error. The `initialize` response is the authoritative source of truth for what a server supports.
+
+For servers: declare only the capabilities you actually implement. Over-declaring capabilities (e.g., declaring `resources: { subscribe: true }` but not handling `resources/subscribe`) will cause client errors and poor UX.
+
+### Evolving your server's capabilities over versions
+
+When you add a new capability to your server (e.g., adding resource support to a tools-only server):
+- Add the capability to your `initialize` response immediately.
+- The capability declaration is backwards compatible — old clients that don't use resources will simply not call `resources/list`.
+- Do not bump your `serverInfo.version` for protocol-level changes; that field tracks your server's own software version.
+
+When you remove a capability (uncommon but possible):
+- Remove it from the `initialize` response.
+- Any client that was relying on it will receive a protocol error when they call the now-unsupported method.
+- Consider maintaining the capability with a deprecation notice in the server's `instructions` field before fully removing it.
+
+### Server software versioning
+
+The `serverInfo.version` in `initialize` is your server's semantic version (e.g., `"1.3.0"`), independent of the MCP protocol version. Follow semantic versioning:
+- **Patch** (1.0.x): bug fixes, no schema changes, no capability changes.
+- **Minor** (1.x.0): new tools/resources/prompts added, existing ones unchanged.
+- **Major** (x.0.0): removed or renamed tools/resources/prompts, breaking schema changes.
+
+Breaking changes in tool `inputSchema` or resource URI patterns are breaking changes for MCP clients that have auto-discovered and cached your server's schema. Treat them as major version bumps and communicate them in advance.
+
+### Supporting multiple protocol versions simultaneously
+
+If you need to serve both old (2024-11-05 HTTP+SSE) and new (2025-11-25 Streamable HTTP) clients:
+- Keep the old SSE GET endpoint and POST endpoint running alongside the new MCP endpoint.
+- Use the `MCP-Protocol-Version` header to route behavior within the Streamable HTTP path.
+- Set a deprecation date for old transport support and communicate it in the `serverInfo` description or via documentation.
+
+For servers that only need to support the latest spec, target `2025-11-25` and do not implement the deprecated HTTP+SSE transport. New clients target the current spec; support for the old transport is only needed if you have existing clients that have not yet migrated.
+
+### Spec evolution cadence
+
+The MCP spec has evolved on roughly a quarterly cadence: `2024-11-05` (initial), `2025-03-26` (Streamable HTTP introduction), `2025-06-18`, `2025-11-25` (current). Major changes between versions: `2024-11-05 → 2025-03-26` introduced Streamable HTTP, deprecating HTTP+SSE. `2025-03-26 → 2025-06-18` added `outputSchema` for tools, `structuredContent`, audio content type, `title` fields, and the `elicitation` client capability. `2025-06-18 → 2025-11-25` added OIDC Discovery 1.0 support; aligned OAuth Protected Resource Metadata to RFC 9728 (`WWW-Authenticate` header now optional with `.well-known` fallback); incremental scope consent and Client ID Metadata Documents for client registration; `icons` metadata on tools/resources/prompts; JSON Schema 2020-12 as the default dialect; input validation errors explicitly directed as Tool Execution Errors (`isError`) for model self-correction; Streamable HTTP servers MUST respond HTTP 403 for invalid Origin headers; stdio servers MAY use stderr for all logging; elicitation gains URL-mode, titled/untitled enums, and primitive default values; sampling gains `tools`/`toolChoice` support; experimental `tasks` feature for durable requests with polling. Watch the spec changelog (https://modelcontextprotocol.io) for new capabilities that may benefit your server.
+
+### Backwards compatibility checklist
+
+When releasing a new server version, verify these backwards compatibility invariants before shipping:
+
+1. **No renamed tools**: renaming a tool (e.g., `search_files` → `find_files`) is a breaking change. Existing clients with auto-approved tool calls will fail silently. Use the old name as an alias or bump major version with advance notice.
+2. **No removed required input fields**: removing a required field from `inputSchema` is non-breaking (callers can stop providing it); adding a new required field IS breaking (callers that don't provide it will receive validation errors).
+3. **No resource URI pattern changes**: changing `file://{path}` to `file://workspace/{path}` breaks all existing resource subscriptions and saved URIs. Treat as a major version change.
+4. **No prompt argument removals**: removing a declared prompt argument breaks clients that pass that argument.
+5. **No capability downgrades without communication**: removing `resources: { subscribe: true }` when clients have active subscriptions causes silent failures.
+
+For patch and minor releases, adding new optional tool parameters, new tools, new resources, or new prompts is always backwards compatible — existing callers ignore what they don't use.
+
+### Version signaling in serverInfo
+
+Use the `serverInfo.version` field as a machine-readable signal for clients that cache schemas:
+
+```json
+{
+  "serverInfo": {
+    "name": "my-mcp-server",
+    "version": "2.1.0"
+  }
+}
+```
+
+Clients can cache tool/resource schemas keyed by `(serverInfo.name, serverInfo.version)`. When the server bumps its version, clients re-fetch schemas rather than serving stale cached definitions. This pattern is especially important for IDE integrations and agent frameworks that pre-load tool definitions at startup.

package/content/methodology/custom-defaults.yml

@@ -43,6 +43,7 @@ steps:
   database-schema: { enabled: true, conditional: "if-needed" }
   review-database: { enabled: true, conditional: "if-needed" }
   api-contracts: { enabled: true, conditional: "if-needed" }
+  mcp-tool-resource-contract: { enabled: false }
   review-api: { enabled: true, conditional: "if-needed" }
   ux-spec: { enabled: true, conditional: "if-needed" }
   review-ux: { enabled: true, conditional: "if-needed" }
@@ -74,6 +75,7 @@ steps:
   apply-fixes-and-freeze: { enabled: true }
   developer-onboarding-guide: { enabled: true }
   implementation-playbook: { enabled: true }
+  materialize-plan-to-beads: { enabled: true, conditional: "if-needed" }
   # Phase 15 — Build (build) — stateless, on-demand execution steps
   single-agent-start: { enabled: true }
   single-agent-resume: { enabled: true }