074dc6cdbd## Summary - Rename `interceptors/mcpserver/` → `interceptors/extension/`, replacing the `Server` wrapper with a lightweight `Extension` that can install itself on any `*mcp.Server` - Remove the stored `*mcp.Server` field — `Extension` is now a pure interceptor container with no server reference - Add `Install(server)` method to register JSON-RPC methods and init middleware on a given server - Update `LocalChain(ctx)` → `LocalChain(ctx, server)` to accept the server as a parameter - Remove `MCPServer()`, `Run()`, and `NewStreamableHTTPHandler()` wrapper methods — users interact with `mcp.Server` directly - Update all examples, tests, and documentation to use the new API ## Why `mcpserver.Server` pretended to *be* the server — it had `Run()`, `NewStreamableHTTPHandler()`, etc. — but it could never cover the full `*mcp.Server` API, so users constantly needed `MCPServer()` to unwrap it. `Extension` doesn't pretend to be the server. It's a pure interceptor container that can install itself on any server (or multiple servers) on the fly. No stored server reference, no wrapping, no delegation surface to maintain. ### Before ```go mcpServer := mcp.NewServer(...) srv := mcpserver.NewServer(mcpServer) srv.AddInterceptor(v) chain, err := srv.LocalChain(ctx) ``` ### After ```go mcpServer := mcp.NewServer(...) ext := extension.New() ext.AddInterceptor(v) ext.Install(mcpServer) chain, err := ext.LocalChain(ctx, mcpServer) ``` Signed-off-by: Kurt Degiorgio <kdegiorgio@bloomberg.net>
150 lines
5.8 KiB
Go
150 lines
5.8 KiB
Go
// 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 defines the core types for the MCP interceptor
|
|
// framework: interceptor descriptors ([Validator], [Mutator]), wire
|
|
// protocol types ([InvokeParams], [InvokeResult]), result types
|
|
// ([ValidationResult], [MutationResult]), and supporting enums.
|
|
//
|
|
// This package is transport-agnostic — it has no dependency on the
|
|
// MCP SDK's server or client types. The chain orchestrator lives in
|
|
// the [interceptors/chain] sub-package, MCP server integration in
|
|
// [interceptors/extension], and middleware in
|
|
// [interceptors/integrations/gomiddleware].
|
|
//
|
|
// # Usage with MCP
|
|
//
|
|
// Create an [extension.Extension], register interceptors, install on
|
|
// an [mcp.Server], then use [extension.Extension.LocalChain] to get a
|
|
// chain for middleware:
|
|
//
|
|
// ext := extension.New()
|
|
// ext.AddInterceptor(myValidator)
|
|
// ext.AddInterceptor(myMutator)
|
|
// ext.Install(mcpServer)
|
|
//
|
|
// chain, err := ext.LocalChain(ctx, mcpServer)
|
|
// mcpServer.AddReceivingMiddleware(
|
|
// gomiddleware.Middleware(chain),
|
|
// )
|
|
//
|
|
// # Validators
|
|
//
|
|
// A [Validator] inspects the payload and decides whether the request
|
|
// or response should proceed. All validators for a given event run
|
|
// in parallel. If any validator in enforced mode ([ModeEnforce])
|
|
// returns an error-severity message, the chain aborts before any
|
|
// mutators run. Only error-severity messages cause an abort; warn
|
|
// and info findings are recorded in the chain execution result but
|
|
// do not block the chain.
|
|
//
|
|
// Interceptor handlers receive [json.RawMessage] payloads when
|
|
// invoked via interceptor/invoke:
|
|
//
|
|
// v := &interceptors.Validator{
|
|
// Metadata: interceptors.Metadata{
|
|
// Name: "block-dangerous-tool",
|
|
// Hook: interceptors.Hook{
|
|
// Events: []string{"tools/call"},
|
|
// Phase: interceptors.PhaseRequest,
|
|
// },
|
|
// Mode: interceptors.ModeEnforce,
|
|
// },
|
|
// Handler: func(ctx context.Context, inv *interceptors.Invocation) (*interceptors.ValidationResult, error) {
|
|
// raw := inv.Payload.(json.RawMessage)
|
|
// var params struct{ Name string `json:"name"` }
|
|
// json.Unmarshal(raw, ¶ms)
|
|
// // inspect params ...
|
|
// return &interceptors.ValidationResult{Valid: true}, nil
|
|
// },
|
|
// }
|
|
//
|
|
// # Mutators
|
|
//
|
|
// A [Mutator] transforms the payload. Mutators run sequentially in
|
|
// priority order (see [Priority]). Each mutator receives the payload
|
|
// as [json.RawMessage], unmarshals it, modifies it, and sets the
|
|
// updated JSON back on inv.Payload. If any mutator fails (and is not
|
|
// configured with FailOpen), the chain aborts. FailOpen mutators
|
|
// record an [InvokeResult] (with the error captured) for
|
|
// observability but do not block.
|
|
//
|
|
// m := &interceptors.Mutator{
|
|
// Metadata: interceptors.Metadata{
|
|
// Name: "redact-pii",
|
|
// Hook: interceptors.Hook{
|
|
// Events: []string{"tools/call"},
|
|
// Phase: interceptors.PhaseResponse,
|
|
// },
|
|
// Mode: interceptors.ModeEnforce,
|
|
// },
|
|
// Handler: func(ctx context.Context, inv *interceptors.Invocation) (*interceptors.MutationResult, error) {
|
|
// raw := inv.Payload.(json.RawMessage)
|
|
// var result map[string]any
|
|
// json.Unmarshal(raw, &result)
|
|
// // modify result ...
|
|
// data, _ := json.Marshal(result)
|
|
// return &interceptors.MutationResult{Modified: true, Payload: data}, nil
|
|
// },
|
|
// }
|
|
//
|
|
// # Execution Order
|
|
//
|
|
// The chain execution order depends on direction:
|
|
//
|
|
// Request phase (untrusted → trusted):
|
|
//
|
|
// Validate (parallel) → Mutate (sequential)
|
|
//
|
|
// Response phase (trusted → untrusted):
|
|
//
|
|
// Mutate (sequential) → Validate (parallel)
|
|
//
|
|
// Validators act as a security gate on the trust boundary side,
|
|
// while mutators prepare or sanitize data on the other side.
|
|
//
|
|
// # Modes and FailOpen
|
|
//
|
|
// Each interceptor has a [Mode] that controls what happens with
|
|
// successful results, and a FailOpen flag that controls what happens
|
|
// when the handler returns a Go error. These are orthogonal:
|
|
//
|
|
// - [ModeEnforce]: fully enforced — validation failures block,
|
|
// mutations are applied.
|
|
// - [ModeAudit]: the handler runs and results are recorded, but
|
|
// validation findings do not block and mutated payloads are
|
|
// not propagated to subsequent interceptors.
|
|
//
|
|
// FailOpen (default false) controls crash resilience:
|
|
//
|
|
// - FailOpen=false: a handler error aborts the chain. An
|
|
// [InvokeResult] and a [chain.AbortInfo] are both recorded.
|
|
// - FailOpen=true: a handler error is logged and an
|
|
// [InvokeResult] is recorded, but the chain continues.
|
|
//
|
|
// Note that [ModeAudit] does NOT imply FailOpen. Audit mode only
|
|
// suppresses enforcement of successful results (validation findings
|
|
// and mutations). If the handler itself returns an error and
|
|
// FailOpen is false, the chain still aborts. For truly safe
|
|
// observation-only interceptors, set both ModeAudit and FailOpen:
|
|
//
|
|
// Metadata: interceptors.Metadata{
|
|
// Mode: interceptors.ModeAudit,
|
|
// FailOpen: true,
|
|
// }
|
|
//
|
|
// Behavior matrix for validators:
|
|
//
|
|
// Mode=Enforce, FailOpen=false → error aborts, Valid=false+SeverityError aborts
|
|
// Mode=Enforce, FailOpen=true → error continues, Valid=false+SeverityError aborts
|
|
// Mode=Audit, FailOpen=false → error aborts, findings recorded only
|
|
// Mode=Audit, FailOpen=true → error continues, findings recorded only
|
|
//
|
|
// Behavior matrix for mutators:
|
|
//
|
|
// Mode=Enforce, FailOpen=false → error aborts, mutations applied
|
|
// Mode=Enforce, FailOpen=true → error continues, mutations applied
|
|
// Mode=Audit, FailOpen=false → error aborts, mutations not propagated
|
|
// Mode=Audit, FailOpen=true → error continues, mutations not propagated
|
|
package interceptors
|