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
4 changed files with 62908 additions and 19 deletions
439
go/sdk/interceptors/chain/chain.go
Normal file
439
go/sdk/interceptors/chain/chain.go
Normal file
|
|
@ -0,0 +1,439 @@
|
|||
// 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 chain
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"log/slog"
|
||||
"slices"
|
||||
"sort"
|
||||
"sync"
|
||||
"time"
|
||||
|
||||
"github.com/modelcontextprotocol/go-sdk/mcp"
|
||||
|
||||
"github.com/modelcontextprotocol/ext-interceptors/go/sdk/interceptors"
|
||||
)
|
||||
|
||||
// ChainEntry pairs an interceptor descriptor with the MCP client
|
||||
// session that hosts it.
|
||||
type ChainEntry struct {
|
||||
Interceptor interceptors.InterceptorInfo
|
||||
Server *mcp.ClientSession
|
||||
}
|
||||
|
||||
// Chain is the SEP-compliant interceptor chain orchestrator. It holds
|
||||
// ChainEntry objects (interceptor descriptors + MCP server connections),
|
||||
// discovers interceptors via interceptors/list, and invokes them via
|
||||
// interceptor/invoke on the appropriate server.
|
||||
type Chain struct {
|
||||
mu sync.Mutex
|
||||
entries []ChainEntry
|
||||
logger *slog.Logger
|
||||
}
|
||||
|
||||
// ChainOption configures a Chain.
|
||||
type ChainOption func(*Chain)
|
||||
|
||||
// WithChainLogger sets the logger for chain execution.
|
||||
// If not set, slog.Default() is used.
|
||||
func WithChainLogger(l *slog.Logger) ChainOption {
|
||||
return func(c *Chain) {
|
||||
c.logger = l
|
||||
}
|
||||
}
|
||||
|
||||
// NewChain creates a new Chain with optional configuration.
|
||||
func NewChain(opts ...ChainOption) *Chain {
|
||||
c := &Chain{}
|
||||
for _, opt := range opts {
|
||||
opt(c)
|
||||
}
|
||||
if c.logger == nil {
|
||||
c.logger = slog.Default()
|
||||
}
|
||||
return c
|
||||
}
|
||||
|
||||
// ExecutionParams configures a chain execution run. These are
|
||||
// SDK-level types used by Chain.Execute, not wire-protocol types.
|
||||
type ExecutionParams struct {
|
||||
Event string `json:"event"`
|
||||
Phase interceptors.InterceptionPhase `json:"phase"`
|
||||
Payload json.RawMessage `json:"payload"`
|
||||
Interceptors []string `json:"interceptors,omitempty"` // optional: restrict to named interceptors
|
||||
Config map[string]map[string]any `json:"config,omitempty"` // optional: per-interceptor config
|
||||
TimeoutMs int64 `json:"timeoutMs,omitempty"`
|
||||
Context *interceptors.InvocationContext `json:"context,omitempty"`
|
||||
}
|
||||
|
||||
// ExecutionResult aggregates results from executing the full
|
||||
// interceptor chain via interceptor/invoke RPCs.
|
||||
type ExecutionResult struct {
|
||||
Status ChainStatus `json:"status"`
|
||||
Event string `json:"event"`
|
||||
Phase interceptors.InterceptionPhase `json:"phase"`
|
||||
Results []interceptors.InvokeResult `json:"results"`
|
||||
FinalPayload json.RawMessage `json:"finalPayload,omitempty"`
|
||||
ValidationSummary ValidationSummary `json:"validationSummary"`
|
||||
TotalDurationMs int64 `json:"totalDurationMs"`
|
||||
AbortedAt []AbortInfo `json:"abortedAt,omitempty"`
|
||||
}
|
||||
|
||||
// AddMCPServer discovers interceptors from an MCP server via
|
||||
// interceptors/list and adds entries for each. The client session's
|
||||
// transport determines how interceptor/invoke calls are made
|
||||
// (in-memory, stdio, HTTP, etc.).
|
||||
func (c *Chain) AddMCPServer(ctx context.Context, cs *mcp.ClientSession) error {
|
||||
var result interceptors.ListResult
|
||||
if err := cs.CallCustom(ctx, interceptors.MethodList, nil, &result); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
c.mu.Lock()
|
||||
defer c.mu.Unlock()
|
||||
for _, info := range result.Interceptors {
|
||||
c.entries = append(c.entries, ChainEntry{
|
||||
Interceptor: info,
|
||||
Server: cs,
|
||||
})
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// Execute runs the chain for a given event and phase per the SEP
|
||||
// execution model:
|
||||
//
|
||||
// - Filter entries by event + phase
|
||||
// - Separate into validators and mutators
|
||||
// - Sort mutators by priorityHint (ascending, alphabetical tiebreak)
|
||||
// - Request phase: validate (parallel) then mutate (sequential)
|
||||
// - Response phase: mutate (sequential) then validate (parallel)
|
||||
// - Call interceptor/invoke via CallCustom for each entry
|
||||
// - For mutators: pass mutated payload from previous to next
|
||||
// - Handle abort, timeout, fail-open
|
||||
func (c *Chain) Execute(ctx context.Context, params *ExecutionParams) (*ExecutionResult, error) {
|
||||
c.mu.Lock()
|
||||
entries := make([]ChainEntry, len(c.entries))
|
||||
copy(entries, c.entries)
|
||||
c.mu.Unlock()
|
||||
|
||||
// Apply timeout if specified.
|
||||
if params.TimeoutMs > 0 {
|
||||
var cancel context.CancelFunc
|
||||
ctx, cancel = context.WithTimeout(ctx, time.Duration(params.TimeoutMs)*time.Millisecond)
|
||||
defer cancel()
|
||||
}
|
||||
|
||||
start := time.Now()
|
||||
|
||||
// Filter entries by event + phase, respecting optional name filter.
|
||||
nameFilter := make(map[string]bool, len(params.Interceptors))
|
||||
for _, n := range params.Interceptors {
|
||||
nameFilter[n] = true
|
||||
}
|
||||
|
||||
var validators []ChainEntry
|
||||
var mutators []ChainEntry
|
||||
|
||||
for _, e := range entries {
|
||||
if len(nameFilter) > 0 && !nameFilter[e.Interceptor.Name] {
|
||||
continue
|
||||
}
|
||||
if !matchesPhase(e.Interceptor.Hook.Phase, params.Phase) {
|
||||
continue
|
||||
}
|
||||
if !slices.Contains(e.Interceptor.Hook.Events, params.Event) {
|
||||
continue
|
||||
}
|
||||
switch e.Interceptor.Type {
|
||||
case interceptors.TypeValidation:
|
||||
validators = append(validators, e)
|
||||
case interceptors.TypeMutation:
|
||||
mutators = append(mutators, e)
|
||||
default:
|
||||
c.logger.Warn("unknown interceptor type, skipping",
|
||||
"interceptor", e.Interceptor.Name,
|
||||
"type", e.Interceptor.Type,
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
// Sort mutators by priority (ascending), alphabetical tiebreak.
|
||||
sort.Slice(mutators, func(i, j int) bool {
|
||||
pi := mutators[i].Interceptor.PriorityHint.Resolve(params.Phase)
|
||||
pj := mutators[j].Interceptor.PriorityHint.Resolve(params.Phase)
|
||||
if pi != pj {
|
||||
return pi < pj
|
||||
}
|
||||
return mutators[i].Interceptor.Name < mutators[j].Interceptor.Name
|
||||
})
|
||||
|
||||
cr := &ExecutionResult{
|
||||
Event: params.Event,
|
||||
Phase: params.Phase,
|
||||
Results: make([]interceptors.InvokeResult, 0, len(validators)+len(mutators)),
|
||||
}
|
||||
|
||||
// Empty chain fast path.
|
||||
if len(validators) == 0 && len(mutators) == 0 {
|
||||
cr.Status = ChainSuccess
|
||||
cr.TotalDurationMs = time.Since(start).Milliseconds()
|
||||
return cr, nil
|
||||
}
|
||||
|
||||
// Trust-boundary-aware ordering.
|
||||
switch params.Phase {
|
||||
case interceptors.PhaseRequest:
|
||||
// Request (receiving): validate → mutate
|
||||
c.runValidators(ctx, params, validators, cr)
|
||||
if len(cr.AbortedAt) > 0 {
|
||||
cr.Status = ChainValidationFailed
|
||||
cr.TotalDurationMs = time.Since(start).Milliseconds()
|
||||
return cr, nil
|
||||
}
|
||||
if ctx.Err() != nil {
|
||||
c.timeoutResult(cr, start)
|
||||
return cr, nil
|
||||
}
|
||||
c.runMutators(ctx, params, mutators, cr)
|
||||
if len(cr.AbortedAt) > 0 {
|
||||
cr.Status = ChainMutationFailed
|
||||
cr.TotalDurationMs = time.Since(start).Milliseconds()
|
||||
return cr, nil
|
||||
}
|
||||
|
||||
case interceptors.PhaseResponse:
|
||||
// Response (sending): mutate → validate
|
||||
c.runMutators(ctx, params, mutators, cr)
|
||||
if len(cr.AbortedAt) > 0 {
|
||||
cr.Status = ChainMutationFailed
|
||||
cr.TotalDurationMs = time.Since(start).Milliseconds()
|
||||
return cr, nil
|
||||
}
|
||||
if ctx.Err() != nil {
|
||||
c.timeoutResult(cr, start)
|
||||
return cr, nil
|
||||
}
|
||||
// Validators must see the post-mutation payload.
|
||||
valParams := *params
|
||||
if cr.FinalPayload != nil {
|
||||
valParams.Payload = cr.FinalPayload
|
||||
}
|
||||
c.runValidators(ctx, &valParams, validators, cr)
|
||||
if len(cr.AbortedAt) > 0 {
|
||||
cr.Status = ChainValidationFailed
|
||||
cr.TotalDurationMs = time.Since(start).Milliseconds()
|
||||
return cr, nil
|
||||
}
|
||||
}
|
||||
|
||||
cr.Status = ChainSuccess
|
||||
cr.TotalDurationMs = time.Since(start).Milliseconds()
|
||||
return cr, nil
|
||||
}
|
||||
|
||||
// runValidators invokes all validators in parallel via interceptor/invoke.
|
||||
func (c *Chain) runValidators(
|
||||
ctx context.Context,
|
||||
params *ExecutionParams,
|
||||
validators []ChainEntry,
|
||||
cr *ExecutionResult,
|
||||
) {
|
||||
if len(validators) == 0 {
|
||||
return
|
||||
}
|
||||
|
||||
var (
|
||||
mu sync.Mutex
|
||||
wg sync.WaitGroup
|
||||
)
|
||||
for _, v := range validators {
|
||||
wg.Add(1)
|
||||
go func(v ChainEntry) {
|
||||
defer wg.Done()
|
||||
result := c.callInvoke(ctx, params, v)
|
||||
mu.Lock()
|
||||
c.recordValidation(v, result, cr)
|
||||
mu.Unlock()
|
||||
}(v)
|
||||
}
|
||||
wg.Wait()
|
||||
}
|
||||
|
||||
// recordValidation processes a validator's invoke result and updates the chain result.
|
||||
func (c *Chain) recordValidation(entry ChainEntry, result invokeOutcome, cr *ExecutionResult) {
|
||||
if result.err != nil {
|
||||
c.logger.Warn("validator invoke error",
|
||||
"interceptor", entry.Interceptor.Name,
|
||||
"error", result.err,
|
||||
)
|
||||
cr.Results = append(cr.Results, interceptors.InvokeResult{
|
||||
Interceptor: entry.Interceptor.Name,
|
||||
Type: interceptors.TypeValidation,
|
||||
Phase: cr.Phase,
|
||||
})
|
||||
if !entry.Interceptor.FailOpen {
|
||||
cr.AbortedAt = append(cr.AbortedAt, AbortInfo{
|
||||
Interceptor: entry.Interceptor.Name,
|
||||
Reason: result.err.Error(),
|
||||
Type: AbortValidation,
|
||||
Phase: string(cr.Phase),
|
||||
})
|
||||
}
|
||||
return
|
||||
}
|
||||
|
||||
cr.Results = append(cr.Results, result.result)
|
||||
|
||||
// Tally validation summary and check for abort in a single pass.
|
||||
if result.result.Validation != nil {
|
||||
shouldAbort := entry.Interceptor.Mode != interceptors.ModeAudit && !result.result.Validation.Valid
|
||||
aborted := false
|
||||
for _, msg := range result.result.Validation.Messages {
|
||||
switch msg.Severity {
|
||||
case interceptors.SeverityError:
|
||||
cr.ValidationSummary.Errors++
|
||||
if shouldAbort && !aborted {
|
||||
cr.AbortedAt = append(cr.AbortedAt, AbortInfo{
|
||||
Interceptor: entry.Interceptor.Name,
|
||||
Reason: msg.Message,
|
||||
Type: AbortValidation,
|
||||
Phase: string(cr.Phase),
|
||||
})
|
||||
aborted = true
|
||||
}
|
||||
case interceptors.SeverityWarn:
|
||||
cr.ValidationSummary.Warnings++
|
||||
case interceptors.SeverityInfo:
|
||||
cr.ValidationSummary.Infos++
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// runMutators invokes mutators sequentially via interceptor/invoke,
|
||||
// passing the mutated payload from each mutator to the next.
|
||||
func (c *Chain) runMutators(
|
||||
ctx context.Context,
|
||||
params *ExecutionParams,
|
||||
mutators []ChainEntry,
|
||||
cr *ExecutionResult,
|
||||
) {
|
||||
if len(mutators) == 0 {
|
||||
return
|
||||
}
|
||||
|
||||
currentPayload := params.Payload
|
||||
mutated := false
|
||||
|
||||
for _, m := range mutators {
|
||||
if ctx.Err() != nil {
|
||||
cr.AbortedAt = append(cr.AbortedAt, AbortInfo{
|
||||
Reason: "context cancelled during mutation chain",
|
||||
Type: AbortTimeout,
|
||||
Phase: string(params.Phase),
|
||||
})
|
||||
return
|
||||
}
|
||||
|
||||
// Build invoke params with current payload.
|
||||
mutParams := *params
|
||||
mutParams.Payload = currentPayload
|
||||
|
||||
result := c.callInvoke(ctx, &mutParams, m)
|
||||
|
||||
if result.err != nil {
|
||||
c.logger.Warn("mutator invoke error",
|
||||
"interceptor", m.Interceptor.Name,
|
||||
"error", result.err,
|
||||
)
|
||||
cr.Results = append(cr.Results, interceptors.InvokeResult{
|
||||
Interceptor: m.Interceptor.Name,
|
||||
Type: interceptors.TypeMutation,
|
||||
Phase: params.Phase,
|
||||
})
|
||||
if !m.Interceptor.FailOpen {
|
||||
cr.AbortedAt = append(cr.AbortedAt, AbortInfo{
|
||||
Interceptor: m.Interceptor.Name,
|
||||
Reason: result.err.Error(),
|
||||
Type: AbortMutation,
|
||||
Phase: string(params.Phase),
|
||||
})
|
||||
return
|
||||
}
|
||||
continue
|
||||
}
|
||||
|
||||
cr.Results = append(cr.Results, result.result)
|
||||
|
||||
// For audit-mode mutators, don't apply the mutated payload.
|
||||
if m.Interceptor.Mode == interceptors.ModeAudit {
|
||||
continue
|
||||
}
|
||||
|
||||
// Apply mutated payload for the next mutator.
|
||||
if result.result.Payload != nil {
|
||||
currentPayload = result.result.Payload
|
||||
mutated = true
|
||||
}
|
||||
}
|
||||
|
||||
if mutated {
|
||||
cr.FinalPayload = currentPayload
|
||||
}
|
||||
}
|
||||
|
||||
// invokeOutcome wraps the result of a single interceptor/invoke call.
|
||||
type invokeOutcome struct {
|
||||
result interceptors.InvokeResult
|
||||
err error
|
||||
}
|
||||
|
||||
// callInvoke calls interceptor/invoke on the appropriate server for
|
||||
// a single chain entry.
|
||||
func (c *Chain) callInvoke(
|
||||
ctx context.Context,
|
||||
params *ExecutionParams,
|
||||
entry ChainEntry,
|
||||
) invokeOutcome {
|
||||
invokeParams := &interceptors.InvokeParams{
|
||||
Name: entry.Interceptor.Name,
|
||||
Event: params.Event,
|
||||
Phase: params.Phase,
|
||||
Payload: params.Payload,
|
||||
Context: params.Context,
|
||||
}
|
||||
|
||||
// Apply per-interceptor config if provided.
|
||||
if cfg, ok := params.Config[entry.Interceptor.Name]; ok {
|
||||
invokeParams.Config = cfg
|
||||
}
|
||||
|
||||
var result interceptors.InvokeResult
|
||||
err := entry.Server.CallCustom(ctx, interceptors.MethodInvoke, invokeParams, &result)
|
||||
if err != nil {
|
||||
return invokeOutcome{err: err}
|
||||
}
|
||||
return invokeOutcome{result: result}
|
||||
}
|
||||
|
||||
// timeoutResult sets the chain result to timeout status.
|
||||
func (c *Chain) timeoutResult(cr *ExecutionResult, start time.Time) {
|
||||
cr.Status = ChainTimeout
|
||||
cr.TotalDurationMs = time.Since(start).Milliseconds()
|
||||
cr.AbortedAt = append(cr.AbortedAt, AbortInfo{
|
||||
Reason: "chain execution timeout exceeded",
|
||||
Type: AbortTimeout,
|
||||
Phase: string(cr.Phase),
|
||||
})
|
||||
}
|
||||
|
||||
// matchesPhase checks if an interceptor's configured phase covers the target
|
||||
// phase. An interceptor with PhaseBoth matches any target phase.
|
||||
func matchesPhase(interceptorPhase, targetPhase interceptors.InterceptionPhase) bool {
|
||||
return interceptorPhase == interceptors.PhaseBoth || interceptorPhase == targetPhase
|
||||
}
|
||||
239
go/sdk/interceptors/chain/chain_test.go
Normal file
239
go/sdk/interceptors/chain/chain_test.go
Normal file
|
|
@ -0,0 +1,239 @@
|
|||
// 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 chain_test
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"log/slog"
|
||||
"testing"
|
||||
|
||||
"github.com/modelcontextprotocol/go-sdk/mcp"
|
||||
"github.com/stretchr/testify/assert"
|
||||
"github.com/stretchr/testify/require"
|
||||
|
||||
"github.com/modelcontextprotocol/ext-interceptors/go/sdk/interceptors"
|
||||
"github.com/modelcontextprotocol/ext-interceptors/go/sdk/interceptors/chain"
|
||||
)
|
||||
|
||||
// setupChainWithInterceptors creates an MCP server with the given
|
||||
// interceptors registered via custom methods, connects a chain via
|
||||
// in-memory transport, and returns the chain ready for testing.
|
||||
func setupChainWithInterceptors(t *testing.T, is ...interceptors.Interceptor) *chain.Chain {
|
||||
t.Helper()
|
||||
|
||||
mcpServer := mcp.NewServer(&mcp.Implementation{
|
||||
Name: "chain-test-server",
|
||||
Version: "0.1.0",
|
||||
}, nil)
|
||||
|
||||
// Register interceptors/list and interceptor/invoke handlers.
|
||||
registerInterceptorMethods(mcpServer, is)
|
||||
|
||||
serverTransport, clientTransport := mcp.NewInMemoryTransports()
|
||||
|
||||
ss, err := mcpServer.Connect(context.Background(), serverTransport, nil)
|
||||
require.NoError(t, err)
|
||||
t.Cleanup(func() { ss.Close() })
|
||||
|
||||
client := mcp.NewClient(&mcp.Implementation{
|
||||
Name: "chain-test-client",
|
||||
Version: "0.1.0",
|
||||
}, nil)
|
||||
cs, err := client.Connect(context.Background(), clientTransport, nil)
|
||||
require.NoError(t, err)
|
||||
t.Cleanup(func() { cs.Close() })
|
||||
|
||||
ch := chain.NewChain(chain.WithChainLogger(slog.Default()))
|
||||
err = ch.AddMCPServer(context.Background(), cs)
|
||||
require.NoError(t, err)
|
||||
|
||||
return ch
|
||||
}
|
||||
|
||||
// registerInterceptorMethods adds interceptors/list and interceptor/invoke
|
||||
// custom methods to the server, backed by the given interceptor list.
|
||||
func registerInterceptorMethods(server *mcp.Server, is []interceptors.Interceptor) {
|
||||
server.AddCustomMethod(interceptors.MethodList,
|
||||
func(_ context.Context, _ *mcp.ServerSession, raw json.RawMessage) (any, error) {
|
||||
var params interceptors.ListParams
|
||||
if len(raw) > 0 {
|
||||
if err := json.Unmarshal(raw, ¶ms); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
}
|
||||
infos := make([]interceptors.InterceptorInfo, 0, len(is))
|
||||
for _, i := range is {
|
||||
if params.Event != "" {
|
||||
match := false
|
||||
for _, e := range i.GetMetadata().Hook.Events {
|
||||
if e == params.Event {
|
||||
match = true
|
||||
break
|
||||
}
|
||||
}
|
||||
if !match {
|
||||
continue
|
||||
}
|
||||
}
|
||||
infos = append(infos, interceptors.InfoFromInterceptor(i))
|
||||
}
|
||||
return &interceptors.ListResult{Interceptors: infos}, nil
|
||||
},
|
||||
)
|
||||
|
||||
server.AddCustomMethod(interceptors.MethodInvoke,
|
||||
func(ctx context.Context, _ *mcp.ServerSession, raw json.RawMessage) (any, error) {
|
||||
var params interceptors.InvokeParams
|
||||
if err := json.Unmarshal(raw, ¶ms); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
var target interceptors.Interceptor
|
||||
for _, i := range is {
|
||||
if i.GetMetadata().Name == params.Name {
|
||||
target = i
|
||||
break
|
||||
}
|
||||
}
|
||||
if target == nil {
|
||||
return nil, fmt.Errorf("interceptor %q not found", params.Name)
|
||||
}
|
||||
|
||||
inv := &interceptors.Invocation{
|
||||
Event: params.Event,
|
||||
Phase: params.Phase,
|
||||
Payload: params.Payload,
|
||||
Config: params.Config,
|
||||
Context: params.Context,
|
||||
}
|
||||
|
||||
result := &interceptors.InvokeResult{
|
||||
Interceptor: params.Name,
|
||||
Type: target.GetType(),
|
||||
Phase: params.Phase,
|
||||
}
|
||||
|
||||
switch v := target.(type) {
|
||||
case *interceptors.Validator:
|
||||
vr, err := v.Handler(ctx, inv)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
result.Validation = vr
|
||||
case *interceptors.Mutator:
|
||||
mr, err := v.Handler(ctx, inv)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
result.Mutation = mr
|
||||
result.Payload = mr.Payload
|
||||
}
|
||||
return result, nil
|
||||
},
|
||||
)
|
||||
}
|
||||
|
||||
func TestChain_FailOpenRecordsExecutionResult(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
t.Run("fail-open validator error is recorded", func(t *testing.T) {
|
||||
t.Parallel()
|
||||
failOpenValidator := &interceptors.Validator{
|
||||
Metadata: interceptors.Metadata{
|
||||
Name: "fo-validator",
|
||||
Hook: interceptors.Hook{
|
||||
Events: []string{"test/event"},
|
||||
Phase: interceptors.PhaseRequest,
|
||||
},
|
||||
Mode: interceptors.ModeEnforce,
|
||||
FailOpen: true,
|
||||
},
|
||||
Handler: func(_ context.Context, _ *interceptors.Invocation) (*interceptors.ValidationResult, error) {
|
||||
return nil, fmt.Errorf("transient failure")
|
||||
},
|
||||
}
|
||||
passingValidator := &interceptors.Validator{
|
||||
Metadata: interceptors.Metadata{
|
||||
Name: "passing-validator",
|
||||
Hook: interceptors.Hook{
|
||||
Events: []string{"test/event"},
|
||||
Phase: interceptors.PhaseRequest,
|
||||
},
|
||||
Mode: interceptors.ModeEnforce,
|
||||
},
|
||||
Handler: func(_ context.Context, _ *interceptors.Invocation) (*interceptors.ValidationResult, error) {
|
||||
return &interceptors.ValidationResult{Valid: true}, nil
|
||||
},
|
||||
}
|
||||
|
||||
ch := setupChainWithInterceptors(t, failOpenValidator, passingValidator)
|
||||
|
||||
payload, _ := json.Marshal(map[string]any{"value": "hello"})
|
||||
cr, err := ch.Execute(context.Background(), &chain.ExecutionParams{
|
||||
Event: "test/event",
|
||||
Phase: interceptors.PhaseRequest,
|
||||
Payload: payload,
|
||||
})
|
||||
require.NoError(t, err)
|
||||
|
||||
// Chain should succeed — fail-open doesn't abort.
|
||||
assert.Equal(t, chain.ChainSuccess, cr.Status)
|
||||
assert.Empty(t, cr.AbortedAt)
|
||||
|
||||
// Both interceptors should have a result entry.
|
||||
require.Len(t, cr.Results, 2)
|
||||
})
|
||||
|
||||
t.Run("fail-open mutator error is recorded", func(t *testing.T) {
|
||||
t.Parallel()
|
||||
failOpenMutator := &interceptors.Mutator{
|
||||
Metadata: interceptors.Metadata{
|
||||
Name: "fo-mutator",
|
||||
Hook: interceptors.Hook{
|
||||
Events: []string{"test/event"},
|
||||
Phase: interceptors.PhaseResponse,
|
||||
},
|
||||
Mode: interceptors.ModeEnforce,
|
||||
FailOpen: true,
|
||||
PriorityHint: interceptors.NewPriority(10),
|
||||
},
|
||||
Handler: func(_ context.Context, _ *interceptors.Invocation) (*interceptors.MutationResult, error) {
|
||||
return nil, fmt.Errorf("transient failure")
|
||||
},
|
||||
}
|
||||
passingMutator := &interceptors.Mutator{
|
||||
Metadata: interceptors.Metadata{
|
||||
Name: "passing-mutator",
|
||||
Hook: interceptors.Hook{
|
||||
Events: []string{"test/event"},
|
||||
Phase: interceptors.PhaseResponse,
|
||||
},
|
||||
Mode: interceptors.ModeEnforce,
|
||||
PriorityHint: interceptors.NewPriority(20),
|
||||
},
|
||||
Handler: func(_ context.Context, _ *interceptors.Invocation) (*interceptors.MutationResult, error) {
|
||||
return &interceptors.MutationResult{Modified: false}, nil
|
||||
},
|
||||
}
|
||||
|
||||
ch := setupChainWithInterceptors(t, failOpenMutator, passingMutator)
|
||||
|
||||
payload, _ := json.Marshal(map[string]any{"value": "hello"})
|
||||
cr, err := ch.Execute(context.Background(), &chain.ExecutionParams{
|
||||
Event: "test/event",
|
||||
Phase: interceptors.PhaseResponse,
|
||||
Payload: payload,
|
||||
})
|
||||
require.NoError(t, err)
|
||||
|
||||
// Chain should succeed — fail-open doesn't abort.
|
||||
assert.Equal(t, chain.ChainSuccess, cr.Status)
|
||||
assert.Empty(t, cr.AbortedAt)
|
||||
|
||||
// Both interceptors should have a result entry.
|
||||
require.Len(t, cr.Results, 2)
|
||||
})
|
||||
}
|
||||
39
go/sdk/interceptors/chain/doc.go
Normal file
39
go/sdk/interceptors/chain/doc.go
Normal file
|
|
@ -0,0 +1,39 @@
|
|||
// 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 chain provides the SEP-compliant interceptor chain
|
||||
// orchestrator. It discovers interceptors from MCP servers via
|
||||
// "interceptors/list" and invokes them via "interceptor/invoke",
|
||||
// implementing trust-boundary-aware execution ordering.
|
||||
//
|
||||
// # Execution Model
|
||||
//
|
||||
// [Chain.Execute] filters registered interceptors by event and phase,
|
||||
// separates them into validators and mutators, and runs them in the
|
||||
// SEP-defined order:
|
||||
//
|
||||
// Request phase (untrusted → trusted):
|
||||
//
|
||||
// Validate (parallel) → Mutate (sequential)
|
||||
//
|
||||
// Response phase (trusted → untrusted):
|
||||
//
|
||||
// Mutate (sequential) → Validate (parallel)
|
||||
//
|
||||
// # Usage
|
||||
//
|
||||
// A [Chain] is created with [NewChain] and populated by adding MCP
|
||||
// servers via [Chain.AddMCPServer]:
|
||||
//
|
||||
// chain := chain.NewChain()
|
||||
// chain.AddMCPServer(ctx, clientSession)
|
||||
// mcpServer.AddReceivingMiddleware(
|
||||
// gomiddleware.Middleware(chain),
|
||||
// )
|
||||
//
|
||||
// For convenience, [mcpserver.Server.LocalChain] creates a chain
|
||||
// pre-configured with a local in-process MCP server:
|
||||
//
|
||||
// chain, err := srv.LocalChain(ctx)
|
||||
package chain
|
||||
39
go/sdk/interceptors/chain/result.go
Normal file
39
go/sdk/interceptors/chain/result.go
Normal file
|
|
@ -0,0 +1,39 @@
|
|||
// 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 chain
|
||||
|
||||
// ChainStatus describes the outcome of a full interceptor chain execution.
|
||||
type ChainStatus string
|
||||
|
||||
const (
|
||||
ChainSuccess ChainStatus = "success"
|
||||
ChainValidationFailed ChainStatus = "validation_failed"
|
||||
ChainMutationFailed ChainStatus = "mutation_failed"
|
||||
ChainTimeout ChainStatus = "timeout"
|
||||
)
|
||||
|
||||
// AbortType classifies the reason an interceptor chain was aborted.
|
||||
type AbortType string
|
||||
|
||||
const (
|
||||
AbortValidation AbortType = "validation"
|
||||
AbortMutation AbortType = "mutation"
|
||||
AbortTimeout AbortType = "timeout"
|
||||
)
|
||||
|
||||
// ValidationSummary counts validation outcomes.
|
||||
type ValidationSummary struct {
|
||||
Errors int `json:"errors"`
|
||||
Warnings int `json:"warnings"`
|
||||
Infos int `json:"infos"`
|
||||
}
|
||||
|
||||
// AbortInfo describes where and why a chain was aborted.
|
||||
type AbortInfo struct {
|
||||
Interceptor string `json:"interceptor"`
|
||||
Reason string `json:"reason"`
|
||||
Type AbortType `json:"type"`
|
||||
Phase string `json:"phase,omitempty"` // phase at which the abort occurred
|
||||
}
|
||||
Loading…
Reference in a new issue