postgres-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

Postgres MCP Pro 是一个 PostgreSQL MCP (Model Context Protocol) 服务器，提供索引调优、执行计划分析、健康检查和安全 SQL 执行功能。

常用命令

开发设置

# 安装依赖
uv sync

# 运行服务器 (stdio 模式)
uv run postgres-mcp --access-mode=unrestricted

# 运行服务器 (SSE 模式)
uv run postgres-mcp --access-mode=unrestricted --transport=sse

# 运行服务器 (streamable-http 模式)
uv run postgres-mcp --access-mode=unrestricted --transport=streamable-http

测试

# 运行所有测试 (需要 Docker)
uv run pytest -v --log-cli-level=INFO

# 运行单个测试文件
uv run pytest tests/unit/sql/test_safe_sql.py -v

# 运行单个测试
uv run pytest tests/unit/sql/test_db_conn_pool.py::test_pool_connect_success -v

代码质量检查

# 格式化检查
uv run ruff format --check .

# 格式化修复
uv run ruff format .

# Lint 检查
uv run ruff check .

# Lint 修复
uv run ruff check . --fix

# 类型检查
uv run pyright

构建

uv build

核心架构

主入口

• src/postgres_mcp/__init__.py: main() 入口点
• src/postgres_mcp/server.py: FastMCP 服务器定义，包含所有 MCP 工具

MCP 工具 (server.py)

工具名	功能
list_schemas	列出数据库所有 schema
list_objects	列出 schema 内的对象 (表、视图、序列、扩展)
get_object_details	获取对象详细信息 (列、约束、索引)
execute_sql	执行 SQL (受访问模式限制)
explain_query	获取查询执行计划，支持假设索引模拟
get_top_queries	基于 pg_stat_statements 报告最慢查询
analyze_workload_indexes	分析工作负载并推荐索引
analyze_query_indexes	分析特定查询并推荐索引
analyze_db_health	全面健康检查

模块结构

• sql: 数据库连接池 (DbConnPool) 和 SQL 执行驱动 (SqlDriver, SafeSqlDriver)

  • safe_sql.py: 只读事务保护，使用 pglast 解析 SQL 防止绕过
  • bind_params.py: 参数绑定，从表统计信息采样生成参数值
  • extension_utils.py: 检查 pg_stat_statements 和 hypopg 扩展状态

• index: 索引调优 (基于 Microsoft DTA Anytime Algorithm)

  • dta_calc.py: DatabaseTuningAdvisor 核心算法
  • index_opt_base.py: 基础索引优化类
  • llm_opt.py: 实验性 LLM 索引优化

• database_health: 数据库健康检查 (源自 PgHero)

  • 索引健康、缓冲缓存命中率、连接健康、Vacuum 健康、复制健康、约束健康、序列健康