Skip to main content
Glama
deenesjakoruzh
LostInBrittany

RAGmonsters Custom PostgreSQL MCP Server

by LostInBrittany
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

为 RAGmonsters 定制的 PostgreSQL MCP 服务器

概述

本仓库演示了一种使用模型上下文协议 (MCP) 将大型语言模型 (LLM) 与数据库集成的更高级方法。虽然通用的 MCP PostgreSQL 服务器允许 LLM 通过原始 SQL 查询来探索数据库，但本项目采用了一种不同的方法，即创建一个自定义的 MCP 服务器，该服务器提供根据应用程序需求定制的领域特定 API。

该实现使用了FastMCP ，这是模型上下文协议的高性能实现，它为基于工具的与 LLM 的交互提供了更高的效率和可靠性。

该项目以RAGmonsters数据集为基础。RAGmonsters 是一个开源项目，它提供了一个丰富的虚构怪物数据集，其中包含各种属性、能力和关系，专为演示和测试检索增强生成 (RAG) 系统而设计。

通用 MCP 数据库访问的问题

通用 MCP PostgreSQL 服务器为 LLM 提供了一个query工具，允许他们：

  • 探索数据库模式

  • 根据自然语言问题制定 SQL 查询

  • 对数据库执行这些查询

虽然这种方法有效，但它在实际应用中有几个局限性：

  • 认知负荷：LLM 必须理解整个数据库模式

  • 效率低下：通常需要多个 SQL 查询才能回答一个问题

  • 安全问题：原始 SQL 访问需要仔细的提示工程以防止注入攻击

  • 性能：如果 LLM 不了解数据库的索引策略，那么复杂的查询可能会效率低下

  • 领域知识差距：法学硕士缺乏对业务规则和领域特定约束的理解

关于 RAGmonsters 数据集

RAGmonsters是一个开放数据集，专为测试和演示检索增强生成 (RAG) 系统而设计。它包含具有丰富属性、能力和关系的虚构怪物信息，非常适合用于自然语言查询演示。

RAGmonsters 的 PostgreSQL 版本提供了一个结构良好的关系数据库，其中包含多个表和关系，包括：

  • 具有各种属性的怪物（攻击力、防御力、健康度等）

  • 怪物可以拥有的能力

  • 具有复杂关系的元素（火、水、土等）

  • 怪物栖息地

  • 怪物之间的进化链和关系

这个丰富、互联的数据集非常适合展示特定领域 API 与通用 SQL 访问的强大功能。

我们的解决方案：特定领域的 MCP API

该项目演示了如何构建自定义 MCP 服务器，为 RAGmonsters 数据集提供更高级别、特定领域的 API。我们的 MCP 服务器不提供原始 SQL 功能，而是提供以下专用函数：

  1. 抽象数据库复杂性：隐藏底层模式和 SQL 细节

  2. 提供特定领域的操作：提供符合业务概念的功能

  3. 针对常见查询进行优化：针对常见问题实施高效的查询模式

  4. 执行业务规则：嵌入特定领域的逻辑和约束

  5. 提高安全性：通过删除直接 SQL 访问来限制攻击面

Related MCP server: scopedb-mcp

Web 界面

该项目包括两个用于与 RAGmonsters 数据集交互的主要接口：

资源管理器界面

一个以数据为中心的界面，用于通过 MCP API 探索和过滤 RAGmonsters 数据集：

  • 按类别、栖息地和稀有度筛选浏览所有怪物

  • 查看每个怪物的详细信息

  • 使用 Bootstrap 构建交互式 UI

聊天界面

用于与 RAGmonsters 数据集交互的自然语言界面：

  • 用自然语言询问有关怪物的问题

  • 获取具有丰富格式的 Markdown 格式响应

  • 由 LangGraph 的 ReAct 代理模式提供支持

  • 与 MCP 工具无缝集成

RAGmonsters 浏览器截图

