Staprompt - Staprompt Orchestrator MCP

Package: staprompt | Command: staprompt Automates the qwe staprompt research workflow in Claude Code, reducing CLAUDE.md by 142 lines while maintaining full functionality.

What It Does

This MCP server transforms staprompt research from manual documentation-heavy workflow into automated, tool-guided process:

Before (Manual):

• AI reads 220+ lines of staprompt docs in CLAUDE.md
• Manually follows workflow steps
• Error-prone delivery process
• Duplication between CLAUDE.md and process

After (Automated with MCP):

• AI reads 50 lines of essentials in CLAUDE.md
• MCP tools provide detailed instructions on-demand
• Automated planning doc creation and handoff
• Single source of truth (MCP tools)

Features

• Automated workflow guidance - Step-by-step instructions returned by tools
• Research mode - Blocks execution tools, enforces research-only mode
• Git analysis - Analyzes recent commits with trust scores
• Documentation validation - Checks doc freshness and reliability
• MCP recommendations - Suggests MCPs based on task type
• Planning doc generation - Creates properly formatted planning docs
• Automatic handoff - Copies to clipboard and launches plan mode

Installation

NPX (Recommended - Always Latest)

No installation needed! Configure Claude Code to use npx:

{
  "mcpServers": {
    "staprompt": {
      "command": "npx",
      "args": ["-y", "staprompt"]
    }
  }
}

Global Install

npm install -g staprompt

Then configure:

{
  "mcpServers": {
    "staprompt": {
      "command": "staprompt"
    }
  }
}

Local Development (Portable Setup)

This repository includes staprompt as a file dependency. When you clone the repo and run npm install, the staprompt MCP is automatically installed locally.

# Clone the repo
git clone <repo-url>
cd <repo-directory>

# Install dependencies (includes staprompt)
npm install

The .mcp.json file is already configured to use the local installation:

{
  "mcpServers": {
    "staprompt": {
      "command": "node",
      "args": ["node_modules/staprompt/run-staprompt.js"]
    }
  }
}

How it works:

• staprompt is listed as a file dependency: "staprompt": "file:./staprompt"
• The run-staprompt.js wrapper dynamically resolves the correct path
• Works on any machine, any directory - no hardcoded paths!

After making changes to staprompt code:

1. Build: cd staprompt && npm run build
2. Restart Claude Code to reload the MCP server

After pulling changes from git:

1. Run npm install (rebuilds staprompt automatically via "prepare" script)
2. Restart Claude Code

No manual reinstall needed - the file dependency link picks up changes automatically.

Available Tools

Core Workflow Tools

1. get_current_mode()

Check if currently in research mode or execution mode.

Returns:

{
  "mode": "research" | "execution",
  "currentTask": "string | null",
  "blockedTools": ["Write", "Edit", "Bash"],
  "researchDuration": "15 minutes"
}

When to use:

• After conversation compacting to check mode
• To verify research mode is active

2. enter_research_mode(task)

Enter research mode and get complete workflow instructions.

Parameters:

• task (string): The task to research (e.g., "Optimize feed performance")

Returns:

• Complete workflow instructions (5 steps)
• Research scope boundaries
• Prompt writing guidelines
• MCP recommendation requirements
• Trust hierarchy

What it does:

• Sets mode to "research"
• Blocks execution tools (Write, Edit, Bash, NotebookEdit)
• Starts research timer
• Returns comprehensive workflow guide

Example:

await use_mcp_tool('staprompt', 'enter_research_mode', {
  task: 'Fix real-time updates in feed'
});

3. create_planning_doc(content, metadata)

Create a planning document with proper template and frontmatter.

Parameters:

• content (string): The planning prompt content (markdown)
• metadata (object):
  • task (string, required): The task name
  • priority (string): "low" | "medium" | "high"
  • estimated_effort (string): e.g., "2-3 hours"
  • related_files (string[]): Related file paths

Returns:

• File path to created planning doc
• Next step instructions

What it does:

• Generates proper frontmatter
• Adds progress tracker template
• Creates findings section
• Saves to docs/planning/[task-slug]-YYYY-MM-DD.md

Example:

await use_mcp_tool('staprompt', 'create_planning_doc', {
  content: '# Planning Prompt\n\n...',
  metadata: {
    task: 'Fix real-time updates',
    priority: 'high',
    estimated_effort: '2-3 hours',
    related_files: ['src/hooks/useRealtimeUpdates.ts']
  }
});

