modelcontextprotocol/experimental-ext-interceptors
Watch
1
0
Fork
You've already forked experimental-ext-interceptors
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Mirror of https://github.com/modelcontextprotocol/experimental-ext-interceptors — Status: Experimental. This repository provides a multi-language reference implementation of the proposed interceptor extension for the Model Context Protocol (MCP), as descr
7 commits 1 branch 0 tags 967 KiB
  • C# 73.8%
  • Go 25.7%
  • TypeScript 0.2%
  • Python 0.2%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Kurt Degiorgio c9900f02ab
 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>
2026-04-29 15:29:25 +01:00
.githooks Implement Go interceptor chain (#4) 2026-04-29 15:29:25 +01:00
.github/workflows Implement Go interceptor chain (#4) 2026-04-29 15:29:25 +01:00
conformance Initial project structure for MCP interceptors (#3) 2026-01-26 17:54:37 +00:00
csharp/sdk C# Implementation (#2) 2026-01-27 23:53:44 +00:00
docs Implement Go interceptor chain (#4) 2026-04-29 15:29:25 +01:00
go/sdk Implement Go interceptor chain (#4) 2026-04-29 15:29:25 +01:00
python/sdk Initial project structure for MCP interceptors (#3) 2026-01-26 17:54:37 +00:00
typescript/sdk Initial project structure for MCP interceptors (#3) 2026-01-26 17:54:37 +00:00
.gitignore Implement Go interceptor chain (#4) 2026-04-29 15:29:25 +01:00
LICENSE Update license from MIT to Apache 2.0 2026-01-23 21:44:11 +00:00
README.md C# Implementation (#2) 2026-01-27 23:53:44 +00:00

README.md

MCP Interceptors (Experimental Extension)

Status: Experimental. This work is for prototyping and feedback only, and is not an accepted or official MCP extension.

This repository provides a multi-language reference implementation of the proposed interceptor extension for the Model Context Protocol (MCP), as described in SEP-1763.

Implementations

Language Directory Package Status
C# csharp/sdk/ ModelContextProtocol.Interceptors In Progress
Go go/sdk/ github.com/modelcontextprotocol/ext-interceptors/go/sdk Planned
Python python/sdk/ mcp-ext-interceptors Planned
TypeScript typescript/sdk/ @ext-modelcontextprotocol/interceptors Planned

CI/CD

This monorepo uses path-based CI workflows to efficiently test only what changes:

How It Works

  1. Language-specific workflows (csharp.yml, python.yml, go.yml, typescript.yml)

    • Only trigger when their language directory or workflow file changes
    • Run all tests, linting, and checks for that language

  2. Status check workflow (status-check.yml)

    • Runs on every PR to verify required checks passed
    • Determines what needs to pass based on which files changed
    • This is the only required check in branch protection

Examples

  • Change python/sdk/file.py → Only Python CI runs → PR requires Python checks to pass
  • Change both Go and TypeScript files → Both CIs run → PR requires both to pass
  • Change only README.md → No language CIs run → PR can merge immediately

Forcing All Checks

To run all language checks regardless of changed files:

  • In a PR: Comment /test all (only works for repo owners/members/collaborators)
  • Manually: Use GitHub Actions UI or CLI to trigger individual workflows

Adding New Required Checks

  1. Add your check to the appropriate language workflow (e.g., python.yml):

    python-security-scan:
  name: "Security Scan"
  runs-on: ubuntu-latest
  steps:
    - name: Run security checks
      run: # your commands here

  2. Update the status check in .github/workflows/status-check.yml:

    const requiredChecks = {
  python: [
    'Python CI / Linting',
    'Python CI / Unit Tests (3.10)',
    // ... existing checks ...
    'Python CI / Security Scan'  // ← Add your new check
  ],

  3. Submit PR - Your new check is now required for all relevant changes!

License

Apache License 2.0 - See LICENSE file for details

Resources