Structural Thinking MCP

MCP server for Prompt → Analysis + Improved Prompt. Analyzes prompts using structural thinking methodology, showing detailed analysis first, then the optimized prompt as clean text.

Tool

• st_refine(prompt, domain?, includeValidation?, includeImprovements?, includeJsonConversion?) → analysis + improved prompt + optional JSON

st_refine - Prompt Enhancement Tool

The st_refine tool enhances your prompts by:

• 🎯 Adding clarity requirements for specific, actionable responses
• 📋 Structuring output format with clear sections and organization
• 🔍 Including success criteria with examples and measurable outcomes
• 🏷️ Adding domain context for better understanding
• ✅ Providing quality scores and readiness assessment

Parameters:

• prompt (required) - The text prompt to analyze
• domain (optional) - Context domain (code, docs, data, product, research)
• includeValidation (optional) - Include validation analysis (default: true)
• includeImprovements (optional) - Include improvement suggestions (default: true)
• includeJsonConversion (optional) - Include JSON conversion for structured prompt engineering (default: false)

Returns analysis displayed on screen, then clean improved prompt:

Analysis Summary

Quality Score: 0.65/1.0
Ready for Use: Yes
Improvements Applied: Added domain context, Added clarity requirements, Added output structure, Added success criteria
Issues Found: 2
Suggestions: 4

Issues Detected

• WARN: Missing markdown sections for output contract (/io/contract/sections)
• INFO: Consider adding constraints (word limit, style, tone) (/constraints)

Validation Warnings

• No constraints specified (/constraints)
• Instructions may be too brief (/instructions)

Improvement Suggestions

1. ADD at /io/contract: {"sections":["Highlights","Details","NextSteps"]}
2. ADD at /constraints: ["max 100 words"]
3. REPLACE at /instructions: [enhanced instructions array]

IMPROVED PROMPT:

Create user authentication system for a web application (Context: code domain). Requirements: Provide a comprehensive response with specific examples and actionable details. Structure the response with clear sections: Overview, Details, and Next Steps. Include specific examples and measurable outcomes where applicable.

Example Usage:

• st_refine("Create user authentication system") - Get improved prompt
• st_refine("Build API endpoint", "code") - With domain context
• st_refine("Write documentation", "docs", true, false) - Skip improvements

Run locally

npm i
npm run build
npm start

This server speaks MCP over stdio (ideal for Cursor and VSCode).

🚀 IDE Integration Guide

📦 Installation

First, install the MCP server globally:

npm install -g structural-thinking-mcp

Or use without global installation:

npx structural-thinking-mcp

🎯 Cursor IDE Setup

Method 1: Using Global Installation (Recommended)

1. Open Cursor Settings:

   • Go to Settings → Features → Model Context Protocol
   • Or use Cmd/Ctrl + , and search for "MCP"

2. Add New MCP Server:

   • Click "Add Server"
   • Server Name: Structural Thinking
   • Command: structural-thinking-mcp (if globally installed)
   • Arguments: Leave empty
   • Environment Variables: Leave empty

3. Enable the Server:

   • Toggle the server ON
   • Restart Cursor to apply changes

Method 2: Using npx (Alternative)

If you prefer not to install globally:

• Command: npx
• Arguments: structural-thinking-mcp

Method 3: Local Development

For local development or custom builds:

• Command: node
• Arguments: /path/to/your/structural-thinking-mcp/dist/server.js

🔧 VSCode Setup

Prerequisites

Install the MCP Extension for VSCode (if available) or use a compatible MCP client.

Configuration

1. Create MCP Configuration: Create or edit your VSCode settings (settings.json):

{
  "mcp.servers": {
    "structural-thinking": {
      "command": "structural-thinking-mcp",
      "args": [],
      "env": {}
    }
  }
}

2. Alternative with npx:

{
  "mcp.servers": {
    "structural-thinking": {
      "command": "npx",
      "args": ["structural-thinking-mcp"],
      "env": {}
    }
  }
}

3. Reload VSCode:
   • Press Cmd/Ctrl + Shift + P
   • Run "Developer: Reload Window"

✅ Testing Your Setup

In Cursor:

1. Open any file or start a new chat
2. Type: st_refine "Create a user authentication system"
3. You should see detailed analysis followed by an improved prompt

In VSCode:

1. Open the Command Palette (Cmd/Ctrl + Shift + P)
2. Look for MCP-related commands
3. Test the st_refine tool with a sample prompt

Expected Output:

## 📊 Analysis Summary
**Quality Score:** 🟡 Good (0.73/1.0)
**Ready for Implementation:** ✅ Yes
...

## 🎯 IMPROVED PROMPT:
Create a user authentication system for a web application. Requirements: Provide a comprehensive response with specific examples and actionable details...

🛠️ Troubleshooting

Common Issues:

❌ "Command not found: structural-thinking-mcp"

• Solution: Install globally with npm install -g structural-thinking-mcp
• Alternative: Use npx structural-thinking-mcp in the command field

❌ "MCP Server not connecting"

• Solution: Restart your IDE after adding the server
• Check: Ensure the command path is correct
• Verify: Run structural-thinking-mcp in terminal to test

❌ "No tools available"

• Solution: Wait a few seconds after IDE restart
• Check: Server status in MCP settings
• Debug: Check IDE console for error messages

