{
  "slug": "io-github-timescale-pg-aiguide",
  "name": "io.github.timescale/pg-aiguide",
  "title": "pg-aiguide",
  "description": "Comprehensive PostgreSQL documentation and best practices, including ecosystem tools",
  "version": "0.6.1",
  "publishedAt": "2026-09-04T19:16:47.690447Z",
  "updatedAt": "2026-09-04T19:16:47.690447Z",
  "repoUrl": "https://github.com/timescale/pg-aiguide",
  "websiteUrl": null,
  "namespace": {
    "type": "github",
    "owner": "timescale"
  },
  "kind": "both",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "@tigerdata/pg-aiguide",
      "version": "0.6.1",
      "transport": "stdio",
      "runtimeHint": null
    },
    {
      "registryType": "oci",
      "identifier": "ghcr.io/timescale/pg-aiguide:0.6.1",
      "version": null,
      "transport": "stdio",
      "runtimeHint": null
    }
  ],
  "remotes": [
    {
      "type": "streamable-http",
      "url": "https://mcp.tigerdata.com/docs"
    }
  ],
  "envVars": [
    {
      "name": "OPENAI_API_KEY",
      "isSecret": true,
      "isRequired": true,
      "description": "Your API key for text embeddings via OpenAI"
    },
    {
      "name": "PGHOST",
      "isSecret": true,
      "isRequired": true,
      "description": "PostgreSQL host to connect to"
    },
    {
      "name": "PGPORT",
      "isSecret": true,
      "isRequired": true,
      "description": "PostgreSQL port to connect to"
    },
    {
      "name": "PGUSER",
      "isSecret": true,
      "isRequired": true,
      "description": "PostgreSQL user to connect as"
    },
    {
      "name": "PGPASSWORD",
      "isSecret": true,
      "isRequired": true,
      "description": "PostgreSQL password to connect with"
    },
    {
      "name": "PGDATABASE",
      "isSecret": true,
      "isRequired": true,
      "description": "PostgreSQL database to connect to"
    },
    {
      "name": "DB_SCHEMA",
      "isSecret": true,
      "isRequired": false,
      "description": "PostgreSQL database schema to use"
    }
  ],
  "category": "databases",
  "subcategory": "sql",
  "company": "",
  "categoryAuto": true,
  "checks": [
    {
      "id": "source-linked",
      "label": "Source repository linked",
      "result": "pass",
      "detail": "https://github.com/timescale/pg-aiguide"
    },
    {
      "id": "version-pinned",
      "label": "Version pinned",
      "result": "pass",
      "detail": "Every package has an explicit version"
    },
    {
      "id": "https-remote",
      "label": "Remote uses HTTPS",
      "result": "pass",
      "detail": "All remote endpoints use https://"
    },
    {
      "id": "secrets-requested",
      "label": "Secrets requested",
      "result": "warn",
      "detail": "Asks for 7 secrets: OPENAI_API_KEY, PGHOST, PGPORT, PGUSER, PGPASSWORD, PGDATABASE, DB_SCHEMA"
    },
    {
      "id": "known-registry",
      "label": "Known package registry",
      "result": "pass",
      "detail": "All packages come from npm, PyPI, OCI, NuGet or MCPB"
    },
    {
      "id": "namespace",
      "label": "Namespace ownership",
      "result": "info",
      "detail": "Name verified via GitHub account timescale"
    },
    {
      "id": "meta-text",
      "label": "Registry text aimed at the AI",
      "result": "pass",
      "detail": "Description and settings contain no hidden characters or instructions to the AI"
    },
    {
      "id": "install-scripts",
      "label": "Install scripts",
      "result": "pass",
      "detail": "@tigerdata/pg-aiguide@0.6.1 runs nothing at install"
    },
    {
      "id": "code-flags",
      "label": "Code red flags",
      "result": "pass",
      "detail": "Read 19 files in @tigerdata/pg-aiguide@0.6.1: no obfuscation, encoded execution, credential reads or data-collection endpoints found"
    },
    {
      "id": "ai-text",
      "label": "Text aimed at the AI",
      "result": "pass",
      "detail": "No hidden characters or instructions to the AI in 19 files, including comments and the README"
    }
  ],
  "scannedAt": "2026-10-29",
  "level": "Scanned",
  "install": [
    {
      "label": "Claude Desktop (npm)",
      "kind": "claude_desktop_json",
      "text": "{\n  \"mcpServers\": {\n    \"pg-aiguide\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@tigerdata/pg-aiguide@0.6.1\"\n      ],\n      \"env\": {\n        \"OPENAI_API_KEY\": \"<your value>\",\n        \"PGHOST\": \"<your value>\",\n        \"PGPORT\": \"<your value>\",\n        \"PGUSER\": \"<your value>\",\n        \"PGPASSWORD\": \"<your value>\",\n        \"PGDATABASE\": \"<your value>\"\n      }\n    }\n  }\n}"
    },
    {
      "label": "Claude Desktop (oci)",
      "kind": "claude_desktop_json",
      "text": "{\n  \"mcpServers\": {\n    \"pg-aiguide\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"-i\",\n        \"--rm\",\n        \"-e\",\n        \"OPENAI_API_KEY\",\n        \"-e\",\n        \"PGHOST\",\n        \"-e\",\n        \"PGPORT\",\n        \"-e\",\n        \"PGUSER\",\n        \"-e\",\n        \"PGPASSWORD\",\n        \"-e\",\n        \"PGDATABASE\",\n        \"ghcr.io/timescale/pg-aiguide:0.6.1\"\n      ],\n      \"env\": {\n        \"OPENAI_API_KEY\": \"<your value>\",\n        \"PGHOST\": \"<your value>\",\n        \"PGPORT\": \"<your value>\",\n        \"PGUSER\": \"<your value>\",\n        \"PGPASSWORD\": \"<your value>\",\n        \"PGDATABASE\": \"<your value>\"\n      }\n    }\n  }\n}"
    },
    {
      "label": "Claude Code (streamable-http)",
      "kind": "claude_code_cli",
      "text": "claude mcp add --transport http pg-aiguide https://mcp.tigerdata.com/docs"
    }
  ],
  "curated": true,
  "stars": 1879,
  "archived": false,
  "pushedAt": "2026-10-28T04:56:06Z",
  "review": {
    "package": "@tigerdata/pg-aiguide",
    "version": "0.6.1",
    "at": "2026-10-31",
    "files": 17,
    "lines": 993,
    "verdict": "pass-with-notes",
    "summary": "Search tool over PostgreSQL, PostGIS and TimescaleDB documentation, read-only. When run yourself, your search text goes to your Postgres docs database and (for semantic search, the default) to OpenAI to build an embedding. The skill texts it serves come from a separate library that was not part of this review.",
    "hosts": [
      {
        "host": "PostgreSQL server from PG* env vars (pg Pool defaults)",
        "when": "when search_docs is called",
        "sends": "the search query text (keyword search) or its embedding vector, plus version/limit, as bound parameters"
      },
      {
        "host": "api.openai.com (via @ai-sdk/openai)",
        "when": "when search_docs is called with semanticWeight > 0 (default 0.7, so most calls)",
        "sends": "the search query text, to create a text-embedding-3-small embedding"
      },
      {
        "host": "OpenTelemetry/Logfire exporter (configured in @tigerdata/mcp-boilerplate, not in this package)",
        "when": "when a tracer is configured",
        "sends": "span attributes: result count and top-3 result ids and scores (no document content)"
      }
    ],
    "env": [
      {
        "name": "PGHOST / PGUSER / PGPASSWORD / PGDATABASE / PGPORT (read by pg)",
        "sent_to": "the configured PostgreSQL server"
      },
      {
        "name": "OPENAI_API_KEY (read by @ai-sdk/openai)",
        "sent_to": "api.openai.com"
      },
      {
        "name": "DB_SCHEMA",
        "sent_to": "local (schema name, strictly validated)"
      },
      {
        "name": "DISABLE_MCP_SKILLS",
        "sent_to": "local (hides view_skill tool)"
      },
      {
        "name": "NODE_ENV",
        "sent_to": "local (DNS-rebinding protection on unless production)"
      }
    ],
    "local": "Loads .env via 'dotenv/config'. No other file access in this package (skills are loaded by the @tigerdata/mcp-boilerplate dependency).",
    "exec": "None in this package. cliEntrypoint from the boilerplate dependency launches stdio.js or httpServer.js (its own files).",
    "telemetry": "No telemetry of its own. It records result ids/scores on an OpenTelemetry span if the host app configured a tracer (searchDocs.js:85-94); with no tracer this is a no-op.",
    "tools": [
      "search_docs",
      "view_skill"
    ],
    "toolText": "clean",
    "deps": [
      "@tigerdata/mcp-boilerplate",
      "@ai-sdk/openai",
      "ai",
      "@opentelemetry/api",
      "pg",
      "zod",
      "dotenv",
      "bun:test (test files only)"
    ],
    "findings": [
      {
        "severity": "note",
        "at": "dist/apis/searchDocs.js:95-101",
        "what": "Unless semanticWeight is 0, every search query is sent to OpenAI to make an embedding. Running it locally needs your own OPENAI_API_KEY and a Postgres loaded with the docs corpus; most users use the hosted endpoint instead."
      },
      {
        "severity": "note",
        "at": "dist/apis/index.js:6-11, dist/prompts/index.js:2",
        "what": "The view_skill tool, its skill list (appended to the tool description) and the MCP prompts come from @tigerdata/mcp-boilerplate/skills, a dependency; that AI-facing text is not in this package and was not reviewed here."
      },
      {
        "severity": "info",
        "at": "dist/util/getDocChunkRows.js:4-23",
        "what": "SQL interpolates schema and table prefix, but schema is validated against ^[a-z_][a-z0-9_$]{0,62}$ (config.js:6-25) and the prefix comes from a fixed enum; user text is always a bound parameter. No SQL injection."
      },
      {
        "severity": "info",
        "at": "dist/*.test.js",
        "what": "5 bun test files are shipped in dist (counted in the line total); they only exercise mocks."
      },
      {
        "severity": "info",
        "at": "package",
        "what": "No package.json in the reviewed copy; dependencies are taken from imports. No obfuscation, install hooks, dynamic code, child_process or hard-coded secrets."
      }
    ]
  },
  "health": {
    "score": 73,
    "parts": {
      "popularity": 0.5753452006149411,
      "activity": 0.9276476915852664,
      "issues": 0.7,
      "security": 0.8
    },
    "fail": 0,
    "warn": 1,
    "raw": {
      "stars": 1879,
      "forks": 120,
      "downloads": 115,
      "hn": {
        "n": 1,
        "pts": 3,
        "t": [
          [
            "46034987",
            "Show HN: Pg-aiguide – Write better PostgreSQL code with AI",
            3,
            0,
            "2025-11-24"
          ]
        ]
      },
      "issuesOpen": 6,
      "issuesClosed": 14,
      "prsMerged": 91,
      "commits90": 28,
      "release": "2026-09-04T19:23:40Z",
      "pushed": "2026-10-28T04:56:06Z",
      "growth": null,
      "growthDays": null,
      "archived": false
    },
    "at": "2026-10-31T07:42:38.200Z"
  }
}