oct.mcp.audit Namespace Reference

Classes
class	McpAuditRecord
class	McpAuditLogger

Functions
str	_utc_now_iso ()
str	_hash_project_root (Path project_root)

Variables
int	MCP_AUDIT_MAX_FILES = 20
int	MCP_AUDIT_MAX_SIZE_BYTES = 5 * 1024 * 1024
str	_AUDIT_TS_FORMAT = "%Y%m%d-%H%M%S"
str	_AUDIT_FILENAME_PREFIX = "mcp-audit-"
str	_AUDIT_FILENAME_SUFFIX = ".jsonl"
str	_AUDIT_GLOB = f"{_AUDIT_FILENAME_PREFIX}*{_AUDIT_FILENAME_SUFFIX}"
Path	_DEFAULT_AUDIT_DIR = Path.home() / ".oct-mcp"
str	_DEFAULT_AUDIT_FILENAME = "audit.log"

Detailed Description

Purpose
-------
JSONL audit logger for the ``oct-mcp`` server. Writes one JSON object per
line to ``~/.oct-mcp/audit.log`` with size-based rotation (5 MB per file)
and count-based pruning (keep the 20 newest files).

Responsibilities
----------------
- Define :class:`McpAuditRecord` - the on-disk schema (blueprint §5.7).
- Implement :class:`McpAuditLogger` with the same rotation/pruning logic
  as :class:`oct.git.audit.AuditLogger`, adapted for the global
  ``~/.oct-mcp/`` path and the richer MCP schema.
- Never log raw ``args`` when ``args_redacted`` is True - callers pass
  the redacted dict; logger serialises whatever it receives.
- Emit diagnostic events via ``_dbg("MCP", ..., level)``.

Diagnostics
-----------
Domain: MCP
Levels:
    L1 - errors: IO failures, serialisation failures
    L2 - lifecycle: file opened/rotated, files pruned
    L3 - (none): lifecycle is reported at L2, per-write detail at L4
    L4 - deep trace: every write() call

Contracts
---------
- This module does not import ``click``, the MCP SDK, or any other
  ``oct.mcp.*`` module (no cycles).
- :meth:`McpAuditLogger.write` must never raise. IO failures are logged
  at level 1 and swallowed - audit logging is observability, not
  correctness.
- Filenames follow ``mcp-audit-YYYYMMDD-HHMMSS.jsonl`` strictly so
  lexical ordering matches chronological ordering for pruning.
- Every :class:`McpAuditRecord` field is JSON-serialisable.

Dependencies
------------
- oct.core.diagnostics (_dbg structured logger)

Function Documentation

_hash_project_root()

str oct.mcp.audit._hash_project_root ( Path project_root )

protected

Return the first 8 hex chars of sha256(str(project_root)).

Definition at line 159 of file audit.py.

_utc_now_iso()

str oct.mcp.audit._utc_now_iso ( )

protected

Return the current UTC time as an ISO 8601 string ending in ``Z``.

Definition at line 154 of file audit.py.

Here is the caller graph for this function:

Variable Documentation

_AUDIT_FILENAME_PREFIX

str oct.mcp.audit._AUDIT_FILENAME_PREFIX = "mcp-audit-"

protected

Definition at line 72 of file audit.py.

_AUDIT_FILENAME_SUFFIX

str oct.mcp.audit._AUDIT_FILENAME_SUFFIX = ".jsonl"

protected

Definition at line 73 of file audit.py.

_AUDIT_GLOB

str oct.mcp.audit._AUDIT_GLOB = f"{_AUDIT_FILENAME_PREFIX}*{_AUDIT_FILENAME_SUFFIX}"

protected

Definition at line 74 of file audit.py.

_AUDIT_TS_FORMAT

str oct.mcp.audit._AUDIT_TS_FORMAT = "%Y%m%d-%H%M%S"

protected

Definition at line 69 of file audit.py.

_DEFAULT_AUDIT_DIR

Path oct.mcp.audit._DEFAULT_AUDIT_DIR = Path.home() / ".oct-mcp"

protected

Definition at line 77 of file audit.py.

_DEFAULT_AUDIT_FILENAME

str oct.mcp.audit._DEFAULT_AUDIT_FILENAME = "audit.log"

protected

Definition at line 81 of file audit.py.

MCP_AUDIT_MAX_FILES

int oct.mcp.audit.MCP_AUDIT_MAX_FILES = 20

Definition at line 63 of file audit.py.

MCP_AUDIT_MAX_SIZE_BYTES

int oct.mcp.audit.MCP_AUDIT_MAX_SIZE_BYTES = 5 * 1024 * 1024

Definition at line 66 of file audit.py.