refactoring-mcp

A local MCP server that gives AI agents searchable access to the Refactoring Guru knowledge base — code smells, refactoring techniques, and design patterns.

How it works

Markdown files from the Refactoring Guru site are stored in an Obsidian vault at /home/pog/Documents/Obsidian Vault/Refactoring Guru/. The server indexes those files using a hybrid search pipeline and exposes the results as MCP tools.

Indexing pipeline

1. Each markdown file is chunked at ## headings — 164 pages become ~430 chunks
2. A BM25 index is built over the tokenized chunk text
3. Each chunk is embedded using all-MiniLM-L6-v2 via sentence-transformers
4. Both the BM25 index and embeddings are persisted to .index/ so startup is instant

Search

At query time, both BM25 and cosine similarity rankings are computed independently, then merged using Reciprocal Rank Fusion (RRF). This means exact keyword matches (e.g. "Extract Method") and semantic matches (e.g. "my class is too big") both work well.

Configuration

Open indexer.py and set VAULT_DIR (line 6) to the folder containing your markdown files:

VAULT_DIR = Path("/path/to/your/md-files")

The server will index all .md files found recursively under that directory.

Prerequisites

pip install mcp rank-bm25 sentence-transformers numpy

Setup

Build the index (only needed once, or after vault files change):

python3 indexer.py

Register with Claude Code:

claude mcp add --scope user refactoring-guru python3 /home/pog/Projects/refactoring-guru-mcp/server.py

Restart Claude Code to pick up the new server.

Tools

| Tool | Description | | --- | --- | | search_refactoring(query, top_k) | Hybrid BM25 + semantic search across all pages. Best for open-ended questions. | | get_refactoring_page(name) | Fetch the full content of a page by name, e.g. "Extract Method", "Decorator". | | list_refactoring_catalog(category) | List all pages, optionally filtered by "Design Patterns", "Smells", or "Refactoring". |

Rebuilding the index

Delete .index/ and re-run indexer.py whenever the vault files change:

rm -rf .index && python3 indexer.py

Project structure

refactoring-guru-mcp/
├── server.py       # MCP server — tool definitions
├── indexer.py      # Chunking, indexing, and hybrid search logic
└── .index/         # Persisted BM25 + embeddings (auto-generated)