4. handoff_to_plan_mode(doc_path)

Complete handoff: copy doc to clipboard, launch plan mode, exit research mode.

Parameters:

• doc_path (string): Path to the planning document

Returns:

• Success confirmation
• Manual instructions (if auto-launch fails)

What it does:

• Reads planning doc
• Copies content to Windows clipboard (PowerShell Set-Clipboard)
• Launches Claude Code with --permission-mode plan in new terminal
• Exits research mode automatically
• Unblocks execution tools
• Note: User must press Ctrl+V in the new window to paste

Example:

await use_mcp_tool('staprompt', 'handoff_to_plan_mode', {
  doc_path: 'docs/planning/fix-realtime-2025-01-31.md'
});

5. exit_research_mode()

Exit research mode and unblock execution tools (internal use).

Returns:

• Confirmation message

Note: Usually called automatically by handoff_to_plan_mode().

Research Helper Tools

6. analyze_git_history(keyword, days)

Analyze git history for recent work with trust scores.

Parameters:

• keyword (string): Search term for commit messages
• days (number, optional): Days to look back (default: 30)

Returns:

• Top 20 matching commits
• Trust scores (higher for recent commits)
• Suggested focus areas
• Next steps

Trust Score Calculation:

• Last 7 days: 90-100%
• 7-14 days: 80-90%
• 14-30 days: 60-80%
• 30-60 days: 30-60%
• 60+ days: 30%

Example:

await use_mcp_tool('staprompt', 'analyze_git_history', {
  keyword: 'realtime',
  days: 30
});

7. check_documentation_freshness(doc_path)

Check documentation freshness and trustworthiness.

Parameters:

• doc_path (string): Path to documentation file

Returns:

• Freshness assessment (fresh/recent/aging/stale/archived/deprecated)
• Trust score (0-100%)
• Recommendation
• Red flags

Freshness Levels:

• Fresh (0-7 days): Trust 100%
• Recent (7-30 days): Trust 85%
• Aging (30-90 days): Trust 60%
• Stale (90+ days): Trust 30%
• Archived: Trust 10%
• Deprecated: Trust 10%

Example:

await use_mcp_tool('staprompt', 'check_documentation_freshness', {
  doc_path: 'docs/PRDs/features/messaging/MESSAGING_FPRD.md'
});

8. suggest_mcps(task_type)

Get MCP recommendations for specific task types.

Parameters:

• task_type (string): Type of task
  • "performance" - Performance optimization
  • "testing" - Testing and QA
  • "ui-debugging" - UI/UX debugging
  • "research" - Research and learning
  • "database" - Database work

Returns:

• Primary MCPs with priority
• Secondary MCPs (if applicable)
• Specific commands to use
• When to use each MCP
• Investigation strategy
• Template for planning prompt

Example:

await use_mcp_tool('staprompt', 'suggest_mcps', {
  task_type: 'performance'
});

Typical Workflow

User triggers: qwe Fix performance issues in feed

Step 1: AI recognizes trigger

// AI calls:
await use_mcp_tool('staprompt', 'enter_research_mode', {
  task: 'Fix performance issues in feed'
});

// Returns complete workflow instructions

Step 2: AI asks questions Uses AskUserQuestion tool:

• "What work have you already done?"
• "What specific performance issues?"
• "Any constraints or priorities?"

Step 3: AI does light research (5-15 min)

Git analysis:

await use_mcp_tool('staprompt', 'analyze_git_history', {
  keyword: 'feed',
  days: 30
});
// Returns: Recent commits with trust scores

Doc validation:

await use_mcp_tool('staprompt', 'check_documentation_freshness', {
  doc_path: 'docs/planning/FEED_PERFORMANCE_FIXES_2024-10-31.md'
});
// Returns: Trust score, freshness, recommendation

MCP recommendations:

await use_mcp_tool('staprompt', 'suggest_mcps', {
  task_type: 'performance'
});
// Returns: Chrome DevTools (critical), Exa (high), strategy

File exploration with Glob/Read (skim structure, not implementation)

Step 4: AI writes planning prompt

Following guidelines from enter_research_mode() instructions:

• What's already done
• Fresh baseline
• Context & research
• Suggested approach
• Relevant files
• Recommended MCPs
• Success criteria

Step 5: AI creates planning doc

