oct.mcp.policy module

oct.mcp.policy module#

Purpose#

Policy Engine (Layer 3) for the oct-mcp six-layer pipeline. Maintains the tool manifest and decides whether a given tool call is permitted under the active MCP profile.

Responsibilities#

  • Define TOOL_MANIFEST mapping tool names to ToolSpec.

  • Define McpPolicy which enforces profile-based rules.

  • Return structured PolicyDecision objects (never raises for policy rejections — callers check the decision).

Diagnostics#

Domain: MCP Levels:

L1 — errors: unknown tool, manifest inconsistency L2 — lifecycle: policy decision L4 — deep trace: profile enforcement details

Contracts#

  • This module does not import click, the MCP SDK, or any other oct.mcp.* module except config.py.

  • McpPolicy.check() never raises for normal policy decisions. Only ValueError is raised for programming errors (e.g. an unknown profile string passed at construction time).

  • In airgapped profile, ALL tool calls are denied regardless of the tool manifest.

  • In strict profile, only tools with auto_approve=True and destructive=False may execute, and repo-level config is ignored.

class oct.mcp.policy.McpPolicy(profile: Literal['default', 'strict', 'airgapped'] = 'default', safe_mode: bool = False)[source]#

Bases: object

Stateless policy engine for the MCP tool manifest.

Parameters:

  • profile – Active MCP profile. One of "default", "strict", or "airgapped".

  • safe_mode – If True, all tool calls are denied regardless of profile. Mirrors McpConfig.safe_mode.

check(tool_name: str) → PolicyDecision[source]#

Check whether tool_name is permitted under the active policy.

Parameters:

tool_name – MCP tool name, e.g. "oct_lint".

Returns:

property profile: Literal['default', 'strict', 'airgapped']#

Active profile name.

oct.mcp.policy.McpProfile#

Valid MCP profile names (independent of git quality-gate profiles).

alias of Literal[‘default’, ‘strict’, ‘airgapped’]

class oct.mcp.policy.PolicyDecision(allowed: bool, decision: str, policy_rule: str, reason: str)[source]#

Bases: object

The result of a McpPolicy.check() call.

allowed#

True iff the tool call should proceed.

Type:

bool

decision#

Human-readable decision string: "allowed", "denied", or "requires_confirmation".

Type:

str

policy_rule#

Short identifier for the rule that produced this decision.

Type:

str

reason#

Human-readable reason (included in audit records and error responses).

Type:

str

allowed: bool#
decision: str#
policy_rule: str#
reason: str#
class oct.mcp.policy.ToolSpec(cli: str, permissions: frozenset[str] = <factory>, destructive: bool = False, auto_approve: bool = True)[source]#

Bases: object

Metadata for one entry in the tool manifest.

cli#

The oct CLI subcommand string (e.g. "lint", "git status").

Type:

str

permissions#

Set of permission tokens required by this tool ("read", "exec"). Phase 5A tools are read-only ({"read"} or {"read", "exec"}).

Type:

frozenset[str]

destructive#

True if the tool can mutate the filesystem. All Phase 5A tools are False; write tools will be True in Phase 5B.

Type:

bool

auto_approve#

True if the tool may execute without explicit user confirmation. All Phase 5A tools are True.

Type:

bool

auto_approve: bool = True#
cli: str#
destructive: bool = False#
permissions: frozenset[str]#