SSW Rules MCP

Unofficial community-built CLI tools and MCP server for searching SSW Rules with semantic search.

SSW Rules is a collection of 3,700+ best-practice rules covering software engineering, project delivery, communication, and more.

What it does

• MCP Server — Exposes SSW Rules to AI agents (Claude Code, VS Code Copilot, Codex, LM Studio) via the Model Context Protocol
• Semantic Search — Find rules by meaning, not just keywords (e.g. "how to handle technical debt" finds "Do you know the importance of paying back Technical Debt?")
• CLI Tools — Search, browse, and read SSW Rules from the terminal
• Auto-sync — Automatically clones and updates SSW.Rules.Content from GitHub

Prerequisites

• Python 3.12+
• uv (recommended) or pip
• Docker for Qdrant vector search

Quick Start

1. Install

git clone https://github.com/jernejk/SSW.Rules.Mcp.git
cd SSW.Rules.Mcp
uv tool install .

This makes the ssw-rules command available system-wide.

To update after pulling new changes:

cd SSW.Rules.Mcp
git pull
uv tool install --force --reinstall .

To uninstall:

uv tool uninstall ssw-rules-mcp

<details> <summary>Alternative: Run from project directory without global install</summary>

git clone https://github.com/jernejk/SSW.Rules.Mcp.git
cd SSW.Rules.Mcp
uv sync

Then prefix all commands with uv run:

uv run ssw-rules index
uv run ssw-rules search "definition of done"

</details>

2. Start Qdrant

docker run -d -p 6333:6333 qdrant/qdrant

3. Build the search index

ssw-rules index

This will:

1. Clone SSW.Rules.Content (shallow clone, ~1 min)
2. Parse all ~3,700 rules from MDX files
3. Generate embeddings with all-MiniLM-L6-v2 (downloads 90MB model on first run)
4. Store vectors in Qdrant (~6MB, takes ~2 min)

On subsequent runs, it does git pull to get the latest rules before re-indexing.

4. Search!

ssw-rules search "definition of done"

CLI Reference

| Command | Description | |---------|-------------| | ssw-rules index | Clone/pull rules and build Qdrant search index | | ssw-rules index --skip-git | Rebuild index without git pull | | ssw-rules search QUERY | Semantic search across all rules | | ssw-rules get URI | Get the full content of a specific rule | | ssw-rules categories | List all categories and subcategories | | ssw-rules category URI | List rules in a specific category | | ssw-rules recent | Show recently updated rules | | ssw-rules source [PATH] | Configure local SSW.Rules.Content path | | ssw-rules config | Show current configuration | | ssw-rules config --reset | Reset all settings to defaults | | ssw-rules mcp | Start the MCP server (stdio) |

Search

ssw-rules search "pull request best practices"
ssw-rules search "technical debt" --limit 5
ssw-rules search "email etiquette" --json
ssw-rules search "scrum ceremonies" --include-archived

Get a specific rule

ssw-rules get 3-steps-to-a-pbi
ssw-rules get definition-of-done --json

Browse categories

ssw-rules categories
ssw-rules category rules-to-better-scrum-using-azure-devops

Recently updated rules

ssw-rules recent              # Last 30 days
ssw-rules recent --days 7     # Last week
ssw-rules recent --json       # JSON output

JSON Output

Add --json to any command for machine-readable output:

ssw-rules search "testing" --json
ssw-rules get definition-of-done --json
ssw-rules categories --json

Source Configuration

By default, ssw-rules index clones SSW.Rules.Content into ~/.config/ssw-rules-mcp/data/. To use an existing local clone instead:

ssw-rules source ~/Developer/SSW.Rules.Content

To use a fork:

ssw-rules source --repo https://github.com/my-fork/SSW.Rules.Content.git

MCP Server

The MCP server exposes SSW Rules to AI agents via stdio transport.

Tools

