StackGuide MCP Server

Dynamic context loading for AI coding assistants. Works with Cursor and GitHub Copilot.

🚀 Quick Start

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "stackguide": {
      "command": "npx",
      "args": ["-y", "@stackguide/mcp-server"]
    }
  }
}

VS Code (.vscode/mcp.json): Same config as above.

💬 Usage

Just talk naturally:

• "Set up my project" → Auto-configures with interactive wizard
• "Review my code" → Analyzes with AST-powered Quick Fixes
• "Generate a component" → Creates boilerplate code
• "Check project health" → Returns health score (A-F)
• "Analyze my project" → Auto-configuration intelligence
• "Browse React rules" → Shows community rules
• "Configure rules" → NEW! Customize analysis rules

🛠️ Tools (13 total)

Core Tools

Tool	Description	Example
setup	Configure project with wizard	setup or setup type:"react-typescript"
context	View current configuration	context or context full:true
rules	List, search, get rules	rules action:"search" query:"security"
knowledge	Access patterns & solutions	knowledge action:"get" query:"architecture"
review	Review code with Quick Fixes	review file:"src/index.ts" focus:"security"

Advanced Features

Tool	Description	Example
generate	Generate boilerplate code	generate type:"component" name:"UserCard"
health	Project health score (A-F)	health detailed:true
analyze	NEW! Project intelligence	analyze action:"full" path:"./my-project"

Integration Tools

Tool	Description	Example
cursor	Browse cursor.directory	cursor action:"browse" query:"react"
docs	Fetch web documentation	docs action:"fetch" url:"https://..."
config	Save/load configurations	config action:"save" name:"my-project"
custom_rule	Create custom rules	custom_rule action:"create" name:"..." content:"..."
help	Get help	help or help topic:"generate"

New in v2.4.0: Advanced Features

🏭 Template Generator

Generate boilerplate for components, hooks, services, tests, API routes, models, and utilities:

generate type:"component" name:"UserCard"
generate type:"hook" name:"useAuth"  
generate type:"service" name:"ApiService"
generate type:"test" name:"UserCard" options:{"framework":"vitest"}
generate type:"api" name:"Users" options:{"framework":"nextjs"}

🔧 Quick Fix Suggestions

Code review now includes actionable Quick Fixes:

🔴 [SEC001] Avoid using eval() - it can execute arbitrary code
- Line: 15
- Code: `eval(userInput)`
- 🔧 Quick Fix: Replace eval() with JSON.parse()
  - Replace: `eval(` → With: `JSON.parse(`

🏥 Project Health Score

Get a comprehensive health analysis with grade (A-F):

health detailed:true

Returns:

• Overall score (0-100) with grade
• Category breakdown (Configuration, Code Quality, Structure, Docs, Testing)
• Critical issues and recommendations

🧙 Interactive Setup Wizard

Setup now provides tailored recommendations:

{
  "wizard": {
    "recommendations": {
      "suggestedTools": ["ESLint", "Prettier", "TypeScript strict mode"],
      "vsCodeExtensions": ["ES7+ React snippets", "Error Lens"],
      "tips": ["Use functional components", "Memoize with useMemo"]
    },
    "nextSteps": ["Run `context`", "Run `review`", "Run `health`"]
  }
}

🆕 New in v3.7.0: Configurable Rules Engine

Custom Rules CRUD

Create, update, delete, and manage custom rules with full persistence:

# Create custom rule
rules action:"create" rule:{"id":"MY-001", "name":"Custom Rule", "description":"...", "severity":"warning", "pattern":"console\\.log"}

# Update rule
rules action:"update" ruleId:"MY-001" updates:{"severity":"error"}

# Delete rule
rules action:"delete" ruleId:"MY-001"

# List all rules (builtin + custom)
rules action:"list" category:"security"

# Import/Export rules
rules action:"export" format:"json"
rules action:"import" rules:[...]

Rule Overrides

Override builtin rule behavior without modifying them:

# Disable a rule
rules action:"override" ruleId:"TS-SEC001" override:{"enabled":false}

# Change severity
rules action:"override" ruleId:"TS-PERF002" override:{"severity":"error"}

# Custom message
rules action:"override" ruleId:"TS-BP001" override:{"customMessage":"Use arrow functions in this project"}

# File-specific overrides
rules action:"override" ruleId:"TS-SEC002" override:{"filePatterns":["!**/tests/**"]}

# Remove override
rules action:"clearOverride" ruleId:"TS-SEC001"

Rule Settings

Configure global rule behavior:

# Get current settings
rules action:"settings"

# Update settings
rules action:"updateSettings" settings:{"enableBuiltin":true, "enableCustom":true, "defaultSeverity":"warning"}

---

🆕 New in v3.6.0: Input Validation (Zod)

All tool inputs are now validated with Zod schemas:

• Type-safe inputs: All parameters are validated against schemas
• Helpful error messages: Clear validation errors with path information
• Path sanitization: Prevents path traversal attacks
• Automatic sanitization: Sensitive data is masked in logs

// Example validation error
{
  "success": false,
  "error": "Validation failed",
  "issues": [
    { "path": ["file"], "message": "Required" },
    { "path": ["focus"], "message": "Invalid enum value. Expected 'security' | 'performance' | 'best-practices'" }
  ]
}

---

🆕 New in v3.5.0: AST-Powered Analysis (Tree-sitter)

Real Semantic Code Analysis

Code review now uses tree-sitter for accurate AST-based analysis:

review file:"src/index.ts" focus:"security"

Supported Languages: TypeScript, JavaScript, Python, Go, Rust

Analysis Categories:

