NixOS/specs/002-mcp-server/data-model.md

Data Model: MCP Server for Repo Maintenance

Entities

MCP Server

• Purpose: Hosts MCP tools for Codex CLI and orchestrates tool discovery and invocation.
• Attributes: transport (stdio), tool registry (list of Tool Catalog Entries), doc mapping (anchors/paths), version metadata.
• Relationships: Contains many Tool Catalog Entries; references Documentation Anchors for guidance.

Tool Catalog Entry

• Purpose: Represents a callable maintenance task exposed via MCP.
• Attributes: name (unique), description, input schema (parameters, types, required flags), execution scope (paths affected), documentation anchor (path + heading), safeguards (preconditions/guards), tags (category).
• Relationships: Linked to one Documentation Anchor; owned by MCP Server.
• Uniqueness: Name must be unique across the catalog.

Documentation Anchor

• Purpose: Points to the AI documentation section explaining when and how to use a tool.
• Attributes: doc path (under docs/), heading id/anchor, summary, last-synced version marker.
• Relationships: Referenced by Tool Catalog Entries; aligns with AI documentation updates.

CI Job

• Purpose: Executes lint, format, and test suites for MCP server on scoped path changes.
• Attributes: path filters (scripts/**, docs/**), steps (setup, install deps, lint, format check, tests, coverage), status output.
• Relationships: Observes repository changes; reports status to Gitea pipeline.