NixOS/specs/001-mcp-server/spec.md

Feature Specification: MCP Server for Repo Maintenance

Feature Branch: 001-mcp-server
Created: 2026-01-30
Status: Draft
Input: User description: "build a mcp server under the directory /scripts the intention for this mcp server is to be consumed by codex-cli to help on modifying the repository by doing but not limited to, the tasks declared on the ai-oriented documentation found in /docs. as an extra, I want this mcp to have tests, which run on the gitea pipeline when any changes done to the mcp or docs directories are commited. expand the ai-documentation on /docs with info about the built mcp so that it is compliant with what of the available tools of the mcp can be called for what specific tasks, ensuring that the mcp provides the easiest up to date assistance to giving this repository maintenance. When it comes to the coding preferences for the server, I want: 1) indentation kept to the bare minimum 2) guard clauses & early returns 3) easy to read coding style, with no comments, but professional easy to maintain code structure 4) functions with docstrings, typehints, etc. 5) give preference to iteration tools such as lambdas, map, filters, as opposed to for loops and multiple ifs. 6) functional code, with reduced duplicated code 7) lint & format the code"

Clarifications

Session 2026-01-30

• Q: How should MCP server access be scoped for Codex CLI users? → A: Restrict MCP server to local-only use with local filesystem permissions.

User Scenarios & Testing (mandatory)

User Story 1 - Codex CLI invokes MCP tools (Priority: P1)

Codex CLI users connect to the MCP server to list and invoke repository maintenance tasks that mirror the AI documentation, receiving clear guidance to execute changes safely.

Why this priority: Enables AI-assisted maintenance with minimal friction and ensures the new MCP server delivers immediate value.

Independent Test: Connect Codex CLI to the MCP server and run a documented maintenance task end-to-end without manual repository edits.

Acceptance Scenarios:

1. Given the MCP server is available to Codex CLI, When a user requests available tools, Then the server returns a list covering the documented maintenance tasks with descriptions and expected inputs.
2. Given a user selects a documented task, When they invoke the corresponding tool, Then the tool executes the task guidance without requiring extra configuration steps outside the documented flow.

---

User Story 2 - Automated checks guard MCP changes (Priority: P2)

Repository maintainers rely on automated tests to validate the MCP server whenever scripts or documentation change, preventing regressions before merging.

Why this priority: Protects repo quality and ensures MCP reliability as docs and tools evolve.

Independent Test: Modify a file in scripts/ or docs/, trigger the pipeline, and confirm MCP tests run and gate the change.

Acceptance Scenarios:

1. Given a commit touching scripts/ or docs/, When the Gitea pipeline runs, Then MCP tests execute and block merging on failure.

---

User Story 3 - AI docs explain MCP usage (Priority: P3)

Documentation readers can quickly understand what MCP tools exist, when to use them, and how they align to repository maintenance tasks.

Why this priority: Keeps AI-facing guidance discoverable and reduces guesswork for tool selection.

Independent Test: From the AI documentation, navigate to the MCP section and identify the correct tool and invocation steps for a chosen maintenance task without external help.

Acceptance Scenarios:

1. Given the AI documentation, When a reader searches for how to run a specific maintenance task, Then they find the mapped MCP tool, inputs, and scope within two clicks.
2. Given new MCP tools are added, When the docs are updated, Then the listed tools and capabilities match what the MCP server exposes.

---

Edge Cases

• Requests for tasks not mapped in the AI documentation should return guidance to supported options rather than executing ambiguous actions.
• Pipeline runs on documentation-only changes must still execute the MCP test suite and report status.
• MCP tool list and documentation drift are detected and corrected during testing or documentation updates.
• Codex CLI connections encountering unavailable MCP services return actionable guidance to retry or fallback without repository impact.

Requirements (mandatory)

Functional Requirements

• FR-001: Provide an MCP server under scripts/ that Codex CLI can connect to for repository maintenance tasks aligned to the AI documentation.
• FR-002: Expose a discoverable catalog of MCP tools with names, purposes, inputs, and scope that mirrors the maintenance tasks defined in docs/.
• FR-003: Ensure MCP tool execution follows documented guardrails, returning clear outcomes and guidance without requiring undocumented configuration.
• FR-004: Deliver automated tests that verify tool availability, parameter handling, and parity between documented tasks and MCP capabilities.
• FR-005: Configure the Gitea pipeline to run the MCP test suite whenever changes touch scripts/ or docs/, marking the pipeline failed on test failures.
• FR-006: Update AI-facing documentation to include MCP server overview, tool mappings to tasks, invocation examples, and maintenance expectations.
• FR-007: Keep coding standards observable in the MCP codebase (minimal indentation, guard clauses, docstrings, type hints, functional style, linted/ formatted outputs) to maintain readability and consistency.
• FR-008: Restrict MCP server availability to local-only access, relying on local filesystem permissions and avoiding remote exposure.
• FR-009: Meet runtime goals for local operation: list and invoke responses under 2 seconds on typical developer hardware and full MCP test suite completion under 60 seconds in CI, with safeguards to detect regressions.

Key Entities

• MCP Server: The service Codex CLI connects to for repository maintenance tasks; defines available tools and their behavior.
• Codex CLI User: Consumers invoking MCP tools to perform maintenance guided by AI documentation.
• Tool Catalog Entry: A documented pairing of a maintenance task, its MCP tool name, expected inputs, and constraints.
• Gitea Pipeline: The automation that runs MCP tests and reports pass/fail status on relevant commits.
• AI Documentation Set: Guidance under docs/ that describes maintenance tasks, tool mappings, and usage flows.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: Codex CLI users can discover and invoke at least five documented maintenance tasks through the MCP server without extra configuration steps.
• SC-002: MCP documentation and tool catalog stay in sync with zero mismatches detected during automated tests across three consecutive pipeline runs.
• SC-003: Any commit modifying scripts/ or docs/ triggers MCP tests, and merges are blocked unless all MCP tests pass.
• SC-004: Readers reach the correct MCP tool guidance for a chosen maintenance task within two clicks from the AI documentation landing page.
• SC-005: Tool discovery/invocation completes within 2 seconds locally and MCP test suite completes within 60 seconds in CI across three consecutive runs.