ref-mcp-module-organization

MCP Tools Module Organization Guidelines

Scope. This skill applies only to MCP server tool modules under src/deephaven_mcp/mcp_systems_server/_tools/. For commands in the local dhcli CLI under src/deephaven_mcp/cli/_commands/, apply the cli-command-add skill instead — the CLI uses a different framework (click), a different async pattern (@run_async from cli/_async.py), and a different error contract (CliError from cli/_errors.py). Do not transplant patterns between the two.

File Organization Principles

1. Module Cohesion: Each file in _tools/ should contain MCP tools and helpers for a single, well-defined domain (e.g., table operations, session lifecycle, script execution).

2. Helper Function Placement:

   • If used by 1 module → keep it in that module (private with _ prefix).
   • If used by 2 modules → duplicate is acceptable. Promote to _tools/shared.py when a third consumer appears (rule below).
   • If used by 3+ modules → move to _tools/shared.py.

3. Constant Placement:

   • Module-specific constants → keep in that module after imports
   • Shared constants → place in _tools/shared.py or the most relevant module
   • Always include a docstring explaining the constant's purpose
   • Operator-tunable values (timeouts, defaults, thresholds) are not module constants — see the ref-configuration-conventions skill for where they live and how to read them.

4. New MCP Tool Placement:

   • Before creating a new file, check if the tool fits an existing domain
   • Only create a new module if the tool represents a distinct new domain
   • Module size is a consequence of one-domain-per-module, not a target to hit

5. Registering New Tool Modules:

   • CRITICAL: Every tool module must define a register_tools(server: FastMCP) -> None function
   • This function calls server.tool()(tool_fn) for each tool in the module
   • After creating a new module, add a module.register_tools(server) call to _register_tools() in src/deephaven_mcp/mcp_systems_server/_fastmcp.py. Registration is not gated by configuration — every tool module registers unconditionally, so the tool surface is stable and self-describing across all deployment shapes (and matches the static dhcli CLI command tree). A tool that needs a configuration section the deployment lacks self-reports applicability when invoked: it returns an empty result where one is meaningful (e.g. enterprise_systems_status → {"systems": []}) or a structured user-facing error otherwise. The section accessors enforce this — get_enterprise_settings raises EnterpriseNotConfiguredError and get_community_settings/get_community_registry raise CommunityNotConfiguredError (both ConfigurationError subclasses), which each tool's except handler converts to a success=False response. Do not gate registration on multi_config.community/multi_config.enterprise. See _register_tools in mcp_systems_server/_fastmcp.py.