Glanser Guidelines 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

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:

cp /path/to/CODING_GUIDELINES.md documents/

3. Ingest (embed once, saved to disk)

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:

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

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:

{
  "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

# 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)

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