| Tool | Description | |------|-------------| | search_rules(query, limit) | Semantic search across all SSW Rules | | get_rule(uri) | Get full content of a rule by its URI slug | | list_categories() | Browse the category hierarchy | | get_category_rules(category_uri) | Get all rules in a category | | get_recent_rules(days, limit) | Get recently updated rules |

Claude Code

Add to your Claude Code MCP settings (~/.claude/settings.json):

{
  "mcpServers": {
    "ssw-rules": {
      "command": "ssw-rules",
      "args": ["mcp"]
    }
  }
}

Note: This requires the global install (uv tool install .). If using uv run instead, use "command": "uv", "args": ["run", "--directory", "/path/to/SSW.Rules.Mcp", "ssw-rules", "mcp"].

Then ask Claude things like:

• "Search SSW Rules for definition of done"
• "What are the SSW rules about pull requests?"
• "Get the SSW rule about technical debt"
• "What SSW Rules categories exist?"

VS Code (Copilot / Continue)

Add to your VS Code settings (.vscode/settings.json or user settings):

{
  "mcp": {
    "servers": {
      "ssw-rules": {
        "command": "ssw-rules",
        "args": ["mcp"]
      }
    }
  }
}

Codex (OpenAI CLI)

{
  "mcpServers": {
    "ssw-rules": {
      "command": "ssw-rules",
      "args": ["mcp"]
    }
  }
}

LM Studio

Configure a new MCP server:

• Name: SSW Rules
• Command: ssw-rules
• Arguments: mcp
• Transport: stdio

Using with SugarLearning MCP

SSW Rules MCP is designed to work alongside SugarLearning MCP for comprehensive SSW process guidance:

• SSW Rules — Public best-practice rules (this tool)
• SugarLearning — Internal training modules and learning paths

Configure both in Claude Code:

{
  "mcpServers": {
    "ssw-rules": {
      "command": "ssw-rules",
      "args": ["mcp"]
    },
    "sugarlearning": {
      "command": "sl",
      "args": ["mcp"]
    }
  }
}

Then ask Claude to combine knowledge from both sources:

• "What SSW rules apply to the Spec Reviews training module?"
• "Create onboarding instructions using SSW Rules and SugarLearning modules"

How Search Works

SSW Rules MCP uses a semantic search approach powered by:

1. sentence-transformers with the all-MiniLM-L6-v2 model (384-dimensional embeddings, runs locally, no API key needed)
2. Qdrant vector database for fast similarity search
3. Text search fallback when Qdrant is unavailable

Each rule is indexed with its title, SEO description, and a preview of its content. Search queries are embedded with the same model and compared using cosine similarity.

With 3,700+ rules, the Qdrant collection uses ~6MB of storage. Indexing takes about 2 minutes.

Project Structure

SSW.Rules.Mcp/
├── src/ssw_rules_mcp/
│   ├── cli.py              # Click CLI entry point
│   ├── config.py           # Pydantic settings (.env)
│   ├── models.py           # Pydantic models (Rule, Category)
│   ├── parser.py           # MDX frontmatter parsing + JSX stripping
│   ├── qdrant_index.py     # Qdrant vector indexing + search
│   ├── categories.py       # Category hierarchy parser
│   └── mcp_server.py       # FastMCP server
├── tests/                  # pytest test suite
├── .env.example            # Configuration template
└── pyproject.toml          # Project definition

Configuration

All settings use the SSW_RULES_ prefix and can be set via environment variables or ~/.config/ssw-rules-mcp/.env:

| Variable | Default | Description | |----------|---------|-------------| | SSW_RULES_CONTENT_PATH | ~/.config/ssw-rules-mcp/data/SSW.Rules.Content | Path to SSW.Rules.Content repo | | SSW_RULES_REPO_URL | https://github.com/SSWConsulting/SSW.Rules.Content.git | Git repo URL for auto-clone | | SSW_RULES_QDRANT_URL | http://localhost:6333 | Qdrant server URL | | SSW_RULES_QDRANT_COLLECTION | ssw-rules | Qdrant collection name |

Running Tests

uv run --extra dev pytest

License

MIT