Pre-shipment review 2026-06-30 — findings tracker

[hrco]

xBridge MCP v3.0.0 — Pre-Shipment Review

Reviewer: pre-shipment-reviewer
Date: 2026-06-30
Scope: usability, security, bugs, code quality, possible upgrades

---

BUG: Chain operations produce garbled output

Severity: High (functional)
File: xbridge_mcp/server.py:1430-1432, xbridge_mcp/tool_chains.py:127-136

Chain step 2 references {last_result} in its template. ToolChain._prepare_arguments resolves it via str() on a CallToolResult MCP object, yielding something like <mcp.types.CallToolResult at 0x...> instead of actual response text.

execute_chain_with_extraction only unwraps CallToolResult after all steps complete — too late for template resolution. All three chain tools are affected:

• grok-chain-search-summarize (step 2 feeds search results into summarizer)
• grok-chain-research (step 3 synthesises web + X results)
• grok-chain-debug (step 2 generates fix from X findings)

Fix: Extract text from each step's CallToolResult before storing in context, or unwrap inside _prepare_arguments.

---

BUG: Version mismatch

Severity: Low
File: xbridge_mcp/__init__.py:11

__version__ = "2.1.0" but pyproject.toml and server.json both say "3.0.0". Breaks __version__ introspection.

---

Security Findings

#	Issue	File	Severity	Detail
S1	Free-limit check is per-process, in-memory	tokenizer.py:71-82	Medium	Restart resets counter. All anonymous users share one bucket (key "anon"). After 50 total calls server-wide, free tier is blocked for everyone.
S2	HTTP key endpoint has no rate limiting	http_server.py:120-144	Medium	/keys/free issues signed Ed25519 license keys with no throttling. LS_SIGNING_SECRET webhook verification is bypassed if env var unset.
S3	Session data at rest in plaintext	session_manager.py	Low	.grok_sessions/*.json stores full conversation history unencrypted. Documented but worth noting for users handling sensitive data.
S4	No input validation on session_id	session_manager.py:204-206	Low	Server-generated UUIDs make path traversal unlikely, but session_id flows directly into file paths for read/delete.
S5	Usage tracker stores truncated API key prefix	token_counter.py:108	Low	First 12 chars of XAI_API_KEY written to .grok_usage/usage.json.

---

Usability & Code Quality

#	Issue	File	Detail
Q1	server.py too large	server.py (~1961 lines)	Violates project convention of small focused functions. Hard to navigate.
Q2	Unpinned dependencies	pyproject.toml:28-29	mcp>=1.0.0, httpx>=0.27.0 — no lockfile. Breaking upstream release could silently break production.
Q3	No conversation history limit	session_manager.py	Unbounded growth of session JSON files. Heavy users accumulate MB per session.
Q4	Template resolution in chains is fragile	tool_chains.py:127-136	str.replace() on {last_result} — if a result contains {step_0_result}, it gets re-replaced. Low probability but fragile.
Q5	No integration tests for chain execution	tests/test_tool_chains.py	Only tests ChainBuilder construction (dataclass setup). No test exercises the full chain through execute_chain_with_extraction.
Q6	No __all__ in __init__.py	__init__.py	from xbridge_mcp import * is a no-op.

---

Recommended Upgrades

1. Split server.py into per-domain handler modules (chat, search, sessions, chains, image/video, docs).
2. Add conversation history pruning — max N messages, TTL-based cleanup, or configurable limit.
3. Add persistent rate limiting — file-backed counters, not in-memory dict that resets on restart.
4. Pin dependency versions — generate a lockfile or switch to exact pins.
5. Add streaming support — MCP SSE transport for chat responses.
6. Expose structured output / JSON mode — Grok models support it; add parameter to grok-chat.
7. Add MCP resource support — currently only tools, no resources (e.g., health, session list).
8. Rate-limit HTTP key endpoints before public launch of the license key infrastructure.
9. Add health check as an MCP resource — currently only available via the separate HTTP server.