pg-aiguide

Searches PostgreSQL documentation using OpenAI's text-embedding-3-small model to generate 1536-dimensional query embeddings, then performs cosine similarity search via pgvector's <=> operator against pre-computed documentation embeddings stored in PostgreSQL. Supports version-specific filtering (PostgreSQL 14-18 and latest) and returns ranked results based on semantic relevance rather than keyword matching, enabling AI assistants to find conceptually related documentation even when exact terminology differs.

Searches PostgreSQL documentation using PostgreSQL's native pg_tsvector full-text search with BM25 ranking algorithm, enabling keyword-based retrieval without external embedding services. Tokenizes and ranks documentation sections based on term frequency and inverse document frequency, returning results ordered by relevance score. Supports version filtering and is faster than semantic search for exact feature name lookups.

Distributes pg-aiguide as an npm package (@tigerdata/pg-aiguide) enabling installation via npm/yarn/pnpm and integration into Node.js projects. Package includes MCP server implementation, documentation ingestion scripts, and CLI tools for local deployment and development. Supports programmatic instantiation of the MCP server within Node.js applications, enabling custom integration and extension.

Publishes pg-aiguide to the official MCP Registry (io.github.timescale/pg-aiguide) enabling discovery and one-click installation in MCP-compatible AI coding assistants (Claude, Cursor, VS Code). Registry entry includes metadata (description, version, capabilities, configuration schema) allowing clients to automatically discover and configure pg-aiguide without manual setup. Registry publication enables seamless integration with AI tools that support MCP registry lookups.

Improves the quality of AI-generated PostgreSQL code by providing AI models with access to version-aware documentation, curated best practices, and semantic search capabilities. When integrated into AI coding assistants, pg-aiguide enables models to ground code generation in authoritative PostgreSQL expertise, resulting in code with more constraints (4× improvement), more indexes (55% improvement), and modern syntax patterns. Quality improvement is achieved through tool-use integration, allowing AI models to autonomously search documentation and consult best-practice skills during code generation.

Exposes a curated library of PostgreSQL best-practice patterns and recommendations through the view_skill MCP tool, providing AI coding assistants with opinionated guidance on data integrity, performance optimization, and modern PostgreSQL features. Skills are pre-authored domain expertise snippets covering topics like constraint design, indexing strategies, identity column syntax, and version-specific recommendations. Each skill includes code examples, rationale, and version applicability, enabling AI models to generate higher-quality PostgreSQL code aligned with established best practices.

Filters and retrieves PostgreSQL documentation specific to requested versions (14, 15, 16, 17, 18, or 'latest'), ensuring AI coding assistants receive version-appropriate syntax, features, and deprecation warnings. Documentation is ingested and indexed per-version, allowing the search_docs tool to return only results applicable to the target version. Prevents AI models from generating code using deprecated syntax or features unavailable in the target PostgreSQL version.

Exposes PostgreSQL documentation and best-practices knowledge as two standardized MCP (Model Context Protocol) tools—search_docs and view_skill—that AI coding assistants can invoke programmatically. Tools follow MCP schema specification with typed parameters, enabling Claude, Cursor, VS Code, and other MCP-compatible clients to call pg-aiguide as a native capability. Tool invocation is stateless and synchronous, returning structured results that AI models can parse and incorporate into code generation.

Automated pipeline that ingests PostgreSQL official documentation (versions 14-18) and Tiger/TimescaleDB documentation, parses HTML/markdown sources, chunks content into searchable sections, generates semantic embeddings via OpenAI API, and indexes all content in PostgreSQL with both vector (pgvector) and full-text search (tsvector) indexes. Pipeline runs on a schedule (CI/CD) and handles schema migrations, version-specific metadata extraction, and incremental updates. Supports multiple documentation sources (PostgreSQL, Tiger, PostGIS) with source-specific parsing logic.

Supports both semantic and keyword search methods for PostgreSQL documentation, allowing AI assistants to choose the most appropriate search strategy per query. Semantic search uses embeddings for conceptual queries; keyword search uses BM25 for exact feature name lookups. Both methods return ranked results from the same documentation corpus, enabling AI models to combine results or fall back to keyword search if semantic results are insufficient. Search method is specified via search_type parameter ('semantic' or 'keyword').

Aggregates PostgreSQL documentation from multiple sources—PostgreSQL official docs (versions 14-18), Tiger/TimescaleDB documentation, and PostGIS documentation—into a unified searchable corpus. Each source is tagged with metadata (source name, version, section hierarchy) enabling source-specific filtering and retrieval. Documentation is ingested separately per source but indexed together, allowing unified search across all sources or filtered search by source. Enables AI assistants to access ecosystem documentation beyond core PostgreSQL.

Exposes pg-aiguide as a public HTTP endpoint (https://mcp.tigerdata.com/docs) enabling direct access to PostgreSQL documentation search without requiring MCP client setup or local deployment. HTTP endpoint accepts REST-style requests with query parameters (search query, search type, source, version, limit) and returns JSON-formatted documentation results. Enables integration with non-MCP tools, web applications, and custom workflows that cannot use MCP protocol.

Distributes pg-aiguide as a Docker image (timescale/pg-aiguide) enabling containerized deployment in Kubernetes, Docker Compose, and cloud environments. Docker image includes all dependencies (Python runtime, PostgreSQL client libraries, MCP server) and can be deployed with environment variable configuration for database connection, OpenAI API key, and server settings. Supports both local PostgreSQL connections and remote database endpoints, enabling flexible deployment architectures.