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:

1. Slash Commands - Global /sm:* commands accessible from any directory

2. Smart Tool - sm MCP tool for executing custom instruction shortcuts

3. Hierarchical Configuration - Global defaults with project-specific overrides

Current Implementation

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:

File Structure

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

1. Install the MCP server:

2. Configure Claude Desktop:

3. Restart Claude Desktop

Usage

Slash Commands (Global)

Smart Tool (Via MCP)

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:

Project-Specific Shortcuts

Create shortcuts.json in your project directory:

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

Install Global Files

Sync and Check Status

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:

MCP tool not available

Problem: sm tool returns "No such tool available"

Solution:

1. Check Claude Desktop config has correct absolute path to smart_mcp.py

2. Restart Claude Desktop completely

3. Start new Claude Code session

4. If still failing, check MCP server logs

Shortcuts not loading

Problem: sm tool works but returns empty or old shortcuts

Solution:

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

Adding New Slash Commands

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

Step-by-Step Process:

1. 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'`

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

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

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

4. 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

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

Project-Local Shortcut (override global):

1. Create shortcuts.json in project directory

2. Add shortcuts (same format as global)

3. Project shortcuts override global (hierarchical merge)

Creating Slash Commands

1. Create markdown file in ~/.claude/commands/sm/

2. Add YAML frontmatter:

3. Write command instructions

4. 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

1. Absolute Paths Required - Claude Desktop config needs absolute path to smart_mcp.py

2. Restart Required - Claude Desktop restart needed for config/shortcut changes

3. JSON Validation - Invalid JSON in shortcuts.json fails silently

4. No Hot Reload - Shortcut changes require new Claude Code session

Contributing

1. Fork the repository

2. Create feature branch

3. Make changes

4. Test with ./scripts/install.sh --dry-run

5. Backup and commit: ./scripts/backup.sh --commit

6. 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