oct.mcp.tools Namespace Reference

Functions
None	_dbg (*args, **kwargs)
str	_run_tool (str tool_name, dict raw_args)
str	_run_tool_write (str tool_name, dict raw_args)
int	_elapsed_ms (float start)
str	_safe_getuser ()
str	_error_response (str message, str tool_name)
None	register_tools (FastMCP mcp)
None	register_write_tools (FastMCP mcp)

Detailed Description

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 :func:`register_tools` which attaches all 9 Phase 5A tools.
- Define :func:`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
  :func:`_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 :func:`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.

Function Documentation

_dbg()

None oct.mcp.tools._dbg ( * args, ** kwargs )

protected

Definition at line 67 of file tools.py.

Here is the caller graph for this function:

_elapsed_ms()

int oct.mcp.tools._elapsed_ms ( float start )

protected

Definition at line 390 of file tools.py.

Here is the caller graph for this function:

_error_response()

str oct.mcp.tools._error_response ( str message, str tool_name )

protected

Return a structured error string visible to the MCP client.

Definition at line 401 of file tools.py.

Here is the caller graph for this function:

_run_tool()

str oct.mcp.tools._run_tool ( str tool_name, dict raw_args )

protected

Execute one tool through the full six-layer pipeline.

This is the single shared entry point called by every tool function.
It handles all error conditions and always writes an audit record.

Parameters
----------
tool_name
    MCP tool name, e.g. ``"oct_lint"``.
raw_args
    Unvalidated dict from the MCP client.

Returns
-------
Redacted tool output string (or a structured error message).

Definition at line 84 of file tools.py.

Here is the call graph for this function:

Here is the caller graph for this function:

_run_tool_write()

str oct.mcp.tools._run_tool_write ( str tool_name, dict raw_args )

protected

Execute one write tool through the HITL-extended pipeline.

Pipeline: rate-limiter → policy → validator → safety gate →
executor → redactor → audit.

When the safety gate requires confirmation (``confirm=False`` in
args), returns a structured ``[oct-mcp requires_confirmation] …``
string without executing anything. The AI host must re-submit with
``confirm=True`` after the user approves.

Parameters
----------
tool_name
    One of the 11 Phase 5B write tool names.
raw_args
    Unvalidated dict from the MCP client.

Returns
-------
Redacted tool output string, a confirmation-required string, or a
structured error message.

Definition at line 221 of file tools.py.

Here is the call graph for this function:

Here is the caller graph for this function:

_safe_getuser()

str oct.mcp.tools._safe_getuser ( )

protected

Definition at line 394 of file tools.py.

Here is the caller graph for this function:

register_tools()

None oct.mcp.tools.register_tools

(

FastMCP

mcp

)

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

Called once during :func:`~oct.mcp.server.start_server`.

Definition at line 411 of file tools.py.

Here is the call graph for this function:

register_write_tools()

None oct.mcp.tools.register_write_tools

(

FastMCP

mcp

)

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 :func:`~oct.mcp.server.start_server`.

Definition at line 569 of file tools.py.

Here is the call graph for this function: