使用 mcp-toolbox 的 mssql-list-tables 工具获取 SQL Server 表结构元数据【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox本指南面向在 MCP Toolbox for Databases即本仓库 mcp-toolbox中需要为 AI Agent 提供 SQL Server 数据库结构感知能力的开发者。mssql-list-tables是一个只读工具能以 JSON 形式返回 SQL Server 数据库中用户表的完整 Schema 信息列、约束、索引、触发器、属主与注释或仅返回表名列表是构建先看结构、再写 SQL的数据库 Agent 工作流的关键一环。读完本文你将掌握该工具的输入参数、YAML 配置方式、两种输出格式的区别以及其底层基于 SQL Server 系统视图的元数据查询实现原理。工具概述为 Agent 提供表结构清单能力在数据库 Agent 场景中模型在生成 SQL 之前通常需要先了解目标表的结构。mssql-list-tables正是为此设计它检索 SQL Server 数据库中全部或指定用户表的 Schema 信息并以 JSON 形式返回内容包括对象类型普通表或分区表、列定义、约束、索引、触发器、属主owner和注释comment。从源码结构看该工具被设计为只读工具在 mssqllisttables.go 的初始化逻辑中它通过tools.NewReadOnlyAnnotations设置只读注解表明它不会对数据库执行任何写操作适合嵌入到需要先探测 Schema 再生成查询语句的 Agent 决策链中。输入参数mssql-list-tables接受两个可选输入参数由 Initialize 中的参数清单定义参数名类型必填默认值说明table_namesstring否逗号分隔的表名列表用于过滤。为空时列出用户 Schema 下的全部表output_formatstring否detailed输出格式simple仅返回表名detailed返回完整表信息table_names按需过滤避免输出过载默认空字符串情况下工具会列出用户 Schema中的全部表。源码中过滤了sys、INFORMATION_SCHEMA、guest以及一系列db_*固定数据库角色 Schema见 listTablesStatement确保系统表与系统对象不会混入结果。当你只需要关注某几张表时可以传入逗号分隔的表名例如table_names: orders,order_items。output_formatsimple 与 detailed 的分工simple仅返回表名适合快速盘点数据库中有哪些表响应体量小、token 消耗低detailed默认返回完整表信息包括每张表的 Schema、列含数据类型、序号、可空性、默认值、注释、约束主键、唯一、外键、CHECK、索引含包含列与过滤条件、触发器及其启用状态。值得注意的是工具在 Invoke 中对output_format做了严格校验取值必须是simple或detailed之一否则返回 Agent 错误invalid value for output_format这一层防御避免了非法参数被透传到 SQL 层。兼容的数据源Compatible Sourcesmssql-list-tables工具必须挂载在兼容的数据源之上运行。该工具通过compatibleSource接口见 mssqllisttables.go与数据源交互要求数据源实现MSSQLDB() *sql.DB与RunSQL(context.Context, string, []any) (any, error)两个方法本仓库内置的mssql类型源internal/sources/mssql/mssql.go天然满足该接口其MSSQLDB()返回基于 github.com/microsoft/go-mssqldb 的连接池RunSQL负责执行查询并把结果集规整为 JSON云端场景下Cloud SQL for SQL Server 集成见 docs/en/integrations/cloud-sql-mssql同样与之兼容因此本工具可同时覆盖自建 SQL Server 与 Google Cloud 托管实例。若配置中指定的source不兼容ValidateSource 会直接报错并拒绝启动这是一种在配置期就把错误暴露出来的设计。配置示例在 Toolbox 配置文件中声明工具与其他工具一样mssql-list-tables通过 YAML 片段声明为一个 tool。下面是最小可用配置kind: tool name: mssql_list_tables type: mssql-list-tables source: mssql-source description: Use this tool to retrieve schema information for all or specified tables. Output format can be simple (only table names) or detailed.Reference 字段说明字段类型必填说明typestringtrue必须为mssql-list-tablessourcestringtrue执行 SQL 的数据源名称须指向一个mssql类型的源descriptionstringtrue传递给 Agent 的工具描述应清晰说明用途与参数语义其中description在源码中是被强制要求的如果为空Initialize 会返回 description is required 错误。name与source的解析逻辑已由单测覆盖见 mssqllisttables_test.go其中验证了authRequired等可选字段也能被正确解析。配套的数据源配置工具引用的source需要在同一配置中定义为mssql类型源完整字段见 docs/en/integrations/mssql/source.mdkind: source name: mssql-source type: mssql host: 127.0.0.1 port: 1433 database: my_db user: ${USER_NAME} password: ${PASSWORD} # encrypt: strict其中user/password支持以${ENV_NAME}形式引用环境变量避免把密钥硬编码进配置文件encrypt可选缺省时使用 go-mssqldb 驱动自身的默认加密级别。对应源码中 mssql.go 的Config结构host、port、user、password、database均为必填初始化时会通过db.PingContext验证连接可用性mssql.go。使用预构建配置快速启动如果不想手工拼装配置可以直接使用预构建配置--prebuilt mssql详见 docs/en/integrations/mssql/prebuilt-configs/microsoft-sql-server.md它会自动注册execute_sql与list_tables两个工具并读取MSSQL_HOST、MSSQL_PORT、MSSQL_DATABASE、MSSQL_USER、MSSQL_PASSWORD环境变量。该模式下list_tables即对应本文介绍的mssql-list-tables。底层实现一段查询驱动全部 Schema 元数据mssql-list-tables的核心是一条长 SQL 语句定义于 mssqllisttables.go它全部基于 SQL Server 系统目录视图catalog views完成元数据采集运行时通过sql.Named参数table_names、output_format注入过滤条件。整体结构可分五层理解1. 表级信息table_info CTE从sys.tables关联sys.schemas、sys.database_principals取 Schema 属主名与sys.extended_properties取MS_Description扩展属性作为表注释。这里有一个值得注意的判定逻辑CASE WHEN EXISTS ( SELECT 1 FROM sys.partitions p WHERE p.object_id t.object_id AND p.partition_number 1 ) THEN PARTITIONED TABLE ELSE TABLE END AS object_type_detail即通过检查sys.partitions中是否存在partition_number 1的记录来区分普通表与分区表——这正是文档中object type字段的实现来源。2. 列级信息columns_info CTE从sys.columns关联sys.types取得基类型is_user_defined 0并把长度、精度等信息拼装成可读的数据类型字符串例如char/varchar/nchar/nvarchar/binary/varbinary会展开为VARCHAR(50)或NVARCHAR(MAX)形式max_length -1时输出MAXnchar/nvarchar的长度按字符而非字节计算decimal/numeric输出精度与标度如DECIMAL(10,2)datetime2/datetimeoffset/time输出小数秒精度。同时关联sys.default_constraints取列默认值、关联扩展属性取列注释并以column_id排序保证列顺序稳定。3. 约束信息constraints_info CTE通过三个UNION ALL分支合并主键与唯一约束来自sys.key_constraintstype_desc去掉_CONSTRAINT后缀得到PRIMARY_KEY/UNIQUE用FOR XML PATH技巧把多列拼成PRIMARY KEY (col1, col2)形式的定义外键来自sys.foreign_keys额外带出被引用表schema.table与被引用列CHECK 约束来自sys.check_constraints直接携带cc.definition表达式。4. 索引与触发器信息indexes_info、triggers_info CTEindexes_info从sys.indexes聚合索引名、方法CLUSTERED/NONCLUSTERED/XML 等、是否唯一、是否主键并生成COLUMNS: (...)、INCLUDE: (...)、FILTER: (...)三段式定义文本通过i.type 0排除堆Heapi.name IS NOT NULL排除未命名索引triggers_info从sys.triggers取 DML 触发器parent_class_desc OBJECT_OR_COLUMN的名称、定义与启用状态ENABLED/DISABLED并排除系统自带触发器is_ms_shipped 0。5. JSON 组装与输出最外层SELECT根据output_format分支simple时每行只输出{ name: 表名 }detailed时用FOR JSON PATH, WITHOUT_ARRAY_WRAPPER把上述 CTE 按table_oid关联组装成包含schema_name、object_name、object_type、owner、comment、columns、constraints、indexes、triggers的单对象 JSON其中数组字段统一用JSON_QUERY(ISNULL(..., []))兜底保证无数据时返回[]而非null。运行期行为补充查询通过source.RunSQL执行Invoke异常统一走util.ProcessGeneralError包装如果结果为空如数据库中没有任何用户表工具会返回空列表[]any{}而不是null方便 Agent 稳定地处理mssqllisttables.go。典型使用场景Schema 探索simpleAgent 接到数据库里有哪些表这类问题先以output_format: simple低成本拿到表名清单再决定下一步SQL 生成前置detailedAgent 需要针对某张表写查询时用table_names精确指定目标表并以detailed格式获取列名、类型、约束从而生成更准确的 SQL——该模式与mssql-execute-sql见 docs/en/integrations/mssql/tools/mssql-execute-sql.md组合即可构成读结构 → 写 SQL → 执行 → 返回结果的完整链路变更感知对表注释、触发器启用状态等细节的返回可帮助 Agent 判断 DDL 变更或审计类需求而无需人工翻阅 SSMS 界面。注意事项与适用前提该工具面向开发者辅助工作流human-in-the-loop与mssql-execute-sql一样不宜直接用于无人值守的生产 Agent 环境执行该工具需要数据库用户具备对系统目录视图的读取权限普通登录用户默认即可读取sys.*视图无需特殊授权预构建配置的权限要求见 microsoft-sql-server.mdtable_names的过滤匹配是精确匹配t.name IN (...)不支持通配符分区表的判定基于任一索引或堆存在分区号大于 1这一启发式规则实际使用中应以目标库的分区设计为准。小结mssql-list-tables用一条精心构造的系统视图查询把 SQL Server 表结构元数据封装成对 LLM 友好的 JSON 输出并通过table_names、output_format两个参数控制粒度与开销。无论是搭配自建mssql源还是 Cloud SQL for SQL Server它都是为数据库 Agent 提供结构感知能力的低成本、只读、可直接嵌入配置的方案。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考