관계형 데이터베이스를 탐색하고 안전하게 쿼리하기 위한 FastMCP 서버입니다. 로컬 개발 데이터베이스는 SQLite이며, SQLAlchemy는 해당 드라이버를 통해 PostgreSQL과 MySQL도 지원합니다.
MCP 클라이언트는 자연어 추론을 수행하고 SQL을 생성합니다. 이 서버는 데이터베이스 도구를 노출하고, 읽기 전용 쿼리를 검증하며, 이를 실행하고 구조화된 결과를 반환합니다.
MCP client LLM -> FastMCP tools -> safety layer -> SQLAlchemy -> database이 서버는 Anthropic을 호출하지 않으므로 Anthropic API 키가 필요하지 않습니다.
Related MCP server: nl2sql-mcp
uv를 설치한 후 이 디렉터리에서 다음을 실행하세요:
uv sync
uv run python tests/seed_test_db.py
uv run pytestuv가 아직 PATH에 없다면 다음을 사용하세요:
py -m uv sync
py -m uv run pytest기본 데이터베이스는 다음과 같습니다:
sqlite:///sample.db다른 데이터베이스를 사용하려면 서버를 시작하기 전에 DATABASE_URL을 설정하세요. 예:
$env:DATABASE_URL = "sqlite:///C:/data/example.db"
$env:DATABASE_URL = "postgresql+psycopg2://user:password@localhost:5432/example"
$env:DATABASE_URL = "mysql+pymysql://user:password@localhost:3306/example"uv run server.py공유 가능한 VS Code MCP 구성은 .vscode/mcp.json에 있습니다. stdio를 통해 서버를 시작하며 MCP 호환 클라이언트 및 Inspector와 함께 사용할 수 있습니다.
원격 호스팅의 경우 Streamable HTTP를 사용하세요:
$env:MCP_TRANSPORT = "streamable-http"
$env:MCP_HOST = "0.0.0.0"
$env:MCP_PORT = "8000"
uv run server.py원격 배포는 인증을 제공하고 비밀 구성을 통해 DATABASE_URL을 보호해야 합니다.
explore_schema: 테이블 목록을 표시하거나 하나의 테이블을 검사합니다
execute_query: 안전한 읽기 전용 SELECT 하나를 실행합니다
explain_query: 네이티브 실행 계획을 반환합니다
validate_schema: 누락된 기본 키와 인덱스가 없는 외래 키를 보고합니다
suggest_index: 테이블 메타데이터 또는 쿼리 계획에서 인덱스를 제안합니다
migration_context: 클라이언트 측 마이그레이션 생성을 위한 스키마 컨텍스트를 제공합니다
validate_migration: 제안된 UP 및 DOWN 스크립트를 실행하지 않고 검증합니다
모든 쿼리 실행과 설명은 안전 계층을 통과합니다. 변경 구문, 주석, 다중 구문은 거부됩니다. 쿼리 결과는 기본적으로 최대 100행으로 제한됩니다.
uv run pytest테스트 스위트는 임시 SQLite 데이터베이스를 사용하며 외부 자격 증명이나 실행 중인 데이터베이스 서버가 필요하지 않습니다.
FastMCP Horizon 배포 단계, 원격 데이터베이스 요구 사항 및 인증 체크리스트는 DEPLOYMENT.md를 참조하세요.
Execute one validated, read-only SQL SELECT query.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | ||
| row_limit | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full transparency burden. It does disclose that the operation is read-only and limited to one SELECT query, which is valuable. However, it does not mention row_limit behavior, validation semantics, permissions, or effect on resources.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no fluff or redundancy. Every word contributes meaning, making it an efficient, front-loaded description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A completed enough for a very simple tool, especially given an output schema exists. However, it omits the row_limit behavior and does not explain what validates the query or how the tool relates to validation, leaving the user without a fully complete picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameter semantics. The description only references the SQL query itself but does not mention row_limit or clarify how the two parameters interact. This leaves an important parameter undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Execute'), the resource ('SQL SELECT query'), and a key constraint ('read-only'). It is specific enough to differentiate from siblings like explain_query and validate_schema, though it does not explicitly name sibling alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given about when to use this tool vs alternatives such as explain_query or validate_schema. The read-only SELECT wording implies the tool is for running queries, but it does not state exclusions or provide decision-making context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the database execution plan for one safe SELECT query.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits itself. It mentions 'safe SELECT' but does not clarify what 'safe' means (e.g., read-only, no side effects) or describe any permissions, limitations, or output format. The description is too terse to adequately inform an agent about behavior beyond the basic function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the primary action and scope. Every word contributes meaning, with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal and does not explain what 'safe' means or what the execution plan looks like claiming to rely on the output schema. Since the tool has an output schemaache, return values are implicitly covered, but the description lacks details on limitations (e.g., only SELECT, read-only behavior, privileges) that are not captured elsewhere. Given the simple nature of the tool and existing output schema, it is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverageaine, so the description must compensate. The phrase 'one safe SELECT query' adds constraint that the sql parameter must be a SELECT statementable, but it does not specify allowed syntax, single-statement requirement, or other constraints. This is minimal compensation; a more detailed description of the sql parameter would be needed for a higher score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a database execution plan for a SELECT query. This is a specific verb-resource pairing that distinguishes it from siblings like execute_query (which actually runs queries) or suggest_index (which recommends indexes).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for SELECT queries only ('one safe SELECT query'), but does not explicitly state when to use this tool instead of alternatives like execute_query or suggest_index. No exclusions or alternative comparisons are provided, so the guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explore database tables, columns, keys, indexes, and sample rows.
| Name | Required | Description | Default |
|---|---|---|---|
| table_name | No | ||
| include_sample_data | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It mentions the tool explores tables, columns, keys, indexes, and sample rows—implying a read-only nature. However, it does not disclose specific behaviors like sample row limits, whether all tables are listed when no table_name is given, or any performance implications for large schemas. Some transparency is present, but important details are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that front-loads the verb and resource list. No wasted words, no redundant information. It is efficient and immediately understandable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and only a single parameter, the description must compensate for context. It lists what the tool explores but does not specify behavior when table_name is null (list all tables?) or provided (details for one table?), nor what 'sample rows' means (count? random? first N?). For a tool with moderate complexity and no other metadata, this is adequate but incomplete—more detail on parameters and behaviors would be expected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema defines table_name as optional (string or null with default null), but the description does not explain its semantics—e.g., 'omit to list all tables' or 'specify to get details for a particular table.' Since schema coverage is limited (no descriptions in the schema), the description could have clarified how the parameter affects behavior. There is a general connection (the tool explores tables, so table_name likely filters by table), but this is only implied, not explicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('explore') with a clear resource list ('database tables, columns, keys, indexes, and sample rows'). This clearly communicates the tool's function and distinguishes it from sibling tools like query execution or explanation tools. It loses one point because it doesn't explicitly differentiate itself by naming any sibling tool or stating what it does NOT do (e.g., modifications, query execution).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys that this tool is for exploring schema structure, which implies usage for inspection rather than data manipulation. However, it lacks explicit guidance on when to use this tool versus alternatives (e.g., 'use get_schema for just columns' or 'don't use this for querying data'). No exclusions or alternative tool references are given, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return schema context for client-side migration generation.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only mentions 'Return schema context' without stating whether it is read-only, what side effects (if any) exist, or performance characteristics. This is minimal and does not add meaningful transparency beyond the tool name itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the tool's purpose. There is no fluff or redundancy, and every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so the description need not explain return values. It is a simple no-parameter tool, and the purpose is clear. However, it could briefly mention what 'schema context' encompasses, but given the output schema and simplicity, it is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4 per the rubric. The description adds no param-related info because there are none, and the schema already confirms no parameters, so there is no deficiency to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'return' and the resource 'schema context' with a specific purpose 'for client-side migration generation.' This distinguishes it from siblings like 'validate_schema' or 'explore_schema' by its intended use, though it doesn't explicitly contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the sibling tools, such as 'explore_schema' or 'validate_migration.' The description only states what it does, leaving the agent to infer usage context without helpful exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Suggest indexes from a query plan or table foreign-key metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | ||
| table_name | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description does not mention side effects, permissions, or behavior when both parameters are provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, clear and free of unnecessary wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks information about the output format, parameter relationships, and expected usage scenarios, making it incomplete for a tool with two optional parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description loosely references the parameters (query plan and table foreign-key metadata) but does not clarify their formats, constraints, or how they are used.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool suggests indexes, using either a query plan or table foreign-key metadata, which distinguishes it from sibling tools like explain_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives, such as when query optimization is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate migration scripts without executing them.
| Name | Required | Description | Default |
|---|---|---|---|
| up_sql | Yes | ||
| down_sql | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of revealing behavior. It does disclose a key trait—non-execution—which is valuable for a validation tool. Nonetheless, it lacks other behavioral details (e.g., does it require a DB connection? what is the failure mode?), leaving some gaps. It adds value but not comprehensively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-constructed sentence delivers the core message with zero wasted words. It is front-loaded and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two string parameters, an output schema (though not shown in the prompt), and a concise description, the context is largely adequate. The description covers the essential safety aspect. Minor gaps exist: potential side-effects or prerequisites are unmentioned, but for a validation utility, the description meets most expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the parameter names 'up_sql' and 'down_sql' are self-explanatory as migration scripts. The description refers to them collectively as 'migration scripts' but adds no detail about format or constraints. The baseline is acceptable due to intuitive parameter names, but the description does not explicitly compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Validate') and resource ('migration scripts'), and adds a crucial qualifier ('without executing them') that distinguishes it from siblings like execute_query and validate_schema. This is a strong, purpose-driven statement that leaves no ambiguity about the tool's role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'without executing them' phrase implies a safe-to-run interpretation, which implicitly guides usage. However, it does not explicitly name alternatives or provide when/when-not conditions. The usage context is implied rather than stated, so it earns a mid-range score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check tables for missing primary keys and unindexed foreign keys.
| Name | Required | Description | Default |
|---|---|---|---|
| table_name | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does not state whether the tool is read-only or if it has side effects, nor does it describe the output format or any side effects, making its behavior opaque.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly states the tool's function with no redundant words or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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, the description should explain what the tool returns, but it omits that. It also lacks context about parameter semantics and usage scenarios, leaving the description incomplete for a tool with even a single parameter and output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameter 'table_name' is not explained. The description does not clarify whether it targets a specific table or all tables, nor what happens when it is null. Since the schema provides no parameter description (0% coverage), the description fails entirely to add meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to check for missing primary keys and unindexed foreign keys. This specific action distinguishes it from sibling tools like explore_schema or suggest_index, making its function unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention scenarios, prerequisites, or how it differs from other validation-related tools, leaving the agent without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0execute_queryexplain_queryexplore_schemamigration_contextsuggest_indexvalidate_migrationvalidate_schemaScored across 7 tools
Most tools have distinct purposes: exploring, executing, explaining, validating, and suggesting indexes are clearly separate. The main overlap risk is between explore_schema and migration_context, since both provide schema context, but their intended use cases differ enough to avoid serious confusion.
Six of seven tools follow a clean verb_noun pattern (explore_schema, execute_query, explain_query, validate_schema, suggest_index, validate_migration). migration_context breaks the pattern by being a noun phrase, but the overall naming style remains predictable and readable.
With 7 tools, the server is well-scoped for the stated purpose of database exploration, query execution, and migration validation. Each tool addresses a meaningful workflow step without unnecessary bloat.
The toolset covers the core read-only database workflows: schema inspection, query validation/execution/explanation, structural tenant-focused checks, index suggestions, and migration validation. No obvious dead-end exists for the server's stated purpose.
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
GibsonAI MCP server: manage your databases with natural language
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
