MCP Toolbox for Databases 的 postgres-list-stored-procedure 工具：存储过程元数据清单查询实战指南

MCP Toolbox for Databases 的 postgres-list-stored-procedure 工具：存储过程元数据清单查询实战指南

【免费下载链接】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（本仓库）中的postgres-list-stored-procedure工具展开，完整讲解其工作原理、底层 SQL 实现、参数语义、配置方法与返回结构，并给出可直接运行的请求示例。读完本文，你将掌握如何通过 MCP 接口批量获取 PostgreSQL 存储过程的定义、属主、语言与注释信息，并将其用于代码审计、文档生成、权限核查、迁移规划与安全评估等真实场景。

工具概览：一次查询返回完整存储过程元数据

postgres-list-stored-procedure是一个只读工具，用于检索 PostgreSQL 数据库中所有存储过程（stored procedure）的元数据。它直接查询 PostgreSQL 系统目录表pg_proc、pg_namespace、pg_roles与pg_language，通过四表 JOIN 组装出包含如下信息的 JSON 数组：

• 存储过程所属的 schema（模式）；
• 存储过程名称；
• 拥有该存储过程的角色（owner）；
• 编写该存储过程的语言（如plpgsql、sql、c）；
• 完整的、可直接执行的CREATE PROCEDURE定义语句；
• 通过COMMENT命令设置的描述信息（可能为null）。

结果默认按 schema 名称与过程名称排序，默认最多返回 20 条记录。

典型使用场景

原文档明确了该工具的六大核心用途，均围绕"批量获取存储过程元数据"这一能力展开：

• 代码审查与审计：导出过程定义用于版本管理或合规审计；
• 文档生成：自动提取过程元数据与描述信息，生成数据库文档；
• 权限审计：识别被特定用户拥有、或位于特定 schema 中的过程；
• 迁移规划：在数据库迁移前一次性取回所有过程定义；
• 依赖分析：通过阅读定义了解过程间的调用链与依赖关系；
• 安全评估：审计哪些角色拥有并可修改存储过程。

底层实现：基于系统目录的 JOIN 查询

在仓库源码 internal/tools/postgres/postgresliststoredprocedure/postgresliststoredprocedure.go 中，工具的核心是一条固化在代码里的参数化 SQL，其结构如下（已按源码整理）：

SELECT n.nspname AS schema_name, p.proname AS name, r.rolname AS owner, l.lanname AS language, pg_catalog.pg_get_functiondef(p.oid) AS definition, pg_catalog.obj_description(p.oid, 'pg_proc') AS description FROM pg_catalog.pg_proc p JOIN pg_catalog.pg_namespace n ON n.oid = p.pronamespace JOIN pg_catalog.pg_roles r ON r.oid = p.proowner JOIN pg_catalog.pg_language l ON l.oid = p.prolang WHERE p.prokind = 'p' AND ($1::text IS NULL OR r.rolname LIKE '%' || $1::text || '%') AND ($2::text IS NULL OR n.nspname LIKE '%' || $2::text || '%') ORDER BY n.nspname, p.proname LIMIT COALESCE($3::int, 20);

对该 SQL 的逐段解读：

• p.prokind = 'p'是关键过滤条件：PostgreSQL 的pg_proc.prokind字段区分过程（'p'）、函数（'f'）、聚合函数（'a'）与窗口函数（'w'）。该条件保证了工具只返回存储过程，而将普通函数等其他可调用对象全部排除；
• pg_get_functiondef(p.oid)：PostgreSQL 内建函数，根据 oid 重建完整的、可直接运行的CREATE OR REPLACE PROCEDURE ...定义文本，这正是definition字段的来源；
• obj_description(p.oid, 'pg_proc')：读取pg_description目录表中该对象的注释，即COMMENT ON PROCEDURE ... IS '...'写入的描述，未设置注释时返回null；
• 三个占位参数$1、$2、$3：分别对应role_name、schema_name与limit。前两者为NULL时过滤条件自动失效，limit通过COALESCE($3::int, 20)在未传值时回退到默认值 20；
• ORDER BY n.nspname, p.proname：保证输出顺序稳定，便于对比与分页。

