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:
Kurt Degiorgio 2026-04-29 15:29:25 +01:00 • committed by GitHub
commit c9900f02ab
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 62908 additions and 19 deletions

View 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
}

View 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, &params); 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, &params); 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)
})
}

View 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

View 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
}