/ 
MCP-Run-0.102
/ MCP::Run::Compress::Filters

NAME

MCP::Run::Compress::Filters - Command Output Compression Reference

VERSION

version 0.102

DESCRIPTION

This document lists all commands that MCP::Run::Compress filters and how they are compressed. Each filter removes noise, truncates verbose output, and limits lines to reduce token count while preserving essential information.

COMMANDS

File System Commands

ls

Long listing format (-l, -la, etc.) is detected automatically from the output. When detected, the filter strips permissions, owner, group, size, date, inode, and device information. Only the file type (d or -) and the filename are preserved.

For non-long listings, common noise directories are filtered: node_modules, .git, .target, .next, .nuxt, .cache, __pycache__, .DS_Store, vendor/bundle.

# Before: drwxr-xr-x 14 getty getty 4096 Apr 24 02:32 .build
# After:  d .build
stat

Strips Device, Inode, and Birth lines.

# Before:
#   Device: 801h/2049d      Inode: 1234567     Links: 1
#   Birth: 2026-03-09 10:00:00.000000000 +0100
# After: (lines removed)
find

Strips permission denied errors and limits results.

df

Truncates columns at 80 characters, limits to 20 lines.

du

Filters out .git and node_modules directories.

Git Commands

git status

Strips branch information, keeps changed/untracked files.

git diff

Strips diff headers (diff --git, index, ---, +++). Keeps actual - and + lines with content.

git diff --stat

Transforms to compact "N+M- filename" format (additions+deletions-filename). Strips summary lines (X files changed, insertions(+), deletions(-)).

# Before:
#  file1.txt | 5 +++ --- 2 deletions(-)
#  file2.rb  | 3 +++ --- 1 deletion(-)
#  2 files changed, 8 insertions(+), 3 deletions(-)
# After:
#  5+2-file1.txt
#  3+1-file2.rb
git log

Shows first 20 and last 10 lines (with total count), strips commit hashes, author, and date noise.

git branch

Strips blank lines, max 30 lines.

git stash

Strips blank lines, max 30 lines.

Build & Compile Commands

make

Strips make[N]: Entering directory, Leaving directory, and Nothing to be done messages.

# On empty output: "make: ok"
gcc, g++

Strips include chain, compiler notes. Keeps errors and warnings.

# Before:
#   In file included from /usr/include/stdio.h:42:
#   main.c:10:5: error: use of undeclared identifier 'foo'
# After:
#   main.c:10:5: error: use of undeclared identifier 'foo'
cargo build

Strips Compiling and Fresh lines. Keeps errors.

cargo test

Strips compilation and running noise. Max 100 lines.

swift build

Short-circuits successful builds to ok (build complete), unless warnings or errors are present.

mix compile

Elixir Mix compiler. Strips Compiling N files, Generated lines.

pio run

PlatformIO build. Strips verbose mode, configuration, LDF, library manager, compiling, linking, building, and size checking messages.

mvn build, gradle

Build system noise stripped, errors preserved.

webpack, esbuild, vite

Bundler/Build tool output condensed.

Container Commands

docker ps, docker images

Truncates columns at 120 characters, max 30 lines.

docker build

