Feat/output length guard rust migration

[prakhar-singh1928]

Closes #145 — Migrate output_length_guard to Rust

Ports the output_length_guard plugin from the pure-Python implementation in
mcp-context-forge to a Rust core with thin PyO3 bindings, following the
established pii_filter pattern. Published as cpex-output-length-guard.

Tracked on the gateway side: IBM/mcp-context-forge#5752

---

What was done

Core migration (a24a944)

• New Rust crate at plugins/rust/python-package/output_length_guard/
• All Python behaviour ported 1:1 — no silent feature changes
• Rust modules: config.rs, guards.rs, structured.rs, plugin.rs
• Thin Python shim at cpex_output_length_guard/output_length_guard.py delegates entirely to the Rust core via PyO3
• plugin-manifest.yaml — hook: tool_post_invoke
• Crate added to workspace Cargo.toml
• tests/test_plugin_catalog.py updated — plugin count 7→8, all expected plugin lists updated in 5 places
• 21 plugin-framework integration tests added in plugins/tests/output_length_guard/test_integration.py
• uv.lock committed for reproducible dev installs

Bug fixes applied during validation

11b4dae — enforce max_structure_size on MCP content lists

• process_mcp_items_result was not checking max_structure_size against the content list length; the check only existed inside process_structured_data (used for structuredContent). Added the guard at the top of process_mcp_items_result, matching the existing behaviour in structured.rs.
• MIN_MAX_STRUCTURE_SIZE lowered from 10 → 1 so that small values (e.g. 2) can be set in config for testing. The unit test updated accordingly (reject 0, not 5).

6dff244 — emit observability metrics for MCP CallToolResult dicts

• handle_mcp_content_dict was modifying the payload but never calling push_metrics_kwargs, so result.metadata["output_length_guard"] was silently absent on every traced tool call whose result was a {"content": [...]} dict — the most common MCP result shape in production.
• process_mcp_items_result return type extended from (Vec, bool) to (Vec, bool, usize, usize) to surface total_chars_seen and items_modified_count without a second pass.
• The old handle_mcp_list tally was iterating out_items (already-truncated dicts) and calling .extract::<String>(), which always failed silently, leaving chars_seen = 0. Both callers now use the accurate counts from the single processing pass.

---

Feature parity

All config options and input shapes from the Python original are implemented.

Config options: min_chars, max_chars, min_tokens, max_tokens, chars_per_token, limit_mode, strategy, ellipsis, word_boundary, max_text_length, max_structure_size, max_recursion_depth

Supported input shapes: plain str, dict with text field, list[str], MCP content array, MCP CallToolResult dict with content list, structuredContent / structured_content recursive processing, type: "resource" item text field guarding

Violation codes: OUTPUT_LENGTH_VIOLATION, OUTPUT_TOKEN_VIOLATION, STRUCTURE_SIZE_VIOLATION, STRUCTURE_DEPTH_VIOLATION

Observability: result.metadata["output_length_guard"] emitted only when extensions.request.trace_id is present — counts and labels only, never raw content.

---

Validation

Check	Result
cargo clippy -p output_length_guard -- -D warnings	✅ PASS
cargo fmt -- --check	✅ PASS
cargo test -p output_length_guard	✅ 63/63 PASS
make test-integration	✅ 21/21 PASS
uv run python3 -m unittest tests.test_plugin_catalog tests.test_install_built_wheel	✅ 126/126 PASS (3 skipped, pre-existing)
uv run python3 tools/plugin_catalog.py validate .	✅ {"status": "ok"}

---

Files changed

Path	Description
plugins/rust/python-package/output_length_guard/	New plugin crate (Rust + Python shim)
plugins/tests/output_length_guard/test_integration.py	21 plugin-framework integration tests
Cargo.toml	Added new crate to workspace members
Cargo.lock	Updated automatically
tests/test_plugin_catalog.py	Plugin count 7→8, all plugin lists updated

---