该界面允许用户：

  • 浏览数据集中的所有怪物

  • 按栖息地、类别和稀有度筛选怪物

  • 查看每个怪物的详细信息，包括力量、能力、优势和劣势

示例：特定领域 API 与通用 SQL

通用 MCP PostgreSQL 方法：

User: "What are the top 3 monsters with the highest attack power that are vulnerable to fire?"

LLM: (Must understand schema, joins, and SQL syntax)
1. First query to understand the schema
2. Second query to find monsters with attack power
3. Third query to find vulnerabilities
4. Final query to join and filter results

我们的定制 MCP 服务器方法：

User: "What are the top 3 monsters with the highest attack power that are vulnerable to fire?"

LLM: (Uses our domain-specific API)
1. Single call: getMonsters({ vulnerableTo: "fire", sortBy: "attackPower", limit: 3 })

项目结构

├── .env.example        # Example environment variables
├── package.json        # Node.js project configuration
├── README.md           # This documentation
├── img/                # Images for documentation
├── scripts/
│   ├── testMcpServer.js # Test script for the MCP server
│   └── testLogger.js    # Logger for test script
├── src/
│   ├── index.js        # Main application server
│   ├── mcp-server/     # Custom MCP server implementation with FastMCP
│   │   ├── index.js    # Server entry point
│   │   ├── tools/      # Domain-specific tools
│   │   │   ├── index.js      # Tool registration
│   │   │   └── monsters.js   # Monster-related operations
│   │   └── utils/     # Helper utilities
│   │       └── logger.js     # Logging functionality
│   ├── llm.js          # LangChain integration for LLM
│   └── public/         # Web interface files
│       ├── index.html  # Monster explorer interface
│       └── chat.html   # Chat interface for LLM interactions

特征

  • 带有 FastMCP 的自定义 MCP 服务器：针对 RAGmonsters 数据的高性能领域特定 API

  • 优化查询：预建高效的数据库操作

  • 业务逻辑层：API 中嵌入的域规则和约束

  • 结构化响应格式：LLM 使用一致的 JSON 响应

  • 全面的日志记录：用于调试和监控的详细日志记录

  • 测试套件：用于验证服务器功能和 LLM 集成的脚本

  • LLM 集成：

    • LangChain.js 与 OpenAI 和其他兼容的 LLM 提供商集成

    • LangGraph ReAct 代理模式，实现高效工具使用

    • 自动处理工具调用和响应

  • Web界面：

    • 用于浏览和过滤怪物的资源管理器界面

    • 采用 Markdown 渲染的聊天界面，可进行自然语言交互

特征

  • LangChain.js 集成：与 MCP 工具完全集成的 LLM 交互

  • Web 界面：用于与 RAGmonsters 数据集交互的资源管理器和聊天界面

  • 部署就绪：配置为在 Clever Cloud 等平台上轻松部署

这种方法的好处

  1. 改进的性能：优化查询和缓存策略

  2. 更好的用户体验：更准确、更快速的响应

  3. 减少令牌使用：LLM 不需要处理复杂的 SQL 或模式信息

  4. 增强的安全性：没有直接的 SQL 访问意味着降低注入攻击的风险

  5. 可维护性：数据库模式的更改不需要重新培训 LLM

  6. 可扩展性：可以处理更大、更复杂的数据库

入门

安装

  1. 克隆此存储库

  2. 安装依赖项： npm install

  3. 将.env.example复制到.env并配置 PostgreSQL 连接字符串和 LLM API 密钥

  4. 运行 MCP 服务器测试脚本： npm run test

  5. 运行 LLM 集成测试脚本： npm run test:llm

  6. 启动服务器： npm start

可用工具

MCP 服务器提供以下工具：

  1. getMonsters - 获取怪物列表，并可选择过滤、排序和分页

    • 参数：过滤器（类别、栖息地、稀有度）、排序（字段、方向）、限制、偏移

    • 返回：包含基本信息的怪物对象数组

  2. getMonsterById - 根据 ID 获取特定怪物的详细信息

    • 参数：monsterId

    • 返回：具有所有属性、力量、能力、优势和弱点的详细怪物对象

  3. add - 用于添加两个数字的简单实用程序（用于测试）

    • 参数：a、b

    • 返回：两个数字的和

