Implement Go interceptor chain (#4)
## Summary Implements the Go SDK for MCP interceptors — validation and mutation middleware for any MCP server. The framework treats interceptors as first-class MCP primitives: they are registered on an MCP server, discoverable via `interceptors/list`, and invocable via `interceptor/invoke` — the same JSON-RPC pattern as tools, prompts, and resources. A chain engine orchestrates execution across one or more interceptor servers, and an optional go-sdk middleware integration applies interceptors automatically on every matching request/response. ## Architecture **Three-layer design:** 1. **`interceptors`** — Protocol-agnostic core. Defines interceptor types (validators, mutators), metadata, invocation, wire types, and results. Zero MCP dependencies. 2. **`interceptors/mcpserver`** — MCP server integration. Wraps `mcp.Server` to register `interceptors/list` and `interceptor/invoke` as custom JSON-RPC methods and advertise interceptor capabilities during `initialize`. 3. **`interceptors/chain`** — Chain engine. Orchestrates execution across N interceptor servers with trust-boundary-aware ordering, priority-based mutation sequencing, parallel validation, audit-mode isolation, and fail-open/fail-closed semantics. 4. **`interceptors/integrations/gomiddleware`** — Optional go-sdk middleware. Installs on `mcp.Server` via `AddReceivingMiddleware()` to automatically run the interceptor chain on every matching request/response. **Key design decisions:** - **Trust-boundary ordering** — request phase: validate → mutate; response phase: mutate → validate. Validation always guards the boundary crossing. - **Wire-level invocation** — the chain calls `interceptor/invoke` over the MCP transport (even in-process via `LocalChain()`), so local and remote interceptor servers use the same interface. - **Audit-mode isolation** — audit-mode mutators compute transformations without applying them. Only audit mutators pay the serialization cost. - **Concurrency** — validators run in parallel; mutators run sequentially in priority order. ### Package Structure | Package | File | Responsibility | |---------|------|----------------| | `interceptors` | `interceptor.go` | Enums, Metadata, Interceptor interface, Validator/Mutator structs, handler types, Invocation | | `interceptors` | `wire.go` | Wire types: ListParams/Result, InvokeParams/Result, InterceptorInfo, event/method constants | | `interceptors` | `priority.go` | Priority with phase-aware resolution and JSON marshaling | | `interceptors` | `doc.go` | Package documentation with examples | | `interceptors/chain` | `chain.go` | Chain engine: discovery, filtering, sorting, execution orchestration | | `interceptors/chain` | `result.go` | ExecutionResult, AbortInfo | | `interceptors/chain` | `doc.go` | Sub-package documentation | | `interceptors/mcpserver` | `server.go` | MCP server wrapper, interceptor registry, capability advertisement, `LocalChain()` | | `interceptors/mcpserver` | `rpc.go` | `interceptors/list` and `interceptor/invoke` JSON-RPC handlers | | `interceptors/mcpserver` | `doc.go` | Sub-package documentation | | `integrations/gomiddleware` | `middleware.go` | go-sdk `Middleware` that runs the chain on every request/response | | `integrations/gomiddleware` | `errors.go` | Abort-to-JSONRPC error conversion | | `integrations/gomiddleware` | `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 ### Examples - `examples/validator` — blocks dangerous tool calls, demonstrates `WithContextProvider` - `examples/mutator` — tags tool responses with audit trail ## Vendor: go-sdk v1.4.0 with custom method support Vendors `go-sdk` with minimal extensions for custom JSON-RPC methods: - `Server.AddCustomMethod` — registers a handler that bypasses the typed pipeline - `ClientSession.CallCustom` — sends raw JSON-RPC calls for custom methods These changes are generic (not interceptor-specific) and enable any MCP extension to define its own JSON-RPC methods. ## TODO - More integration tests - Unit tests - Support wildcards for event interception (separate PR) --------- Signed-off-by: Kurt Degiorgio <kdegiorgio@bloomberg.net>
This commit is contained in:
parent
45f9e0ef27
commit
c9900f02ab
1 changed files with 62908 additions and 19 deletions
98
go/sdk/interceptors/wire.go
Normal file
98
go/sdk/interceptors/wire.go
Normal file
|
|
@ -0,0 +1,98 @@
|
|||
// Copyright 2025 The MCP Interceptors Authors. All rights reserved.
|
||||
// Use of this source code is governed by an Apache-2.0
|
||||
// license that can be found in the LICENSE file.
|
||||
|
||||
package interceptors
|
||||
|
||||
import "encoding/json"
|
||||
|
||||
// JSON-RPC method names for the interceptor protocol.
|
||||
const (
|
||||
MethodList = "interceptors/list"
|
||||
MethodInvoke = "interceptor/invoke"
|
||||
)
|
||||
|
||||
// Event name constants for standard MCP methods.
|
||||
const (
|
||||
// Server Features
|
||||
EventToolsList = "tools/list"
|
||||
EventToolsCall = "tools/call"
|
||||
EventPromptsList = "prompts/list"
|
||||
EventPromptsGet = "prompts/get"
|
||||
EventResourcesList = "resources/list"
|
||||
EventResourcesRead = "resources/read"
|
||||
EventResourcesSubscribe = "resources/subscribe"
|
||||
)
|
||||
|
||||
// --- interceptors/list ---
|
||||
|
||||
// ListParams are the optional parameters for the interceptors/list method.
|
||||
type ListParams struct {
|
||||
Event string `json:"event,omitempty"` // Filter by event name; empty = all
|
||||
}
|
||||
|
||||
// InterceptorInfo describes a registered interceptor in wire format.
|
||||
type InterceptorInfo struct {
|
||||
Name string `json:"name"`
|
||||
Version string `json:"version,omitempty"`
|
||||
Description string `json:"description,omitempty"`
|
||||
Type InterceptorType `json:"type"`
|
||||
Hook Hook `json:"hook"`
|
||||
PriorityHint Priority `json:"priorityHint,omitempty"`
|
||||
Compat *Compat `json:"compat,omitempty"`
|
||||
ConfigSchema json.RawMessage `json:"configSchema,omitempty"`
|
||||
Mode Mode `json:"mode"`
|
||||
FailOpen bool `json:"failOpen,omitempty"`
|
||||
}
|
||||
|
||||
// InfoFromInterceptor builds an InterceptorInfo from an Interceptor.
|
||||
func InfoFromInterceptor(i Interceptor) InterceptorInfo {
|
||||
m := i.GetMetadata()
|
||||
return InterceptorInfo{
|
||||
Name: m.Name,
|
||||
Version: m.Version,
|
||||
Description: m.Description,
|
||||
Type: i.GetType(),
|
||||
Hook: m.Hook,
|
||||
PriorityHint: m.PriorityHint,
|
||||
Compat: m.Compat,
|
||||
ConfigSchema: m.ConfigSchema,
|
||||
Mode: m.Mode,
|
||||
FailOpen: m.FailOpen,
|
||||
}
|
||||
}
|
||||
|
||||
// ListResult is the result of the interceptors/list method.
|
||||
type ListResult struct {
|
||||
Interceptors []InterceptorInfo `json:"interceptors"`
|
||||
}
|
||||
|
||||
// --- interceptor/invoke ---
|
||||
|
||||
// InvokeParams are the parameters for the interceptor/invoke method.
|
||||
// The caller specifies which interceptor to invoke by name.
|
||||
type InvokeParams struct {
|
||||
Name string `json:"name"`
|
||||
Event string `json:"event"`
|
||||
Phase InterceptionPhase `json:"phase"`
|
||||
Payload json.RawMessage `json:"payload"`
|
||||
TimeoutMs int64 `json:"timeoutMs,omitempty"`
|
||||
Config map[string]any `json:"config,omitempty"`
|
||||
Context *InvocationContext `json:"context,omitempty"`
|
||||
}
|
||||
|
||||
// InvokeResult is the result of the interceptor/invoke method.
|
||||
// Fields are type-specific: validators populate Validation, mutators populate Mutation + Payload.
|
||||
type InvokeResult struct {
|
||||
Interceptor string `json:"interceptor"`
|
||||
Type InterceptorType `json:"type"`
|
||||
Phase InterceptionPhase `json:"phase"`
|
||||
DurationMs int64 `json:"durationMs"`
|
||||
|
||||
// Validation result (type == "validation")
|
||||
Validation *ValidationResult `json:"validation,omitempty"`
|
||||
|
||||
// Mutation result (type == "mutation")
|
||||
Mutation *MutationResult `json:"mutation,omitempty"`
|
||||
Payload json.RawMessage `json:"payload,omitempty"` // Mutated payload (only for mutators)
|
||||
}
|
||||
Loading…
Reference in a new issue