Implement Go interceptor chain

[Degiorgio]

Summary

Implements the server-side interceptor chain for Go, enabling validation and mutation middleware on
any server that processes request/response pairs.

The core interceptor framework (chain engine, validators, mutators, invocations, results) is fully
protocol-agnostic with zero MCP dependencies. The MCP-specific server integration lives in a
separate mcpserver sub-package, wiring interceptors into go-sdk's middleware for all transports
(stdio, HTTP).

Protocol-Level Methods — Current Limitation

The SEP defines interceptors as a first-class resource type, like tools, prompts, and resources.
The server should expose them via interceptors/list and interceptor/executeChain, and
consumers — including the middleware integration — should call them as clients through the
transport, the same way a client calls tools/call.

Where we want to be:

• The interceptor server exposes interceptors/list and interceptor/executeChain as JSON-RPC methods
• The middleware integration is just another client — it calls interceptor/executeChain via
  mcp.Client to run the chain, rather than calling the Chain engine directly
• This enables both in-process and sidecar/remote interceptor deployments through the same interface

Where we are right now:

• The middleware calls the Chain engine directly (in-process only)
• The go-sdk (v1.4.0) does not support custom JSON-RPC method registration —
  checkRequest() rejects unknown methods before middleware runs, and there is no AddMethod API
• Once the go-sdk supports custom methods, the middleware can be refactored to go through the protocol

Blocked on go-sdk:

• Upstream AddMethod (or equivalent) to go-sdk
• Register interceptors/list and interceptor/executeChain as protocol methods
• Refactor middleware to use mcp.Client as the entry point

---

Architecture

• Protocol-agnostic core — the interceptors package exposes a public Chain type that manages
  interceptor registration and execution with no transport coupling. Any server can use
  Chain.ExecuteForReceiving / Chain.ExecuteForSending directly.
• Typed payload — Invocation.Payload carries the live Go value (any) directly through the chain, the
  same pattern as gRPC-Go interceptors. Handlers type-assert to the concrete type and mutate in place. Zero JSON
  operations in the normal path.
• Trust-boundary ordering — request phase runs validate → mutate (validators gate before mutation);
  response phase runs mutate → validate (mutations prepare before validation).
• Audit-mode isolation — audit-mode mutators receive a deep copy via JSON round-trip so their
  modifications don't affect the real payload. Only audit mutators pay this cost.
• Chain caching — chainExecutors are cached per event|phase in a sync.Map, invalidated implicitly on
  Add via atomic snapshot swap.
• Concurrency — validators run in parallel (goroutines + mutex); mutators run sequentially in priority
  order.

Package Structure

Package	File	Responsibility
interceptors	chain.go	Public Chain type, NewChain, Add, ExecuteForReceiving/Sending, IsEmpty
interceptors	chain_executor.go	Internal chainExecutor, filtering, sorting, snapshot caching
interceptors	chain_validate.go	Parallel validator dispatch
interceptors	chain_mutate.go	Sequential mutator execution
interceptors	interceptor.go	Types, Metadata, Validator/Mutator structs
interceptors	invocation.go	Invocation with audit-mode payload cloning
interceptors	result.go	ValidationResult, MutationResult, ChainResult, AbortInfo
interceptors	doc.go	Package documentation with examples
interceptors/mcpserver	server.go	MCP Server wrapper, middleware, capability declaration
interceptors/mcpserver	events.go	MCP event name constants
interceptors/mcpserver	doc.go	Sub-package documentation

Documentation

• doc/DESIGN.md — architecture, execution model, integration with go-sdk
• doc/CONFORMANCE.md — SEP conformance status
• doc/PERFORMANCE.md — per-request cost model
• doc.go — detailed go docs

TODO

• More integration tests
• Unit tests
• Implement SEP's protocol-level methods (interceptors/*) — blocked on go-sdk custom method support
• Support wildcards for event interception (separate PR)

[StevenRChen]

Can you include go version 1.26 too

[Degiorgio]

yes, will add!

[StevenRChen]

Will it be better to embed the mcp.Server direclty?

type Server struct {
    *mcp.Server
    // ...
}

[Degiorgio]

I opted not to embed *mcp.Server to avoid leaking AddReceivingMiddleware (or the sending equiv). The interceptor server installs its own middleware during construction, and exposing AddReceivingMiddleware on the wrapper would let callers unknowingly affect middleware ordering. Wrapping keeps the API surface explicit.

[StevenRChen]

interceptResponse may need access to the request payload too.
Can you include it as one of the argument or part of InvocationContext?

[Degiorgio]

I agree this will be useful, added a getter, see tests

[StevenRChen]

Is there a plan to support the third interceptor type from the SEP, observability?

[Degiorgio]

No, check the comments on the SEP, in short, we added an audit mode for validators and mutators instead