LLM 集成架构

该项目采用现代方法将 LLM 与特定领域工具集成：

LangGraph ReAct 代理模式

该应用程序使用 LangGraph 的 ReAct（推理和代理）代理模式，该模式：

  1. 处理用户查询以了解意图

  2. 根据查询确定要使用的工具

  3. 自动执行适当的工具

  4. 将结果综合成连贯的响应

  5. 在需要时处理多步骤推理

测试 LLM 集成

该项目包含一个测试脚本，演示如何使用 LangChain.js 将 LLM 与 MCP 服务器集成：

npm run test:llm

此脚本：

  1. 使用 StdioClientTransport 连接到 MCP 服务器

  2. 使用 LangChain 的 MCP 适配器加载所有可用的 MCP 工具

  3. 使用 OpenAI API 创建 LangChain 代理

  4. 处理关于怪物的自然语言查询

  5. 展示 LLM 如何调用工具来检索信息

  6. 记录有关交互的详细信息

您可以修改脚本中的测试查询，以探索系统的不同功能。该脚本位于scripts/testLlmWithMcpServer.js 。

先决条件

  • Node.js 23 或更高版本

  • 包含 RAGmonsters 数据的 PostgreSQL 数据库

  • 访问 LLM API（例如 OpenAI）

  • FastMCP 包（包含在依赖项中）

环境变量

使用以下变量创建.env文件：

# PostgreSQL connection string
POSTGRESQL_ADDON_URI=postgres://username:password@host:port/database

# LLM API configuration
LLM_API_KEY=your_openai_api_key
LLM_API_MODEL=gpt-4o-mini
LLM_API_URL=https://api.openai.com/v1

LLM 配置

  • LLM_API_KEY ：您的 OpenAI API 密钥或兼容提供商密钥

  • LLM_API_MODEL ：要使用的模型（默认值：gpt-4o-mini）

  • LLM_API_URL ：API 端点（默认：OpenAI 的端点）

该应用程序支持任何与 OpenAI 兼容的 API，包括自托管模型和替代提供商。

部署到 Clever Cloud

使用 Clever Cloud CLI

  1. 安装 Clever Cloud CLI：

    npm install -g clever-tools

  2. 登录您的 Clever Cloud 帐户：

    clever login

  3. 创建新应用程序：

    clever create --type node <APP_NAME>

  4. 添加您的域名（可选但建议添加）：

    clever domain add <YOUR_DOMAIN_NAME>

  5. 创建 PostgreSQL 附加组件并将其链接到您的应用程序：

    clever addon create <APP_NAME>-pg --plan dev
clever service link-addon <APP_NAME>-pg

    这将自动在您的应用程序中设置POSTGRESQL_ADDON_URI环境变量。

  6. 设置所需的环境变量：

    clever env set LLM_API_KEY "your-openai-api-key"
clever env set LLM_API_MODEL "gpt-4o-mini" # Optional, defaults to gpt-4o-mini
clever env set LLM_API_URL "https://api.your-llm-provider.com" # Optional, for alternative OpenAI-compatible providers

  7. 部署您的应用程序：

    clever deploy

  8. 打开您的应用程序：

    clever open

使用 Clever Cloud 控制台

您也可以直接从Clever Cloud Console部署：

  1. 在控制台中创建一个新的应用程序

  2. 选择 Node.js 作为运行时

  3. 创建 PostgreSQL 附加组件并将其链接到您的应用程序

  4. 在控制台中设置所需的环境变量：

    • LLM_API_KEY ：您的 OpenAI API 密钥

    • LLM_API_MODEL ：（可选）要使用的模型，默认为 gpt-4o-mini

  5. 使用 Git 或 GitHub 集成部署您的应用程序

