From 3bb951034d22c3a51cc51dfa85bac82583413126 Mon Sep 17 00:00:00 2001 From: Jimisola Laursen Date: Sun, 19 Apr 2026 10:28:14 +0200 Subject: [PATCH 1/4] feat(mcp): add MCP server integration to skills and init - /reqstool:status now tries the reqstool MCP get_status tool first; notifies user immediately when falling back to CLI - /reqstool:add-req and /reqstool:add-svc verification steps prefer MCP (get_requirement_status / get_svc) with CLI fallback - /reqstool:init offers to write .mcp.json (project or global scope) after creating .reqstool-ai.yaml - README: add MCP server section with config example and version note - Bump plugin and marketplace versions to 0.3.0 Requires reqstool >= 0.9.0 for MCP server support. Signed-off-by: Jimisola Laursen --- .claude-plugin/marketplace.json | 2 +- .github/plugin/marketplace.json | 2 +- README.md | 25 ++++++++++++- plugins/reqstool/.claude-plugin/plugin.json | 2 +- .../reqstool/skills/reqstool/add-req/SKILL.md | 5 ++- .../reqstool/skills/reqstool/add-svc/SKILL.md | 6 +-- .../reqstool/skills/reqstool/init/SKILL.md | 37 +++++++++++++++++-- .../reqstool/skills/reqstool/status/SKILL.md | 32 ++++++++++++---- 8 files changed, 90 insertions(+), 21 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 7955033..fa0943d 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,7 +6,7 @@ "url": "https://github.com/reqstool" }, "metadata": { - "version": "0.2.0", + "version": "0.3.0", "description": "AI-assisted reqstool requirements traceability — skills and commands for managing requirements, SVCs, and filters, with optional OpenSpec integration." }, "plugins": [ diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json index 7955033..fa0943d 100644 --- a/.github/plugin/marketplace.json +++ b/.github/plugin/marketplace.json @@ -6,7 +6,7 @@ "url": "https://github.com/reqstool" }, "metadata": { - "version": "0.2.0", + "version": "0.3.0", "description": "AI-assisted reqstool requirements traceability — skills and commands for managing requirements, SVCs, and filters, with optional OpenSpec integration." }, "plugins": [ diff --git a/README.md b/README.md index c8a3e7d..87eb8f5 100644 --- a/README.md +++ b/README.md @@ -98,7 +98,7 @@ modules: | `/reqstool:init` | Create or update `.reqstool-ai.yaml` configuration interactively | | `/reqstool:add-req` | Add a new requirement and update subproject filters | | `/reqstool:add-svc` | Add a new Software Verification Case and update filters | -| `/reqstool:status` | Show requirements traceability status for system or a module | +| `/reqstool:status` | Show requirements traceability status (uses MCP server if configured, falls back to CLI) | ### Skills (auto-applied) | When you're... | Skill | @@ -129,7 +129,9 @@ Add a new Software Verification Case (SVC) to the system-level `software_verific ### `/reqstool:status` -Run `reqstool status local` for the system or a specific module. Accepts an optional module name (e.g., `/reqstool:status core`); defaults to the system-level path from `.reqstool-ai.yaml`. Reqstool traverses imports and implementation config automatically. +Show requirements traceability status for the system or a specific module. Accepts an optional module name (e.g., `/reqstool:status core`); defaults to the system-level path from `.reqstool-ai.yaml`. + +Uses the `reqstool` MCP server (`get_status` tool) when configured. Falls back to `reqstool status local` CLI if the server is not available, notifying you immediately when it does. ## Skill details @@ -150,6 +152,25 @@ OpenSpec integration conventions, auto-applied when working with spec.md files: - **reqstool-openspec-conventions.md** — how to reference reqstool IDs in OpenSpec specs - **config-rules.yaml** — reqstool rules for openspec/config.yaml +## MCP server + +The [reqstool MCP server](https://github.com/reqstool/reqstool-client) (reqstool ≥ 0.9.0) exposes structured tools for AI agents: `get_status`, `list_requirements`, `get_requirement_status`, and more. + +The `/reqstool:init` command can configure it automatically. To set it up manually, add to `.mcp.json` in your project root (project-scoped) or `~/.config/claude/mcp.json` (global): + +```json +{ + "mcpServers": { + "reqstool": { + "command": "reqstool", + "args": ["mcp", "local", "-p", ""] + } + } +} +``` + +When configured, skills like `/reqstool:status` use MCP for structured data. If the server is not available they fall back to `reqstool status local` automatically, notifying you when they do. + ## Prerequisites - [reqstool CLI](https://github.com/reqstool/reqstool-client) (`pipx install reqstool`) diff --git a/plugins/reqstool/.claude-plugin/plugin.json b/plugins/reqstool/.claude-plugin/plugin.json index 0dc942d..1ae3d88 100644 --- a/plugins/reqstool/.claude-plugin/plugin.json +++ b/plugins/reqstool/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "reqstool", "description": "AI-assisted reqstool requirements traceability — skills and commands for managing requirements, SVCs, and filters.", - "version": "0.2.0", + "version": "0.3.0", "author": { "name": "reqstool", "url": "https://github.com/reqstool" diff --git a/plugins/reqstool/skills/reqstool/add-req/SKILL.md b/plugins/reqstool/skills/reqstool/add-req/SKILL.md index 8a63e62..dde72c2 100644 --- a/plugins/reqstool/skills/reqstool/add-req/SKILL.md +++ b/plugins/reqstool/skills/reqstool/add-req/SKILL.md @@ -83,9 +83,10 @@ For reqstool fundamentals (imports, filters, implementations), see `reqstool-ove Add the new requirement ID to the `filters..requirement_ids.includes` list in the relevant module's `/requirements.yml`. -6. **Verify with reqstool** +6. **Verify the new requirement is tracked** - Run `reqstool status local -p ` and confirm the new requirement appears. + - **If MCP is available**: call `get_requirement_status()` on the `reqstool` MCP server and confirm the requirement is returned. + - **Otherwise**: run `reqstool status local -p ` and confirm the new requirement appears. 7. **Report** diff --git a/plugins/reqstool/skills/reqstool/add-svc/SKILL.md b/plugins/reqstool/skills/reqstool/add-svc/SKILL.md index 41882e7..a77667d 100644 --- a/plugins/reqstool/skills/reqstool/add-svc/SKILL.md +++ b/plugins/reqstool/skills/reqstool/add-svc/SKILL.md @@ -94,10 +94,10 @@ For reqstool fundamentals (imports, filters, implementations), see `reqstool-ove Add the new SVC ID to the `filters..svc_ids.includes` list in the relevant module's `/software_verification_cases.yml`. -7. **Verify with reqstool** +7. **Verify the new SVC is tracked** - Run `reqstool status local -p ` and confirm the new SVC appears - under the linked requirement. + - **If MCP is available**: call `get_svc()` on the `reqstool` MCP server and confirm the SVC is returned. + - **Otherwise**: run `reqstool status local -p ` and confirm the new SVC appears under the linked requirement. 8. **Report** diff --git a/plugins/reqstool/skills/reqstool/init/SKILL.md b/plugins/reqstool/skills/reqstool/init/SKILL.md index ee50299..17858a3 100644 --- a/plugins/reqstool/skills/reqstool/init/SKILL.md +++ b/plugins/reqstool/skills/reqstool/init/SKILL.md @@ -78,7 +78,37 @@ Create or update `.reqstool-ai.yaml` configuration for this project. structure, comments, and formatting. Replace placeholder values with the user's inputs and include only the modules the user defined. -5. **Verify (if possible)** +5. **Configure MCP server (optional)** + + Offer to configure the reqstool MCP server (requires reqstool ≥ 0.9.0): + + > The reqstool MCP server gives AI tools structured access to your requirements. + > Would you like me to add the MCP server configuration? + + If yes, use **AskUserQuestion** to ask the scope: + - **Project** — `.mcp.json` in the project root (shared with the team via version control) + - **Global** — `~/.config/claude/mcp.json` (just for you, not committed) + + Read the chosen file (create if missing) and add or update the `reqstool` entry: + + ```json + { + "mcpServers": { + "reqstool": { + "command": "reqstool", + "args": ["mcp", "local", "-p", ""] + } + } + } + ``` + + If the chosen file already has a `reqstool` entry, show it and ask before overwriting. + + If `reqstool` is not yet installed, skip this step and tell the user: + > Install reqstool first (`pipx install reqstool`), then re-run `/reqstool:init` + > or add the MCP config manually. + +6. **Verify (if possible)** If `reqstool` CLI is installed **and** the system path contains existing reqstool files, run `reqstool status local -p ` to verify the config. @@ -86,12 +116,13 @@ Create or update `.reqstool-ai.yaml` configuration for this project. If reqstool is not installed or files don't exist yet, skip verification and tell the user they can run `/reqstool:status` later once their reqstool files are in place. -6. **Report** +7. **Report** Show the user: - The created/updated config (print the file contents) - Whether this was a new file or an update - - Remind them to add `.reqstool-ai.yaml` to version control + - Whether the MCP server was configured and in which scope + - Remind them to add `.reqstool-ai.yaml` to version control (and `.mcp.json` if project-scoped) - Next steps: "Run `/reqstool:add-req` to add your first requirement, or `/reqstool:status` to check traceability status." diff --git a/plugins/reqstool/skills/reqstool/status/SKILL.md b/plugins/reqstool/skills/reqstool/status/SKILL.md index 979a5be..bf7f8e9 100644 --- a/plugins/reqstool/skills/reqstool/status/SKILL.md +++ b/plugins/reqstool/skills/reqstool/status/SKILL.md @@ -7,7 +7,7 @@ metadata: version: "1.0" --- -Run `reqstool status local` for a reqstool directory in this project. +Show requirements traceability status. Uses the reqstool MCP server if configured, falls back to the CLI. --- @@ -30,7 +30,22 @@ Read `.reqstool-ai.yaml` — see `reqstool-conventions.md` for field reference. - If the user is working inside a module directory (e.g., a Gradle subproject), ask whether they want to run status for that module or for the system level. -3. **Run reqstool status** +3. **Try MCP first** + + Call the `reqstool` MCP server `get_status` tool. + + - If it succeeds: present the returned status (requirements met/total, test summary). + Note: the MCP server always reflects the system-level path it was started with. + If the user asked for a specific module and the MCP result does not scope to that path, + note this limitation and proceed to the CLI fallback for the module path. + +4. **Fall back to CLI** + + If the MCP server is not configured or the call fails, immediately tell the user: + + > The reqstool MCP server is not configured — falling back to CLI. + + Then run: ```bash reqstool status local -p @@ -39,14 +54,15 @@ Read `.reqstool-ai.yaml` — see `reqstool-conventions.md` for field reference. Show the output directly — reqstool traverses imports and implementation configuration automatically, so no further summarization is needed. -4. **If reqstool is not installed** +5. **If neither works** - If the command fails with "not found", tell the user: - ``` - reqstool is not installed. Install with: pipx install reqstool - ``` + If `reqstool` CLI is also not found, tell the user: + + > Both the reqstool MCP server and CLI are unavailable. + > - To install the CLI: `pipx install reqstool` + > - To configure the MCP server: run `/reqstool:init` **Guardrails** - Always run from the project root directory - Do not modify any files — this is a read-only status command -- Do not summarize or reformat reqstool output — show it as-is +- Do not summarize or reformat reqstool CLI output — show it as-is From 22b227f1b045cfd454057be64284c1d78354c587 Mon Sep 17 00:00:00 2001 From: Jimisola Laursen Date: Sun, 19 Apr 2026 10:30:43 +0200 Subject: [PATCH 2/4] fix(plugin): remove unrecognized root description key from marketplace.json Signed-off-by: Jimisola Laursen --- .claude-plugin/marketplace.json | 1 - 1 file changed, 1 deletion(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index fa0943d..9171287 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,6 +1,5 @@ { "name": "reqstool-ai", - "description": "AI-assisted reqstool requirements traceability — skills and commands for managing requirements, SVCs, and filters.", "owner": { "name": "reqstool", "url": "https://github.com/reqstool" From 176a0d6c6ecb2a9d0aa0cf9fdf229709c77d2db2 Mon Sep 17 00:00:00 2001 From: Jimisola Laursen Date: Sun, 19 Apr 2026 10:31:29 +0200 Subject: [PATCH 3/4] docs: link CONTRIBUTING.md from CLAUDE.md pre-commit section Signed-off-by: Jimisola Laursen --- CLAUDE.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 8d07bb6..5e275dd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -32,4 +32,6 @@ copilot plugin install --path ./plugins/reqstool-openspec ## Pre-commit checks +See [CONTRIBUTING.md](CONTRIBUTING.md) for the full testing and contribution process. + Run `claude plugin validate .` before committing to catch manifest errors, missing fields, and path issues. From dff86ef5da46a79e66f88f842fdcd231ea42d286 Mon Sep 17 00:00:00 2001 From: Jimisola Laursen Date: Sun, 19 Apr 2026 10:31:45 +0200 Subject: [PATCH 4/4] =?UTF-8?q?docs:=20simplify=20CLAUDE.md=20pre-commit?= =?UTF-8?q?=20section=20=E2=80=94=20details=20in=20CONTRIBUTING.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Jimisola Laursen --- CLAUDE.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 5e275dd..d8de527 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -33,5 +33,3 @@ copilot plugin install --path ./plugins/reqstool-openspec ## Pre-commit checks See [CONTRIBUTING.md](CONTRIBUTING.md) for the full testing and contribution process. - -Run `claude plugin validate .` before committing to catch manifest errors, missing fields, and path issues.