How atlassian-labs/mcp-compressor works
1. What this repo is
mcp-compressor is a multi-language workspace for compressing MCP tool surfaces. Its core job is to sit between an agent/client and one or more MCP backends, expose a smaller “wrapper” API first, and only fetch full schemas for tools that are actually selected.
2. Top-level architecture
The repository is split into one shared Rust core plus three distribution layers:
- a Rust CLI/binary,
- Python bindings/package,
- TypeScript bindings/package.
The Rust core is the authoritative implementation; the other language surfaces mostly wrap or adapt it.
3. Shared Rust core as the center
crates/mcp-compressor-core contains the main architecture. It owns:
- compression logic,
- MCP server/backend orchestration,
- proxying and routing,
- client generation,
- OAuth/session handling,
- FFI-facing DTOs and interfaces.
This crate is the main boundary where “tool compression” is implemented.
4. Compression subsystem
The compression module defines the compression levels and the transformation engine that reduces verbose MCP tool metadata into compact wrapper tools. The README’s flow matches this: initial tools/list returns a compressed surface, then get_tool_schema retrieves the full schema for a chosen tool, and invoke_tool performs the actual call.
5. Backend/server management
The server module is responsible for discovering and talking to backend MCP servers, caching tool registration, and adapting backend responses into the compressed model. File names like connect, registration, tool_cache, compressed, and dynamic_http_client indicate support for both local subprocess-style servers and remote streamable HTTP MCP endpoints.
6. Proxy/runtime layer
The proxy module is the boundary that exposes the compressed view to a frontend client. It includes auth, routing, registry, and server pieces, which suggests it acts as the runtime façade for “compressed MCP proxy” mode: client requests come in, are routed to the selected backend, and are transformed into the smaller tool surface.
7. CLI and process entrypoint
crates/mcp-compressor is the end-user binary. It is thin compared with the core and mostly wires together argument parsing, runtime setup, and the core proxy/server stack. The CLI is the primary way to run mcp-compressor as a standalone proxy around an existing MCP server or server command.
8. Configuration and topology
The config and app modules define how servers are declared, how command/HTTP backends are described, how paths/options are resolved, and how runtime mode is chosen. This is the boundary where user intent from CLI flags, config files, or SDK builders becomes an executable server topology.
9. Generated clients and code output
The client_gen subsystem produces consumer-facing clients in Python, TypeScript, and CLI form. This is a distinct architecture path from the proxy mode: instead of a generic MCP frontend, the system emits tailored helper code or shell commands that call through the compression/session mechanism.
10. SDKs and FFI boundaries
The ffi module and the mcp-compressor-python / mcp-compressor-node crates expose the same core functionality to Python and Node/TypeScript. The public SDKs in Rust, Python, and TypeScript are aligned around the same concepts: CompressorClient, server definitions, compression levels, invocation, and session/proxy lifecycle.
11. Language-specific packages
The python/mcp-compressor package and typescript/ package are not separate implementations; they are adapters and developer-facing APIs around the shared Rust core. The TypeScript side includes native integration plus bridges for local tools and executable tools, while the Python package exposes similar client/core behavior and CLI entry points.
12. Auth, remote access, and sessions
OAuth and session handling are first-class because the repository supports remote MCP backends and generated clients that need authenticated access. The README’s “local session proxy/token auth” pattern maps to the oauth, session, and proxy-related modules that keep generated clients from needing to spawn a full stdio subprocess.
13. Validation and release boundary
The repo is heavily test-driven with Rust integration tests, Python tests, TypeScript tests, and golden output fixtures for agent-facing behavior. Separate workflow files and scripts prepare releases for Rust, Python, and TypeScript artifacts, which reinforces that this is a single product delivered through three package ecosystems.
14. How to draw the main data flow
A good architecture diagram should show:
- client/agent or generated code on the left,
- mcp-compressor proxy/SDK in the middle,
- one or more MCP backends on the right,
- a compression step between backend tool metadata and the frontend tool surface,
- optional OAuth/session/auth services alongside remote backend access.
The key concept is that metadata is compressed once at the boundary, while tool invocation and schema expansion happen lazily on demand.
Main entry points: lib.rs Core crate · server/mod.rs Server layer · proxy/mod.rs Proxy layer · client_gen/mod.rs Client gen
Components 22
Workspace
Multi-language MCP compressor repository
- MCP backends · One or more backend MCP servers or remote endpoints
- Agent/client · Human or agent consumer that uses the CLI, SDKs, or generated clients
Rust core
Shared implementation and runtime boundary
- Core crate · Authoritative implementation of compression, proxying, and SDK-facing behavior
crates/mcp-compressor-core/src/lib.rs - App runtime · Command parsing, paths, options, and process wiring
crates/mcp-compressor-core/src/app/mod.rs - Topology · Server definitions, backend descriptions, and runtime mode selection
crates/mcp-compressor-core/src/config/topology.rs - Compression · Reduces verbose MCP tool metadata into compact wrapper tools
crates/mcp-compressor-core/src/compression/engine.rs - Server layer · Connects to MCP backends, caches registrations, and serves compressed views
crates/mcp-compressor-core/src/server/mod.rs - Backend connect · Discovers and connects to subprocess or remote MCP backends
crates/mcp-compressor-core/src/server/connect.rs - Tool cache · Stores backend tool registrations and compressed tool state
crates/mcp-compressor-core/src/server/tool_cache.rs - HTTP client · Handles streamable HTTP style backend communication
crates/mcp-compressor-core/src/server/dynamic_http_client.rs - Proxy layer · Exposes the compressed surface to clients and routes requests
crates/mcp-compressor-core/src/proxy/mod.rs - Router · Routes client calls to the selected backend and selected tool
crates/mcp-compressor-core/src/proxy/router.rs - Proxy auth · Coordinates auth and token handling for proxy mode
crates/mcp-compressor-core/src/proxy/auth.rs - OAuth/session · Shared OAuth and session lifecycle for remote access
crates/mcp-compressor-core/src/oauth.rs - Client gen · Produces Python, TypeScript, and CLI-oriented client outputs
crates/mcp-compressor-core/src/client_gen/mod.rs - FFI boundary · DTOs and host-facing interfaces for foreign language bindings
crates/mcp-compressor-core/src/ffi/mod.rs
Distributions
Language-specific packages and CLI surfaces
- CLI binary · End-user command that boots the compressor runtime
crates/mcp-compressor/src/main.rs - Rust SDK · Shared Rust-facing client and helper surface
crates/mcp-compressor-core/src/sdk.rs - Python package · Python adapter package built on the shared Rust core
python/mcp-compressor/mcp_compressor/core.py - TypeScript package · TypeScript adapter package and native bridge built on the shared Rust core
typescript/src/index.ts - Node bridge · Node native integration that forwards into the Rust core
crates/mcp-compressor-node/src/lib.rs - Python bridge · Python-native binding layer over the Rust core
crates/mcp-compressor-python/src/lib.rs
Connections 26
- Agent/client → CLI binary: run · Starts the standalone proxy/runtime
- Agent/client → Rust SDK: use · Consumes the Rust SDK directly
- Agent/client → Python package: use · Consumes the Python package
- Agent/client → TypeScript package: use · Consumes the TypeScript package
- CLI binary → Core crate: wires · Delegates execution to the shared core
- Core crate → App runtime: boots · Initializes command-line and runtime setup
- App runtime → Topology: loads · Resolves declared backends and runtime mode
- Core crate → Compression: compresses · Transforms backend tool metadata into wrapper tools
- Core crate → Server layer: orchestrates · Manages backend connections and compressed serving
- Server layer → Backend connect: connects · Opens backend sessions
- Server layer → Tool cache: caches · Stores tool registrations and compressed metadata
- Backend connect → HTTP client: uses · Talks to remote HTTP backends when needed
- Server layer → MCP backends: proxies to · Sits in front of one or more MCP backends
- Core crate → Proxy layer: exposes · Serves the compressed surface to frontends
- Proxy layer → Router: routes · Dispatches requests to the right backend/tool
- Proxy layer → Proxy auth: secures · Applies auth and token handling
- Proxy auth → OAuth/session: persists · Shares OAuth and session lifecycle state
- Core crate → Client gen: generates · Emits consumer-facing helper clients and commands
- Core crate → FFI boundary: exports · Provides foreign-function interfaces and DTOs
- Rust SDK → Core crate: wraps · Public Rust API over the shared core
- Python package → Python bridge: bridges · Python package loads the native binding layer
- Python bridge → FFI boundary: binds · Calls into the shared FFI surface
- TypeScript package → Node bridge: bridges · TypeScript package loads the native binding layer
- Node bridge → FFI boundary: binds · Calls into the shared FFI surface
- Client gen → Python package: targets · Produces Python-oriented client output
- Client gen → TypeScript package: targets · Produces TypeScript-oriented client output