重要说明

  • 当您将 PostgreSQL 附加组件链接到应用程序时，Clever Cloud 会自动设置POSTGRESQL_ADDON_URI环境变量

  • 该应用程序需要 Node.js 20 或更高版本，可在 Clever Cloud 上获取

  • 该应用程序将自动在端口 8080 上运行，这是 Clever Cloud 上 Node.js 应用程序的默认端口

执照

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

致谢

Available Tools

6 tools
addA

Add two numbers

ParametersJSON Schema
NameRequiredDescriptionDefault
aYes
bYes

TDQS

A3.5/5.0
Behavior4/5

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

No annotations are provided, so the description carries the full burden. 'Add two numbers' accurately describes a pure, stateless, non-destructive operation. For such a simple arithmetic tool, this is sufficient transparency, though it could explicitly state that it has no side effects.

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 a single, front-loaded sentence that conveys the essential action without any unnecessary words. It is highly concise and structured effectively.

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

Completeness4/5

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

Given the tool's extreme simplicity (add two numbers), the description is largely complete. It could mention the return value (the sum), but that is easily inferred. The lack of output schema does not significantly degrade completeness here.

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

Parameters1/5

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

Schema description coverage is 0% – the description does not explain the two parameters 'a' and 'b' or their roles beyond what the schema already provides. With no additional meaning added, this dimension is severely lacking.

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 'Add two numbers', specifying the verb 'add' and the resource 'two numbers'. This distinguishes it from sibling tools like sub, mul, div, mod, and sqrt, which perform different operations.

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?

The description provides no guidance on when to use this tool versus alternatives. For example, it does not explain when addition is preferred over subtraction or multiplication. The usage context is entirely implied.

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

getHabitatsB

