MCP tools

The GenLabZ Author MCP server exposes ten tools. Five are read-only and auto-approved; five make AWS API calls or mutate state and require explicit approval.

Auto-approved tools (read-only)

These tools read from disk or session state only — they make no AWS calls and do not modify anything.

`init_project`

Scaffolds the standard project directory layout under the current working directory.

init_project(
    project_id,    # str, required — kebab-case identifier
    title,         # str, required
    purpose,       # str, required — author-facing pedagogical intent
    overview,      # str, required — student-facing introduction (markdown)
    summary,       # str, required — one-liner for catalog cards (~150 chars)
    outcomes,      # list[str], required — learning outcomes (min 1)
    difficulty,    # str, optional — "beginner" | "intermediate" | "advanced"
    duration,      # int, optional — estimated minutes
    tags,          # list[str], optional
    services,      # list[str], optional — AWS service identifiers
) → InitProjectResult

Creates the directory structure and an initial spec.yaml with the provided metadata. Fails without modifying disk if the project directory already exists.

Returns: project path, list of created files, status message.

`get_project_context`

Returns structured context for content generation at project, objective, or step scope.

get_project_context(
    project_id,    # str, required
    scope,         # str, optional — "project" (default) | "objective" | "step"
    objective_id,  # str, required when scope is "objective" or "step"
    step_id,       # str, required when scope is "step"
) → ProjectContext

Scope options:

Scope	Returns
`"project"`	Full spec, all objective contexts, all existing handles, file layout, conventions, and project-scoped generation guidance
`"objective"`	Guidance scoped to the objective; `available_inputs` contains output handle names from all prior objectives
`"step"`	Guidance scoped to the step; `available_inputs` contains output handle names from all prior steps across all prior objectives

The generation_guidance dict in every response includes:

current_phase — "scaffold" / "spec_structure" / "code_generation" / "review", detected from spec completeness and files on disk
next_action — human-readable instruction for what to do next

`validate_project`

Validates the entire project against the spec schema and handle wiring rules.

validate_project(
    project_id,    # str, required
) → ValidationResult

Checks: spec schema, handle naming and prefixes, resource types, dependency ordering, cross-step references, platform config, and file structure.

Returns: errors (blocking), warnings (non-blocking), suggestions. The valid field is true only when errors is empty.

Content-related codes:

Code	Severity	Trigger
`MISSING_STEP_CONTENT`	error	A step has no `instructions` field and no corresponding content file at `content/{objective_id}_{step_id}.md`
`BROKEN_IMAGE_REFERENCE`	warning	A content file references an image that does not exist in `images/`
`UNREFERENCED_IMAGE`	warning	A file in `images/` is not referenced by any content file

`validate_step`

Validates a single step’s output handles and input dependencies. Faster than validate_project for iterative editing.

validate_step(
    project_id,    # str, required
    objective_id,  # str, required
    step_id,       # str, required
) → ValidationResult

Returns an error if the objective or step ID doesn’t exist in the spec.

`review_project`

Comprehensive final check across all code files.

review_project(
    project_id,    # str, required
) → ReviewResult

Checks: Python syntax (ast.parse), function signatures (async def run(session, context, logger)), file completeness (every spec step has solution + evaluation files, every objective has a cleanup file), and orphaned files (code files with no matching spec entry).

Run this as the final gate before testing. It is separate from validate_project so schema validation stays fast during mid-workflow iteration.

Content-related codes:

Code	Severity	Trigger
`INVALID_CALLOUT_TYPE`	warning	A content file uses a callout type other than `NOTE`, `TIP`, `WARNING`, or `IMPORTANT`
`ORPHANED_CONTENT_FILE`	warning	A file in `content/` has no matching scope in the spec (not `overview.md`, `recap.md`, `{objective_id}.md`, or `{objective_id}_{step_id}.md` for an existing step)
`BROKEN_IMAGE_REFERENCE`	warning	A content file references an image that does not exist in `images/`
`EMPTY_CONTENT_FILE`	warning	A content file exists but is blank or whitespace-only

`get_test_session`

Returns current test session state. Creates a session if none exists.

get_test_session(
    project_id,    # str, required
    profile,       # str, optional — AWS profile name
    region,        # str, optional — AWS region
) → TestSession

Returns: resolved handles accumulated across steps, which steps have been tested, results per step, cleanup results per objective.

`get_test_summary`

Returns pre-rendered markdown for test results. Makes no AWS calls and does not mutate state.

get_test_summary(
    project_id,    # str, required
    scope,         # str, required — "last" | "session" | "objective"
    objective_id,  # str, required when scope is "objective"
) → str (markdown)

Scope	Returns
`"last"`	Formatted output for the most recent `test_*` run
`"session"`	Full project progress grid across all objectives
`"objective"`	Single objective’s history across all phases

Call get_test_summary scope=last after every test_* tool call and display the output verbatim.

Approval-required tools (state-changing)

These tools create, read, or delete real AWS resources. They require explicit approval before execution.

`test_solution`

Runs solution code for the specified scope against the author’s AWS account.

test_solution(
    project_id,    # str, required
    scope,         # str, required — "next" | "step OO.SS" | "objective OO" | "all"
    profile,       # str, optional — AWS profile name
    region,        # str, optional — AWS region
) → TestResult

Creates real AWS resources. The test runner stores returned resource handles in the session as generated handles.

`test_evaluation`

Runs evaluation code for the specified scope.

test_evaluation(
    project_id,    # str, required
    scope,         # str, required — "next" | "step OO.SS" | "objective OO" | "all"
    profile,       # str, optional
    region,        # str, optional
) → TestResult

Makes AWS API calls to verify resource configuration. Handles that pass evaluation are promoted from generated to resolved in the session.

`test_cleanup`

Runs cleanup code for the specified scope.

test_cleanup(
    project_id,    # str, required
    scope,         # str, required — "current" | "objective OO" | "all"
    profile,       # str, optional
    region,        # str, optional
) → TestResult

Deletes real AWS resources. scope=current cleans up whichever objectives currently have resources in the session.

Scope reference

Scope value	Applies to	Meaning
`"next"`	solution, evaluation	The next untested step based on session state
`"step OO.SS"`	solution, evaluation	A specific step (e.g. `"step 01.02"`)
`"objective OO"`	solution, evaluation, cleanup	All steps in a specific objective (e.g. `"objective 02"`)
`"current"`	cleanup	Objectives that currently have resources in the session
`"all"`	solution, evaluation, cleanup	All objectives in the project

AWS credentials

The test tools resolve credentials in this order:

Explicit profile and region parameters on the tool call
Project config in config.local.toml under [test]
Default AWS credential chain

Account ID is verified via sts:GetCallerIdentity at session creation.