# atlassian-labs/mcp-compressor architecture

> Architecture diagram of the GitHub repository atlassian-labs/mcp-compressor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/atlassian-labs/mcp-compressor
- Repository: https://github.com/atlassian-labs/mcp-compressor

## Overview

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: [`crates/mcp-compressor-core/src/lib.rs`](https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/lib.rs) (Core crate), [`crates/mcp-compressor-core/src/server/mod.rs`](https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/server/mod.rs) (Server layer), [`crates/mcp-compressor-core/src/proxy/mod.rs`](https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/proxy/mod.rs) (Proxy layer), [`crates/mcp-compressor-core/src/client_gen/mod.rs`](https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/client_gen/mod.rs) (Client gen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace"]
  node_external_backends[("MCP backends<br/>External MCP servers")]
  node_agent_client(("Agent/client<br/>Consumer"))
end

subgraph group_rust_core["Rust core"]
  node_core_lib["Core crate<br/>Rust library<br/>[lib.rs]"]
  node_app_runtime["App runtime<br/>Runtime setup<br/>[mod.rs]"]
  node_config_topology["Topology<br/>Config model<br/>[topology.rs]"]
  node_compression_engine{{"Compression<br/>Transform engine<br/>[engine.rs]"}}
  node_server_layer["Server layer<br/>Backend orchestration<br/>[mod.rs]"]
  node_backend_connect["Backend connect<br/>Backend adapter<br/>[connect.rs]"]
  node_tool_cache[("Tool cache<br/>Registry cache<br/>[tool_cache.rs]")]
  node_dynamic_http_client["HTTP client<br/>Remote transport"]
  node_proxy_layer["Proxy layer<br/>Runtime façade<br/>[mod.rs]"]
  node_proxy_router["Router<br/>Request routing<br/>[router.rs]"]
  node_proxy_auth["Proxy auth<br/>Auth boundary<br/>[auth.rs]"]
  node_oauth_session(("OAuth/session<br/>Auth state<br/>[oauth.rs]"))
  node_client_gen["Client gen<br/>Code generation<br/>[mod.rs]"]
  node_ffi_boundary["FFI boundary<br/>Interop layer<br/>[mod.rs]"]
end

subgraph group_distributions["Distributions"]
  node_cli_bin["CLI binary<br/>Rust entrypoint<br/>[main.rs]"]
  node_rust_sdk["Rust SDK<br/>Public API<br/>[sdk.rs]"]
  node_python_pkg["Python package<br/>Python binding<br/>[core.py]"]
  node_typescript_pkg["TypeScript package<br/>TypeScript binding<br/>[index.ts]"]
  node_node_bridge["Node bridge<br/>Native bridge<br/>[lib.rs]"]
  node_python_bridge["Python bridge<br/>Native bridge<br/>[lib.rs]"]
end

node_agent_client -->|"run"| node_cli_bin
node_agent_client -->|"use"| node_rust_sdk
node_agent_client -->|"use"| node_python_pkg
node_agent_client -->|"use"| node_typescript_pkg
node_cli_bin -->|"wires"| node_core_lib
node_core_lib -->|"boots"| node_app_runtime
node_app_runtime -->|"loads"| node_config_topology
node_core_lib -->|"compresses"| node_compression_engine
node_core_lib -->|"orchestrates"| node_server_layer
node_server_layer -->|"connects"| node_backend_connect
node_server_layer -->|"caches"| node_tool_cache
node_backend_connect -->|"uses"| node_dynamic_http_client
node_server_layer -->|"proxies to"| node_external_backends
node_core_lib -->|"exposes"| node_proxy_layer
node_proxy_layer -->|"routes"| node_proxy_router
node_proxy_layer -->|"secures"| node_proxy_auth
node_proxy_auth -->|"persists"| node_oauth_session
node_core_lib -->|"generates"| node_client_gen
node_core_lib -->|"exports"| node_ffi_boundary
node_rust_sdk -->|"wraps"| node_core_lib
node_python_pkg -->|"bridges"| node_python_bridge
node_python_bridge -->|"binds"| node_ffi_boundary
node_typescript_pkg -->|"bridges"| node_node_bridge
node_node_bridge -->|"binds"| node_ffi_boundary
node_client_gen -->|"targets"| node_python_pkg
node_client_gen -->|"targets"| node_typescript_pkg

click node_cli_bin "https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor/src/main.rs"
click node_core_lib "https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/lib.rs"
click node_app_runtime "https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/app/mod.rs"
click node_config_topology "https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/config/topology.rs"
click node_compression_engine "https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/compression/engine.rs"
click node_server_layer "https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/server/mod.rs"
click node_backend_connect "https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/server/connect.rs"
click node_tool_cache "https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/server/tool_cache.rs"
click node_dynamic_http_client "https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/server/dynamic_http_client.rs"
click node_proxy_layer "https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/proxy/mod.rs"
click node_proxy_router "https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/proxy/router.rs"
click node_proxy_auth "https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/proxy/auth.rs"
click node_oauth_session "https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/oauth.rs"
click node_client_gen "https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/client_gen/mod.rs"
click node_ffi_boundary "https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/ffi/mod.rs"
click node_rust_sdk "https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/sdk.rs"
click node_python_pkg "https://github.com/atlassian-labs/mcp-compressor/blob/main/python/mcp-compressor/mcp_compressor/core.py"
click node_typescript_pkg "https://github.com/atlassian-labs/mcp-compressor/blob/main/typescript/src/index.ts"
click node_node_bridge "https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-node/src/lib.rs"
click node_python_bridge "https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-python/src/lib.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_external_backends,node_agent_client toneBlue
class node_core_lib,node_app_runtime,node_config_topology,node_compression_engine,node_server_layer,node_backend_connect,node_tool_cache,node_dynamic_http_client,node_proxy_layer,node_proxy_router,node_proxy_auth,node_oauth_session,node_client_gen,node_ffi_boundary toneAmber
class node_cli_bin,node_rust_sdk,node_python_pkg,node_typescript_pkg,node_node_bridge,node_python_bridge toneMint
```

## Components

### Workspace

Multi-language MCP compressor repository

- **MCP backends**: External MCP servers · One or more backend MCP servers or remote endpoints
- **Agent/client**: Consumer · Human or agent consumer that uses the CLI, SDKs, or generated clients

### Rust core

Shared implementation and runtime boundary

- [Core crate](https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/lib.rs): Rust library · Authoritative implementation of compression, proxying, and SDK-facing behavior · `crates/mcp-compressor-core/src/lib.rs`
- [App runtime](https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/app/mod.rs): Runtime setup · Command parsing, paths, options, and process wiring · `crates/mcp-compressor-core/src/app/mod.rs`
- [Topology](https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/config/topology.rs): Config model · Server definitions, backend descriptions, and runtime mode selection · `crates/mcp-compressor-core/src/config/topology.rs`
- [Compression](https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/compression/engine.rs): Transform engine · Reduces verbose MCP tool metadata into compact wrapper tools · `crates/mcp-compressor-core/src/compression/engine.rs`
- [Server layer](https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/server/mod.rs): Backend orchestration · Connects to MCP backends, caches registrations, and serves compressed views · `crates/mcp-compressor-core/src/server/mod.rs`
- [Backend connect](https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/server/connect.rs): Backend adapter · Discovers and connects to subprocess or remote MCP backends · `crates/mcp-compressor-core/src/server/connect.rs`
- [Tool cache](https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/server/tool_cache.rs): Registry cache · Stores backend tool registrations and compressed tool state · `crates/mcp-compressor-core/src/server/tool_cache.rs`
- [HTTP client](https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/server/dynamic_http_client.rs): Remote transport · Handles streamable HTTP style backend communication · `crates/mcp-compressor-core/src/server/dynamic_http_client.rs`
- [Proxy layer](https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/proxy/mod.rs): Runtime façade · Exposes the compressed surface to clients and routes requests · `crates/mcp-compressor-core/src/proxy/mod.rs`
- [Router](https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/proxy/router.rs): Request routing · Routes client calls to the selected backend and selected tool · `crates/mcp-compressor-core/src/proxy/router.rs`
- [Proxy auth](https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/proxy/auth.rs): Auth boundary · Coordinates auth and token handling for proxy mode · `crates/mcp-compressor-core/src/proxy/auth.rs`
- [OAuth/session](https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/oauth.rs): Auth state · Shared OAuth and session lifecycle for remote access · `crates/mcp-compressor-core/src/oauth.rs`
- [Client gen](https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/client_gen/mod.rs): Code generation · Produces Python, TypeScript, and CLI-oriented client outputs · `crates/mcp-compressor-core/src/client_gen/mod.rs`
- [FFI boundary](https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/ffi/mod.rs): Interop layer · 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](https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor/src/main.rs): Rust entrypoint · End-user command that boots the compressor runtime · `crates/mcp-compressor/src/main.rs`
- [Rust SDK](https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-core/src/sdk.rs): Public API · Shared Rust-facing client and helper surface · `crates/mcp-compressor-core/src/sdk.rs`
- [Python package](https://github.com/atlassian-labs/mcp-compressor/blob/main/python/mcp-compressor/mcp_compressor/core.py): Python binding · Python adapter package built on the shared Rust core · `python/mcp-compressor/mcp_compressor/core.py`
- [TypeScript package](https://github.com/atlassian-labs/mcp-compressor/blob/main/typescript/src/index.ts): TypeScript binding · TypeScript adapter package and native bridge built on the shared Rust core · `typescript/src/index.ts`
- [Node bridge](https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-node/src/lib.rs): Native bridge · Node native integration that forwards into the Rust core · `crates/mcp-compressor-node/src/lib.rs`
- [Python bridge](https://github.com/atlassian-labs/mcp-compressor/blob/main/crates/mcp-compressor-python/src/lib.rs): Native bridge · Python-native binding layer over the Rust core · `crates/mcp-compressor-python/src/lib.rs`

## Connections

- 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