Get a list of all available habitats in the database

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.2/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states it retrieves a list but doesn't specify if it's read-only, safe, paginated, or has any side effects. For a tool with zero annotation coverage, this is a significant gap in transparency.

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 a single, efficient sentence that directly states the tool's function without any fluff. It's appropriately sized and front-loaded, making it easy to parse quickly.

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 tool's simplicity (0 parameters, no output schema, no annotations), the description is minimally adequate. However, it lacks details on behavioral aspects like safety or output format, which would be helpful for an agent to use it correctly, especially without annotations.

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 input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description doesn't add param info, which is fine here, but it could hint at any implicit constraints (e.g., sorting or limits), though not required. Baseline is high due to no parameters.

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 clearly states the verb ('Get') and resource ('list of all available habitats'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'getMonsterByHabitat' or 'getMonsters', which also retrieve data but with different scopes or filters, so it lacks sibling distinction.

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?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention scenarios where this tool is preferred over siblings like 'getMonsterByHabitat' (which filters by habitat) or 'getMonsters' (which retrieves monsters instead of habitats), leaving the agent without usage context.

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

getMonsterByHabitatA

Get monsters by habitat (exact match only). IMPORTANT: for best results, first call getHabitats to get a list of available habitats, then find the most appropriate one to use with this tool.

ParametersJSON Schema
NameRequiredDescriptionDefault
habitatYesExact habitat name (must match exactly). For best results, first call getHabitats to get a list of available habitats, then find the most appropriate one to use with this tool.
limitNoMaximum number of results to return (default: 10)

TDQS

A4/5.0
Behavior3/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the 'exact match only' constraint, which is useful behavioral context beyond basic functionality. However, it lacks details on error handling, rate limits, authentication needs, or what the return format looks like (e.g., list of monsters with specific fields).

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 concise and well-structured: two sentences that efficiently convey purpose and usage guidelines without wasted words. The first sentence states the core functionality, and the second provides critical procedural advice, both earning their place.

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

Completeness4/5

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

Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is fairly complete. It covers purpose, usage guidelines, and a key behavioral constraint ('exact match only'). However, without annotations or an output schema, it could benefit from more details on return values or error cases, but it's adequate for basic use.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents both parameters ('habitat' and 'limit') with descriptions. The description repeats the guidance about calling 'getHabitats' for the 'habitat' parameter but doesn't add new semantic meaning beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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 clearly states the tool's purpose: 'Get monsters by habitat (exact match only).' It specifies the verb ('Get'), resource ('monsters'), and constraint ('by habitat, exact match only'). However, it doesn't explicitly differentiate from siblings like 'getMonsters' (which might fetch all monsters) or 'getMonsterByName' (which filters by name rather than habitat).

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

Usage Guidelines5/5

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

The description provides explicit usage guidance: 'for best results, first call getHabitats to get a list of available habitats, then find the most appropriate one to use with this tool.' This tells the agent when to use this tool (after retrieving habitat list) and references a sibling tool ('getHabitats') as a prerequisite, offering clear alternatives and context.

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

getMonsterByIdB

Get detailed information about a specific monster by ID

ParametersJSON Schema
NameRequiredDescriptionDefault
monsterIdYesID of the monster to retrieve

TDQS

B3.1/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves 'detailed information' but doesn't specify what that includes (e.g., stats, abilities, weaknesses), whether it's a read-only operation, error handling for invalid IDs, or performance characteristics like rate limits. This leaves significant gaps for agent understanding.

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 a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is front-loaded with the core action and resource, making it easy to parse quickly.

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?

For a simple lookup tool with one parameter and no output schema, the description is minimally adequate. However, it lacks details on the returned data structure (e.g., what 'detailed information' entails) and behavioral aspects like error cases, which would help an agent use it correctly. The absence of annotations exacerbates these gaps.

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

Parameters3/5

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

The schema description coverage is 100%, with the parameter 'monsterId' clearly documented as 'ID of the monster to retrieve'. The description adds no additional semantic context beyond what the schema provides, such as format examples or valid ranges. Given the high schema coverage, the baseline score of 3 is appropriate.

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 clearly states the verb ('Get detailed information') and resource ('about a specific monster by ID'), making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'getMonsterByName' or 'getMonsterByHabitat', which also retrieve monster information but use different identifiers.

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?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'getMonsterByName' (for name-based lookup) or 'getMonsterByHabitat' (for habitat-based filtering), nor does it specify prerequisites such as needing a valid monster ID.

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

getMonsterByNameA

Get monsters by name (partial match, returns up to 5 matches)

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesName of the monster to search for (can be partial)

TDQS

A3.5/5.0
Behavior3/5

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

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: partial matching and a limit of 5 results, which are valuable beyond basic 'get' functionality. However, it lacks details on error handling, authentication needs, or rate limits, leaving gaps for a tool with no annotation coverage.

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 extremely concise and front-loaded: a single sentence that efficiently conveys the core functionality and key constraints. Every word earns its place, with no wasted text or redundancy.

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 tool's low complexity (1 parameter, no output schema, no annotations), the description is minimally complete. It covers the basic operation and behavioral constraints but lacks details on output format or error cases. For a simple lookup tool, this is adequate but leaves room for improvement in contextual richness.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents the 'name' parameter as 'Name of the monster to search for (can be partial).' The description adds no additional meaning beyond this, merely restating 'partial match.' Baseline 3 is appropriate as the schema handles parameter documentation adequately.

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 clearly states the tool's purpose: 'Get monsters by name' specifies the verb (get) and resource (monsters). It distinguishes from siblings like getMonsterById and getMonsters by focusing on name-based retrieval. However, it doesn't explicitly differentiate from getMonsterByHabitat, which is a similar lookup but by different criteria.

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

Usage Guidelines3/5

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

The description implies usage context through 'partial match, returns up to 5 matches,' suggesting it's for fuzzy name searches with result limits. However, it doesn't explicitly state when to use this versus alternatives like getMonsterById (exact ID match) or getMonsters (full list). No guidance on prerequisites or exclusions is provided.

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

getMonstersB

Get a list of monsters with optional filtering, sorting, and pagination

ParametersJSON Schema
NameRequiredDescriptionDefault
filtersNoOptional filters for the query
limitNoMaximum number of results to return (default: 10)
offsetNoNumber of results to skip for pagination (default: 0)
sortNoOptional sorting parameters

TDQS

B3.2/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions filtering, sorting, and pagination but doesn't describe important traits like whether this is a read-only operation, what happens with invalid filters, rate limits, authentication requirements, or the format of returned results. For a list retrieval tool with zero annotation coverage, this leaves significant gaps.

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 a single, efficient sentence that front-loads the core purpose ('Get a list of monsters') and then succinctly lists the key capabilities. Every word earns its place with no redundancy or unnecessary elaboration.

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

Completeness2/5

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

Given no annotations and no output schema, the description is incomplete for a tool with four parameters and nested objects. It doesn't explain what the returned list looks like, how errors are handled, or important behavioral aspects like default values or constraints. For a list retrieval tool with filtering capabilities, more context is needed to be fully helpful.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all four parameters thoroughly. The description adds minimal value by mentioning 'optional filtering, sorting, and pagination' which aligns with the schema but doesn't provide additional semantic context beyond what's already in the parameter descriptions. This meets the baseline for high schema coverage.

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 clearly states the verb ('Get') and resource ('list of monsters'), making the purpose immediately understandable. It distinguishes itself from siblings like getMonsterById or getMonsterByName by indicating it returns a list rather than a single entity. However, it doesn't explicitly differentiate from getMonsterByHabitat which also involves filtering.

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

Usage Guidelines3/5

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

The description implies usage through 'optional filtering, sorting, and pagination', suggesting this tool is for general queries rather than specific lookups. However, it doesn't explicitly state when to use this versus alternatives like getMonsterByHabitat or getMonsterById, nor does it provide any exclusions or prerequisites for usage.

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. 6 tool updatesv1.0.0
    • First observedadd
    • First observedgetHabitats
    • First observedgetMonsterByHabitat
    • First observedgetMonsterById
    • First observedgetMonsterByName
    • First observedgetMonsters
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.2/5.0

Scored across 6 tools

Disambiguation4/5

Most tools have distinct purposes, but 'getMonsterByHabitat' and 'getMonsters' could cause confusion since both retrieve monsters with filtering capabilities. The descriptions clarify that 'getMonsterByHabitat' is for exact habitat matching while 'getMonsters' offers broader filtering, but agents might still misselect between them.

Naming Consistency3/5

The naming is mixed with inconsistent patterns: 'add' uses a generic verb, 'getHabitats' and 'getMonsters' follow a verb_noun plural pattern, while 'getMonsterByHabitat', 'getMonsterById', and 'getMonsterByName' use a verb_noun_preposition format. This creates readability but lacks uniformity across all tools.

Tool Count4/5

With 6 tools, the count is reasonable for a PostgreSQL-based monster database server. It covers core operations like adding data and querying monsters in various ways, though it might benefit from additional tools for updates or deletions to be fully scoped.

Completeness3/5

The tool set covers querying and adding data well, but there are notable gaps for a database server: no update or delete tools for monsters or habitats, and no tool for creating habitats. This limits full lifecycle management and could cause agent failures in more complex workflows.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-ohmy-sql

    MacHu-GWU
    -
    license
    Not graded
    quality
    C
    maintenance
    An MCP server that bridges AI assistants with SQL databases, enabling natural language querying across multiple database types with built-in optimization and security.
    3
    -

  • scopedb-mcp

    xieweicong
    A
    license
    Not graded
    quality
    D
    maintenance
    Config-driven MCP server that gives AI scoped, auditable database access without exposing the entire database.
    5 npm
    6
    MIT

  • sqldb-mcp-server

    akrym1582
    A
    license
    A
    quality
    A
    maintenance
    A read-only MCP server that exposes SQL database access to LLMs, supporting multiple database types, compact columnar results, pagination, and file export.
    7
    28 npm
    MIT