从源码可以看出，参数全部通过pgx连接池以参数化查询方式传入（见 postgresliststoredprocedure.go），不存在 SQL 注入拼接问题，这是一个安全设计细节。

工具注册与调用链路

该工具遵循 MCP Toolbox 统一的"注册—配置—调用"模式：

1. 包内init()调用tools.Register("postgres-list-stored-procedure", newConfig)完成类型注册（postgresliststoredprocedure.go），Register的通用机制定义在 internal/tools/tools.go；
2. 配置解析阶段声明三个入参role_name、schema_name、limit（postgresliststoredprocedure.go），其中limit带默认值 20；
3. Invoke方法从请求参数中取出标准参数，通过source.PostgresPool().Query(...)执行上述 SQL，并逐行把结果字段名与取值组装为map[string]any返回（postgresliststoredprocedure.go）。

兼容数据源：一次实现，三种数据库引擎复用

原文档通过compatible-sources声明了该工具的兼容来源。结合源码 postgresliststoredprocedure.go，工具定义了一个最小接口compatibleSource：

type compatibleSource interface { PostgresPool() *pgxpool.Pool }

只要数据源实现了PostgresPool()方法即可直接复用本工具。源码中通过编译期断言确认了以下三类数据源均满足该接口：

• PostgreSQL原生数据源，见 internal/sources/postgres；
• AlloyDB for PostgreSQL，见 internal/sources/alloydbpg；
• Cloud SQL for PostgreSQL，见 internal/sources/cloudsqlpg。

因此，同一份工具配置可以无缝切换到本地 PostgreSQL、AlloyDB 或 Cloud SQL for PostgreSQL 连接。这一点与官方文档中 AlloyDB 与 Cloud SQL for PostgreSQL 的兼容说明一致。若传入的数据源不满足该接口，Invoke会返回"source used is not compatible with the tool"错误（postgresliststoredprocedure.go）。

参数说明

工具的请求参数如下表（与源码中parameters.Parameters声明一致）：

参数语义要点：

• role_name与schema_name都使用LIKE '%' || $n || '%'做包含式（部分）匹配，例如传"app"会同时命中app_user、app_admin等角色；
• 两个过滤参数均为可选，缺省时对应NULL，过滤条件自动失效，即"不过滤"；
• limit缺省为 20，传入值通过COALESCE覆盖默认值；当数据库中的过程数量很大时建议显式调高。

配置方法

在 MCP Toolbox 的 YAML 配置体系中，该工具以kind: tool声明，并归属到某个 source。文档给出的最小配置示例如下：

kind: tool name: list_stored_procedure type: postgres-list-stored-procedure source: postgres-source description: "Retrieves stored procedure metadata including definitions and owners."

配置字段说明：

• name：工具实例名称，供 Agent 调用时引用；
• type：固定为postgres-list-stored-procedure，是注册表中的资源类型标识；
• source：指向一个已配置且兼容的数据源（PostgreSQL / AlloyDB / Cloud SQL for PostgreSQL）；
• description：可选的工具描述，缺省时源码会自动填入默认描述（postgresliststoredprocedure.go）；
• authRequired：可选，可声明该工具调用所需的 Google 认证服务列表（见测试用例中的用法）。

此外，仓库的预构建配置 internal/prebuiltconfigs/tools/postgres.yaml 已经内置了一个开箱即用的实例list_stored_procedure（关联到postgresql-source），并将其挂载进名为data的 toolset（postgres.yaml）。同样的工具实例也出现在 alloydb-postgres.yaml、cloud-sql-postgres.yaml 与 alloydb-omni.yaml 中，进一步印证了其跨数据源的通用性。

配置解析的验证

仓库的单元测试 internal/tools/postgres/postgresliststoredprocedure/postgresliststoredprocedure_test.go 验证了 YAML 配置能被正确解析为Config结构体，覆盖了"带authRequired"与"不带authRequired"两种形态，并断言type、source、name、description等字段的解析结果与期望一致。同时，集成测试辅助文件 tests/common.go 也注册了PostgresListStoredProcedureToolType = "postgres-list-stored-procedure"，说明该工具被纳入端到端测试体系。

示例请求

工具通过 MCP 的tools/call语义被调用，请求体即参数的 JSON 对象。以下是文档给出的各类典型请求：

