MCP authoring wizard, corpus index, and contract alignment

This document describes the deterministic authoring wizard (tooling/ainl_get_started.py), related MCP tools and resources in scripts/ainl_mcp_server.py, the mined strict-valid family index under corpus/, and how ArmaraOS surfaces wizard progress in the system prompt and graph memory.

Ground truth in code: tooling/ainl_get_started.py (state machine, ADAPTER_CONTRACTS, step examples), scripts/ainl_mcp_server.py (MCP tools, contract_validation_status / contract_alignment), tooling/corpus_mining.py (regenerate corpus/strict_valid_family_index.json).

ArmaraOS: crates/openfang-runtime/src/mcp_ainl_session.rs (session cache, wizard hint text, graph tag mcp:ainl:wizard_state), graph_memory_learning.rs (when to persist wizard facts), prompt_builder.rs (PromptContext.mcp_ainl_wizard_state_hint). Host doc: armaraos/docs/mcp-a2a.md (AINL MCP digest).

MCP tools (authoring)

| Tool | Role | |------|------| | ainl_get_started | Maps a natural-language goal to a wizard payload (wizard_state, checkpoints, recommended_next_tools, etc.). Pass wizard_state_json (string) on follow-up calls to continue the same session. | | ainl_step_examples | Returns snippet examples and optional strict-valid corpus paths for a step or topic (request_examples_for, e.g. http, fs, queue) without advancing wizard state. Response includes ok: true and schema_version. | | ainl_adapter_contract | Per-adapter contract slice (complements ainl://adapter-contracts). | | ainl_validate / ainl_compile | On successful graph compile, include contract_validation_status and contract_alignment (see below). |

MCP resources (corpus and cheatsheets)

| URI | Content | |-----|---------| | ainl://strict-valid-examples | JSON list of paths from tooling/artifact_profiles.json → strict-valid (CI-checked templates). | | ainl://strict-valid-families | JSON from corpus/strict_valid_family_index.json: adapter families and example paths grouped for wizard / classifier fixtures. Generated by tooling/corpus_mining.py (see Regenerating the family index). | | ainl://adapter-contracts, ainl://strict-authoring-cheatsheet, … | Unchanged; see AGENTS.md MCP section. |

contract_validation_status and contract_alignment

On ainl_validate and ainl_compile success, the server attaches:

• contract_validation_status: one of syntax_valid_contract_verified | syntax_valid_contract_unknown | syntax_valid_contract_mismatch (lightweight check vs ADAPTER_CONTRACTS in tooling/ainl_get_started.py and a fixed adapter allowlist in the MCP server).
• contract_alignment: object with schema_version, status (duplicates contract_validation_status), severity, verified_adapters, unknown_adapters, adapters_checked, and mismatched_calls: list of structured entries for adapter/verb pairs not listed in the get-started contract bundle (non-fatal warnings; runtime may still support the verb). Consumers (including ArmaraOS) should read mismatched_calls; some hosts also accept a legacy items alias for the same list when present in older payloads.

This is a static alignment hint, not a substitute for ainl_capabilities / ainl://adapter-contracts or an ainl_run smoke test when side effects matter.

Regenerating the family index and fixtures

• tooling/corpus_mining.py — builds corpus/strict_valid_family_index.json from strict-valid sources and artifact_profiles.json.
• corpus/reverse_prompt_fixtures.json — optional reverse-prompt / classifier seed data; generation path is described in tooling/corpus_mining.py and tests.

Re-run these after large changes to strict-valid example sets or when extending adapter families in CI.

ArmaraOS: prompt and graph memory

• System prompt: When the in-process MCP session or graph memory has a fresh wizard digest, the runtime may append a short line built from the JSON (field mcp_ainl_wizard_state_hint on PromptContext in prompt_builder.rs). Naming uses _state_ to reflect persisted wizard state, not a one-line UI label only.
• Graph memory (semantic tags): On successful mcp_ainl_* calls, the loop may persist digests with tags such as mcp:ainl:capabilities, mcp:ainl:recommended_next, and when wizard state is updated, mcp:ainl:wizard_state, with companion v:<sha16> for deduplication. See armaraos/docs/mcp-a2a.md.

MCP exposure profiles (AINL_MCP_EXPOSURE_PROFILE)

Named profiles in tooling/mcp_exposure_profiles.json control which tools and ainl://… resources the stdio server registers. ainl_step_examples and ainl://strict-valid-families are included in design_impact_first, inspect_only, safe_workflow, and full. validate_only exposes ainl_step_examples but keeps resources empty (no ainl:// URIs), matching the narrow validation-only posture.

See also

• MCP research / compile contracts: docs/operations/MCP_RESEARCH_CONTRACT.md (frame_hints, ainl_run limits, cache)
• Agent field guide: AGENTS.md (HTTP adapter, ainl_run adapters=, resources list)
• Example contract: examples/README.md, docs/EXAMPLE_SUPPORT_MATRIX.md