await use_mcp_tool('staprompt', 'create_planning_doc', {
  content: '# Planning Prompt\n\n...',
  metadata: {
    task: 'Fix feed performance',
    priority: 'high',
    estimated_effort: '2-3 hours',
    related_files: ['src/app/page.tsx', 'src/hooks/useInfiniteScroll.ts']
  }
});
// Returns: docs/planning/fix-feed-performance-2025-01-31.md

Step 6: AI completes handoff

await use_mcp_tool('staprompt', 'handoff_to_plan_mode', {
  doc_path: 'docs/planning/fix-feed-performance-2025-01-31.md'
});
// - Copies planning doc to clipboard
// - Launches Claude Code in plan mode (new terminal window)
// - Exits research mode
// - User pastes with Ctrl+V in new window

Done! AI is back in execution mode, planning doc ready to paste into plan mode.

When NOT to Use

• Simple bug fixes - Just fix directly, no staprompt needed
• UI text changes - No research needed
• Documentation updates - Direct editing is fine
• Single-file changes - No complex planning required

Integration with Existing Workflow

In CLAUDE.md (Minimal)

## Staprompt System

**Trigger:** `qwe [task]`

**Workflow (Automated via MCP):**
1. Call `enter_research_mode(task)` - Get workflow instructions
2. Ask questions - Use AskUserQuestion
3. Light research - Use research helpers, Glob, Read, Exa
4. Write planning prompt - Follow returned guidelines
5. Call `create_planning_doc()` → `handoff_to_plan_mode()`

**The MCP guides you through each step. Follow its instructions.**

Post-Compacting Enforcement

After conversation compacting:

// AI should call:
await use_mcp_tool('staprompt', 'get_current_mode');

// If mode = "research" and planning doc not delivered:
// Complete handoff steps, DO NOT execute

Benefits

1. Reduced Context Token Usage

• Before: 220 lines of staprompt docs in CLAUDE.md
• After: 50 lines of essentials
• Savings: ~1,000-1,500 tokens per session

2. Improved Maintainability

• MCP tools are single source of truth
• No duplication between CLAUDE.md and workflow
• Update once, works everywhere

3. Better User Experience

• Cleaner CLAUDE.md (easier to scan)
• AI gets detailed docs only when needed
• Automated handoff (less error-prone)

4. Preserved Functionality

• All information retained
• Comprehensive workflow guidance
• Zero functionality loss

Development

Building

npm install
npm run build

Watch Mode

npm run watch

Testing Locally

1. Build the MCP:

cd staprompt-mcp
npm install
npm run build

2. Configure Claude Code (.claude/settings.local.json):

{
  "mcpServers": {
    "staprompt-dev": {
      "command": "node",
      "args": ["C:/path/to/staprompt-mcp/build/index.js"]
    }
  }
}

3. Restart Claude Code

4. Test with: qwe Test task

5. Verify tools work:

await use_mcp_tool('staprompt', 'get_current_mode');
await use_mcp_tool('staprompt', 'enter_research_mode', {
  task: 'Test task'
});

Experimental: Auto-Input via Wrapper (POC)

The staprompt MCP includes experimental wrapper scripts that implement --input-file functionality:

How It Works

If claude-with-file.bat exists in the package directory:

• Planning prompt is automatically loaded into plan mode
• No manual Ctrl+V pasting required!
• Falls back to clipboard approach if wrapper is missing

Using the Wrapper Manually

# Windows
cd staprompt
claude-with-file.bat --input-file docs/planning/task.md --permission-mode plan

# Bash
./claude-with-file.sh --input-file docs/planning/task.md --permission-mode plan

Status

• ✅ Windows wrapper implemented
• ✅ Bash wrapper implemented
• ✅ Auto-detection in MCP
• ⏳ Testing in progress
• ❌ Official --input-file flag (pending Claude Code team)

See INPUT_FILE_POC.md for full technical details and proposal for official flag.

Versioning

• v0.x.x - Beta/experimental (breaking changes OK)
• v1.0.0 - First stable release
• v1.x.x - Stable, backwards-compatible only
• v2.0.0 - Breaking changes

Current: v0.2.0 (clipboard fixes + input-file POC)

Contributing

Issues and PRs welcome at: https://github.com/elmodather/staprompt

License

MIT

Credits

Built for vibecoding workflows where AI assistants handle all code generation. Optimized for Claude Code staprompt research mode.

Ready to publish? See PUBLISHING.md for step-by-step publishing guide.