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