requ-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nourreddine HOUARI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,217 @@
+# requ-mcp
+
+[![CI](https://github.com/nouhouari/requ-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/nouhouari/requ-mcp/actions/workflows/ci.yml)
+
+An MCP server that tracks **requirements coverage** for a project, and how it
+**evolves across phases/releases**. It gives AI agents structured tools to
+maintain a living traceability graph:
+
+```
+Requirement → User Story → (descriptive acceptance criteria)
+                 ▲
+                 │  link = an @US-xxx tag on a cucumber scenario
+                 │
+Phase (v1.0, v1.1, …) → Execution (a scenario result for a run)
+```
+
+At the end of a working session — or for any release — you ask the server one
+question — *"what's our coverage?"* — and get a precise, always-current answer
+instead of a stale spreadsheet, plus the **trend** of how coverage changed
+release over release.
+
+## Quickstart
+
+```bash
+git clone https://github.com/nouhouari/requ-mcp.git
+cd requ-mcp
+npm install
+npm run build      # compiles to dist/
+npm run smoke      # optional: end-to-end self-test
+```
+
+Register it with your MCP client (e.g. Claude Code) — once, globally:
+
+```json
+{
+  "mcpServers": {
+    "requ": {
+      "command": "node",
+      "args": ["/absolute/path/to/requ-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+Then a typical flow, all driven through the agent:
+
+1. `init_project` — create `.requ/` and point at your Conductor project (`conductorPath`), optionally create a first phase.
+2. `create_requirement` — import the requirements (with `components`).
+3. `create_user_story` — PO authors stories, each tracing to ≥1 requirement.
+4. **Tag scenarios** `@US-007` in your feature files — that *is* the test link.
+5. `import_execution_report` — ingest a Conductor cucumber-json run into the active phase.
+6. `coverage_report` / `find_gaps` / `coverage_trend` — see coverage now and how it evolves.
+
+## Why
+
+- **The server** serves the imported **requirements** (the upstream "what must be built").
+- A **PO agent** reads them and authors **user stories**, each tracing to **≥1 requirement** (enforced) with **acceptance criteria**.
+- A **tester agent** links **Conductor tests** (cucumber scenarios) to each criterion and records results per phase.
+
+A requirement is only **verified** when it has a story *and* every acceptance
+criterion of every linked story has a passing test **in that phase**. That
+distinction — "has tests" vs. real **coverage** — is the whole point.
+
+### Phases & executions
+
+A **TestLink** is pure intent ("this scenario verifies this criterion").
+Results are **Executions** owned by a **Phase**, so the same test can pass in
+v1.0 and fail in v1.1 — and coverage reflects it. Coverage is computed in one of
+two modes:
+
+- **cumulative** (default) — the latest known result for each test *as of* the
+  phase, carried forward from earlier phases. The smooth evolution curve.
+- **strict** — only runs recorded *in* that phase count. Honest release sign-off:
+  anything not re-run this phase is uncovered.
+
+`coverage_trend` returns the summary at each phase in order — the evolution view.
+
+### Components
+
+Requirements carry a `components` array, so coverage can be sliced per
+sub-system (the `byComponent` rollup in every report).
+
+### Ingesting Conductor results
+
+Conductor runs `cucumber-js --format json`. Point `import_execution_report` at
+that file and it records one execution per scenario into a phase, then reports
+how many results mapped onto a linked test.
+
+It pairs with [Conductor](https://github.com/nouhouari/conductor): Conductor
+owns the e2e *test definitions*; requ-mcp owns the *requirements and their
+coverage*. A test reference is a cucumber scenario (feature + scenario name);
+maestro-driven mobile tests run through cucumber step definitions and appear in
+the report as scenarios too, so scenarios are the single unit of linkage.
+References are validated by reading the Conductor project's
+`features/**/*.feature` directly off disk — no runtime coupling between the two
+servers.
+
+## Storage
+
+Everything is flat YAML under `.requ/`, so coverage is version-controlled and
+reviewable in PRs:
+
+```
+.requ/
+  config.yaml                 # project name, Conductor path, active phase
+  requirements/REQ-001.yaml
+  stories/US-001.yaml         # story → criteria → linked tests
+  phases/PHASE-001.yaml       # a phase / release
+  executions/PHASE-001.yaml   # test results recorded against that phase
+```
+
+## Tools
+
+| Tool | Actor | Purpose |
+|------|-------|---------|
+| `init_project` | setup | Create `.requ/`, record Conductor + report path, optional first phase |
+| `create_requirement` / `list_requirements` / `get_requirement` / `update_requirement` | server | Manage imported requirements (with `components`) |
+| `create_user_story` | PO | Author a story (rejects unless it links ≥1 existing requirement) |
+| `update_user_story` / `add_acceptance_criterion` / `list_user_stories` / `get_user_story` | PO | Edit stories & criteria |
+| `create_phase` / `list_phases` / `update_phase` / `set_active_phase` | release | Manage phases/releases |
+| `list_links` | tester | Show which scenarios are tagged to which story; flag dangling `@US-xxx` tags and stories with no scenario |
+| `record_execution` | tester | Record one scenario result against a phase |
+| `import_execution_report` | tester | Ingest a Conductor cucumber-json file into a phase |
+| `coverage_report` | reporting | Phase/mode rollup + per-component + summary % (json or markdown) |
+| `coverage_trend` | reporting | Coverage summary at each phase — the evolution view |
+| `find_gaps` | reporting | Requirements without stories, stories without scenarios, stories not covered (per phase) |
+
+Every tool also accepts an optional `projectPath` (see below).
+
+## Linking tests — `@US-xxx` tags
+
+There is no manual link step. A scenario is linked to a story by tagging it in
+the feature file:
+
+```gherkin
+@US-007
+Scenario: Reset email is sent for a registered address
+  ...
+```
+
+One feature file can hold scenarios for many stories. The server derives the
+links by scanning `features/**/*.feature` (the same tags ride along in the
+cucumber-JSON, so imported results map straight onto stories). `list_links`
+shows the derived graph and flags `@US-xxx` tags that point at a story that
+doesn't exist.
+
+## Develop
+
+```bash
+npm install
+npm run build      # tsc -> dist/
+npm run smoke      # end-to-end test against the built server over stdio
+npm run dev        # run from source with tsx
+```
+
+## Register with an MCP client
+
+The server talks stdio. It can be installed **once at the user level** and serve
+any project — it resolves the target project per call:
+
+```json
+{
+  "mcpServers": {
+    "requ": {
+      "command": "node",
+      "args": ["/absolute/path/to/requ-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+### How it finds the project
+
+For each tool call, the project root (the directory containing `.requ/`) is
+resolved in this order:
+
+1. The tool's explicit **`projectPath`** argument, if given (use this in monorepos).
+2. The **`REQU_ROOT`** env var, if set at launch (a hard pin).
+3. A **workspace root** advertised by the client (MCP `roots`) that contains `.requ/`.
+4. The nearest **ancestor of the cwd** that contains `.requ/`.
+5. Otherwise the first workspace root, else the cwd (used by `init_project`).
+
+So a single global server works across projects: most clients (Claude Code, IDEs)
+advertise the open workspace as a root, and you can always pass `projectPath`
+explicitly. The Conductor `features/` location is read from `.requ/config.yaml`
+relative to that resolved root.
+
+## Releasing (npm)
+
+Publishing is automated by `.github/workflows/publish.yml`, which runs on a
+GitHub Release and ships to npm with provenance.
+
+One-time setup:
+
+1. Create an npm **Automation** access token at npmjs.com → Access Tokens.
+2. Add it as a repo secret named `NPM_TOKEN`
+   (`gh secret set NPM_TOKEN`, or repo → Settings → Secrets → Actions).
+
+To cut a release:
+
+```bash
+# bump the version in package.json (e.g. 0.1.0), commit, then:
+git tag v0.1.0
+git push origin v0.1.0
+gh release create v0.1.0 --generate-notes
+```
+
+The workflow verifies the tag matches `package.json`, builds, runs the smoke
+test, and publishes. The release tag (`vX.Y.Z`) must match the `package.json`
+version.
+
+## Coverage metrics (story-level)
+
+- **Story coverage** — % of active requirements that trace to ≥1 story.
+- **Story tested** — the story has ≥1 scenario tagged `@US-xxx`.
+- **Story covered** — every tagged scenario passes in the phase.
+- **Verified** — % of active requirements where every linked story is covered.

package/dist/conductor.d.ts

@@ -0,0 +1,46 @@
+import { testKey } from "./schema.js";
+/**
+ * Reads the Conductor project's feature files directly off disk — no runtime
+ * coupling to the Conductor MCP server.
+ *
+ * A test is a cucumber scenario (feature name + scenario name) in
+ * features/**\/*.feature. Scenario → user-story links are declared as `@US-xxx`
+ * tags on the scenario and derived here; the feature files are the single
+ * source of truth for linkage.
+ */
+export interface ConductorScenario {
+    feature: string;
+    name: string;
+    file: string;
+    /** All tags on the scenario (incl. inherited feature-level tags), e.g. "@US-007". */
+    tags: string[];
+    /** Story ids parsed from tags, e.g. ["US-007"]. */
+    stories: string[];
+}
+export interface ConductorIndex {
+    scenarios: ConductorScenario[];
+}
+/** Build an index of all scenarios in a Conductor project. */
+export declare function indexConductor(conductorRoot: string): Promise<ConductorIndex>;
+export interface ValidationResult {
+    ok: boolean;
+    reason?: string;
+    suggestions?: string[];
+}
+/** Check that a test ref resolves to a real Conductor scenario. */
+export declare function validateTestRef(ref: {
+    feature: string;
+    name: string;
+}, index: ConductorIndex): ValidationResult;
+/** Map of story id → the scenarios tagged with it. */
+export declare function scenariosByStory(index: ConductorIndex): Map<string, ConductorScenario[]>;
+/** testKeys of every scenario that carries at least one @US-xxx tag. */
+export declare function linkedScenarioKeys(index: ConductorIndex): Set<string>;
+/** Scenario tags that reference a story id not present in `knownStoryIds`. */
+export declare function danglingStoryTags(index: ConductorIndex, knownStoryIds: Set<string>): {
+    feature: string;
+    name: string;
+    file: string;
+    story: string;
+}[];
+export { testKey };

package/dist/conductor.js

@@ -0,0 +1,175 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { STORY_TAG_RE, testKey } from "./schema.js";
+async function walk(dir, match) {
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err?.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    const out = [];
+    for (const e of entries) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) {
+            if (e.name === "node_modules" || e.name.startsWith("."))
+                continue;
+            out.push(...(await walk(full, match)));
+        }
+        else if (match(e.name)) {
+            out.push(full);
+        }
+    }
+    return out;
+}
+function parseTags(line) {
+    return line.split(/\s+/).filter((t) => t.startsWith("@"));
+}
+function storiesFromTags(tags) {
+    const out = [];
+    for (const t of tags) {
+        const m = t.match(STORY_TAG_RE);
+        if (m && !out.includes(m[1]))
+            out.push(m[1]);
+    }
+    return out;
+}
+/**
+ * Lightweight gherkin scan: pull the Feature name, each Scenario name, and the
+ * tags attached to each (tag lines immediately above the Scenario, plus
+ * feature-level tags above the `Feature:` line, which apply to all scenarios).
+ */
+function parseFeatureFile(content, file) {
+    let feature = path.basename(file, ".feature");
+    let featureTags = [];
+    let pendingTags = [];
+    const scenarios = [];
+    for (const lineRaw of content.split(/\r?\n/)) {
+        const line = lineRaw.trim();
+        if (line === "" || line.startsWith("#"))
+            continue;
+        if (line.startsWith("@")) {
+            pendingTags.push(...parseTags(line));
+            continue;
+        }
+        const fm = line.match(/^Feature:\s*(.+)$/);
+        if (fm) {
+            feature = fm[1].trim();
+            featureTags = pendingTags;
+            pendingTags = [];
+            continue;
+        }
+        const sm = line.match(/^Scenario(?:\s+Outline)?:\s*(.+)$/);
+        if (sm) {
+            const tags = [...featureTags, ...pendingTags];
+            scenarios.push({
+                feature,
+                name: sm[1].trim(),
+                file,
+                tags,
+                stories: storiesFromTags(tags),
+            });
+            pendingTags = [];
+            continue;
+        }
+        // Any other content line (steps, Background, Examples) ends a tag block.
+        pendingTags = [];
+    }
+    return scenarios;
+}
+/** Build an index of all scenarios in a Conductor project. */
+export async function indexConductor(conductorRoot) {
+    const featureFiles = await walk(path.join(conductorRoot, "features"), (f) => f.endsWith(".feature"));
+    const scenarios = [];
+    for (const file of featureFiles) {
+        scenarios.push(...parseFeatureFile(await fs.readFile(file, "utf8"), file));
+    }
+    return { scenarios };
+}
+/** Check that a test ref resolves to a real Conductor scenario. */
+export function validateTestRef(ref, index) {
+    const matches = index.scenarios.filter((s) => s.name === ref.name && s.feature === ref.feature);
+    if (matches.length > 0)
+        return { ok: true };
+    // Fall back to a name-only match to produce a precise hint.
+    const byName = index.scenarios.filter((s) => s.name === ref.name);
+    if (byName.length > 0) {
+        return {
+            ok: false,
+            reason: `Scenario "${ref.name}" exists, but not in feature "${ref.feature}".`,
+            suggestions: byName.map((s) => `${s.feature} :: ${s.name}`),
+        };
+    }
+    return {
+        ok: false,
+        reason: `No scenario "${ref.name}" found in feature "${ref.feature}".`,
+        suggestions: closest(ref.name, index.scenarios.map((s) => `${s.feature} :: ${s.name}`)),
+    };
+}
+/** Cheap fuzzy match for helpful "did you mean" suggestions. */
+function closest(target, pool, limit = 5) {
+    const t = target.toLowerCase();
+    return pool
+        .map((c) => ({ c, d: levenshtein(t, c.toLowerCase()) }))
+        .sort((a, b) => a.d - b.d)
+        .slice(0, limit)
+        .map((x) => x.c);
+}
+function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    let prev = Array.from({ length: n + 1 }, (_, i) => i);
+    let curr = new Array(n + 1);
+    for (let i = 1; i <= m; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[n];
+}
+// ---------------------------------------------------------------------------
+// Tag-derived linkage
+// ---------------------------------------------------------------------------
+/** Map of story id → the scenarios tagged with it. */
+export function scenariosByStory(index) {
+    const map = new Map();
+    for (const sc of index.scenarios) {
+        for (const story of sc.stories) {
+            const arr = map.get(story) ?? [];
+            arr.push(sc);
+            map.set(story, arr);
+        }
+    }
+    return map;
+}
+/** testKeys of every scenario that carries at least one @US-xxx tag. */
+export function linkedScenarioKeys(index) {
+    const set = new Set();
+    for (const sc of index.scenarios)
+        if (sc.stories.length)
+            set.add(testKey(sc));
+    return set;
+}
+/** Scenario tags that reference a story id not present in `knownStoryIds`. */
+export function danglingStoryTags(index, knownStoryIds) {
+    const out = [];
+    for (const sc of index.scenarios) {
+        for (const story of sc.stories) {
+            if (!knownStoryIds.has(story))
+                out.push({ feature: sc.feature, name: sc.name, file: sc.file, story });
+        }
+    }
+    return out;
+}
+export { testKey };
+//# sourceMappingURL=conductor.js.map

package/dist/conductor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conductor.js","sourceRoot":"","sources":["../src/conductor.ts"],"names":[],"mappings":"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"}

package/dist/coverage.d.ts

@@ -0,0 +1,109 @@
+import { type CoverageMode, type Execution, type Phase, type Requirement, type TestStatus, type UserStory } from "./schema.js";
+import type { ConductorScenario } from "./conductor.js";
+/**
+ * Phase-aware, story-level coverage rollup.
+ *
+ * Links are derived from `@US-xxx` scenario tags (see conductor.ts), so a story
+ * owns the scenarios tagged with its id. A test's result is resolved from the
+ * Executions recorded against a phase:
+ *
+ *   strict      — only executions recorded *in* the target phase count.
+ *   cumulative  — the latest known result as of the target phase (carried
+ *                 forward from earlier phases, by phase order then ranAt).
+ *
+ * Coverage rules (story-level):
+ *   - A story is COVERED when it has ≥1 tagged scenario and all of them pass.
+ *   - A requirement is VERIFIED when it has ≥1 story and all its stories are
+ *     covered.
+ * Acceptance criteria are descriptive and do not affect coverage.
+ */
+export type StatusMap = Map<string, TestStatus>;
+export type ScenariosByStory = Map<string, ConductorScenario[]>;
+export declare function resolveStatuses(executionsByPhase: Map<string, Execution[]>, phases: Phase[], targetPhaseId: string | null, mode: CoverageMode): StatusMap;
+export interface ScenarioCoverage {
+    feature: string;
+    name: string;
+    status: TestStatus;
+}
+export interface StoryCoverage {
+    id: string;
+    title: string;
+    status: string;
+    requirements: string[];
+    scenarios: ScenarioCoverage[];
+    passing: number;
+    failing: number;
+    pending: number;
+    /** Has ≥1 tagged scenario. */
+    tested: boolean;
+    /** Covered = tested AND every tagged scenario passes. */
+    covered: boolean;
+}
+export interface RequirementCoverage {
+    id: string;
+    title: string;
+    priority: string;
+    status: string;
+    components: string[];
+    storyIds: string[];
+    hasStory: boolean;
+    verified: boolean;
+}
+export interface ComponentCoverage {
+    component: string;
+    requirements: number;
+    withStory: number;
+    verified: number;
+    verifiedPct: number;
+}
+export interface CoverageSummary {
+    requirementsTotal: number;
+    requirementsWithStory: number;
+    requirementsVerified: number;
+    storiesTotal: number;
+    storiesTested: number;
+    storiesCovered: number;
+    scenariosLinked: number;
+    scenariosPassing: number;
+    storyCoveragePct: number;
+    verifiedPct: number;
+    testedStoryCoveragePct: number;
+}
+export interface CoverageReport {
+    phase: string | null;
+    mode: CoverageMode;
+    requirements: RequirementCoverage[];
+    stories: StoryCoverage[];
+    byComponent: ComponentCoverage[];
+    summary: CoverageSummary;
+}
+export declare function computeStoryCoverage(story: UserStory, scenariosByStory: ScenariosByStory, status: StatusMap): StoryCoverage;
+export declare function buildReport(requirements: Requirement[], stories: UserStory[], scenariosByStory: ScenariosByStory, status: StatusMap, phaseId: string | null, mode: CoverageMode): CoverageReport;
+export interface TrendPoint {
+    phase: string;
+    phaseName: string;
+    order: number;
+    summary: CoverageSummary;
+}
+export declare function buildTrend(requirements: Requirement[], stories: UserStory[], scenariosByStory: ScenariosByStory, executionsByPhase: Map<string, Execution[]>, phases: Phase[], mode: CoverageMode): TrendPoint[];
+export interface Gaps {
+    phase: string | null;
+    mode: CoverageMode;
+    requirementsWithoutStory: {
+        id: string;
+        title: string;
+        priority: string;
+        components: string[];
+    }[];
+    storiesWithoutScenario: {
+        id: string;
+        title: string;
+    }[];
+    storiesNotCovered: {
+        id: string;
+        title: string;
+        failing: string[];
+        pending: string[];
+    }[];
+}
+export declare function findGaps(requirements: Requirement[], stories: UserStory[], scenariosByStory: ScenariosByStory, status: StatusMap, phaseId: string | null, mode: CoverageMode): Gaps;