Orchestrator/bahn/teamlandkarte-mcp/openspec/changes/add-capacity-matching-mcp-server/specs/capacity-matching/spec.md

Capacity Matching Specification

ADDED Requirements

Requirement: Workflow overview (Round 6)

The system SHALL support two primary workflows:

1. Database task workflow (Phase 0): Users browse published tasks from the database, inspect details, optionally validate, and run a capacity search for an existing task.
2. Ad-hoc workflow (Phases 1-3): Users gather requirements (free-text extraction, structured input, or guided capture), optionally update requirements, explicitly confirm, execute search, and refine results.

The system SHALL expose the MCP tools required to support the workflows below. The implementation MAY add additional tools over time.

Scenario: Tool surface includes both DB-task and ad-hoc workflows

Phase 0 – Task Management (Database tasks)

• list_open_tasks(limit=20)
• get_task_details(task_id)
• validate_task_requirements(task_id)
• find_capacities_for_task(task_id)
• infer_roles(task_id? | task_description?, limit=5)

Phase 1 – Requirement Gathering (Ad-hoc)

• extract_requirements(task_description) → writes pending requirements
• collect_structured_requirement_data(role_name?, competences?, date_start?, date_end?, description?) → writes pending requirements
• update_requirements(change_description) → writes pending requirements
• Guided capture tools:
  • start_guided_capture()
  • guided_set_description(description)
  • guided_set_role(role_name)
  • guided_set_time_range(date_start?, date_end?) (open-ended allowed)
  • guided_set_competences(competences) → writes pending requirements
• Review/ask tools:
  • show_pending_requirements() → returns a review table and marks that user confirmation was requested
  • request_requirements_confirmation() → marks that the assistant asked the user to confirm (no table)
• confirm_requirements(confirm: bool = True)

Phase 2 – Search Execution (Ad-hoc)

• find_matching_capacities(role_name, competences, date_start?, date_end?)

Phase 3 – Result Refinement

• filter_search_results(search_id, role_filter?, competence_filter?, availability_date_start?, availability_date_end?, min_similarity=0.7) → returns filter_id
• get_results_by_category(search_id, filter_id?, category="Top", page=1, page_size=20)

Requirement: Confirmation gating

The system SHALL ensure that matching execution is confirmation-gated by default and behaves deterministically based on configuration.

Scenario: Matching is refused until requirements are confirmed (default)

• Confirmation gating:
  • The server's confirmation state is stored in in-memory session state and is not safe as a multi-client / multi-tenant source of truth. Therefore, treat confirmation gating primarily as a client-side UX rule: clients should only trigger matching after an explicit user Yes/No.
  • If matching.require_confirmation = true (default), matching tools MUST refuse to run unless requirements have been explicitly confirmed.
  • If matching.require_confirmation = false, clients MUST NOT ask for confirmation and MUST NOT call confirmation tools; matching MUST proceed once requirements are complete.
  • The confirmation flow MUST be two-step:
    1. show_pending_requirements() (preferred) OR request_requirements_confirmation()
    2. user explicitly confirms in chat
    3. confirm_requirements(confirm=true)
  • Servers MAY refuse confirm_requirements(confirm=true) if step (1) did not occur.

Requirement: Tool outputs and result headers

The system SHALL emit table-first tool output formats and deterministic, machine-readable headers for search-session tools.

Scenario: Tool results are table-first and include deterministic header metadata

• Tool outputs:

  • get_task_details MUST be table-first (summary table + description below)
  • validate_task_requirements MUST be table-first (single comparison table + short written summary)
  • infer_roles MUST return a ranked table: Rank | Role | Rationale

• Search session output headers (robust client parsing):

  • The tools find_matching_capacities, filter_search_results, and get_results_by_category MUST emit deterministic, machine-readable header lines.
  • On success, the first line MUST be exactly:
    • Using SEARCH_ID=<uuid>
  • The output MUST also contain:
    • SEARCH_ID=<uuid>
    • FILTER_ID=<uuid> (only if a filter was created/used)
    • META=<json> (MUST include at least { "search_id": "...", "status": "ok"|... })

Requirement: Search session validation and table guarantees

The system SHALL validate search session identifiers deterministically and MUST always return well-formed Markdown tables for search result tools.

Scenario: Invalid or expired search_id inputs produce deterministic errors and tables are always present

• Search session validation:

  • search_id inputs MUST be validated as UUIDs.
  • If the search_id is not a UUID, the tool MUST return META.status=invalid_search_id_format and guidance to copy the id from tool output.
  • If the search_id is unknown/expired, the tool MUST return META.status=unknown_or_expired and guidance to re-run the matching tool.

• Table-first guarantees for search results:

  • find_matching_capacities MUST include the ## Summary table.
  • find_matching_capacities MUST include a results table for the first non-empty category in this order: Top → Good → Partial → Low.
    • If all categories are empty, it MUST still emit a valid Markdown table (a single dummy row is acceptable).
  • filter_search_results and get_results_by_category MUST NOT repeat the summary counts table.
  • filter_search_results MUST output a flat results table (not split by category) and MUST include a Category column separate from the numeric Score.
  • filter_search_results MUST always return the results as a valid Markdown table (even for exactly one match, and also when there are zero matches).