Strips build progress (# N [M/N], Step N/M:).

docker run

Strips image pulling and status messages.

kubectl get

Truncates columns at 150 characters, max 50 lines.

kubectl describe

Strips name, namespace, labels, annotations noise. Max 100 lines.

Cloud & Infrastructure Commands

terraform plan, terraform apply

Strips Refreshing state... and progress messages.

tofu plan, tofu validate, tofu init, tofu fmt

OpenTofu variants. Strips tofu-specific noise.

helm install, helm upgrade

Strips NAME, NAMESPACE, STATUS, REVISION, NOTES noise.

ansible-playbook

Strips PLAY/TASK banners, running handlers, and recap headers. Max 100 lines.

docker-compose

Compose service output filtered.

kubectl

K8s CLI output compacted.

gcloud

GCP CLI output filtered.

Package Managers

cpanm

Strips -- Working on, OK, FAIL noise. Shows only essential progress.

cpan

CPAN shell output filtered.

cpm

Perl cpm package manager output filtered.

npm install

Strips added/found packages confirmation and warnings.

yarn, pnpm

Strips Done in..., Resolving completed, Linking completed.

composer install

Strips repository loading, dependency updating, lock file operations.

pip install

Strips Collecting, Downloading, Installing collected packages.

brew install

Package manager output filtered.

poetry install

Python Poetry dependency installer output.

uv sync

Python UV package manager.

System Commands

ps

Truncates columns at 120 characters, max 30 lines.

systemctl status

Strips status bullets (●), Loaded, Main PID lines.

journalctl

Strips -- Reboot --, -- Logs begin at..., -- No entries --. Max 100 lines.

iptables -L

Truncates columns at 150 characters, max 50 lines.

ping

Strips PING header, resolves, and statistics.

rsync

Strips sent/received bytes and total size summary.

netstat

Truncates columns at 150 characters, max 50 lines.

Truncates at 150 characters, max 30-50 lines.

mount

Truncates columns at 200 characters, max 50 lines.

lsblk

Lists block devices in tree format. Truncates at 150 characters, max 50 lines.

blkid

Lists block device attributes. Truncates at 200 characters, max 50 lines.

fail2ban-client

Strips blank lines, max 30 lines.

jira

Strips verbose metadata and CLI option noise.

Development Tools

grep

Truncates lines at 150 characters, max 100 lines.

cat

Strips blank lines, truncates at 500 characters, max 100 lines.

curl

Merges stderr into stdout, strips progress (% Total, Resolving, Connected to, HTTP/... responses).

wget

Strips timestamp, resolving, connecting, length, saving, and progress bar lines.

pytest

Strips coverage and HTML report generation lines.

ollama run

Strips ANSI spinner characters (⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏).

quarto render

Short-circuits on Output created: success to ok (output created). Strips processing, validating, resolving messages.

Version Control Systems

jj

Jujutsu VCS. Strips Hint lines and Working copy now at: messages. Max 30 lines.

shopify theme push, shopify theme pull

Keeps only the last 5 lines (typically the success/failure result).

Other Commands

sops

Secrets management output filtered.

ty

TigerBeetle CLI. Strips zig noise.

yamllint, hadolint, shellcheck

Linter output filtered for essential findings.

jq

JSON processor output handled.

just

Justfile runner output filtered.

mise

DEV tools version manager.

FILTER STAGES

Each filter applies output through this pipeline:

  1. strip_ansi - Removes ANSI escape codes (colors, cursor control)

  2. filter_stderr - Merges stderr into stdout if configured

  3. match_output - Short-circuits on pattern match (e.g., success messages)

  4. transform - Line-by-line transformation (e.g., strip ls permissions)

  5. strip_lines_matching - Removes lines matching regex patterns

  6. keep_lines_matching - Keeps only lines matching patterns

  7. truncate_lines_at - Truncates each line to N characters

  8. head_lines / tail_lines - Keeps first/last N lines

  9. max_lines - Absolute line limit

  10. on_empty - Fallback message when output is empty after filtering

ADDING CUSTOM FILTERS

use MCP::Run::Compress;

my $compressor = MCP::Run::Compress->new;

# Legacy regex-based matching
$compressor->register_filter(
    command => '^my-command\b',
    strip_lines_matching => [
        qr(^\s*$),
        qr(^Verbose:),
    ],
    truncate_lines_at => 100,
    max_lines => 30,
    on_empty => 'my-command: ok',
);

# New parsed_command matching (order-independent flags)
$compressor->register_filter(
    parsed_command => {
        program    => 'my-tool',
        subcommand => 'process',
        flags      => { verbose => 1, output => 1 },
    },
    strip_lines_matching => [qr(^\s*$)],
    max_lines => 50,
);

PARSED COMMAND APPROACH

Filters can use either regex-based command matching (legacy) or the new parsed_command approach. The parsed approach extracts program, subcommand, and flags using Getopt::Long, enabling order-independent flag matching.

# Matches: git diff --stat, git diff --stat -w 5, git -C /path diff --stat
$compressor->register_filter(
    parsed_command => {
        program    => 'git',
        subcommand => 'diff',
        flags      => { stat => 1 },
    },
    transform => sub { ... },
);

The flags hash specifies which flags must be present. Flag values are ignored - only presence matters for matching.

SEE ALSO

MCP::Run::Compress, MCP::Run

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-mcp-run/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.