Metadata-Version: 2.4
Name: mcp-compressor
Version: 0.16.0
Summary: Rust-backed experimental Python package for mcp-compressor.
Author-email: Tim Esler <tesler@atlassian.com>
Requires-Python: >=3.11, <4.0
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://atlassian-labs.github.io/mcp-compressor/
Project-URL: Repository, https://github.com/atlassian-labs/mcp-compressor

# mcp-compressor Python SDK

Python SDK and CLI wrapper for `mcp-compressor`.

The public Python import is `mcp_compressor`:

```python
from mcp_compressor import CompressorClient
```

## Quick start

The primary SDK object is `CompressorClient`. It starts a local Rust-backed proxy in-process and returns a `CompressorProxy`; no `mcp-compressor` stdio subprocess is required.

```python
from mcp_compressor import CompressorClient

servers = {
    "alpha": {
        "command": "python",
        "args": ["alpha_server.py"],
    },
    "atlassian": {
        "url": "https://mcp.atlassian.com/v1/mcp",
    },
}

with CompressorClient(
    servers=servers,
    mode="compressed",
    compression_level="medium",
    include_tools=["getConfluencePage", "updateConfluencePage"],
    toonify=True,
) as proxy:
    print([tool.name for tool in proxy.tools])
    result = proxy.invoke(
        "getAccessibleAtlassianResources",
        {},
        server="atlassian",
    )
    print(result)
```

## Modes

`CompressorClient` accepts these modes:

- `compressed` — expose compressed wrapper tools such as `<server>_get_tool_schema` and `<server>_invoke_tool`.
- `cli` — expose CLI/help transform metadata through the shared Rust runtime.
- `bash` — expose Just Bash provider metadata through the shared Rust runtime.

Generated Python and TypeScript clients are produced with `proxy.write_client(...)` rather than by selecting a long-lived session mode.

## Just Bash metadata

Just Bash mode exposes the compressed proxy bridge plus typed provider metadata. Language hosts can use this metadata to register backend MCP tools as Just Bash commands without the Rust runtime executing shell commands itself:

```python
from mcp_compressor import CompressorClient, create_just_bash_commands

with CompressorClient(servers=servers, mode="bash") as proxy:
    commands = {cmd.command_name: cmd for cmd in create_just_bash_commands(proxy)}
    print(commands["atlassian_get-accessible-atlassian-resources"]([]))
```

Duplicate backend command names are prefixed with the provider name, for example `alpha_echo` and `beta_echo`.

## Generated clients

A connected proxy can write shell, Python, or TypeScript clients that call the live proxy:

```python
with CompressorClient(servers=servers, compression_level="max") as proxy:
    proxy.write_client("cli", "./bin", name="atlassian")
    proxy.write_client("python", "./generated-py", name="atlassian")
    proxy.write_client("typescript", "./generated-ts", name="atlassian")
```

## Packaging smoke test

Build a local wheel and verify it imports from a clean virtualenv:

```bash
uvx maturin build --release --out dist
python -m venv /tmp/mcp-compressor-wheel-test
/tmp/mcp-compressor-wheel-test/bin/python -m pip install "$PWD"/dist/*.whl
cd /tmp
/tmp/mcp-compressor-wheel-test/bin/python -c "from mcp_compressor import CompressorClient, ToolSpec"
```

CI runs the same kind of wheel smoke test before uploading the built wheel as an artifact.

## Advanced helpers

Low-level helpers such as `compress_tool_listing`, `parse_tool_argv`, and `ToolSpec` remain available for tests and advanced integrations, but the primary SDK entry point is `CompressorClient`.

