docs2db-mcp-server: Instructions file for Codex

AGENTS.md

Knowledge base for AI agents working on this repository.

Project Overview

docs2db-mcp-server is an MCP (Model Context Protocol) server that exposes docs2db-api's RAG engine as tools for AI assistants. It provides semantic and hybrid search capabilities for RHEL documentation.

Stack: FastMCP → docs2db-api (UniversalRAGEngine) → PostgreSQL/pgvector

Related repositories:

• docs2db — builds the RAG database that this server queries
• docs2db-api — RAG query engine this server wraps
• docs2db-mcp-server — this repo

Author: Ellis Low ([email protected]) License: Apache-2.0 Python: >=3.12,<3.14 Package manager: uv MCP framework: FastMCP

Development Environment

# Install dependencies
uv sync

# Install pre-commit hooks
uv run pre-commit install

# Run linting/formatting/type checks
uv run pre-commit run --all-files

# CI-safe test run (excludes tests needing external services)
make test-ci

# Run all tests
make test

# Type check
make typecheck

# Run the MCP server locally
export DOCS2DB_MCP_DB_HOST=localhost
export DOCS2DB_MCP_DB_PASSWORD=postgres
uv run python -m docs2db_mcp

Code Architecture

src/docs2db_mcp/
├── __init__.py           # Package metadata
├── __main__.py           # Entry point (python -m docs2db_mcp)
├── config.py             # Pydantic settings (DOCS2DB_MCP_* env vars)
├── engine.py             # Singleton wrapper for UniversalRAGEngine
├── server.py             # FastMCP server instance and @mcp.tool() registrations
└── tools/
    ├── __init__.py
    └── search_documents.py  # MCP tool implementation

Key Patterns and Conventions

• Logging: structlog (structlog.get_logger()). Do NOT use stdlib logging.
• Log formatting: Avoid f-strings in structlog calls. Use %s style for lazy evaluation.
• Config/settings: Pydantic BaseSettings with env_prefix="DOCS2DB_MCP_". Environment variables are the ONLY configuration method. No config files.
• Imports: Absolute imports only. Example: from docs2db_mcp.config import CONFIG
• FastMCP imports: from fastmcp import FastMCP, ToolAnnotations
• docs2db-api imports: from docs2db_api.rag.engine import UniversalRAGEngine
• Singleton engine: The RAG engine uses a module-level singleton to avoid multiple initializations. See engine.py.
• Async tools: All MCP tools are async def. Use async def for all I/O operations.
• ToolAnnotations: Set annotations=ToolAnnotations(readOnlyHint=True) for read-only tools.
• Tool returns: Return dictionaries (JSON-serializable). Include error handling with graceful degradation.
• Type hints: Required for all functions and parameters. All modules start with descriptive docstrings.