# SSW Rules MCP

> **Unofficial** community-built CLI tools and MCP server for searching [SSW Rules](https://www.ssw.com.au/rules) with semantic search.

[SSW Rules](https://www.ssw.com.au/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](https://modelcontextprotocol.io/)
- **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](https://docs.astral.sh/uv/) (recommended) or pip
- [Docker](https://www.docker.com/) for Qdrant vector search

## Quick Start

### 1. Install

```bash
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:

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

To uninstall:

```bash
uv tool uninstall ssw-rules-mcp
```

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

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

Then prefix all commands with `uv run`:

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

</details>

### 2. Start Qdrant

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

### 3. Build the search index

```bash
ssw-rules index
```

This will:
1. Clone [SSW.Rules.Content](https://github.com/SSWConsulting/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!

```bash
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

```bash
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

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

### Browse categories

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

### Recently updated rules

```bash
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:

```bash
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:

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

To use a fork:

```bash
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`):

```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):

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

### Codex (OpenAI CLI)

```json
{
  "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](https://github.com/jernejk/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:

```json
{
  "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](https://www.sbert.net/)** with the `all-MiniLM-L6-v2` model (384-dimensional embeddings, runs locally, no API key needed)
2. **[Qdrant](https://qdrant.tech/)** 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

```bash
uv run --extra dev pytest
```

## License

MIT