oct.mcp.validator Namespace Reference

Classes
class	LintArgs
class	HealthArgs
class	SkeletonArgs
class	DepsArgs
class	OctTestArgs
class	TypecheckArgs
class	DiagArgs
class	GitStatusArgs
class	GitCheckArgs
class	FormatArgs
class	DocsArgs
class	ExportSourceArgs
class	NewArgs
class	ScaffoldArgs
class	CleanArgs
class	InstallHooksArgs
class	GitCommitArgs
class	GitHooksInstallArgs
class	GitInitArgs
class	GitChangelogArgs

Functions
bool	is_within_project_root (Path path, Path project_root)
str	check_shell_metacharacters (str value)
str	validate_path_in_project (str path_str, Path|None project_root)
str	_check_str (str v)
list[str]	_check_paths (list[str] paths, ValidationInfo info)
BaseModel	validate_tool_args (str tool_name, dict raw_args, Path|None project_root=None)

Variables
frozenset	_SHELL_METACHARACTERS
re	_SHELL_META_RE
	_LINT_PROFILES = Literal["proto", "compact", "strict"]

Detailed Description

Purpose
-------
Input Validator (Layer 2) for the ``oct-mcp`` six-layer pipeline.
Defines one Pydantic model per MCP tool (9 models for the Phase 5A
read-only tool manifest). All models enforce:

- Unknown-field rejection (``model_config = ConfigDict(extra="forbid")``)
- Integer field clamping via ``ge``/``le`` constraints
- Enum allowlists (e.g. for ``profile``)
- Shell-metacharacter rejection for all string fields
- Path containment enforcement for all ``paths`` fields

Responsibilities
----------------
- Provide :func:`validate_tool_args` as the single entry point: takes a
  tool name and a raw ``dict`` and returns a validated ``BaseModel``
  instance, or raises :class:`pydantic.ValidationError` on failure.
- Define :func:`check_shell_metacharacters` for reuse by tests.
- Define :func:`validate_path_in_project` for reuse by tests.

Diagnostics
-----------
Domain: MCP
Levels:
    L2 - lifecycle: validation outcome
    L3 - (none): the outcome is reported at L2, field values at L4
    L4 - deep trace: individual field values

Contracts
---------
- This module does not import ``click`` or the MCP SDK.
- All models are instantiated with ``model_validate(data, context=context)``
  where ``context`` carries ``{"project_root": Path}``.
- :func:`validate_tool_args` raises ``ValueError`` for unknown tool names
  before Pydantic even runs.
- Shell metacharacters are rejected by a @field_validator applied to
  every ``str`` field in every model via the ``_ShellSafe`` mixin.

Dependencies
------------
- oct.core.diagnostics (_dbg structured logger)
- oct.core.project_root (is_within_project_root, the path containment check)
- oct.git.conventional (lazy; validate_commit_message for the oct_git_commit message)
- pydantic (BaseModel, ConfigDict, Field, field_validator and ValidationInfo for the tool argument models)

Function Documentation

_check_paths()

list[str] oct.mcp.validator._check_paths ( list[str] paths, ValidationInfo info )

protected

Shell-safe + path-containment check for a list of paths.

Definition at line 150 of file validator.py.

Here is the call graph for this function:

Here is the caller graph for this function:

_check_str()

str oct.mcp.validator._check_str ( str v )

protected

Combined: shell-metachar check for a single string value.

Definition at line 145 of file validator.py.

Here is the call graph for this function:

check_shell_metacharacters()

str oct.mcp.validator.check_shell_metacharacters

(

str

value

)

Raise ``ValueError`` if *value* contains any shell metacharacter.

Called by field validators in every model that handles free-form
string input. Never called on boolean or integer fields.

Definition at line 96 of file validator.py.

Here is the caller graph for this function:

is_within_project_root()

bool oct.mcp.validator.is_within_project_root	(	Path	path,
		Path	project_root )

Definition at line 73 of file validator.py.

Here is the caller graph for this function:

validate_path_in_project()

str oct.mcp.validator.validate_path_in_project	(	str	path_str,
		Path | None	project_root )

Validate that *path_str* resolves inside *project_root*.

Relative paths are resolved against *project_root* (not the process
cwd) so that ``"src"`` is interpreted as ``<project_root>/src``.
Absolute paths are resolved as-is.

Raises ``ValueError`` on path traversal attempts. When
``project_root`` is ``None``, the check is skipped (permissive
fallback for contexts where the root is not yet bound).

Definition at line 115 of file validator.py.

Here is the call graph for this function:

Here is the caller graph for this function:

validate_tool_args()

BaseModel oct.mcp.validator.validate_tool_args	(	str	tool_name,
		dict	raw_args,
		Path | None	project_root = None )

Validate *raw_args* against the model for *tool_name*.

Parameters
----------
tool_name
    One of the 20 tool names in the manifest (e.g. ``"oct_lint"``).
raw_args
    Unvalidated dict from the MCP client.
project_root
    Absolute project root path, threaded through to path-containment
    validators via Pydantic's ``model_validate`` context.

Returns
-------
A fully validated Pydantic model instance.

Raises
------
ValueError
    If *tool_name* is not in the tool manifest.
pydantic.ValidationError
    If *raw_args* fails any field validator.

Definition at line 561 of file validator.py.

Variable Documentation

_LINT_PROFILES

oct.mcp.validator._LINT_PROFILES = Literal["proto", "compact", "strict"]

protected

Definition at line 166 of file validator.py.

_SHELL_META_RE

re oct.mcp.validator._SHELL_META_RE

protected

Initial value:

=  re.compile(
    r"[;&|`$><(){}!\\\"']"
)

Definition at line 91 of file validator.py.

_SHELL_METACHARACTERS

frozenset oct.mcp.validator._SHELL_METACHARACTERS

protected

Initial value:

=  frozenset(
    ";&|`$><(){}!\\\"'"
)

Definition at line 86 of file validator.py.