• 🔒 Security: eval detection, SQL injection, XSS, hardcoded secrets
• ⚡ Performance: nested loops, inefficient operations
• ✨ Best Practices: any usage, console.log in production, unused vars
• 🏗️ Maintainability: function complexity, file length

Code Metrics:

{
  "metrics": {
    "linesOfCode": 150,
    "functions": 12,
    "classes": 3,
    "imports": 8,
    "exports": 5,
    "complexity": 24,
    "maxNesting": 4
  }
}

---

🆕 New in v3.4.0: Architecture Improvements

SQLite Persistence

All configuration now persists across sessions:

config action:"save" name:"my-project"
config action:"load" name:"my-project"
config action:"list"
config action:"delete" name:"my-project"

Real Filesystem Access

Analyze actual project files:

analyze action:"full" path:"./src"
health detailed:true

HTTP Client with Caching

Rate-limited API calls with automatic caching:

docs action:"fetch" url:"https://react.dev/reference/react"
cursor action:"browse" query:"nextjs"

---

New in v3.3.0: Auto-Configuration Intelligence 🧠

Project Intelligence Analysis

Get comprehensive analysis with actionable recommendations:

analyze action:"full" path:"./my-project"
analyze action:"structure"     # Analyze only project structure
analyze action:"config"        # Analyze only configurations
analyze action:"dependencies"  # Analyze only dependencies
analyze action:"generate" configType:"eslint"  # Generate optimal config
analyze action:"apply"         # Apply all auto-fixes

Returns:

• Overall Score (0-100) with grade (A-F)
• Structure Analysis: Missing dirs/files, directory organization
• Configuration Analysis: Missing ESLint, Prettier, TSConfig recommendations
• Dependency Analysis: Missing packages, security advisories
• Priority Actions: Sorted by impact with estimated effort
• Suggested Workflow: Step-by-step improvement plan

{
  "overallScore": 72,
  "grade": "C",
  "priorityActions": [
    { "action": "Add ESLint configuration", "priority": "high", "impact": "Improves code quality" },
    { "action": "Add tests directory", "priority": "medium", "impact": "Enables testing" }
  ],
  "suggestedWorkflow": [
    { "step": 1, "action": "Run `analyze action:generate configType:eslint`" },
    { "step": 2, "action": "Run `analyze action:generate configType:prettier`" }
  ]
}

Enhanced Setup with Intelligence

Setup now includes quick intelligence analysis:

{
  "intelligence": {
    "structureScore": 85,
    "configScore": 60,
    "dependencyScore": 90,
    "quickWins": ["Add .prettierrc for consistent formatting"]
  }
}

📋 Supported Stacks

python-django · python-fastapi · python-flask · react-node · react-typescript · vue-node · nextjs · express · nestjs · laravel · rails · golang · rust

📖 Examples

# Auto-setup with wizard
setup

# Generate React component
generate type:"component" name:"Dashboard"

# Review with AST-powered Quick Fixes
review file:"src/App.tsx" focus:"performance"

# Check project health
health

# Analyze project intelligence
analyze action:"full"
analyze action:"generate" configType:"prettier"

# Browse and import community rules
cursor action:"popular"
cursor action:"import" slug:"typescript-best-practices"

# Configure rules
rules action:"list" category:"security"
rules action:"create" rule:{"id":"MY-001", "name":"No TODO", "pattern":"TODO", "severity":"info"}
rules action:"override" ruleId:"TS-SEC001" override:{"severity":"error"}

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                    MCP Server                            │
├─────────────────────────────────────────────────────────┤
│  Router (handler registration + validation)              │
├─────────────────────────────────────────────────────────┤
│  Handlers (setup, review, generate, health, etc.)        │
├─────────────────────────────────────────────────────────┤
│  Services Layer                                          │
│  ├── AST Analysis (tree-sitter multi-language)          │
│  ├── Rules Engine (builtin + custom + overrides)        │
│  ├── Code Analyzer (semantic analysis)                  │
│  ├── Rule Manager (data loading)                        │
│  └── Auto Detect (project type detection)               │
├─────────────────────────────────────────────────────────┤
│  Infrastructure                                          │
│  ├── Validation (Zod schemas)                           │
│  ├── Persistence (SQLite storage)                       │
│  ├── ProjectFs (filesystem abstraction)                 │
│  └── HttpClient (rate-limited + cached)                 │
└─────────────────────────────────────────────────────────┘

🧪 Testing

# Run all tests
npm test

# With coverage
npm run test:coverage

# Watch mode
npm run test:watch

Test Statistics: 659 tests across 35 test files

📚 API Reference

Tool Parameters

setup

Parameter	Type	Description
type	string	Project type (optional, auto-detected)
path	string	Project path (default: current dir)

review

Parameter	Type	Description
file	string	Required. File path to review
content	string	File content (optional, read from file)
focus	string	security | performance | best-practices
detailed	boolean	Include code metrics

generate

Parameter	Type	Description
type	string	Required. component | hook | service | test | api | model | util
name	string	Required. Name for generated code
options	object	Framework-specific options

rules

Parameter	Type	Description
action	string	Required. list | search | get | create | update | delete | override | clearOverride | settings | import | export
ruleId	string	Rule ID (for get/update/delete/override)
rule	object	Rule definition (for create)
override	object	Override settings
category	string	Filter by category

health

Parameter	Type	Description
detailed	boolean	Include category breakdown
path	string	Project path

analyze

Parameter	Type	Description
action	string	Required. full | structure | config | dependencies | generate | apply
path	string	Project path
configType	string	For generate: eslint | prettier | tsconfig

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing)
3. Run tests (npm test)
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing)
6. Open a Pull Request

📄 License

MIT