Support mocking Model Context Protocol (MCP) - Streamable HTTP Transport

[kpavlov]

Support mocking Model Context Protocol (MCP) - Streamable HTTP Transport.

Requires JSON-RPC 2.0 support in Mokksy

[kpavlov]

@coderabbitai plan

[coderabbitai]

Coding Plan

Summary

• Follow the A2A module pattern with separate models and mock modules, enabling future client reuse
• Leverage existing mokksy infrastructure for HTTP handling, header matching (containsHeader), and SSE streaming (respondsWithStream with ServerSentEvent.toString() pattern)
• Implement MCP Streamable HTTP Transport with POST for requests, optional GET for server-initiated streams, and DELETE for session termination
• Use header matching for session management rather than a complex session registry, keeping the implementation simple whilst supporting typical testing scenarios

Design Choices

Design Choice 1: Should MCP models be in a separate module or inline?

Options Considered:

1. Separate ai-mocks-mcp-models module (like ai-mocks-a2a-models) — enables future MCP client module reuse, cleaner separation
2. Inline models within ai-mocks-mcp (like ai-mocks-openai) — simpler initial setup, fewer modules to maintain

Chosen Option: 1

Rationale: MCP is a protocol standard with complex JSON-RPC types that would benefit from separation, and this aligns with the A2A pattern which is architecturally most similar.

Design Choice 2: Which MCP methods should be supported in the initial implementation?

Options Considered:

1. All MCP methods including sampling, roots, logging, completion
2. Core subset: initialize, tools/, resources/, prompts/* plus a generic fallback handler

Chosen Option: 2

Rationale: Focus on the most commonly used methods that cover typical testing scenarios. A generic handler allows users to mock any additional methods without waiting for explicit support.

Design Choice 3: How should session management (MCP-Session-Id) be implemented?

Options Considered:

1. Full session registry with automatic ID generation and validation
2. Header matching via existing containsHeader() DSL — users explicitly match session IDs in their stubs

Chosen Option: 2

Rationale: Simpler initial implementation that leverages existing mokksy infrastructure. Users can match specific session IDs or use predicate matchers for dynamic validation. A registry can be added later if demand warrants.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Project Setup and Protocol Models

This phase establishes the module structure and defines the MCP protocol data classes. The models module will be dependency-free (apart from kotlinx-serialization) to enable reuse by a future MCP client.

Task 1: Create Module Structure and Build Configuration

Register the new modules in the build system and configure their dependencies following the established A2A pattern.

• Add :ai-mocks-mcp-models and :ai-mocks-mcp entries to settings.gradle.kts
• Create ai-mocks-mcp-models/gradle.properties with description for the models module
• Create ai-mocks-mcp-models/build.gradle.kts applying kotlin-convention, dokka-convention, publish-convention; dependencies limited to kotlinx-serialization-json
• Create ai-mocks-mcp/gradle.properties with description for the mock server module
• Create ai-mocks-mcp/build.gradle.kts applying conventions plus netty-convention and shadow-convention; depends on :ai-mocks-core and :ai-mocks-mcp-models
• Add both modules to the Kover aggregation block in root build.gradle.kts

Task 2: Define JSON-RPC Base Types

Implement the foundational JSON-RPC 2.0 types that all MCP messages build upon.

• Create package structure under ai-mocks-mcp-models/src/commonMain/kotlin/dev/mokksy/aimocks/mcp/models/
• Define JsonRpcRequest open class with jsonrpc, id, method properties and generic params type parameter
• Define JsonRpcResponse with jsonrpc, id, result (success) or error (failure) sealed structure
• Define JsonRpcError with code, message, data properties following JSON-RPC 2.0 spec
• Define JsonRpcNotification for messages without id field
• Add custom @Serializable annotations and any required KSerializer implementations for polymorphic dispatch

Task 3: Define MCP Request and Response Types

Implement the specific MCP method request/response types for the core protocol operations.

• Define InitializeRequest and InitializeResult with protocolVersion, capabilities, serverInfo/clientInfo structures
• Define ToolsListRequest and ToolsListResult with tools array containing Tool objects (name, description, inputSchema)
• Define ToolsCallRequest (with name, arguments) and ToolsCallResult (with content array of TextContent/ImageContent/EmbeddedResource)
• Define ResourcesListRequest and ResourcesListResult with resources array containing Resource objects
• Define ResourcesReadRequest (with uri) and ResourcesReadResult (with contents array)
• Define PromptsListRequest and PromptsListResult with prompts array containing Prompt objects
• Define PromptsGetRequest (with name, arguments) and PromptsGetResult (with messages array)
• Define PingRequest and empty PingResult for connection health checks
• Create Kotlin builder classes for each result type to enable fluent test setup (following A2A builder pattern)

Task 4: Define Capability and Content Types

Implement supporting types for capabilities negotiation and content representation.

• Define ClientCapabilities and ServerCapabilities with optional feature flags (tools, resources, prompts, logging, experimental)
• Define Implementation with name and version for client/server identification
• Define content part types: TextContent, ImageContent, EmbeddedResource with polymorphic serialisation via type discriminator
• Define ResourceContents with uri, mimeType, text/blob variants
• Define PromptMessage with role and content for prompt responses

🤖 Prompt for AI agents

Set up the two new Gradle modules (`ai-mocks-mcp-models` and `ai-mocks-mcp`) and
implement all MCP protocol data classes. The goal is to establish the full
module structure and define every data class needed for the MCP Streamable HTTP
Transport before any server logic is written.

**Module Setup**
- Add `:ai-mocks-mcp-models` and `:ai-mocks-mcp` to `settings.gradle.kts`
- Create `ai-mocks-mcp-models/gradle.properties` and
`ai-mocks-mcp-models/build.gradle.kts` applying `kotlin-convention`,
`dokka-convention`, `publish-convention`; only dependency is
`kotlinx-serialization-json`
- Create `ai-mocks-mcp/gradle.properties` and `ai-mocks-mcp/build.gradle.kts`
applying conventions plus `netty-convention` and `shadow-convention`; depends on
`:ai-mocks-core` and `:ai-mocks-mcp-models`
- Add both modules to the Kover aggregation block in root `build.gradle.kts`
- Follow the established A2A module pattern throughout

**JSON-RPC Base Types** (package: `dev/mokksy/aimocks/mcp/models/`)
- `JsonRpcRequest` open class with `jsonrpc`, `id`, `method`, and a generic
`params` type parameter
- `JsonRpcResponse` with `jsonrpc`, `id`, and a sealed `result`/`error`
structure
- `JsonRpcError` with `code`, `message`, `data` per JSON-RPC 2.0 spec
- `JsonRpcNotification` for messages without an `id` field
- Add `@Serializable` annotations and any `KSerializer` implementations required
for polymorphic dispatch

**MCP Request/Response Types**
- `InitializeRequest` / `InitializeResult` — include `protocolVersion`,
`capabilities`, `serverInfo`/`clientInfo`
- `ToolsListRequest` / `ToolsListResult` — `tools` array with `Tool` objects
(name, description, inputSchema)
- `ToolsCallRequest` (name, arguments) / `ToolsCallResult` (content array of
`TextContent`/`ImageContent`/`EmbeddedResource`)
- `ResourcesListRequest` / `ResourcesListResult` — `resources` array with
`Resource` objects
- `ResourcesReadRequest` (uri) / `ResourcesReadResult` (contents array)
- `PromptsListRequest` / `PromptsListResult` — `prompts` array with `Prompt`
objects
- `PromptsGetRequest` (name, arguments) / `PromptsGetResult` (messages array)
- `PingRequest` and an empty `PingResult`
- Create Kotlin builder classes for each result type to enable fluent test setup
(following A2A builder pattern)

**Capability and Content Types**
- `ClientCapabilities` and `ServerCapabilities` with optional feature flags
(tools, resources, prompts, logging, experimental)
- `Implementation` with `name` and `version`
- `TextContent`, `ImageContent`, `EmbeddedResource` with polymorphic
serialisation via a `type` discriminator
- `ResourceContents` with `uri`, `mimeType`, `text`/`blob` variants
- `PromptMessage` with `role` and `content`

Phase 2: Core Mock Server Implementation

This phase implements the main mock server class and the fluent DSL for registering request handlers. The architecture mirrors MockAgentServer from the A2A module.

Task 1: Implement MockMcpServer

Create the primary entry point that wraps MokksyServer and exposes MCP-specific endpoint registration methods.

• Create MockMcpServer class in ai-mocks-mcp/src/commonMain/kotlin/dev/mokksy/aimocks/mcp/ extending AbstractMockLlm
• Constructor accepts port: Int = 0, verbose: Boolean = true, and optional endpointPath: String = "/mcp" for custom endpoint paths
• Configure Ktor's ContentNegotiation with kotlinx.serialization.json in ServerConfiguration
• Implement initialize() method returning McpBuildingStep<InitializeRequest> — registers POST handler matching method == "initialize"
• Implement toolsList() returning building step for tools/list method
• Implement toolsCall() returning building step for tools/call method
• Implement resourcesList() returning building step for resources/list method
• Implement resourcesRead() returning building step for resources/read method
• Implement promptsList() returning building step for prompts/list method
• Implement promptsGet() returning building step for prompts/get method
• Implement ping() returning building step for ping method
• Implement generic method(methodName: String) for arbitrary method matching
• Each method uses mokksy.post() with bodyMatchesPredicate { it?.method == "..." } pattern from A2A

Task 2: Implement Request Specification DSL

Create the request specification class that enables matching MCP requests by various criteria.

• Create McpRequestSpecification<P> extending ModelRequestSpecification<P> in the mcp package
• Add protocolVersion(version: String) matcher that validates the MCP-Protocol-Version header via containsHeader()
• Add sessionId(id: String) matcher for MCP-Session-Id header matching
• Add hasSessionId() predicate matcher that asserts the header is present (any value)
• Add paramContains(substring: String) for matching within the params JSON
• Add paramMatches(predicate: (P?) -> Boolean) for typed parameter matching
• Inherit requestBodyContains(), requestMatchesPredicate() from base class for general body matching

Task 3: Implement Non-Streaming Building Step and Response Specification

Create the building step and response specification for standard JSON responses.

• Create McpBuildingStep<P, R> extending AbstractBuildingStep<P, R> for non-streaming MCP operations
• Override responds() to delegate to buildingStep.respondsWith { }, configuring JSON response body
• Create McpResponseSpecification<P, T> extending AbstractResponseSpecification<P, T> holding the result object
• Add result(value: T) method to set the JSON-RPC result payload
• Add error(code: Int, message: String, data: Any? = null) method to configure error responses
• Add sessionId(id: String) method to set MCP-Session-Id response header
• The building step's responds block serialises a JsonRpcResponse wrapping the configured result/error

🤖 Prompt for AI agents

Implement the core mock server class and its fluent DSL for registering and
matching MCP request handlers. This phase mirrors the `MockAgentServer`
architecture from the A2A module.

**MockMcpServer** (`ai-mocks-mcp/src/commonMain/kotlin/dev/mokksy/aimocks/mcp/`)
- Extend `AbstractMockLlm`
- Constructor parameters: `port: Int = 0`, `verbose: Boolean = true`,
`endpointPath: String = "/mcp"`
- Configure Ktor's `ContentNegotiation` plugin with `kotlinx.serialization.json`
inside `ServerConfiguration`
- Implement the following methods, each returning the appropriate
`McpBuildingStep` and using `mokksy.post()` with `bodyMatchesPredicate {
it?.method == "..." }`:
  - `initialize()` → matches `method == "initialize"`
  - `toolsList()` → matches `method == "tools/list"`
  - `toolsCall()` → matches `method == "tools/call"`
  - `resourcesList()` → matches `method == "resources/list"`
  - `resourcesRead()` → matches `method == "resources/read"`
  - `promptsList()` → matches `method == "prompts/list"`
  - `promptsGet()` → matches `method == "prompts/get"`
  - `ping()` → matches `method == "ping"`
  - `method(methodName: String)` → generic fallback for arbitrary method names

**McpRequestSpecification<P>**
- Extend `ModelRequestSpecification<P>`
- `protocolVersion(version: String)` — validates `MCP-Protocol-Version` header
via `containsHeader()`
- `sessionId(id: String)` — matches `MCP-Session-Id` header via
`containsHeader()`
- `hasSessionId()` — predicate matcher asserting the `MCP-Session-Id` header is
present with any value
- `paramContains(substring: String)` — substring match within the params JSON
- `paramMatches(predicate: (P?) -> Boolean)` — typed parameter predicate
matching
- Inherited: `requestBodyContains()`, `requestMatchesPredicate()`

**McpBuildingStep<P, R>** and **McpResponseSpecification<P, T>**
- `McpBuildingStep` extends `AbstractBuildingStep<P, R>`; override `responds()`
to delegate to `buildingStep.respondsWith { }`
- `McpResponseSpecification` extends `AbstractResponseSpecification<P, T>`:
  - `result(value: T)` — sets the JSON-RPC result payload
- `error(code: Int, message: String, data: Any? = null)` — configures a JSON-RPC
error response
  - `sessionId(id: String)` — sets the `MCP-Session-Id` response header
- The `responds` block must serialise a `JsonRpcResponse` wrapping the
configured result or error

Phase 3: Streaming and SSE Support

This phase adds SSE streaming capabilities for MCP responses that may emit multiple messages before completing, and implements the GET endpoint for server-initiated streams.

Task 1: Implement Streaming Response Specification

Create the response specification for SSE-based streaming responses following the A2A pattern.

• Create McpStreamingResponseSpecification<P> extending AbstractStreamingResponseSpecification in the mcp package
• Add responseFlow: Flow<JsonRpcMessage>? property for emitting arbitrary JSON-RPC messages (requests, notifications, responses)
• Add chunks(vararg messages: JsonRpcMessage) convenience method converting to a Flow
• Add notifications(flow: Flow<JsonRpcNotification>) for server-to-client notifications
• Add delayBetweenChunks: Duration property (inherited) for pacing
• Add finalResult(value: T) method to set the terminal JSON-RPC response
• Add JVM extension in jvmMain accepting java.util.concurrent.Flow.Publisher<JsonRpcMessage> for Java interop

Task 2: Implement Streaming Building Step

Create the building step that wires streaming responses to mokksy's SSE infrastructure.

• Create McpStreamingBuildingStep<P> extending AbstractStreamingBuildingStep for streaming MCP operations
• Override respondsStream() to delegate to buildingStep.respondsWithStream { }
• Inside the lambda: collect responseFlow, map each JsonRpcMessage to JSON string via Json.encodeToString()
• Wrap each JSON string in ServerSentEvent(data = json).toString() + '\n' following A2A pattern
• Set SSE headers: Content-Type: text/event-stream, Cache-Control: no-store, Connection: keep-alive
• After flow completes, emit the final result if configured

Task 3: Add GET Endpoint for Server-Initiated SSE Streams

Implement the optional GET handler for opening SSE streams that the server can push notifications to.

• Add openStream() method to MockMcpServer returning a streaming building step
• Registers a GET handler on the MCP endpoint path via mokksy.get()
• The response specification accepts a Flow<JsonRpcMessage> for server-initiated messages
• Implement MCP-Session-Id header matching so streams can be scoped to sessions
• This enables testing scenarios where the server pushes notifications/requests independently of client POST requests

Task 4: Add DELETE Endpoint for Session Termination

Implement the DELETE handler for explicit session termination.

• Add deleteSession() method to MockMcpServer returning a simple building step
• Registers a DELETE handler on the MCP endpoint path via mokksy.delete()
• The response specification supports configuring the response status (204 No Content typically)
• Match MCP-Session-Id header to scope termination to specific sessions
• Support 405 response configuration for servers that don't allow client-initiated termination

🤖 Prompt for AI agents

Add SSE streaming support to the MCP mock server, including a streaming response
specification, streaming building step, a GET endpoint for server-initiated
streams, and a DELETE endpoint for session termination. Follow the A2A module's
SSE pattern throughout.

**McpStreamingResponseSpecification<P>**
- Extend `AbstractStreamingResponseSpecification`
- `responseFlow: Flow<JsonRpcMessage>?` — emits arbitrary JSON-RPC messages
(requests, notifications, responses)
- `chunks(vararg messages: JsonRpcMessage)` — convenience method that converts
the vararg to a `Flow`
- `notifications(flow: Flow<JsonRpcNotification>)` — dedicated method for
server-to-client notifications
- `delayBetweenChunks: Duration` — inherited property for pacing
- `finalResult(value: T)` — sets the terminal JSON-RPC response emitted after
the flow completes
- In `jvmMain`, add an extension accepting
`java.util.concurrent.Flow.Publisher<JsonRpcMessage>` for Java interop

**McpStreamingBuildingStep<P>**
- Extend `AbstractStreamingBuildingStep`
- Override `respondsStream()` to delegate to `buildingStep.respondsWithStream {
}`
- Inside the lambda:
- Collect `responseFlow`, mapping each `JsonRpcMessage` to a JSON string via
`Json.encodeToString()`
- Wrap each JSON string as `ServerSentEvent(data = json).toString() + '\n'` (A2A
pattern)
- Set headers: `Content-Type: text/event-stream`, `Cache-Control: no-store`,
`Connection: keep-alive`
  - After the flow completes, emit the final result if one is configured

**GET Endpoint — openStream()**
- Add `openStream()` to `MockMcpServer`, returning a streaming building step
- Registers a GET handler on `endpointPath` via `mokksy.get()`
- The response specification accepts a `Flow<JsonRpcMessage>` for
server-initiated messages
- Support `MCP-Session-Id` header matching so streams can be scoped to specific
sessions

**DELETE Endpoint — deleteSession()**
- Add `deleteSession()` to `MockMcpServer`, returning a simple building step
- Registers a DELETE handler on `endpointPath` via `mokksy.delete()`
- Response specification supports configuring the response status (default 204
No Content)
- Match `MCP-Session-Id` header to scope termination to specific sessions
- Support 405 response configuration for servers that do not allow
client-initiated termination

Phase 4: Integration Testing and Documentation

This phase validates the implementation against real HTTP clients and ensures the DSL is ergonomic for typical testing scenarios.

Task 1: Create Integration Tests for Core Operations

Write tests exercising the main MCP operations using Ktor's HttpClient.

• Create test class in ai-mocks-mcp/src/jvmTest/kotlin/ using JUnit 5
• Test initialize flow: POST with initialize request, verify JSON response with capabilities
• Test tools/list and tools/call: register tools, call them, verify responses
• Test resources/list and resources/read: register resources, read them
• Test prompts/list and prompts/get: register prompts, retrieve them
• Test error responses: configure error results, verify JSON-RPC error structure
• Use Ktor HttpClient directly (like A2A tests in Clients.kt) rather than a dedicated MCP client
• Verify MCP-Protocol-Version and MCP-Session-Id header handling

Task 2: Create Integration Tests for Streaming

Write tests exercising SSE streaming functionality.

• Test streaming response: configure a flow of notifications followed by final result
• Verify SSE frame format: data: {...}\n\n structure
• Test delayBetweenChunks behaviour
• Test GET endpoint for server-initiated streams
• Use Ktor's SSE client support to consume the streams
• Verify proper stream termination after final result

Task 3: Add Usage Examples and KDoc

Document the public API with examples showing common testing patterns.

• Add KDoc to MockMcpServer class with overview and basic usage example
• Add KDoc to each public method showing typical stub registration
• Document request specification matchers with examples
• Document response specification methods
• Add example showing streaming response configuration
• Ensure all public API has explicitApi() visibility modifiers (enforced by kotlin-convention)

🤖 Prompt for AI agents

Write JUnit 5 integration tests for core and streaming MCP operations, then add
KDoc documentation to all public API surfaces. Tests live in
`ai-mocks-mcp/src/jvmTest/kotlin/` and use Ktor's `HttpClient` directly
(following the A2A `Clients.kt` pattern).

**Core Operation Tests**
- `initialize` flow: POST an initialize request, assert the JSON response
contains the expected capabilities
- `tools/list` and `tools/call`: register tool stubs, invoke them, verify
responses
- `resources/list` and `resources/read`: register resource stubs, read them,
verify responses
- `prompts/list` and `prompts/get`: register prompt stubs, retrieve them, verify
responses
- Error responses: configure error results and assert the JSON-RPC error
structure (`code`, `message`, `data`)
- Header handling: verify `MCP-Protocol-Version` and `MCP-Session-Id` matching
behaviour

**Streaming Tests**
- Configure a flow of notifications followed by a final result; assert all SSE
frames are received in order
- Verify SSE frame format: `data: {...}\n\n` structure
- Test `delayBetweenChunks` behaviour
- Test GET endpoint for server-initiated streams
- Use Ktor's SSE client support to consume streams
- Verify proper stream termination after the final result is emitted

**KDoc and API Documentation**
- Add KDoc to `MockMcpServer` with an overview and a basic usage example
- Add KDoc to each public method showing a typical stub registration snippet
- Document all request specification matchers and response specification methods
with examples
- Include a streaming response configuration example
- Confirm all public API members carry `explicitApi()` visibility modifiers as
enforced by `kotlin-convention`

Research

The project is a Kotlin Multiplatform monorepo providing mock servers for various AI/LLM protocols. The core architecture consists of mokksy (a WireMock-style HTTP mock server built on Ktor), ai-mocks-core (base classes for LLM mocks), and provider-specific modules (openai, anthropic, gemini, ollama, a2a). Each provider module follows a consistent pattern: a mock server class extending AbstractMockLlm, building steps for fluent DSL registration, request specifications for matching, and response specifications for configuring replies. The A2A module is the closest architectural reference as it also uses JSON-RPC over HTTP with SSE streaming and has a separate models submodule.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Set up the two new Gradle modules (`ai-mocks-mcp-models` and `ai-mocks-mcp`) and
implement all MCP protocol data classes. The goal is to establish the full
module structure and define every data class needed for the MCP Streamable HTTP
Transport before any server logic is written.

**Module Setup**
- Add `:ai-mocks-mcp-models` and `:ai-mocks-mcp` to `settings.gradle.kts`
- Create `ai-mocks-mcp-models/gradle.properties` and
`ai-mocks-mcp-models/build.gradle.kts` applying `kotlin-convention`,
`dokka-convention`, `publish-convention`; only dependency is
`kotlinx-serialization-json`
- Create `ai-mocks-mcp/gradle.properties` and `ai-mocks-mcp/build.gradle.kts`
applying conventions plus `netty-convention` and `shadow-convention`; depends on
`:ai-mocks-core` and `:ai-mocks-mcp-models`
- Add both modules to the Kover aggregation block in root `build.gradle.kts`
- Follow the established A2A module pattern throughout

**JSON-RPC Base Types** (package: `dev/mokksy/aimocks/mcp/models/`)
- `JsonRpcRequest` open class with `jsonrpc`, `id`, `method`, and a generic
`params` type parameter
- `JsonRpcResponse` with `jsonrpc`, `id`, and a sealed `result`/`error`
structure
- `JsonRpcError` with `code`, `message`, `data` per JSON-RPC 2.0 spec
- `JsonRpcNotification` for messages without an `id` field
- Add `@Serializable` annotations and any `KSerializer` implementations required
for polymorphic dispatch

**MCP Request/Response Types**
- `InitializeRequest` / `InitializeResult` — include `protocolVersion`,
`capabilities`, `serverInfo`/`clientInfo`
- `ToolsListRequest` / `ToolsListResult` — `tools` array with `Tool` objects
(name, description, inputSchema)
- `ToolsCallRequest` (name, arguments) / `ToolsCallResult` (content array of
`TextContent`/`ImageContent`/`EmbeddedResource`)
- `ResourcesListRequest` / `ResourcesListResult` — `resources` array with
`Resource` objects
- `ResourcesReadRequest` (uri) / `ResourcesReadResult` (contents array)
- `PromptsListRequest` / `PromptsListResult` — `prompts` array with `Prompt`
objects
- `PromptsGetRequest` (name, arguments) / `PromptsGetResult` (messages array)
- `PingRequest` and an empty `PingResult`
- Create Kotlin builder classes for each result type to enable fluent test setup
(following A2A builder pattern)

**Capability and Content Types**
- `ClientCapabilities` and `ServerCapabilities` with optional feature flags
(tools, resources, prompts, logging, experimental)
- `Implementation` with `name` and `version`
- `TextContent`, `ImageContent`, `EmbeddedResource` with polymorphic
serialisation via a `type` discriminator
- `ResourceContents` with `uri`, `mimeType`, `text`/`blob` variants
- `PromptMessage` with `role` and `content`
===============================================================================

Task: 2

Implement the core mock server class and its fluent DSL for registering and
matching MCP request handlers. This phase mirrors the `MockAgentServer`
architecture from the A2A module.

**MockMcpServer** (`ai-mocks-mcp/src/commonMain/kotlin/dev/mokksy/aimocks/mcp/`)
- Extend `AbstractMockLlm`
- Constructor parameters: `port: Int = 0`, `verbose: Boolean = true`,
`endpointPath: String = "/mcp"`
- Configure Ktor's `ContentNegotiation` plugin with `kotlinx.serialization.json`
inside `ServerConfiguration`
- Implement the following methods, each returning the appropriate
`McpBuildingStep` and using `mokksy.post()` with `bodyMatchesPredicate {
it?.method == "..." }`:
  - `initialize()` → matches `method == "initialize"`
  - `toolsList()` → matches `method == "tools/list"`
  - `toolsCall()` → matches `method == "tools/call"`
  - `resourcesList()` → matches `method == "resources/list"`
  - `resourcesRead()` → matches `method == "resources/read"`
  - `promptsList()` → matches `method == "prompts/list"`
  - `promptsGet()` → matches `method == "prompts/get"`
  - `ping()` → matches `method == "ping"`
  - `method(methodName: String)` → generic fallback for arbitrary method names

**McpRequestSpecification<P>**
- Extend `ModelRequestSpecification<P>`
- `protocolVersion(version: String)` — validates `MCP-Protocol-Version` header
via `containsHeader()`
- `sessionId(id: String)` — matches `MCP-Session-Id` header via
`containsHeader()`
- `hasSessionId()` — predicate matcher asserting the `MCP-Session-Id` header is
present with any value
- `paramContains(substring: String)` — substring match within the params JSON
- `paramMatches(predicate: (P?) -> Boolean)` — typed parameter predicate
matching
- Inherited: `requestBodyContains()`, `requestMatchesPredicate()`

**McpBuildingStep<P, R>** and **McpResponseSpecification<P, T>**
- `McpBuildingStep` extends `AbstractBuildingStep<P, R>`; override `responds()`
to delegate to `buildingStep.respondsWith { }`
- `McpResponseSpecification` extends `AbstractResponseSpecification<P, T>`:
  - `result(value: T)` — sets the JSON-RPC result payload
- `error(code: Int, message: String, data: Any? = null)` — configures a JSON-RPC
error response
  - `sessionId(id: String)` — sets the `MCP-Session-Id` response header
- The `responds` block must serialise a `JsonRpcResponse` wrapping the
configured result or error
===============================================================================

Task: 3

Add SSE streaming support to the MCP mock server, including a streaming response
specification, streaming building step, a GET endpoint for server-initiated
streams, and a DELETE endpoint for session termination. Follow the A2A module's
SSE pattern throughout.

**McpStreamingResponseSpecification<P>**
- Extend `AbstractStreamingResponseSpecification`
- `responseFlow: Flow<JsonRpcMessage>?` — emits arbitrary JSON-RPC messages
(requests, notifications, responses)
- `chunks(vararg messages: JsonRpcMessage)` — convenience method that converts
the vararg to a `Flow`
- `notifications(flow: Flow<JsonRpcNotification>)` — dedicated method for
server-to-client notifications
- `delayBetweenChunks: Duration` — inherited property for pacing
- `finalResult(value: T)` — sets the terminal JSON-RPC response emitted after
the flow completes
- In `jvmMain`, add an extension accepting
`java.util.concurrent.Flow.Publisher<JsonRpcMessage>` for Java interop

**McpStreamingBuildingStep<P>**
- Extend `AbstractStreamingBuildingStep`
- Override `respondsStream()` to delegate to `buildingStep.respondsWithStream {
}`
- Inside the lambda:
- Collect `responseFlow`, mapping each `JsonRpcMessage` to a JSON string via
`Json.encodeToString()`
- Wrap each JSON string as `ServerSentEvent(data = json).toString() + '\n'` (A2A
pattern)
- Set headers: `Content-Type: text/event-stream`, `Cache-Control: no-store`,
`Connection: keep-alive`
  - After the flow completes, emit the final result if one is configured

**GET Endpoint — openStream()**
- Add `openStream()` to `MockMcpServer`, returning a streaming building step
- Registers a GET handler on `endpointPath` via `mokksy.get()`
- The response specification accepts a `Flow<JsonRpcMessage>` for
server-initiated messages
- Support `MCP-Session-Id` header matching so streams can be scoped to specific
sessions

**DELETE Endpoint — deleteSession()**
- Add `deleteSession()` to `MockMcpServer`, returning a simple building step
- Registers a DELETE handler on `endpointPath` via `mokksy.delete()`
- Response specification supports configuring the response status (default 204
No Content)
- Match `MCP-Session-Id` header to scope termination to specific sessions
- Support 405 response configuration for servers that do not allow
client-initiated termination
===============================================================================

Task: 4

Write JUnit 5 integration tests for core and streaming MCP operations, then add
KDoc documentation to all public API surfaces. Tests live in
`ai-mocks-mcp/src/jvmTest/kotlin/` and use Ktor's `HttpClient` directly
(following the A2A `Clients.kt` pattern).

**Core Operation Tests**
- `initialize` flow: POST an initialize request, assert the JSON response
contains the expected capabilities
- `tools/list` and `tools/call`: register tool stubs, invoke them, verify
responses
- `resources/list` and `resources/read`: register resource stubs, read them,
verify responses
- `prompts/list` and `prompts/get`: register prompt stubs, retrieve them, verify
responses
- Error responses: configure error results and assert the JSON-RPC error
structure (`code`, `message`, `data`)
- Header handling: verify `MCP-Protocol-Version` and `MCP-Session-Id` matching
behaviour

**Streaming Tests**
- Configure a flow of notifications followed by a final result; assert all SSE
frames are received in order
- Verify SSE frame format: `data: {...}\n\n` structure
- Test `delayBetweenChunks` behaviour
- Test GET endpoint for server-initiated streams
- Use Ktor's SSE client support to consume streams
- Verify proper stream termination after the final result is emitted

**KDoc and API Documentation**
- Add KDoc to `MockMcpServer` with an overview and a basic usage example
- Add KDoc to each public method showing a typical stub registration snippet
- Document all request specification matchers and response specification methods
with examples
- Include a streaming response configuration example
- Confirm all public API members carry `explicitApi()` visibility modifiers as
enforced by `kotlin-convention`

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!