grounded-code-mcp: Instructions file for Codex

grounded-code-mcp — Project Context

Global rules (TDD, security, quality gates, Python standards, AI behavior) are in ~/.config/opencode/AGENTS.md and apply here automatically. This file contains only what is specific to this project.

---

Project Overview

• Name: grounded-code-mcp
• Purpose: Local MCP server providing RAG over a persistent knowledge base of vetted technical documentation; eliminates hallucination by grounding AI coding assistant responses in authoritative sources.
• Phase: Maintain
• Jira project key: N/A — tracked via GitHub issues
• Confluence space: N/A
• Definition of success: Any AI coding session using this server produces grounded, citation-backed responses with zero reliance on training-data guesses for covered domains.

---

Technology Stack

• Language: Python 3.10–3.12
• Framework: FastMCP (<3) for MCP server; Click + Rich for CLI
• Vector store: Qdrant (primary), ChromaDB (fallback)
• Document parsing: Docling ≥2.70.0
• Embeddings: Ollama — model: snowflake-arctic-embed2 (1024-dim, 8192-token context)
• Configuration: TOML + Pydantic v2
• Test framework: pytest + pytest-asyncio + pytest-cov
• CI/CD: GitHub Actions — .github/workflows/ci.yml (lint, type-check, test matrix 3.10–3.12, dep-audit) + security.yml (Semgrep, Bandit, CodeQL, Trivy)
• Package manager: pip / hatchling build; runtime install via pipx

---

Architecture

• Pattern: Ingest pipeline → vector search → MCP tool layer. Transport is stdio (default) or HTTP (local only, binds 127.0.0.1).
• Entry points:
  • src/grounded_code_mcp/__main__.py — Click CLI (ingest, serve, status, search)
  • src/grounded_code_mcp/server.py — FastMCP server and all MCP tool handlers
• Key directories:
  • src/grounded_code_mcp/ — production source (8 pipeline modules)
  • tests/ — pytest unit tests; integration tests marked @pytest.mark.integration
  • sources/ — knowledge base documents organised by collection subdirectory
  • .grounded-code-mcp/ — runtime data: Qdrant storage, manifest.json
  • scripts/ — utility scripts (doc downloaders)
  • .github/workflows/ — CI definitions
• Non-obvious constraints:
  • CLI is installed via pipx, not .venv. After any code change run pipx install ".[all]" --force.
  • Ollama must be running with snowflake-arctic-embed2 pulled before ingest or search.
  • Qdrant must be running (Docker Compose or system service) for vector operations.
  • Ingest jobs must run sequentially — parallel ingest causes OOM. Never run two collections simultaneously.
  • Collection names in queries use the bare suffix (e.g., "rust"); the server prepends grounded_ automatically.
  • Machine-specific config (Ollama host, Qdrant URL, port overrides) belongs in ~/.config/grounded-code-mcp/config.toml, never in the committed config.toml.
  • Flash Attention 2 (optional, GPU-only): pip install flash-attn --no-build-isolation Requires CUDA toolkit and an Ampere+ GPU (RTX 30xx/40xx, A100, H100). Enable in config.toml: cuda_use_flash_attention2 = true under [docling].