Smart MCP

SuperClaude-style global MCP framework for custom instruction shortcuts. Create reusable command shortcuts that work from ANY directory.

What is Smart MCP?

Smart MCP is a Model Context Protocol (MCP) server that provides:

Slash Commands - Global /sm:* commands accessible from any directory
Smart Tool - sm MCP tool for executing custom instruction shortcuts
Hierarchical Configuration - Global defaults with project-specific overrides

Current Implementation

Component	Status	Lines	Description
MCP Server	✅ Production	~100	Python server with hierarchical shortcuts loading
/sm:refactor	✅ Ready	183 lines	Surgical refactoring with golden-master testing
/sm:debug	✅ Ready	129 lines	7-step systematic debugging process
/sm:audit	✅ Ready	204 lines	8-stage repository assessment
/sm:introspect	✅ Ready	247 lines	Meta-cognitive solution analysis

Latest Update: Fixed /sm:introspect synchronization bug - all 4 commands now fully global (2025-11-06)

Features

Global Architecture: Works from any directory once configured
Hierarchical Shortcuts: Global defaults + project-specific overrides
Single Tool Interface: All shortcuts accessible via one sm tool
Slash Commands: /sm:refactor, /sm:debug, /sm:audit, /sm:introspect work everywhere
JSON-Based Storage: Easy to read and edit shortcut definitions
Variable Substitution: Use {task}, {file}, {context}, or {target} placeholders
Extensible: Add global or project-specific shortcuts

Architecture

Dual-Interface System

Smart MCP uses a two-stage architecture combining Claude Code slash commands with an MCP server:

┌─────────────────────────────────────────────┐
│ Stage 1: Slash Commands (.md files)         │
│ Location: ~/.claude/commands/sm/*.md       │
│ Purpose: Discovery, documentation, metadata │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│ Stage 2: MCP Server (shortcuts.json)        │
│ Location: ~/.claude/smart_mcp/shortcuts.json│
│ Purpose: Instruction storage, variables     │
└─────────────────────────────────────────────┘

File Structure

~/.claude/                           # Global SuperClaude configuration
├── smart_mcp/
│   └── shortcuts.json              # Global instruction storage (REQUIRED)
├── commands/sm/
│   ├── refactor.md                 # /sm:refactor interface (REQUIRED)
│   ├── debug.md                    # /sm:debug interface (REQUIRED)
│   ├── audit.md                    # /sm:audit interface (REQUIRED)
│   └── introspect.md               # /sm:introspect interface (REQUIRED)
├── MCP_SmartMCP.md                 # Integration documentation
└── CLAUDE.md                       # Global working contract

Project (Optional Override):
$CWD/shortcuts.json                 # Project-specific shortcuts

Synchronization Requirement

CRITICAL: Both components must be deployed together:

✅ .md file in ~/.claude/commands/sm/ (interface)
✅ Entry in ~/.claude/smart_mcp/shortcuts.json (implementation)

Missing either component will cause the command to fail.

Merge Strategy: Project-local shortcuts override global (like .gitignore)

Quick Start

Installation

Install the MCP server:

git clone https://github.com/btangonan/smart_mcp.git
cd smart_mcp
./scripts/install.sh

Configure Claude Desktop:

{
  "mcpServers": {
    "smart-mcp": {
      "type": "stdio",
      "command": "python3",
      "args": ["/absolute/path/to/smart_mcp/smart_mcp.py"],
      "env": {}
    }
  }
}

Restart Claude Desktop

Usage

Slash Commands (Global)

/sm:refactor auth.ts           # Surgical refactoring with testing
/sm:debug login-error          # 7-step debugging process
/sm:audit                      # Repository assessment
/sm:introspect                 # Meta-cognitive analysis

Smart Tool (Via MCP)

// In Claude Code conversations
sm { "shortcut": "refactor", "context": "auth.ts" }
sm { "shortcut": "debug", "context": "login-error" }

Available Commands

/sm:refactor

Purpose: Surgical refactoring with golden-master testing and fitness functions

Use When:

Need to improve code quality without changing behavior
Want systematic refactoring with safety validation
Reducing technical debt methodically

Key Features:

Pre/post behavior capture for safety
Fitness functions for quality metrics
Incremental improvements with validation

/sm:debug

Purpose: 7-step systematic debugging process

Use When:

Facing complex bugs or unexpected behavior
Need structured approach to problem-solving
Want to avoid debugging anti-patterns

Key Features:

Evidence-based hypothesis generation
Systematic root cause analysis
Solution validation framework

/sm:audit

Purpose: 8-stage comprehensive repository assessment

Use When:

Need to assess codebase health
Preparing for technical debt reduction
Evaluating project maturity

Key Features:

LOC discipline analysis
Validation coverage assessment
Secrets hygiene scanning
Maturity scoring (0-3 scale)

/sm:introspect

Purpose: Meta-cognitive analysis for solution soundness evaluation

Use When:

Unsure if solving the RIGHT problem
Need to validate approach before implementation
Want to detect cognitive biases

Key Features:

Naive-agent perspective reset
Alternative hypothesis generation (min 3)
Cognitive bias detection
Soundness scoring with recommendations

Configuration

Global Shortcuts

Located at ~/.claude/smart_mcp/shortcuts.json:

{
  "shortcuts": {
    "refactor": {
      "description": "Surgical refactoring with golden-master testing",
      "instruction": "..."
    },
    "debug": {
      "description": "7-step debugging process",
      "instruction": "..."
    },
    "audit": {
      "description": "Repository assessment",
      "instruction": "..."
    },
    "introspect": {
      "description": "Meta-cognitive analysis",
      "instruction": "..."
    }
  }
}

Project-Specific Shortcuts

Create shortcuts.json in your project directory:

{
  "shortcuts": {
    "deploy": {
      "description": "Deploy to staging",
      "instruction": "Deploy {target} to staging environment with pre-flight checks"
    },
    "refactor": {
      "description": "Custom refactor for this project",
      "instruction": "Project-specific refactoring rules..."
    }
  }
}

Merge Behavior:

deploy - Available only in this project (new shortcut)
refactor - Uses project version (overrides global)
debug, audit, introspect - Use global versions (no override)

Management Scripts

Backup Global Files

./scripts/backup.sh              # Copy ~/.claude/ → global/
./scripts/backup.sh --commit     # Backup and auto-commit
./scripts/backup.sh --dry-run    # Preview changes

Install Global Files

./scripts/install.sh             # Copy global/ → ~/.claude/
./scripts/install.sh --force     # Overwrite without prompt
./scripts/install.sh --dry-run   # Preview installation

Sync and Check Status

./scripts/sync.sh                # Check sync status
./scripts/sync.sh --to-global    # Force ~/.claude/ → global/
./scripts/sync.sh --to-claude    # Force global/ → ~/.claude/

Documentation

FOR_FUTURE_CLAUDE.md - Complete system overview for new agents
GLOBAL_SETUP.md - Detailed installation and setup guide
IMPLEMENTATION_SUMMARY.md - Technical architecture details

Troubleshooting

Slash commands not appearing

Problem: /sm:refactor shows "command not found"

Solution:

# Verify files exist
ls ~/.claude/commands/sm/

# Should show: audit.md, debug.md, introspect.md, refactor.md
# If missing, run: ./scripts/install.sh

MCP tool not available

Problem: sm tool returns "No such tool available"

Solution:

Check Claude Desktop config has correct absolute path to smart_mcp.py
Restart Claude Desktop completely
Start new Claude Code session
If still failing, check MCP server logs

Shortcuts not loading

Problem: sm tool works but returns empty or old shortcuts

Solution:

# Verify shortcuts.json exists
cat ~/.claude/smart_mcp/shortcuts.json

# Check for JSON syntax errors
python3 -m json.tool ~/.claude/smart_mcp/shortcuts.json

# If corrupted, restore from repo
./scripts/install.sh --force

Chroma MCP race condition

Problem: First Chroma call fails with "No such tool available"

Solution: This is handled automatically by global CLAUDE.md Session Lifecycle rules - waits 2 seconds and retries once. If persists, verify Chroma MCP server is configured in Claude Desktop.

Development

Project Structure

smart_mcp/
├── smart_mcp.py               # MCP server with hierarchical loading
├── shortcuts.json             # Example/override shortcuts
├── CLAUDE.md                  # Project-specific contract
├── README.md                  # This file
├── .claude/
│   └── commands/sm/           # Reference commands (deprecated)
├── global/                    # Version-controlled global files
│   ├── CLAUDE.md              # Global SuperClaude framework
│   ├── commands/sm/           # Canonical slash commands
│   ├── smart_mcp/shortcuts.json
│   └── MCP_SmartMCP.md
├── scripts/                   # Management scripts
│   ├── install.sh
│   ├── backup.sh
│   └── sync.sh
├── docs/                      # Documentation
└── archive/                   # Obsolete planning documents

Adding New Slash Commands

IMPORTANT: Both .md file AND shortcuts.json entry are required. Missing either breaks the command.

Step-by-Step Process:

Create .md file: global/commands/sm/commandname.md

---
name: commandname
description: "Brief one-line description"
category: gitignored
complexity: basic|intermediate|advanced
mcp-servers: [sequential, chroma]
personas: [architect, auditor]
---

# Documentation sections
# See existing commands for template

## Invocation
This command executes: `Use the sm tool with shortcut='commandname' and context='$ARGS'`

Add to shortcuts.json: global/smart_mcp/shortcuts.json

{
  "shortcuts": {
    "commandname": {
      "description": "Same as .md description",
      "instruction": "Full instruction framework with {task} {context} placeholders"
    }
  }
}

Deploy: ./scripts/install.sh (copies to ~/.claude/)

Verify:

ls ~/.claude/commands/sm/commandname.md
grep "commandname" ~/.claude/smart_mcp/shortcuts.json

# CRITICAL: Test from outside repo to verify global deployment
cd /tmp && /sm:commandname test

Commit: ./scripts/backup.sh --commit

Project-Local Shortcut (override global):

Create shortcuts.json in project directory
Add shortcuts (same format as global)
Project shortcuts override global (hierarchical merge)

Creating Slash Commands

Create markdown file in ~/.claude/commands/sm/
Add YAML frontmatter:

---
tags: project, gitignored
---

Write command instructions
Optionally add to shortcuts.json for sm tool access

Benefits

✅ Global Accessibility - Commands work from ANY directory ✅ SuperClaude Integration - Follows /sc:* command pattern ✅ Hierarchical Config - Global defaults + project overrides ✅ Version Controlled - Global files backed up in repo ✅ Zero Duplication - No copying commands to every project ✅ Extensible - Easy to add custom shortcuts ✅ Maintainable - Clear separation of global vs project config

Limitations

Absolute Paths Required - Claude Desktop config needs absolute path to smart_mcp.py
Restart Required - Claude Desktop restart needed for config/shortcut changes
JSON Validation - Invalid JSON in shortcuts.json fails silently
No Hot Reload - Shortcut changes require new Claude Code session

Contributing

Fork the repository
Create feature branch
Make changes
Test with ./scripts/install.sh --dry-run
Backup and commit: ./scripts/backup.sh --commit
Submit pull request

License

MIT License - See LICENSE file for details

Credits

Built with the SuperClaude framework pattern for global Claude Code configuration.

Changelog

2025-10-23

Added Chroma MCP race condition fix to global CLAUDE.md
Cleaned up documentation structure
Archived obsolete planning documents
Updated README to reflect actual implementation

2025-10-19

Added /sm:introspect command for meta-cognitive analysis
Enhanced global file management with backup/sync scripts

2025-10-17

Transformed to global SuperClaude-style framework
Implemented hierarchical shortcuts loading
Created global slash commands (/sm:refactor, /sm:debug, /sm:audit)
Added comprehensive documentation

2025-10-16

Initial project creation
Basic MCP server implementation
Project-local slash commands

Smart MCP

SuperClaude-style global MCP framework for custom instruction shortcuts. Create reusable command shortcuts that work from ANY directory.

What is Smart MCP?

Smart MCP is a Model Context Protocol (MCP) server that provides:

Slash Commands - Global /sm:* commands accessible from any directory
Smart Tool - sm MCP tool for executing custom instruction shortcuts
Hierarchical Configuration - Global defaults with project-specific overrides

Current Implementation

Component	Status	Lines	Description
MCP Server	✅ Production	~100	Python server with hierarchical shortcuts loading
/sm:refactor	✅ Ready	183 lines	Surgical refactoring with golden-master testing
/sm:debug	✅ Ready	129 lines	7-step systematic debugging process
/sm:audit	✅ Ready	204 lines	8-stage repository assessment
/sm:introspect	✅ Ready	247 lines	Meta-cognitive solution analysis

Latest Update: Fixed /sm:introspect synchronization bug - all 4 commands now fully global (2025-11-06)

Features

Global Architecture: Works from any directory once configured
Hierarchical Shortcuts: Global defaults + project-specific overrides
Single Tool Interface: All shortcuts accessible via one sm tool
Slash Commands: /sm:refactor, /sm:debug, /sm:audit, /sm:introspect work everywhere
JSON-Based Storage: Easy to read and edit shortcut definitions
Variable Substitution: Use {task}, {file}, {context}, or {target} placeholders
Extensible: Add global or project-specific shortcuts

Architecture

Dual-Interface System

Smart MCP uses a two-stage architecture combining Claude Code slash commands with an MCP server:

┌─────────────────────────────────────────────┐
│ Stage 1: Slash Commands (.md files)         │
│ Location: ~/.claude/commands/sm/*.md       │
│ Purpose: Discovery, documentation, metadata │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│ Stage 2: MCP Server (shortcuts.json)        │
│ Location: ~/.claude/smart_mcp/shortcuts.json│
│ Purpose: Instruction storage, variables     │
└─────────────────────────────────────────────┘

File Structure

~/.claude/                           # Global SuperClaude configuration
├── smart_mcp/
│   └── shortcuts.json              # Global instruction storage (REQUIRED)
├── commands/sm/
│   ├── refactor.md                 # /sm:refactor interface (REQUIRED)
│   ├── debug.md                    # /sm:debug interface (REQUIRED)
│   ├── audit.md                    # /sm:audit interface (REQUIRED)
│   └── introspect.md               # /sm:introspect interface (REQUIRED)
├── MCP_SmartMCP.md                 # Integration documentation
└── CLAUDE.md                       # Global working contract

Project (Optional Override):
$CWD/shortcuts.json                 # Project-specific shortcuts

Synchronization Requirement

CRITICAL: Both components must be deployed together:

✅ .md file in ~/.claude/commands/sm/ (interface)
✅ Entry in ~/.claude/smart_mcp/shortcuts.json (implementation)

Missing either component will cause the command to fail.

Merge Strategy: Project-local shortcuts override global (like .gitignore)

Quick Start

Installation

Install the MCP server:

git clone https://github.com/btangonan/smart_mcp.git
cd smart_mcp
./scripts/install.sh

Configure Claude Desktop:

{
  "mcpServers": {
    "smart-mcp": {
      "type": "stdio",
      "command": "python3",
      "args": ["/absolute/path/to/smart_mcp/smart_mcp.py"],
      "env": {}
    }
  }
}

Restart Claude Desktop

Usage

Slash Commands (Global)

/sm:refactor auth.ts           # Surgical refactoring with testing
/sm:debug login-error          # 7-step debugging process
/sm:audit                      # Repository assessment
/sm:introspect                 # Meta-cognitive analysis

Smart Tool (Via MCP)

// In Claude Code conversations
sm { "shortcut": "refactor", "context": "auth.ts" }
sm { "shortcut": "debug", "context": "login-error" }

Available Commands

/sm:refactor

Purpose: Surgical refactoring with golden-master testing and fitness functions

Use When:

Need to improve code quality without changing behavior
Want systematic refactoring with safety validation
Reducing technical debt methodically

Key Features:

Pre/post behavior capture for safety
Fitness functions for quality metrics
Incremental improvements with validation

/sm:debug

Purpose: 7-step systematic debugging process

Use When:

Facing complex bugs or unexpected behavior
Need structured approach to problem-solving
Want to avoid debugging anti-patterns

Key Features:

Evidence-based hypothesis generation
Systematic root cause analysis
Solution validation framework

/sm:audit

Purpose: 8-stage comprehensive repository assessment

Use When:

Need to assess codebase health
Preparing for technical debt reduction
Evaluating project maturity

Key Features:

LOC discipline analysis
Validation coverage assessment
Secrets hygiene scanning
Maturity scoring (0-3 scale)

/sm:introspect

Purpose: Meta-cognitive analysis for solution soundness evaluation

Use When:

Unsure if solving the RIGHT problem
Need to validate approach before implementation
Want to detect cognitive biases

Key Features:

Naive-agent perspective reset
Alternative hypothesis generation (min 3)
Cognitive bias detection
Soundness scoring with recommendations

Configuration

Global Shortcuts

Located at ~/.claude/smart_mcp/shortcuts.json:

{
  "shortcuts": {
    "refactor": {
      "description": "Surgical refactoring with golden-master testing",
      "instruction": "..."
    },
    "debug": {
      "description": "7-step debugging process",
      "instruction": "..."
    },
    "audit": {
      "description": "Repository assessment",
      "instruction": "..."
    },
    "introspect": {
      "description": "Meta-cognitive analysis",
      "instruction": "..."
    }
  }
}

Project-Specific Shortcuts

Create shortcuts.json in your project directory:

{
  "shortcuts": {
    "deploy": {
      "description": "Deploy to staging",
      "instruction": "Deploy {target} to staging environment with pre-flight checks"
    },
    "refactor": {
      "description": "Custom refactor for this project",
      "instruction": "Project-specific refactoring rules..."
    }
  }
}

Merge Behavior:

deploy - Available only in this project (new shortcut)
refactor - Uses project version (overrides global)
debug, audit, introspect - Use global versions (no override)

Management Scripts

Backup Global Files

./scripts/backup.sh              # Copy ~/.claude/ → global/
./scripts/backup.sh --commit     # Backup and auto-commit
./scripts/backup.sh --dry-run    # Preview changes

Install Global Files

./scripts/install.sh             # Copy global/ → ~/.claude/
./scripts/install.sh --force     # Overwrite without prompt
./scripts/install.sh --dry-run   # Preview installation

Sync and Check Status

./scripts/sync.sh                # Check sync status
./scripts/sync.sh --to-global    # Force ~/.claude/ → global/
./scripts/sync.sh --to-claude    # Force global/ → ~/.claude/

Documentation

FOR_FUTURE_CLAUDE.md - Complete system overview for new agents
GLOBAL_SETUP.md - Detailed installation and setup guide
IMPLEMENTATION_SUMMARY.md - Technical architecture details

Troubleshooting

Slash commands not appearing

Problem: /sm:refactor shows "command not found"

Solution:

# Verify files exist
ls ~/.claude/commands/sm/

# Should show: audit.md, debug.md, introspect.md, refactor.md
# If missing, run: ./scripts/install.sh

MCP tool not available

Problem: sm tool returns "No such tool available"

Solution:

Check Claude Desktop config has correct absolute path to smart_mcp.py
Restart Claude Desktop completely
Start new Claude Code session
If still failing, check MCP server logs

Shortcuts not loading

Problem: sm tool works but returns empty or old shortcuts

Solution:

# Verify shortcuts.json exists
cat ~/.claude/smart_mcp/shortcuts.json

# Check for JSON syntax errors
python3 -m json.tool ~/.claude/smart_mcp/shortcuts.json

# If corrupted, restore from repo
./scripts/install.sh --force

Chroma MCP race condition

Problem: First Chroma call fails with "No such tool available"

Solution: This is handled automatically by global CLAUDE.md Session Lifecycle rules - waits 2 seconds and retries once. If persists, verify Chroma MCP server is configured in Claude Desktop.

Development

Project Structure

smart_mcp/
├── smart_mcp.py               # MCP server with hierarchical loading
├── shortcuts.json             # Example/override shortcuts
├── CLAUDE.md                  # Project-specific contract
├── README.md                  # This file
├── .claude/
│   └── commands/sm/           # Reference commands (deprecated)
├── global/                    # Version-controlled global files
│   ├── CLAUDE.md              # Global SuperClaude framework
│   ├── commands/sm/           # Canonical slash commands
│   ├── smart_mcp/shortcuts.json
│   └── MCP_SmartMCP.md
├── scripts/                   # Management scripts
│   ├── install.sh
│   ├── backup.sh
│   └── sync.sh
├── docs/                      # Documentation
└── archive/                   # Obsolete planning documents

Adding New Slash Commands

IMPORTANT: Both .md file AND shortcuts.json entry are required. Missing either breaks the command.

Step-by-Step Process:

Create .md file: global/commands/sm/commandname.md

---
name: commandname
description: "Brief one-line description"
category: gitignored
complexity: basic|intermediate|advanced
mcp-servers: [sequential, chroma]
personas: [architect, auditor]
---

# Documentation sections
# See existing commands for template

## Invocation
This command executes: `Use the sm tool with shortcut='commandname' and context='$ARGS'`

Add to shortcuts.json: global/smart_mcp/shortcuts.json

{
  "shortcuts": {
    "commandname": {
      "description": "Same as .md description",
      "instruction": "Full instruction framework with {task} {context} placeholders"
    }
  }
}

Deploy: ./scripts/install.sh (copies to ~/.claude/)

Verify:

ls ~/.claude/commands/sm/commandname.md
grep "commandname" ~/.claude/smart_mcp/shortcuts.json

# CRITICAL: Test from outside repo to verify global deployment
cd /tmp && /sm:commandname test

Commit: ./scripts/backup.sh --commit

Project-Local Shortcut (override global):

Create shortcuts.json in project directory
Add shortcuts (same format as global)
Project shortcuts override global (hierarchical merge)

Creating Slash Commands

Create markdown file in ~/.claude/commands/sm/
Add YAML frontmatter:

---
tags: project, gitignored
---

Write command instructions
Optionally add to shortcuts.json for sm tool access

Benefits

Limitations

Absolute Paths Required - Claude Desktop config needs absolute path to smart_mcp.py
Restart Required - Claude Desktop restart needed for config/shortcut changes
JSON Validation - Invalid JSON in shortcuts.json fails silently
No Hot Reload - Shortcut changes require new Claude Code session

Contributing

Fork the repository
Create feature branch
Make changes
Test with ./scripts/install.sh --dry-run
Backup and commit: ./scripts/backup.sh --commit
Submit pull request

License

MIT License - See LICENSE file for details

Credits

Built with the SuperClaude framework pattern for global Claude Code configuration.

Changelog

2025-10-23

Added Chroma MCP race condition fix to global CLAUDE.md
Cleaned up documentation structure
Archived obsolete planning documents
Updated README to reflect actual implementation

2025-10-19

Added /sm:introspect command for meta-cognitive analysis
Enhanced global file management with backup/sync scripts

2025-10-17

Transformed to global SuperClaude-style framework
Implemented hierarchical shortcuts loading
Created global slash commands (/sm:refactor, /sm:debug, /sm:audit)
Added comprehensive documentation

2025-10-16

Initial project creation
Basic MCP server implementation
Project-local slash commands