Purpose
-------
Phase 5A + 5B tool manifest - 20 MCP tools (9 read-only + 11 write)
registered with the :class:`mcp.server.MCPServer` instance. 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.
- Hold ``_TOOL_CALL_LOCK``, the process-wide choke point that keeps the
pipeline single-threaded under MCP SDK v2 (plan 244, P3).
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.
Nothing here raises an SDK error, so a failure reaches the host as a
result and never as a JSON-RPC error (plan 244, P4).
- The :func:`register_tools` function is idempotent for a given
:class:`~mcp.server.MCPServer` instance.
- Tool functions always write one audit record per invocation, even on
policy denial or validation failure.
- MCP SDK v2 dispatches synchronous tool handlers to worker threads and
lets requests overlap. Every call therefore passes through
``_TOOL_CALL_LOCK`` before entering the pipeline, so the rate limiter,
executor, audit logger and metrics behind the server-state singleton
still see one caller at a time (plan 244, P3).
Dependencies
------------
- oct.core.diagnostics (_dbg structured logger)
- oct.mcp.audit (McpAuditRecord and the timestamp and project-root hash helpers for each audit record)
- oct.mcp.safety (SafetyDecision and the confirmation-request text of the write-tool safety gate)
- oct.mcp.server (get_server_state, the shared pipeline instances)
- oct.mcp.validator (validate_tool_args, the Layer 2 argument validation)
- oct.mcp.policy (lazy; TOOL_MANIFEST, the tool spec a write call hands the safety gate)
- mcp (MCPServer, the SDK server the tools register on)
| str oct.mcp.tools._run_tool_write_pipeline |
( |
str | tool_name, |
|
|
dict | raw_args ) |
|
protected |
Run the write pipeline; caller holds ``_TOOL_CALL_LOCK``.
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 291 of file tools.py.
1.15.0