@recapt/mcp 0.0.4-beta → 0.0.6-beta

package/package.json

@@ -1,31 +1,37 @@
 {
   "name": "@recapt/mcp",
-  "version": "0.0.4-beta",
+  "version": "0.0.6-beta",
   "description": "MCP exposing recapt behavioral intelligence to AI coding agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
   "scripts": {
-    "build": "tsc",
+    "build": "npm run generate-catalog && tsc && cp src/tools/catalog/toolCatalog.json dist/tools/catalog/",
     "clean": "rimraf ./dist",
     "dev": "tsx --watch src/index.ts",
     "start": "node dist/index.js",
     "prettify": "prettier --write .",
-    "type-check": "tsc --noEmit"
+    "type-check": "tsc --noEmit",
+    "generate-catalog": "tsx scripts/generateCatalog.ts"
   },
   "bin": {
-    "recapt-mcp": "./dist/index.js"
+    "recapt-mcp": "./dist/index.js",
+    "recapt": "./dist/cli/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
-
   "author": "Recapt",
   "license": "ISC",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
+    "commander": "^14.0.3",
     "zod": "^3.24.0"
   },
+  "optionalDependencies": {
+    "@xenova/transformers": "^2.17.0"
+  },
   "peerDependencies": {
     "@types/node": "^24.3.1",
     "dotenv": "^17.2.2",

package/skills/deep-dive.md

@@ -0,0 +1,92 @@
+# Recapt Deep Dive Analysis
+
+Use this workflow for comprehensive analysis of a specific page, flow, or user segment using recapt behavioral data.
+
+## When to Use
+
+- User asks to analyze a specific page in depth
+- User wants to understand why a page has poor metrics
+- User asks "what's wrong with [page]?" or "why is [page] underperforming?"
+- User wants a data-driven improvement strategy for a specific area
+
+## Workflow
+
+### 1. Establish Context
+
+Start by understanding what you're analyzing:
+
+- Search: "site overview" → `scan_site`, `list_pages`, `get_ux_health_report`
+- Identify the target page(s) and their current health scores
+
+### 2. Page-Level Analysis
+
+Gather comprehensive metrics for the target page:
+
+- Search: "page analysis" → `get_page_metrics`
+- Search: "element friction" → `get_element_friction`
+- Search: "dead clicks" → `get_dead_clicks`
+- Search: "console errors" → `get_console_errors`
+- Search: "form friction" → `get_form_friction` (if page has forms)
+
+### 3. Flow Analysis
+
+Understand how users arrive at and leave the page:
+
+- Search: "user navigation" → `analyze_flow`, `get_journey_patterns`
+- Search: "funnel" → `analyze_funnel`, `get_flow_friction`
+- Identify where users come from and where they drop off
+
+### 4. Trend Analysis
+
+Check if issues are new or long-standing:
+
+- Search: "trends" → `get_page_trends`
+- Search: "regressions" → `detect_regressions`
+- Search: "anomalies" → `get_anomalies`
+
+### 5. Session Deep-Dive
+
+Examine specific user sessions for qualitative insights:
+
+- Search: "session details" → `search_sessions`, `list_sessions`, `get_session_details`
+- Look for patterns in high-frustration or high-confusion sessions
+
+### 6. Segment Comparison
+
+Compare different user groups:
+
+- Search: "compare users" → `compare_cohorts`, `compare_periods`
+- Search: "personas" → `discover_personas`
+- Identify if issues affect all users or specific segments
+
+## Output Format
+
+After gathering data, synthesize findings into:
+
+1. **Executive Summary** — 2-3 sentence overview of the page's health
+2. **Key Metrics** — Health score, frustration, confusion, confidence levels
+3. **Top Issues** — Prioritized list of problems with severity
+4. **User Flow Insights** — Where users come from, where they go, drop-off points
+5. **Recommendations** — Specific, actionable improvements ranked by impact
+
+## Tool Discovery Reference
+
+| Analysis Type | Search Query            | Tools                                                     |
+| ------------- | ----------------------- | --------------------------------------------------------- |
+| Overview      | "site overview"         | `scan_site`, `list_pages`, `get_ux_health_report`         |
+| Page metrics  | "page analysis"         | `get_page_metrics`                                        |
+| Elements      | "element friction"      | `get_element_friction`, `get_dead_clicks`                 |
+| Errors        | "console errors"        | `get_console_errors`                                      |
+| Forms         | "form friction"         | `get_form_friction`                                       |
+| Navigation    | "user navigation"       | `analyze_flow`, `get_journey_patterns`                    |
+| Funnels       | "funnel"                | `analyze_funnel`, `get_flow_friction`                     |
+| Trends        | "trends", "regressions" | `get_page_trends`, `detect_regressions`, `get_anomalies`  |
+| Sessions      | "session details"       | `search_sessions`, `list_sessions`, `get_session_details` |
+| Segments      | "compare users"         | `compare_cohorts`, `compare_periods`, `discover_personas` |
+
+## Tips
+
+- Use `memory_save` to store intermediate results when analysis spans many tools
+- Start broad (site overview) then narrow down to specific issues
+- Always check for console errors when frustration is high but confusion is low
+- Compare mobile vs desktop cohorts — issues often differ by device

package/skills/regression-hunt.md

@@ -0,0 +1,120 @@
+# Recapt Regression Hunt
+
+Use this workflow to find and fix recent regressions — UX issues introduced by recent code changes.
+
+## When to Use
+
+- User reports that something "broke" or "got worse"
+- Metrics show a sudden spike in frustration or drop-off
+- User asks to find what changed or what regressed
+- After a deployment when users report issues
+
+## Workflow
+
+### 1. Detect Regressions
+
+Start by identifying what regressed and when:
+
+- Search: "regressions" → `detect_regressions`
+- Search: "anomalies" → `get_anomalies`
+- Search: "drift" → `detect_drift`
+
+Look for:
+
+- `spike_ratio` > 2: Critical regression, likely recent
+- Sudden changes in frustration, confusion, or drop-off rates
+- New console errors that weren't present before
+
+### 2. Establish Timeline
+
+Narrow down when the regression started:
+
+- Search: "trends" → `get_page_trends`
+- Search: "compare periods" → `compare_periods`
+- Compare metrics before and after the suspected change date
+
+### 3. Identify Affected Areas
+
+Determine scope of the regression:
+
+- Search: "page analysis" → `get_page_metrics`
+- Search: "element friction" → `get_element_friction`
+- Is it one page, one flow, or site-wide?
+
+### 4. Find Root Cause
+
+Investigate the specific issue:
+
+- Search: "console errors" → `get_console_errors` (often the culprit)
+- Search: "dead clicks" → `get_dead_clicks` (broken interactions)
+- Search: "investigate issue" → `investigate_issue`
+
+### 5. Examine Sessions
+
+Look at specific user sessions during the regression period:
+
+- Search: "session details" → `search_sessions`, `get_session_details`
+- Filter for high-frustration sessions after the regression date
+- Look for common patterns or error states
+
+### 6. Fix and Track
+
+Once you've identified the cause:
+
+- Implement the fix
+- Search: "propose fix" → `propose_fix`
+- Search: "deployment" → `confirm_deployment`
+- Monitor with `evaluate_fix` after 24-48 hours
+
+## Regression Indicators
+
+| Metric             | Normal | Warning   | Critical |
+| ------------------ | ------ | --------- | -------- |
+| spike_ratio        | < 1.5  | 1.5 - 2.0 | > 2.0    |
+| frustration delta  | < 0.1  | 0.1 - 0.2 | > 0.2    |
+| new console errors | 0      | 1-2       | 3+       |
+| drop_off increase  | < 5%   | 5-15%     | > 15%    |
+
+## Common Regression Patterns
+
+### JavaScript Errors
+
+- **Signal**: High frustration, low confusion, rage clicks on body/root
+- **Search**: "console errors" → check for new errors
+- **Fix**: Debug and fix the JS error
+
+### Broken Interactions
+
+- **Signal**: Dead clicks on previously working elements
+- **Search**: "dead clicks" → find non-responsive elements
+- **Fix**: Check event handlers, z-index issues, or removed elements
+
+### Layout Shifts
+
+- **Signal**: Misclicks, clicks on wrong elements
+- **Search**: "element friction" → look for unexpected click targets
+- **Fix**: Check CSS changes, loading states, or dynamic content
+
+### Performance Regression
+
+- **Signal**: High abandonment, low engagement time
+- **Search**: "session details" → check session durations
+- **Fix**: Profile and optimize slow code paths
+
+## Tool Discovery Reference
+
+| Phase      | Search Query        | Tools                                    |
+| ---------- | ------------------- | ---------------------------------------- |
+| Detect     | "regressions"       | `detect_regressions`                     |
+| Detect     | "anomalies"         | `get_anomalies`                          |
+| Detect     | "drift"             | `detect_drift`                           |
+| Timeline   | "trends"            | `get_page_trends`                        |
+| Timeline   | "compare periods"   | `compare_periods`                        |
+| Scope      | "page analysis"     | `get_page_metrics`                       |
+| Scope      | "element friction"  | `get_element_friction`                   |
+| Root cause | "console errors"    | `get_console_errors`                     |
+| Root cause | "dead clicks"       | `get_dead_clicks`                        |
+| Root cause | "investigate issue" | `investigate_issue`                      |
+| Sessions   | "session details"   | `search_sessions`, `get_session_details` |
+| Fix        | "propose fix"       | `propose_fix`                            |
+| Track      | "deployment"        | `confirm_deployment`, `evaluate_fix`     |

package/skills/self-healing.md

@@ -0,0 +1,95 @@
+# Recapt Self-Healing Workflow
+
+Use this workflow when asked to "fix issues", "heal the site", or improve UX based on behavioral data from recapt.
+
+## When to Use
+
+- User asks to fix UX issues or friction points
+- User wants to improve conversion or reduce drop-offs
+- User asks to "heal" or "diagnose" their site
+- After identifying issues with `run_full_diagnostic`
+
+## Workflow
+
+### 0. Check Pending Fixes (if returning)
+
+Before diagnosing new issues, check if there are previously tracked fixes awaiting validation:
+
+- Search: "pending fixes" → `list_pending_fixes`
+
+If pending fixes exist:
+
+1. For each fix, call `evaluate_fix` to check validation status
+2. The tool will indicate if sufficient time has passed and enough sessions have interacted with the affected areas
+3. If data is insufficient, inform the user:
+
+> "You have X fixes deployed Y hours ago. We need more session data (or more time) before we can validate their impact. Want to proceed with diagnosing new issues, or check back later?"
+
+If fixes have sufficient data:
+
+- Present the validation results (improved, no change, or regressed)
+- Discuss next steps for any fixes that didn't improve metrics
+- Then proceed to diagnose new issues
+
+### 1. Diagnose
+
+Start with `run_full_diagnostic` (always available) to get a prioritized list of issues across the site.
+
+### 2. Investigate
+
+For each high-priority issue, search for investigation tools:
+
+- Search: "investigate issue" → `investigate_issue`, `validate_issue`
+- This provides detailed context: affected sessions, element interactions, timing patterns
+
+### 3. Triage
+
+Present findings to the user. Not all detected issues need fixing:
+
+- Search: "dismiss issue" → `dismiss_issue`, `mark_intended_behavior`
+- Some behaviors are intentional (e.g., rage clicks on a "copy" button)
+- Ask the user which issues to address before proceeding
+
+### 4. Fix
+
+Implement code changes to address the issues. After making changes:
+
+- Search: "propose fix" → `propose_fix`, `get_similar_fixes`, `get_fix_history`
+- Log the remediation so recapt can track its effectiveness
+
+### 5. Track
+
+Mark fixes as deployed so recapt can measure impact:
+
+- Search: "deployment" → `confirm_deployment`, `evaluate_fix`, `list_pending_fixes`
+
+### 6. Learn
+
+Build site knowledge for future reference:
+
+- Search: "site knowledge" → `get_site_knowledge`, `add_site_knowledge`
+- Document patterns, intended behaviors, and architectural decisions
+
+## Post-Fix Behavior
+
+After implementing fixes, always ask:
+
+> "Fixes implemented. Want me to track these so we can validate the changes had a positive impact?"
+
+If the user agrees:
+
+1. Use `confirm_deployment` to mark the fix as deployed
+2. Explain that recapt will monitor the affected pages/elements
+3. Suggest checking back in 24-48 hours with `evaluate_fix` to measure improvement
+
+## Tool Discovery Reference
+
+| Phase         | Search Query        | Tools                                                      |
+| ------------- | ------------------- | ---------------------------------------------------------- |
+| Check Pending | "pending fixes"     | `list_pending_fixes`, `evaluate_fix`                       |
+| Diagnose      | (always available)  | `run_full_diagnostic`                                      |
+| Investigate   | "investigate issue" | `investigate_issue`, `validate_issue`                      |
+| Triage        | "dismiss issue"     | `dismiss_issue`, `mark_intended_behavior`                  |
+| Fix           | "propose fix"       | `propose_fix`, `get_similar_fixes`, `get_fix_history`      |
+| Track         | "deployment"        | `confirm_deployment`, `evaluate_fix`, `list_pending_fixes` |
+| Learn         | "site knowledge"    | `get_site_knowledge`, `add_site_knowledge`                 |