Verification Commands:

# Test installation
structural-thinking-mcp --help

# Test with npx
npx structural-thinking-mcp --help

# Check global installation
npm list -g structural-thinking-mcp

💡 Usage Examples

Basic Usage:

st_refine "Write API documentation"

With Domain Context:

st_refine "Build a React component" --domain code

Skip Validation:

st_refine "Create marketing copy" --includeValidation false

With JSON Conversion:

st_refine "Create a pet naming system" --includeJsonConversion true

📋 JSON Conversion Feature

The includeJsonConversion parameter converts your natural language prompt into a structured JSON format ideal for AI prompt engineering. This feature extracts:

📊 JSON Structure:

• Task: Main objective (e.g., "create", "generate", "build")
• Subject: Entity being described (e.g., "pet chinchilla", "login system")
• Constraints: Specific requirements and formatting rules
• Requirements: Quality and content specifications
• Output Format: Desired structure and organization
• Domain: Context domain for better understanding

🎯 Example Output:

{
  "task": "create",
  "subject": "pet naming system",
  "constraints": [
    "10 unique names",
    "each labeled"
  ],
  "requirements": [
    "Provide comprehensive response",
    "Include specific examples", 
    "Structure output clearly",
    "Include actionable details"
  ],
  "outputFormat": {
    "structure": ["Overview", "Details", "Next Steps"],
    "type": "structured response",
    "includeExamples": true,
    "includeMeasurableOutcomes": true
  },
  "domain": "general",
  "originalPrompt": "create a pet naming system with 10 unique names"
}

🚀 Use Cases:

• API Integration: Convert prompts to JSON for programmatic use
• Prompt Engineering: Structure requirements for AI systems
• Documentation: Create structured prompt specifications
• Automation: Enable systematic prompt processing

🔄 Updating

To update to the latest version:

npm update -g structural-thinking-mcp

Then restart your IDE to use the updated version.

📚 Documentation: For more details, see the MCP Protocol Documentation and Cursor MCP Guide.

Development (ts-node)

npm run dev

Schema

See src/schema/structural-thinking.v1.json.

Robust Configuration-Driven System

This solution has been completely validated and optimized with:

🔧 Configuration Management

• No hardcoded values - all scoring parameters are configurable
• Proportional scoring based on text length and context
• Configurable thresholds for all calculation components
• Easy tuning via SCORING_CONFIG object

🛡️ Comprehensive Input Validation

• Parameter validation for all tool inputs
• Length and type checking with proper error messages
• Graceful error handling with try-catch blocks throughout
• Domain validation for structured thinking contexts

📊 Enhanced Dynamic Metrics

Clarity Score (0.0-1.0) with proportional calculation:

• Vague language penalty (optimize, better, good, etc.) - proportional to text length
• Clarity indicators bonus (specifically, must, required, etc.)
• Concrete measurements bonus (numbers with units: words, hours, %, etc.)
• Action verbs bonus (create, analyze, compare, etc.)
• Sentence structure analysis with configurable thresholds
• Structured formatting bonus (bullets, lists)

Completeness Score (0.0-1.0) with word-count based analysis:

• Essential component presence (title, instructions, constraints)
• Context domain specification
• Output format requirements
• Section definitions for structured output
• Instruction depth using word count (not character count)
• Examples and concrete references
• Enhanced instruction quality assessment

🔍 Advanced Pattern Matching

• Expanded word lists with regex variations (plurals, tenses)
• Improved pattern detection with word boundaries
• Context-aware scoring based on domain and content type
• Better edge case handling for calculations

Validation & Quality Assurance

• ✅ Zero hardcoded values - fully configuration-driven
• ✅ Comprehensive input validation on all tool parameters
• ✅ Robust error handling with graceful degradation
• ✅ Proportional scoring that scales with content size
• ✅ No lint errors - clean, production-ready code
• ✅ Enhanced pattern matching with proper regex boundaries
• ✅ Word-count based analysis instead of character counting
• ✅ Improvement tracking showing before/after metric changes
• ⭐ Complete workflow integration with st_refine combining all analysis tools

Testing

The project includes comprehensive unit testing with Jest:

# Run all tests
npm test

# Run tests in watch mode  
npm run test:watch

# Run tests with coverage report
npm run test:coverage

# Run integration tests only
npm run test:integration

Test Structure

• tests/unit/ - Unit tests for core functionality and helper functions
• tests/integration/ - Integration tests for the complete st_refine tool workflow
• tests/performance/ - Performance tests for measuring response times and memory usage
• tests/schema/ - Schema validation tests for Structural Thinking v1 specification

Coverage Targets

• Branches: 70%
• Functions: 70%
• Lines: 70%
• Statements: 70%

CI/CD Integration

The project includes GitHub Actions workflow for automated testing:

• Tests run on Node.js versions 18.x, 20.x, and 22.x
• Coverage reports are uploaded to Codecov
• Security audits are performed on dependencies
• Build artifacts are validated

Notes

• This system uses a rule-based parser with extensive configuration options
• No prompt execution by design (analysis-focused scope)
• Metrics recalculated dynamically with proper rounding and validation
• All calculations validated for edge cases and error conditions
• Ready for production with comprehensive error handling
• Full test coverage with unit, integration, and performance testing

Generated: 2025-09-02T05:36:57.820062