列出全部存储过程（默认上限 20 条）：

{}

按属主过滤：

{ "role_name": "app_user" }

按 schema 过滤：

{ "schema_name": "public" }

同时按属主与 schema 过滤并调整上限：

{ "role_name": "postgres", "schema_name": "public", "limit": 50 }

按部分 schema 名匹配：

{ "schema_name": "audit" }

输出格式与示例响应

工具返回一个 JSON 数组，每个元素对应一个存储过程，字段定义如下：

一个典型的响应示例如下：

[ { "schema_name": "public", "name": "process_payment", "owner": "postgres", "language": "plpgsql", "definition": "CREATE OR REPLACE PROCEDURE public.process_payment(p_order_id integer, p_amount numeric)\n LANGUAGE plpgsql\nAS $procedure$\nBEGIN\n UPDATE orders SET status = 'paid', amount = p_amount WHERE id = p_order_id;\n INSERT INTO payment_log (order_id, amount, timestamp) VALUES (p_order_id, p_amount, now());\n COMMIT;\nEND\n$procedure$", "description": "Processes payment for an order and logs the transaction" }, { "schema_name": "public", "name": "cleanup_old_records", "owner": "postgres", "language": "plpgsql", "definition": "CREATE OR REPLACE PROCEDURE public.cleanup_old_records(p_days_old integer)\n LANGUAGE plpgsql\nAS $procedure$\nDECLARE\n v_deleted integer;\nBEGIN\n DELETE FROM audit_logs WHERE created_at < now() - (p_days_old || ' days')::interval;\n GET DIAGNOSTICS v_deleted = ROW_COUNT;\n RAISE NOTICE 'Deleted % records', v_deleted;\nEND\n$procedure$", "description": "Removes audit log records older than specified days" }, { "schema_name": "audit", "name": "audit_table_changes", "owner": "app_user", "language": "plpgsql", "definition": "CREATE OR REPLACE PROCEDURE audit.audit_table_changes()\n LANGUAGE plpgsql\nAS $procedure$\nBEGIN\n INSERT INTO audit.change_log (table_name, operation, changed_at) VALUES (TG_TABLE_NAME, TG_OP, now());\nEND\n$procedure$", "description": null } ]

值得注意的是，definition字段是pg_get_functiondef重建出的完整可执行语句，可以直接用于重建过程或纳入迁移脚本；而description来自COMMENT命令，因此既可能是有意义的文本，也可能如第三个示例那样为null。

高级用法与注意事项

性能考量

• 过滤在数据库层完成，使用的是LIKE包含式匹配（形如'%' || 值 || '%'），因此天然支持部分匹配，但也意味着无法利用常规 B-tree 索引做前缀匹配加速，在超大规模角色/schema 集合下建议配合limit使用；
• 过程的definition字段可能很长（包含完整函数体），当库中过程数量较多时，务必通过limit控制返回体量，避免响应过大；
• 结果按 schema 名与过程名排序，输出顺序稳定，便于与上一次结果做差异比对；
• 默认上限 20 条适合多数场景，确有需要时按实际规模调大。

使用注意

• 只返回存储过程：prokind = 'p'过滤确保普通函数（prokind = 'f'）等其他可调用对象不会混入结果，如需函数清单请使用其他工具；
• 过滤为部分匹配：role_name: "app"会同时匹配app_user、app_admin等所有包含app的名称，按需精确过滤时请给出完整名称；
• definition字段包含完整的、可直接运行的CREATE PROCEDURE语句；
• description字段由 PostgreSQL 的COMMENT命令写入，可能为null。

小结

postgres-list-stored-procedure以一条精心设计的系统目录 JOIN 查询为内核，通过 MCP Toolbox 统一的注册—配置—调用机制，将 PostgreSQL 存储过程的 schema、名称、属主、语言、完整定义与注释一次性暴露给 Agent。它天然兼容 PostgreSQL、AlloyDB for PostgreSQL 与 Cloud SQL for PostgreSQL 三类数据源，参数化查询、只读注解与排序/分页设计使其适合作为审计、文档化、迁移与安全评估流程中的稳定数据来源。结合 源码实现 与 预构建配置 可以进一步了解其细节，并将其快速接入你自己的工具箱配置。

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox