Smart

Provides global instruction shortcuts via slash commands and a unified tool, with hierarchical global and project overrides.

python

0

GitHub Stars

python

Language

4 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "btangonan-smart_mcp": {
      "command": "python3",
      "args": [
        "/absolute/path/to/smart_mcp/smart_mcp.py"
      ],
      "env": {
        "NONE": "<NONE>"
      }
    }
  }
}

Smart MCP is a lightweight, two-stage MCP server framework that lets you define global instruction shortcuts and access them from any directory through a single tool or via slash commands. It enables hierarchical defaults with project-specific overrides, so you can standardize common workflows while customizing behavior per project.

How to use

You interact with the Smart MCP server primarily through two entry points: a global slash command surface and a single MCP tool named sm that runs shortcuts from any directory. Use slash commands for quick, discoverable actions like /sm:refactor, /sm:debug, /sm:audit, and /sm:introspect. Use the sm tool inside Claude Code conversations to execute a shortcut with a given context, for example sm { "shortcut": "refactor", "context": "auth.ts" }.

How to install

Follow these steps to set up the Smart MCP server locally and connect it to your Claude Desktop environment.

# Step 1: Install the MCP server
# You will run an installation script that prepares the Python-based MCP server
# and places the necessary shortcut definitions in your global configuration.
# This example mirrors the typical flow shown in the integration steps.

Configuration

Two configuration layers exist: a global layer and an optional project-local override. The global layer stores defaults and the master set of shortcuts. Project-specific shortcuts can override global definitions where they overlap.

# Global (example) shortcuts.json
{
  "shortcuts": {
    "refactor": {
      "description": "Surgical refactoring with golden-master testing",
      "instruction": "Full instruction framework for refactoring with safety checks"
    },
    "debug": {
      "description": "7-step debugging process",
      "instruction": "Structured debugging workflow with evidence gathering"
    },
    "audit": {
      "description": "Repository assessment",
      "instruction": "8-stage health and maturity evaluation"
    },
    "introspect": {
      "description": "Meta-cognitive analysis",
      "instruction": "Cognitive checks and alternative hypotheses"
    }
  }
}

# Project-local shortcuts.json (override example)
{
  "shortcuts": {
    "deploy": {
      "description": "Deploy to staging",
      "instruction": "Deploy {target} with pre-flight checks"
    },
    "refactor": {
      "description": "Project-specific refactor",
      "instruction": "Project-local refactoring rules"
    }
  }
}

Troubleshooting

If slash commands do not appear or the sm tool is unavailable, verify that the global commands exist and the MCP server is running with the configured path. Restart your environment after updates to the command surfaces or shortcut implementations.

Development notes

The server uses a two-stage architecture: Stage 1 discovers slash commands documented as Markdown files, while Stage 2 loads the actual shortcuts and variables from a JSON storage. Both stages must be present and synchronized to function correctly.

Available tools

sm

A single MCP tool to execute shortcuts from Claude Code conversations.

/sm:refactor

Global slash command for surgical refactoring workflows.

/sm:debug

Global slash command for seven-step debugging workflows.

/sm:audit

Global slash command for repository health assessment.

/sm:introspect

Global slash command for meta-cognitive analysis.