Style And Conventions

General:

Python 3.14, src/ layout, Pydantic v2 where external/boundary validation is useful.
Prefer explicit dataclasses for runtime/internal models and Pydantic for config/wire-ish boundary validation.
Async-first for MCP calls and workflow runtime interactions.
Keep MCP proxy concepts separate from workflow-specific concepts like outcome.
Do not leak workflow-only fields into MCP tools/list.

MCP/proxy conventions:

Transparent proxy mode is the product path; old broker mode is secondary/debug/admin-oriented.
Admin tools live under the reserved namespace wf.mcp_*.
Upstream FastMCP names use Namespace behavior: <connection_id>_<local_tool_name>, e.g. everything.default_echo.
Keep name parsing and unmangling in names.py; do not scatter string slicing across modules.
Keep cursor mechanics in pagination.py; use opaque cursors and nextCursor to mirror MCP pagination style.
Keep config disk writes in config_manager.py; transparent proxy code should expose/administer behavior, not own JSON mutation details.
wf_mcp.config.json is user-owned live config. Do not edit/revert it unless explicitly asked.

Code style:

Use precise type hints and modern Python collection syntax (list[str], dict[str, Any]).
Keep modules layered by responsibility; avoid stuffing everything into service/runtime files.
Prefer small helper modules when behavior becomes a boundary (config_models.py, config_manager.py, proxy_validation.py, names.py, pagination.py).
Validation should fail early with clear errors.
Tests should exercise behavior through public APIs/MCP calls where practical.
For MCP client CallToolResult.structured_content, guard for None in tests before subscripting; use helper assertions where useful.

Editing rules from repo collaboration:

Use apply_patch for manual code edits.
Do not revert user-owned changes.
Direct Serena MCP is available and can be used for semantic navigation/editing; onboarding is already complete.