Skip to main content
Glama

pg-aiguide

by io.github.timescale
OverviewDiscussionsAdmin

Server Details

Comprehensive PostgreSQL documentation and best practices, including ecosystem tools

If you are the author of this connector, you can claim ownership with GitHub, an HTTP challenge, or a DNS record. Claimed connector authors can inspect health checks, view analytics, and manage their listing.
Status
Healthy
Last Tested
Transport
Streamable HTTP
URL
Repository
timescale/pg-aiguide
GitHub Stars
1,835
Server Listing
pg-aiguide

TDQS

A3.7/5.0

Scored across 2 tools

Disambiguation4/5

search_docs and view_skill are largely distinct: one performs hybrid documentation search, the other retrieves a specific named skill. There is some overlap because both are information-retrieval entry points, but the descriptions provide clear enough usage boundaries.

Naming Consistency5/5

Both tools follow a consistent verb_noun snake_case pattern: search_docs and view_skill. The naming is predictable and aligned with the server's retrieval-focused purpose.

Tool Count3/5

Two tools is a thin surface for a server covering PostgreSQL, TimescaleDB, and PostGIS guidance. However, search_docs plus view_skill forms a minimal but functional knowledge-retrieval pair, so it sits at the borderline rather than being clearly insufficient.

Completeness4/5

The pair covers the main needs of a guide server: finding relevant documentation and retrieving detailed skill content. The available skills are exposed as metadata, which mitigates the lack of a dedicated list_skills tool; minor browsing gaps remain.

Available Tools

2 tools
search_docsSearch DocumentationA
Read-onlyIdempotent
Inspect

Search documentation with hybrid semantic (vector) and keyword (BM25) search. Use semanticWeight to choose keyword-only (0), semantic-only (1), or a blend; mid values fuse rankings with RRF. Supports Tiger Cloud (TimescaleDB), PostgreSQL, and PostGIS.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitYesThe maximum number of matches to return. Defaults to 20.
queryYesThe search query. Used for BM25 when keyword or hybrid search applies, and for the embedding when semantic or hybrid search applies.
sourceYesThe documentation source to search. "tiger" for Tiger Cloud and TimescaleDB, "postgres" for PostgreSQL, "postgis" for PostGIS spatial extension. Specific versions provided with _X.X suffixes.
semanticWeightYesControls the balance between semantic and keyword search. 0 = keyword only, 0.5 = equal mix, 1 = semantic only. Default is 0.7 (favor semantic search).

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultsYes

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (readOnly, idempotent), the description discloses the hybrid search mechanism, BM25, semantic vectors, RRF fusion for mid values, and supported database platforms. This adds substantial behavioral context without contradicting annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core purpose, and every piece of information earns its place. No fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema and detailed annotations, the description sufficiently covers the tool's functionality, parameter tuning, and supported sources. It does not need to detail return values since the output schema exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already covers all parameters, but the description adds meaning by explaining the semanticWeight scale and that query is used for both BM25 and embedding where relevant. This goes beyond simple parameter names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches documentation using hybrid semantic and keyword search, which is a specific verb+resource combination. It also distinguishes from the sibling tool view_skill by focusing on search rather than viewing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on using semanticWeight values (0, 1, blend) and lists supported sources. However, it does not explicitly contrast with view_skill or state when not to use this tool, so it lacks full alternative guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

view_skillView SkillB
Read-onlyIdempotent
Inspect

Retrieve detailed skills for TimescaleDB operations and best practices.

Available Skills

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesA relative path to a file or directory within the skill to view. If empty, will view the `SKILL.md` file by default. Use `.` to list the root directory of the skill.
skill_nameYesThe name of the skill to browse, or `.` to list all available skills.

Output Schema

ParametersJSON Schema
NameRequiredDescription
contentYesThe content of the file or directory listing.

TDQS

