How timescale/pg-aiguide works
pg-aiguide gives coding agents PostgreSQL expertise through MCP documentation search and installable skills. The main runtime path is an agent request entering the MCP server, dispatching a search or skill tool, and returning documentation results or curated guidance. A separate ingestion path scrapes PostgreSQL, PostGIS, and Tiger/Timescale documentation, chunks and embeds it, then stores searchable records. Source excerpts establish core call relationships; skill availability and remote MCP usage are documented in the README, while some ingestion-stage wiring is supported only by the SOURCE INDEX.
Main entry points: document_importer.py Page Importer · searchDocs.ts Search Tool · index.ts Skill Tool · httpServer.ts HTTP Transport
Components 23
MCP Server
- Entrypoint
src/index.ts - HTTP Transport
src/httpServer.ts - Stdio Transport
src/stdio.ts - Server Context
src/serverInfo.ts
Documentation Search
- Tool Registry
src/apis/index.ts - Search Tool
src/apis/searchDocs.ts - Chunk Query
src/util/getDocChunkRows.ts - Rank Fusion
src/util/rrf.ts
Documentation Ingestion
- Postgres Import
ingest/postgres_docs.py - PostGIS Import
ingest/postgis_docs.py - Tiger Docs Scraper
ingest/tiger_docs.py - HTML Conversion
ingest/utils/beautiful_soup.py - Page Importer
ingest/document_importer.py - Markdown Chunking
ingest/utils/chunking.py - Page And Chunk Models
ingest/models.py
Agent Skills
- Skill Tool
src/apis/index.ts - Postgres Skill Library
skills/postgres - Schema Exploration
skills/schema-exploration - Specialist Skills
skills/design-postgres-tables
Other components
- Coding Agent
- Embedding API
- Documentation Store
- Ingest Operator
Connections 30
- Coding Agent → HTTP Transport: sends requests
README.md - Coding Agent → Stdio Transport: uses tools
README.md - Entrypoint → HTTP Transport: launches transport
src/index.ts - Entrypoint → Stdio Transport: launches transport
src/index.ts - HTTP Transport → Tool Registry: registers tools
src/httpServer.ts - Stdio Transport → Tool Registry: registers tools
src/stdio.ts - Tool Registry → Search Tool: registers search
src/apis/index.ts - HTTP Transport → Skill Tool: registers prompts
src/httpServer.ts - Stdio Transport → Skill Tool: registers prompts
src/stdio.ts - Skill Tool → Postgres Skill Library: retrieves skills
README.md - Skill Tool → Schema Exploration: retrieves skills
README.md - Skill Tool → Specialist Skills: retrieves skills
README.md - Search Tool → Chunk Query: queries chunks
src/apis/searchDocs.ts - Search Tool → Rank Fusion: fuses rankings
src/apis/searchDocs.ts - Search Tool → Embedding API: embeds query
src/apis/searchDocs.ts - Chunk Query → Documentation Store: queries records
src/util/getDocChunkRows.ts - Search Tool → Server Context: uses pool context
src/apis/searchDocs.ts - Ingest Operator → Postgres Import: starts import
- Ingest Operator → PostGIS Import: starts import
- Ingest Operator → Tiger Docs Scraper: starts scrape
- Postgres Import → Page Importer: uses importer
ingest/postgres_docs.py - PostGIS Import → Page Importer: uses importer
ingest/postgis_docs.py - Postgres Import → HTML Conversion: converts HTML
ingest/postgres_docs.py - PostGIS Import → HTML Conversion: converts HTML
ingest/postgis_docs.py - Page Importer → Markdown Chunking: chunks markdown
ingest/document_importer.py - Page Importer → Page And Chunk Models: uses page models
ingest/document_importer.py - Page Importer → Embedding API: requests embeddings
ingest/document_importer.py - Page Importer → Documentation Store: writes chunks
ingest/document_importer.py - Tiger Docs Scraper → Documentation Store: stores scraped docs
ingest/tiger_docs.py - Tiger Docs Scraper → HTML Conversion: uses HTML utilities
ingest/tiger_docs.py