[PR #104] [MERGED] feat: add guided MCP workflow prompts #1836

New issue

Closed

opened 2026-10-16 21:11:37 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:11:37 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/104
Author: @N0zoM1z0
Created: 7/13/2026
Status: ✅ Merged
Merged: 7/13/2026
Merged by: @morluto

Base: main ← Head: feat/mcp-prompts-completion

📝 Commits (3)

24c3adb feat: add guided MCP workflow prompts
05fb9b1 test: strengthen MCP prompt acceptance coverage
b394903 Merge remote-tracking branch 'origin/main' into feat/mcp-prompts-completion

📊 Changes

11 files changed (+1740 additions, -14 deletions)

View changed files

📝 README.md (+6 -0)
➕ docs/mcp-prompts.md (+113 -0)
➕ scripts/verify-package-prompts.mjs (+62 -0)
📝 scripts/verify-package.mjs (+9 -14)
➕ src/contracts/promptContracts.ts (+405 -0)
📝 src/server/createServer.ts (+2 -0)
➕ src/server/promptCompletion.ts (+206 -0)
➕ src/server/registerPrompts.ts (+115 -0)
➕ tests/promptCompletion.test.ts (+295 -0)
➕ tests/promptContracts.test.ts (+104 -0)
➕ tests/promptMcp.test.ts (+423 -0)

📄 Description

Summary

Closes #102.

This PR adds provider-neutral MCP workflow prompts and live, session-scoped argument completion without moving Hopper-specific behavior into the domain or application layers.

Adds six guided workflows: investigate_feature, compare_application_versions, verify_reconstruction, trace_crash, audit_residual_unknowns, and prepare_bounded_process_capture.
Adds completion for open documents, procedures, provider IDs, Evidence IDs, Process Capture IDs, artifact manifest IDs, artifact occurrence IDs, and active residual-unknown IDs.
Advertises prompts.listChanged and emits notifications/prompts/list_changed when a registered workflow is updated.
Documents prompt discovery, retrieval, completion semantics, lifecycle behavior, and protocol limitations.
Extends packaged-artifact verification to cover the six-prompt catalog and completion before target open, while open, and after target close.

Behavior and safety

Prompts compose the existing 68 tools; they do not invoke tools or duplicate analysis logic. Each workflow uses current tool names and explicit ordering, and requires agents to keep observed evidence, inference, and unknowns separate. Prompt arguments and completion selections are rendered as untrusted data rather than instructions or authorization.

Completion is a read-only live projection of the active provider and session. Results are Unicode-normalized, case-insensitive prefix matches, deduplicated, deterministically sorted, and bounded to 10,000 scanned candidates. Procedure discovery is additionally capped at 5,000 unique addresses in pages of 500. Procedure names are offered only after exhaustive discovery proves that the name resolves to one address; partial discovery returns observed addresses only.

The MCP response remains bounded by the SDK's 100-value wire limit and reports total and hasMore. Malformed provider output, unsupported operations, stale sessions, and provider failures produce empty completion rather than unverified identifiers. Switching or closing a target immediately changes the next completion result because REA does not cache completion data.

MCP currently defines completion for prompt arguments and resource-template variables, not arbitrary tool-call arguments. This implementation therefore exposes completion through guided prompt arguments and does not claim completion for every tool input.

Contract impact

This is additive:

Tool inventory remains unchanged at 68 tools.
The MCP server now exposes 6 prompts.
Existing CLI, MCP tool, Hopper bridge, and session contracts are unchanged.
No provider-specific logic was added outside the provider adapter boundary.

Verification

npm run check
- 60 test files and 372 tests passed.
- Coverage: 80.27% statements, 69.28% branches, 82.26% functions, and 82.28% lines.
npm run verify:package
- Verified the packed CLI and stdio MCP server.
- Confirmed 68 tools, 6 prompts, prompt completion, and the open/switch/close completion lifecycle.
npm run knip
npm run jscpd
npm run scan:todos
Focused prompt suites passed with shuffled seeds 101, 202, and 303.
Additional tests cover empty sessions, stale identifiers, ambiguous procedure names, malformed provider results, large result sets, scan bounds, non-advancing pagination, Unicode matching, concurrent completion, cancellation recovery, prompt cache invalidation, and target lifecycle changes.

Real Hopper verification

npm run verify:hopper was not run. This change does not modify Hopper launch, bridge, socket protocol, or provider behavior; the packaged stdio MCP path and provider boundary are exercised through the repository's production seams.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/104 **Author:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Created:** 7/13/2026 **Status:** ✅ Merged **Merged:** 7/13/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `feat/mcp-prompts-completion` --- ### 📝 Commits (3) - [`24c3adb`](https://github.com/morluto/rea/commit/24c3adb553407fb9ac696e8e7c8d6eea643d14d6) feat: add guided MCP workflow prompts - [`05fb9b1`](https://github.com/morluto/rea/commit/05fb9b17c91b2ed7bfb58c3399499e0fb9e3f73e) test: strengthen MCP prompt acceptance coverage - [`b394903`](https://github.com/morluto/rea/commit/b394903b884a26ad9bc0c0fdedd75d67dbe30924) Merge remote-tracking branch 'origin/main' into feat/mcp-prompts-completion ### 📊 Changes **11 files changed** (+1740 additions, -14 deletions) <details> <summary>View changed files</summary> 📝 `README.md` (+6 -0) ➕ `docs/mcp-prompts.md` (+113 -0) ➕ `scripts/verify-package-prompts.mjs` (+62 -0) 📝 `scripts/verify-package.mjs` (+9 -14) ➕ `src/contracts/promptContracts.ts` (+405 -0) 📝 `src/server/createServer.ts` (+2 -0) ➕ `src/server/promptCompletion.ts` (+206 -0) ➕ `src/server/registerPrompts.ts` (+115 -0) ➕ `tests/promptCompletion.test.ts` (+295 -0) ➕ `tests/promptContracts.test.ts` (+104 -0) ➕ `tests/promptMcp.test.ts` (+423 -0) </details> ### 📄 Description ## Summary Closes #102. This PR adds provider-neutral MCP workflow prompts and live, session-scoped argument completion without moving Hopper-specific behavior into the domain or application layers. - Adds six guided workflows: `investigate_feature`, `compare_application_versions`, `verify_reconstruction`, `trace_crash`, `audit_residual_unknowns`, and `prepare_bounded_process_capture`. - Adds completion for open documents, procedures, provider IDs, Evidence IDs, Process Capture IDs, artifact manifest IDs, artifact occurrence IDs, and active residual-unknown IDs. - Advertises `prompts.listChanged` and emits `notifications/prompts/list_changed` when a registered workflow is updated. - Documents prompt discovery, retrieval, completion semantics, lifecycle behavior, and protocol limitations. - Extends packaged-artifact verification to cover the six-prompt catalog and completion before target open, while open, and after target close. ## Behavior and safety Prompts compose the existing 68 tools; they do not invoke tools or duplicate analysis logic. Each workflow uses current tool names and explicit ordering, and requires agents to keep observed evidence, inference, and unknowns separate. Prompt arguments and completion selections are rendered as untrusted data rather than instructions or authorization. Completion is a read-only live projection of the active provider and session. Results are Unicode-normalized, case-insensitive prefix matches, deduplicated, deterministically sorted, and bounded to 10,000 scanned candidates. Procedure discovery is additionally capped at 5,000 unique addresses in pages of 500. Procedure names are offered only after exhaustive discovery proves that the name resolves to one address; partial discovery returns observed addresses only. The MCP response remains bounded by the SDK's 100-value wire limit and reports `total` and `hasMore`. Malformed provider output, unsupported operations, stale sessions, and provider failures produce empty completion rather than unverified identifiers. Switching or closing a target immediately changes the next completion result because REA does not cache completion data. MCP currently defines completion for prompt arguments and resource-template variables, not arbitrary tool-call arguments. This implementation therefore exposes completion through guided prompt arguments and does not claim completion for every tool input. ## Contract impact This is additive: - Tool inventory remains unchanged at 68 tools. - The MCP server now exposes 6 prompts. - Existing CLI, MCP tool, Hopper bridge, and session contracts are unchanged. - No provider-specific logic was added outside the provider adapter boundary. ## Verification - `npm run check` - 60 test files and 372 tests passed. - Coverage: 80.27% statements, 69.28% branches, 82.26% functions, and 82.28% lines. - `npm run verify:package` - Verified the packed CLI and stdio MCP server. - Confirmed 68 tools, 6 prompts, prompt completion, and the open/switch/close completion lifecycle. - `npm run knip` - `npm run jscpd` - `npm run scan:todos` - Focused prompt suites passed with shuffled seeds 101, 202, and 303. - Additional tests cover empty sessions, stale identifiers, ambiguous procedure names, malformed provider results, large result sets, scan bounds, non-advancing pagination, Unicode matching, concurrent completion, cancellation recovery, prompt cache invalidation, and target lifecycle changes. ## Real Hopper verification `npm run verify:hopper` was not run. This change does not modify Hopper launch, bridge, socket protocol, or provider behavior; the packaged stdio MCP path and provider boundary are exercised through the repository's production seams. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-16 21:11:37 +00:00