canon: Instructions file for Codex

AGENTS.md - AI Agent Development Guide

Project: mcp-canon
Purpose: MCP server providing architectural patterns and best practices to LLM agents via RAG
License: MIT

---

Overview of Project

mcp-canon is a Model Context Protocol (MCP) server that provides architectural consultant capabilities to AI agents. It uses Retrieval-Augmented Generation (RAG) to serve best practices and coding guidelines from a vector database.

Key Features

• Bundled knowledge base with pre-indexed guides for Python, Docker, Kubernetes, etc.
• Custom indexing capability for creating your own knowledge bases from Markdown files
• HTTP server mode for remote access and multi-client scenarios
• Offline-first design — all data is local, no external API calls required

Core Architecture

┌──────────────────────────────────────────────────────────────────┐
│                     DEV ENVIRONMENT (Indexing)                    │
│  Sources (MD/PDF/URL) → Docling → LangChain Chunking → LanceDB  │
└──────────────────────────────────────────────────────────────────┘
                              ↓
┌──────────────────────────────────────────────────────────────────┐
│                     USER ENVIRONMENT (Runtime)                    │
│  MCP Client → FastMCP Server → SearchEngine → LanceDB Vectors   │
└──────────────────────────────────────────────────────────────────┘

---

Technologies

Language

• Python 3.11+ (supports 3.11, 3.12, 3.13)

Main Frameworks & Libraries

Component	Library	Purpose
MCP Protocol	mcp	Communication with LLM clients
Vector Database	lancedb	Embedded vector storage
Embeddings	fastembed	ONNX-based text vectorization (nomic-embed-v1.5-Q default)
CLI	typer	Command-line interface
Data Validation	pydantic	Schema validation
HTTP Server	uvicorn + starlette	Streamable HTTP (optional)
Document Parsing	docling	PDF/DOCX/HTML conversion (indexing only)
Text Splitting	langchain-text-splitters	Markdown chunking (indexing only)