B3.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds a catalog of valid skill names but little about operational behavior, such as defaulting to SKILL.md, using '.' to list roots, or how output is structured (though some of that is in the schema). No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The opening sentence is concise and front-loaded, but the description is dominated by an enormous inline skill catalog with lengthy trigger phrases and keyword lists. While the catalog is informative, it makes the tool description overly large and mixes operational guidance with content that arguably belongs elsewhere.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the schema covers both parameters and annotations cover safety, an agent can likely call this tool correctly. The available-skills list helps select skill_name, and the output schema removes the need to describe return values. However, the description misses routing guidance versus search_docs and subtly mischaracterizes the tool as TimescaleDB-only when the catalog spans many PostgreSQL topics.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description goes further by enumerating actual valid skill_name values in the available_skills list. This is especially useful because the schema has no enum and skill_name is otherwise a free-form string. The description does not add much for the path parameter beyond what the schema already says.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb and resource: 'Retrieve detailed skills' for database operations, and the name/title align with that purpose. However, it frames the tool as TimescaleDB-specific while the embedded skill catalog is broader (Postgres, pgvector, migrations), and it does not explicitly differentiate from the sibling search_docs, so it is not a perfect 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to use view_skill versus search_docs, nor any when-not-to-use conditions. The large available-skills catalog implies the tool is for browsing/selecting a skill, but it never states that search_docs is for searching documentation or that view_skill is the right tool for reading skill files.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool update
    • Changedsearch_docs6 fields changed
      • changedInput schema / properties / limit / description
        Previous value: -"The maximum number of matches to return. If not provided, default is 10."New value: +"The maximum number of matches to return. Defaults to 20."
      • changedInput schema / properties / query / description
        Previous value: -"The search query. For semantic search, use natural language. For keyword search, provide keywords."New value: +"The search query. Used for BM25 when keyword or hybrid search applies, and for the embedding when semantic or hybrid search applies."
      • removedInput schema / properties / search_type
        Removed value: -{
-  "description": "The type of search to perform. \"semantic\" uses natural language vector similarity, \"keyword\" uses BM25 keyword matching.",
-  "enum": [
-    "semantic",
-    "keyword"
-  ],
-  "type": "string"
-}
      • addedInput schema / properties / semanticWeight
        Added value: +{
+  "anyOf": [
+    {
+      "maximum": 1,
+      "minimum": 0,
+      "multipleOf": 0.1,
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Controls the balance between semantic and keyword search. 0 = keyword only, 0.5 = equal mix, 1 = semantic only. Default is 0.7 (favor semantic search)."
+}
      • changedInput schema / required
        Previous value: -[
-  "source",
-  "search_type",
-  "query",
-  "limit"
-]New value: +[
+  "source",
+  "query",
+  "limit",
+  "semanticWeight"
+]
      • changedOutput schema / properties / results / items / anyOf
        Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "content": {
-        "description": "The content of the documentation entry.",
-        "type": "string"
-      },
-      "distance": {
-        "description": "The distance score indicating the relevance of the entry to the query. Lower values indicate higher relevance.",
-        "type": "number"
-      },
-      "id": {
-        "description": "The unique identifier of the documentation entry.",
-        "maximum": 9007199254740991,
-        "minimum": -9007199254740991,
-        "type": "integer"
-      },
-      "metadata": {
-        "description": "Additional metadata about the documentation entry, as a JSON encoded string.",
-        "type": "string"
-      }
-    },
-    "required": [
-      "id",
-      "content",
-      "metadata",
-      "distance"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "content": {
-        "description": "The content of the documentation entry.",
-        "type": "string"
-      },
-      "id": {
-        "description": "The unique identifier of the documentation entry.",
-        "maximum": 9007199254740991,
-        "minimum": -9007199254740991,
-        "type": "integer"
-      },
-      "metadata": {
-        "description": "Additional metadata about the documentation entry, as a JSON encoded string.",
-        "type": "string"
-      },
-      "score": {
-        "description": "The score indicating the relevance of the entry to the keywords. Higher values indicate higher relevance.",
-        "type": "number"
-      }
-    },
-    "required": [
-      "id",
-      "content",
-      "metadata",
-      "score"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "content": {
+        "description": "The content of the documentation entry.",
+        "type": "string"
+      },
+      "distance": {
+        "description": "The distance score indicating the relevance of the entry to the query. Lower values indicate higher relevance.",
+        "type": "number"
+      },
+      "id": {
+        "description": "The unique identifier of the documentation entry.",
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "metadata": {
+        "description": "Additional metadata about the documentation entry, as a JSON encoded string.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "id",
+      "content",
+      "metadata",
+      "distance"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "content": {
+        "description": "The content of the documentation entry.",
+        "type": "string"
+      },
+      "id": {
+        "description": "The unique identifier of the documentation entry.",
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "metadata": {
+        "description": "Additional metadata about the documentation entry, as a JSON encoded string.",
+        "type": "string"
+      },
+      "score": {
+        "description": "The score indicating the relevance of the entry to the keywords. Higher values indicate higher relevance.",
+        "type": "number"
+      }
+    },
+    "required": [
+      "id",
+      "content",
+      "metadata",
+      "score"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "content": {
+        "description": "The content of the documentation entry.",
+        "type": "string"
+      },
+      "id": {
+        "description": "The unique identifier of the documentation entry.",
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "metadata": {
+        "description": "Additional metadata about the documentation entry, as a JSON encoded string.",
+        "type": "string"
+      },
+      "rrf_score": {
+        "description": "Hybrid search: fused RRF score from combining semantic and keyword result rankings.",
+        "type": "number"
+      }
+    },
+    "required": [
+      "id",
+      "content",
+      "metadata",
+      "rrf_score"
+    ],
+    "type": "object"
+  }
+]
  2. 1 tool update
    • Changedsearch_docs9 fields changed
      • addedInput schema / properties / limit / anyOf
        Added value: +[
+  {
+    "maximum": 9007199254740991,
+    "minimum": -9007199254740991,
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]
      • changedInput schema / properties / limit / description
        Previous value: -"The maximum number of matches to return. Default is 10."New value: +"The maximum number of matches to return. If not provided, default is 10."
      • removedInput schema / properties / limit / maximum
        Removed value: -9007199254740991
      • removedInput schema / properties / limit / minimum
        Removed value: --9007199254740991
      • removedInput schema / properties / limit / type
        Removed value: -"integer"
      • changedInput schema / properties / source / description
        Previous value: -"The documentation source to search. \"tiger\" for Tiger Cloud and TimescaleDB, \"postgres\" for PostgreSQL, \"postgis\" for PostGIS spatial extension."New value: +"The documentation source to search. \"tiger\" for Tiger Cloud and TimescaleDB, \"postgres\" for PostgreSQL, \"postgis\" for PostGIS spatial extension. Specific versions provided with _X.X suffixes."
      • changedInput schema / properties / source / enum
        Previous value: -[
-  "tiger",
-  "postgres",
-  "postgis"
-]New value: +[
+  "tiger",
+  "postgres_14",
+  "postgres_15",
+  "postgres_16",
+  "postgres_17",
+  "postgres_18",
+  "postgis_3.3",
+  "postgis_3.4",
+  "postgis_3.5",
+  "postgis_3.6"
+]
      • removedInput schema / properties / version
        Removed value: -{
-  "anyOf": [
-    {
-      "enum": [
-        "14",
-        "15",
-        "16",
-        "17",
-        "18",
-        "latest"
-      ],
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "description": "The PostgreSQL major version (ignored when searching \"tiger\"). Recommended to assume the latest version if unknown. Only applicable when source is Postgres. Defaults to latest version."
-}
      • changedInput schema / required
        Previous value: -[
-  "source",
-  "search_type",
-  "query",
-  "version",
-  "limit"
-]New value: +[
+  "source",
+  "search_type",
+  "query",
+  "limit"
+]
  3. 2 tool updates
    • Changedsearch_docs4 fields changed
      • removedInput schema / additionalProperties
        Removed value: -false
      • addedInput schema / properties / limit / maximum
        Added value: +9007199254740991
      • addedInput schema / properties / limit / minimum
        Added value: +-9007199254740991
      • changedOutput schema / properties / results / items / anyOf
        Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "content": {
-        "description": "The content of the documentation entry.",
-        "type": "string"
-      },
-      "distance": {
-        "description": "The distance score indicating the relevance of the entry to the query. Lower values indicate higher relevance.",
-        "type": "number"
-      },
-      "id": {
-        "description": "The unique identifier of the documentation entry.",
-        "type": "integer"
-      },
-      "metadata": {
-        "description": "Additional metadata about the documentation entry, as a JSON encoded string.",
-        "type": "string"
-      }
-    },
-    "required": [
-      "id",
-      "content",
-      "metadata",
-      "distance"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "content": {
-        "$ref": "#/properties/results/items/anyOf/0/properties/content"
-      },
-      "id": {
-        "$ref": "#/properties/results/items/anyOf/0/properties/id"
-      },
-      "metadata": {
-        "$ref": "#/properties/results/items/anyOf/0/properties/metadata"
-      },
-      "score": {
-        "description": "The score indicating the relevance of the entry to the keywords. Higher values indicate higher relevance.",
-        "type": "number"
-      }
-    },
-    "required": [
-      "id",
-      "content",
-      "metadata",
-      "score"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "content": {
+        "description": "The content of the documentation entry.",
+        "type": "string"
+      },
+      "distance": {
+        "description": "The distance score indicating the relevance of the entry to the query. Lower values indicate higher relevance.",
+        "type": "number"
+      },
+      "id": {
+        "description": "The unique identifier of the documentation entry.",
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "metadata": {
+        "description": "Additional metadata about the documentation entry, as a JSON encoded string.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "id",
+      "content",
+      "metadata",
+      "distance"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "content": {
+        "description": "The content of the documentation entry.",
+        "type": "string"
+      },
+      "id": {
+        "description": "The unique identifier of the documentation entry.",
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "metadata": {
+        "description": "Additional metadata about the documentation entry, as a JSON encoded string.",
+        "type": "string"
+      },
+      "score": {
+        "description": "The score indicating the relevance of the entry to the keywords. Higher values indicate higher relevance.",
+        "type": "number"
+      }
+    },
+    "required": [
+      "id",
+      "content",
+      "metadata",
+      "score"
+    ],
+    "type": "object"
+  }
+]
    • Changedview_skill1 field changed
      • removedInput schema / additionalProperties
        Removed value: -false
  4. 1 tool update
    • Changedsearch_docs4 fields changed
      • addedInput schema / properties / version / anyOf
        Added value: +[
+  {
+    "enum": [
+      "14",
+      "15",
+      "16",
+      "17",
+      "18",
+      "latest"
+    ],
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
      • changedInput schema / properties / version / description
        Previous value: -"The PostgreSQL major version (ignored when searching \"tiger\"). Recommended to assume the latest version if unknown."New value: +"The PostgreSQL major version (ignored when searching \"tiger\"). Recommended to assume the latest version if unknown. Only applicable when source is Postgres. Defaults to latest version."
      • removedInput schema / properties / version / enum
        Removed value: -[
-  "14",
-  "15",
-  "16",
-  "17",
-  "18",
-  "latest"
-]
      • removedInput schema / properties / version / type
        Removed value: -"string"
  5. 1 tool update
    • Changedsearch_docs2 fields changed
      • changedInput schema / properties / source / description
        Previous value: -"The documentation source to search. \"tiger\" for Tiger Cloud and TimescaleDB, \"postgres\" for PostgreSQL."New value: +"The documentation source to search. \"tiger\" for Tiger Cloud and TimescaleDB, \"postgres\" for PostgreSQL, \"postgis\" for PostGIS spatial extension."
      • changedInput schema / properties / source / enum
        Previous value: -[
-  "tiger",
-  "postgres"
-]New value: +[
+  "tiger",
+  "postgres",
+  "postgis"
+]
  6. 2 tool updates
    • First observedsearch_docs
    • First observedview_skill

Related MCP Connectors

Related MCP Servers

  • postgres-mcp-server

    mukul975
    A
    license
    Not graded
    quality
    F
    maintenance
    Enables AI assistants to manage, monitor, and optimize PostgreSQL databases with over 200 specialized tools for operations, security, performance tuning, and diagnostics.
    17
    8
    MIT

  • Postgres MCP Pro

    BACH-AI-Tools
    A
    license
    B
    quality
    D
    maintenance
    Enables comprehensive PostgreSQL database management including index tuning, query plan analysis, health monitoring, schema-aware SQL generation, and safe SQL execution with configurable access control for both development and production environments.
    9
    MIT

  • MCP PostgreSQL Operations

    call518
    A
    license
    A
    quality
    B
    maintenance
    Enables comprehensive PostgreSQL database monitoring, analysis, and management through natural language queries. Provides performance insights, bloat analysis, vacuum monitoring, and intelligent maintenance recommendations across PostgreSQL versions 12-17.
    34
    161
    MIT

  • PostgreSQL MCP Server

    jamesjohnsdev
    A
    license
    B
    quality
    F
    maintenance
    Facilitates management and optimization of PostgreSQL databases, offering analysis, setup guidance, and debugging, while ensuring secure and efficient database operations.
    3
    7
    23
    AGPL 3.0
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources