oct.mcp.tools module

oct.mcp.tools module#

Purpose#

Phase 5A + 5B tool manifest — 20 MCP tools (9 read-only + 11 write) registered with the FastMCP server. Each tool function wires the validated input through the six-layer pipeline: validator → policy → executor → redactor → audit logger. Write tools add a HITL safety gate step between policy and execution.

Responsibilities#

  • Define register_tools() which attaches all 9 Phase 5A tools.

  • Define register_write_tools() which attaches all 11 Phase 5B write tools.

  • Each read tool function follows the six-layer pipeline.

  • Each write tool function follows the same pipeline but calls _run_tool_write() which inserts the safety gate (Layer 2.5) between policy and execution.

Write tool pipeline (HITL gate)#

rate-limiter → policy → validator → safety gate → executor → redactor → audit

Diagnostics#

Domain: MCP Levels:

L2 — lifecycle: tool called, tool returned L3 — request details L4 — deep trace

Contracts#

  • Tool functions never raise for expected error conditions — they return a structured error string that the MCP client sees as tool output.

  • The register_tools() function is idempotent for a given FastMCP instance.

  • Tool functions always write one audit record per invocation, even on policy denial or validation failure.

oct.mcp.tools.register_tools(mcp: FastMCP) → None[source]#

Register all 9 Phase 5A tools with the FastMCP server instance.

Called once during start_server().

oct.mcp.tools.register_write_tools(mcp: FastMCP) → None[source]#

Register all 11 Phase 5B write tools with the FastMCP server instance.

All write tools require the user to confirm with confirm=True before execution proceeds (HITL gate). Without confirmation the tool returns a [oct-mcp requires_confirmation] string describing what would happen.

Called once during start_server().