# Glanser Guidelines MCP Server

Semantic search over the team's coding guidelines corpus.
Powered by **FastMCP + ChromaDB + sentence-transformers (all-MiniLM-L6-v2)**.
100% free — no API keys, no external services, runs fully offline after setup.

---

## Folder Structure

```
mcp-server/
├── server.py          ← MCP server (run this on the host)
├── ingest.py          ← One-time ingestion script
├── requirements.txt   ← Python dependencies
├── documents/         ← Drop your .md guideline files here
│   └── CODING_GUIDELINES.md
└── chroma_db/         ← Created automatically by ingest.py (do not edit)
```

---

## Setup (run once on the host machine)

### 1. Install dependencies

```bash
pip install -r requirements.txt
```

> `sentence-transformers` will download the `all-MiniLM-L6-v2` model (~80 MB)
> on first run and cache it. Subsequent runs are fully offline.

### 2. Add your documents

Copy markdown files into the `documents/` folder:

```bash
cp /path/to/CODING_GUIDELINES.md documents/
```

### 3. Ingest (embed once, saved to disk)

```bash
python ingest.py
```

This reads every `.md` file in `documents/`, embeds each section, and
persists the vectors to `chroma_db/`. **You only re-run this when adding
a new document.**

Useful flags:

```bash
python ingest.py --file documents/NEW_DOC.md   # add a single new doc
python ingest.py --reset                        # wipe and re-ingest everything
python ingest.py --list                         # see what is currently indexed
```

### 4. Start the server

```bash
python server.py
```

Server starts on `http://0.0.0.0:8000`.

---

## Hosting (team access)

Deploy to **Railway** or **Render** (both have free tiers):

1. Push this `mcp-server/` folder to a git repo
2. Create a new service pointing to that repo
3. Set start command: `python server.py`
4. Mount a persistent volume at `/app/chroma_db` (so embeddings survive deploys)
5. Run `python ingest.py` once via the host console after deploy

Railway/Render automatically provision an HTTPS URL like:
`https://glanser-guidelines-mcp.railway.app`

---

## Team .mcp.json entry

Each team member adds this to their `.mcp.json`:

```json
{
  "mcpServers": {
    "coding-guidelines": {
      "type": "http",
      "url": "https://your-hosted-domain.com/mcp"
    }
  }
}
```

---

## Available Tools

| Tool | What it does |
|------|-------------|
| `search_guidelines` | Semantic search across all docs — use this first |
| `get_section` | Fetch full content of a specific section |
| `list_sections` | Browse all section titles across the corpus |
| `get_by_scope` | Filter rules by `library`, `client`, or `both` |
| `list_documents` | See all indexed documents and their section counts |

---

## Adding a New Document

```bash
# 1. Copy the new doc
cp NEW_GUIDELINES.md documents/

# 2. Ingest only the new file (does not re-embed existing docs)
python ingest.py --file documents/NEW_GUIDELINES.md

# 3. No server restart needed — ChromaDB is queried live
```

---

## Local dev / testing (without hosting)

```json
{
  "mcpServers": {
    "coding-guidelines": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}
```