Next steps (gateway side — IBM/mcp-context-forge#5752)

• Install cpex-output-length-guard>=0.1.0 and update pyproject.toml plugins extra
• Update plugins/config.yaml kind to cpex_output_length_guard.output_length_guard.OutputLengthGuardPlugin
• Add limit_mode, strategy to _SAFE_STRING_FIELD_NAMES and chars_seen, truncated_count to _SAFE_NUMERIC_FIELD_NAMES in mcpgateway/plugins/utils.py
• Remove plugins/output_length_guard/ (Python implementation)
• Tag output-length-guard-v0.1.0 on main to trigger PyPI publish

[lucarlig]

I compared this PR at 30e41b00324dffe533fc83270cfa9d7909e08cb4 against the current Python output_length_guard implementation in mcp-context-forge main at ff1fcc828966e8cf6c1905a4bd189415b6412904, using both source review and differential calls through the real cpex hook models.

There are several observable differences. A difference does not automatically mean the Rust behavior is bad—some may be worthwhile security hardening, stricter validation, or intentional cleanup. However, because #145 asks for a 1:1 port with no silent feature changes, could you please review each difference, make a conscious choice about whether it is acceptable, and then either align the implementation or explicitly document and test the intentional divergence?

Observed differences

1. UTF-8 slicing can raise a panic

   guards.rs::cap_at_max_text_length slices &value[..max_text_length] at an arbitrary byte offset. For example, token mode with max_tokens=1, max_text_length=1000, and a result of "€" * 400 returns "€€€€…" in Python, while the Rust path raises pyo3_runtime.PanicException because byte 1000 splits a character.

2. Oversized MCP arrays bypass individual length guarding in truncate mode

   process_mcp_items_result returns the oversized list unchanged when strategy=truncate, so the item-processing loop below is never reached. With 11 text items, max_structure_size=10, and max_chars=2, Python truncates each "abcdef" to "a…"; Rust returns no modified payload. The comment says individual content is still guarded, but the early return prevents that.

   In block mode, Rust also introduces a top-level STRUCTURE_SIZE_VIOLATION for MCP content arrays, whereas the Python handler does not apply max_structure_size to that top-level MCP array. That hardening may be desirable, but it is a behavioral change to choose explicitly.

3. Violation transport codes are not preserved

   The Python implementation sets mcp_error_code=-32000 and http_status_code=422 on every violation. Rust build_violation does not populate either field. The gateway consumes these fields, so blocked calls can expose a different JSON-RPC code (-32602 fallback rather than -32000), and the generic HTTP exception-handler path can fall back to status 200 because the output-length violation codes are not in PLUGIN_VIOLATION_CODE_MAPPING.

4. Token accounting uses UTF-8 bytes rather than Python Unicode codepoints

   Rust uses str::len() for token estimation, structured token counts, metrics, and some metadata; Python uses len(str). For "é" * 5, chars_per_token=4, and max_tokens=1, Python estimates one token and leaves the result unchanged, while Rust estimates two and truncates it to "éé…". Unicode word-boundary behavior can also differ because some calculations mix byte and character indexes.

5. Legacy result metadata differs

   TextResult::Unchanged currently conflates within-bounds, numeric-exempt, and below-min-in-truncate-mode states. The caller labels all of them within_bounds=true. For a below-min value such as "short" with min_chars=10, Python returns metadata containing within_bounds=false, limit_mode, strategy, truncated=false, and new_length; Rust reports within_bounds=true.

   Other metadata differences include:

   • blocked Rust results omit the Python length/mode/strategy metadata;
   • list[str] results omit Python's per-item items metadata and block-mode violation_index/total_items;
   • numeric strings omit Python's numeric: true marker;
   • structured-content block/modify paths omit several Python metadata fields;
   • Rust reports byte lengths for non-ASCII strings where Python reports codepoint lengths.

6. Configuration validation/defaults differ

   • Python requires max_structure_size >= 10; Rust accepts values down to 1. The Rust integration test using max_structure_size=2 therefore cannot run against the Python implementation.
   • With an empty plugin config, Python defaults max_chars to None (unlimited), while Rust defaults it to 15,000 and truncates longer outputs. Both manifests specify 15,000, but direct/plugin-programmatic construction behaves differently.
   • Pydantic accepts/coerces some values such as numeric strings and common boolean forms that the Rust extractor rejects. Stricter Rust parsing may be preferable, but it is another compatibility choice.

7. Numeric-string exemption is not identical

   Python uses math.isfinite(float(text)); Rust uses text.trim().parse::<f64>(). For example, Python treats "1_000" as numeric and preserves it, while Rust treats it as non-numeric and can block/truncate it. Some Unicode numeric forms differ as well.

8. Additional edge-case output differences

   • An empty list is handled as list[str] in Python and returns metadata={"items": []}; Rust classifies it as unsupported and returns skipped metadata.
   • Structured dictionaries with non-string keys preserve the data in both implementations, but Rust converts the key to an empty path component for violation reporting, so Python may report location 1 while Rust reports root.
   • Unsupported-result metadata differs: Python includes the result type in reason, while Rust emits the generic unsupported_type.

Verification performed

• Rust PR suite: 141 Rust unit tests passed.
• Rust/PyO3 integration suite: 21 tests passed.
• Python reference suite: 326 tests passed.
• Current PR CI is green.

Those suites validate each implementation independently, but they do not currently assert cross-language equivalence. A small table-driven differential suite that invokes both implementations with the same configs/payloads would make the intended compatibility decisions durable. Gateway-level E2E coverage is still tracked separately in IBM/mcp-context-forge#5752.

Again, I am not assuming every difference should be removed. Please make and record the intended choice for each one so consumers know which behaviors are compatibility guarantees and which are intentional changes.

[lucarlig]

Requesting changes because the PR currently claims a 1:1 behavioral port, while the inline threads identify observable compatibility differences. A difference is not automatically bad: some may be desirable hardening or cleanup. Please make a conscious choice for each thread—either align with the Python counterpart, or explicitly document and regression-test the intentional divergence. The earlier consolidated comment contains the differential-test matrix and verification details.

[lucarlig]

[P1] This slices at an arbitrary UTF-8 byte offset. With token mode, max_tokens=1, max_text_length=1000, and "€" * 400, Python returns "€€€€…", while Rust raises pyo3_runtime.PanicException because byte 1000 splits a character. Please use a codepoint/character-boundary-aware cap. This looks like a correctness issue rather than merely a compatibility preference.

[lucarlig]

[P1] In truncate mode this early return passes the entire oversized MCP array through unchanged, so the item-processing loop below never runs despite the comment. With 11 items, max_structure_size=10, and max_chars=2, Python truncates every abcdef to a…; Rust returns no modified payload. Please either continue into individual guarding or explicitly choose and document this bypass behavior.

[lucarlig]

[P2] Applying max_structure_size to a top-level MCP content array in block mode is new behavior: the Python MCP-array handlers do not enforce this structural limit there. The hardening may be desirable, but it is not a 1:1 port. Please consciously retain and document/test it, or align with the Python scope.

[lucarlig]

[P1] The Python implementation sets mcp_error_code=-32000 and http_status_code=422 on every violation, but this builder omits both. The gateway consumes these fields, so blocked requests can change to JSON-RPC -32602; the generic HTTP handler can also fall back to status 200 because these violation codes are not mapped. Please preserve the Python transport codes unless this client-visible change is explicitly accepted.

[lucarlig]

[P2] str::len() counts UTF-8 bytes, while Python len(str) counts Unicode codepoints. For "é" * 5, chars_per_token=4, and max_tokens=1, Python estimates one token and leaves the value unchanged; Rust estimates two and truncates it. The same choice appears in structured token counting and metrics. Byte counting may be intentional, but please choose one semantic consistently and document/test the divergence if retained.

[lucarlig]

[P2] Direct PyO3 extraction is stricter than the Pydantic configuration boundary it replaces. The Python model accepts/coerces values such as max_chars="10", chars_per_token="4", and common boolean forms, while Rust raises TypeError. Strict parsing may be preferable, but please decide whether this is an intentional configuration-compatibility break and document/test it if retained.

[lucarlig]

[P2] Rust f64 parsing does not recognize exactly the same numeric strings as Python float(). For example, Python treats "1_000" as finite numeric content and exempts it, while Rust treats it as non-numeric and can block/truncate it; some Unicode numeric forms also differ. Neither parser is inherently the only correct choice, but please consciously define the numeric-exemption grammar and add parity/intent tests.

[lucarlig]

[P3] This non-empty gate changes the empty-list path. Python's all(isinstance(...)) treats [] as list[str] and returns metadata={"items": []}; Rust classifies it as unsupported/skipped. Please align or explicitly accept and test the new classification.

[lucarlig]

[P3] Non-string dict keys become an empty path component because extraction falls back to "". Python string-formats the key, so a violation under {1: "abcdef"} reports location 1, whereas Rust reports root. The data remains intact, but violation diagnostics differ; please stringify non-string keys or document the narrower key contract.

[lucarlig]

[P3] Python emits reason=unsupported_type_<type name>, while Rust emits only unsupported_type. This is a small metadata difference, but downstream diagnostics can observe it. Please retain the type suffix or explicitly accept/test the simplified reason.

[prakhar-singh1928]

Thanks for the detailed review, Luca. All four blocking issues are resolved. Here's the full picture.

──────────────────────────────────────────────────────────────────────
FIXED — Issues 1–4
──────────────────────────────────────────────────────────────────────

Issue 1 — UTF-8 panic in cap_at_max_text_length
The old &value[..max_text_length] slice is replaced with a snap loop:

while cut > 0 && !value.is_char_boundary(cut) { cut -= 1; }

Regression: cap_at_max_text_length_does_not_panic_on_multibyte_boundary
("€".repeat(400), max_text_length=1000 — byte 1000 falls mid-codepoint;
snap moves it to 999).

Issue 2 — Oversized MCP content list bypassed per-item guarding in truncate mode
The STRUCTURE_SIZE_VIOLATION early-return in process_mcp_items_result is now
gated on strategy == Block only. In truncate mode a warning is logged and the
item loop proceeds so each string is still truncated individually.

Note: the block-mode top-level STRUCTURE_SIZE_VIOLATION for MCP content arrays
is an intentional hardening divergence from the Python implementation (which
does not apply max_structure_size to that array). It is explicitly tested and
kept as a deliberate security choice.

Regressions:

• mcp_content_dict_oversized_list_truncate_mode_still_guards_item_text
  (3 items, max_structure_size=2, max_chars=2: each item text verified ≤ 2 chars)

Issue 3 — Violation transport codes not populated
build_violation now passes mcp_error_code=-32000 and http_status_code=422 on
every PluginViolation, satisfying the gateway contract and avoiding the
-32603 fallback in the exception handler.

Regression: violation_carries_mcp_error_code_and_http_status_code
(asserts both fields equal -32000 / 422 on the returned violation object).

Issue 4 — below_min in truncate mode returned within_bounds=true
TextResult::BelowMin is now a distinct enum variant. handle_text returns it
when below_min && !above_max in truncate mode. handle_plain_string and
handle_text_dict have a dedicated BelowMin arm calling
build_text_meta_dict(..., false) (within_bounds=false). The three other
match sites use BelowMin | Unchanged => and fall through identically.

Regression: below_min_truncate_mode_reports_within_bounds_false
(min_chars=20, input "short": within_bounds=false, no modified_payload).

──────────────────────────────────────────────────────────────────────
INTENTIONAL DIVERGENCES — Issues 5–8 (not changed in this PR)
──────────────────────────────────────────────────────────────────────

These are acknowledged differences that are either deliberate hardening or
out of scope for this PR. Each is explicitly tested so the behaviour is durable.

5 — Token estimation uses chars().count() not byte len()
Rust uses char_count (Unicode codepoints) for limit evaluation and metadata,
matching the intent of max_chars/min_chars. The byte-count path in
estimate_tokens is a known approximation in both implementations.
Will track alignment in a follow-up.

6 — Several result metadata fields absent
(blocked paths, list items, numeric marker, structured-content fields,
byte vs codepoint lengths in metadata)
These are observability-only fields that do not affect gateway routing,
violation codes, or payload modification. Tracked as a follow-up against
the integration test suite.

7 — Config validation / defaults differ
Stricter Rust parsing is preferred over silent Pydantic coercion. The
max_structure_size >= 10 Python minimum is a heuristic guard, not a
security requirement. The empty-config max_chars default difference is
a manifest-layer concern — both manifests specify 15000. Documented.

8 — "1_000" is non-numeric in Rust (trim().parse::()) but numeric in Python
Python's float("1_000") accepting underscore separators is a language quirk.
Rust's stricter parse is preferable — underscore-separated numbers are not
a common MCP output format and should not be exempt from length guarding.
Documented.