oct.mcp.audit Namespace Reference

Classes
class	McpAuditRecord
class	McpAuditLogger

Functions
None	_dbg (*args, **kwargs)
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
    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.

Function Documentation

_dbg()

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

protected

Definition at line 53 of file audit.py.

Here is the caller graph for this function:

_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 161 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 156 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 74 of file audit.py.

_AUDIT_FILENAME_SUFFIX

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

protected

Definition at line 75 of file audit.py.

_AUDIT_GLOB

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

protected

Definition at line 76 of file audit.py.

_AUDIT_TS_FORMAT

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

protected

Definition at line 71 of file audit.py.

_DEFAULT_AUDIT_DIR

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

protected

Definition at line 79 of file audit.py.

_DEFAULT_AUDIT_FILENAME

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

protected

Definition at line 83 of file audit.py.

MCP_AUDIT_MAX_FILES

int oct.mcp.audit.MCP_AUDIT_MAX_FILES = 20

Definition at line 65 of file audit.py.

MCP_AUDIT_MAX_SIZE_BYTES

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

Definition at line 68 of file audit.py.