postgresql-mcp-pro 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. postgresql_mcp_pro-1.0.0/.env.example +2 -0
  2. postgresql_mcp_pro-1.0.0/.github/workflows/build.yml +54 -0
  3. postgresql_mcp_pro-1.0.0/.github/workflows/release.yml +117 -0
  4. postgresql_mcp_pro-1.0.0/.gitignore +186 -0
  5. postgresql_mcp_pro-1.0.0/.python-version +1 -0
  6. postgresql_mcp_pro-1.0.0/Dockerfile +63 -0
  7. postgresql_mcp_pro-1.0.0/LICENSE +21 -0
  8. postgresql_mcp_pro-1.0.0/PKG-INFO +235 -0
  9. postgresql_mcp_pro-1.0.0/README.en.md +124 -0
  10. postgresql_mcp_pro-1.0.0/README.md +215 -0
  11. postgresql_mcp_pro-1.0.0/README.zh-CN.md +5 -0
  12. postgresql_mcp_pro-1.0.0/assets/postgresql-mcp-pro.png +0 -0
  13. postgresql_mcp_pro-1.0.0/devenv.lock +155 -0
  14. postgresql_mcp_pro-1.0.0/devenv.nix +84 -0
  15. postgresql_mcp_pro-1.0.0/devenv.yaml +22 -0
  16. postgresql_mcp_pro-1.0.0/docker-entrypoint.sh +99 -0
  17. postgresql_mcp_pro-1.0.0/examples/movie-app.md +130 -0
  18. postgresql_mcp_pro-1.0.0/justfile +28 -0
  19. postgresql_mcp_pro-1.0.0/pyproject.toml +112 -0
  20. postgresql_mcp_pro-1.0.0/scripts/smoke_mcp_tools.py +217 -0
  21. postgresql_mcp_pro-1.0.0/smithery.yaml +22 -0
  22. postgresql_mcp_pro-1.0.0/src/postgres_mcp/__init__.py +24 -0
  23. postgresql_mcp_pro-1.0.0/src/postgres_mcp/artifacts.py +323 -0
  24. postgresql_mcp_pro-1.0.0/src/postgres_mcp/catalog_facts.py +134 -0
  25. postgresql_mcp_pro-1.0.0/src/postgres_mcp/database_health/__init__.py +4 -0
  26. postgresql_mcp_pro-1.0.0/src/postgres_mcp/database_health/buffer_health_calc.py +62 -0
  27. postgresql_mcp_pro-1.0.0/src/postgres_mcp/database_health/connection_health_calc.py +76 -0
  28. postgresql_mcp_pro-1.0.0/src/postgres_mcp/database_health/constraint_health_calc.py +101 -0
  29. postgresql_mcp_pro-1.0.0/src/postgres_mcp/database_health/database_health.py +98 -0
  30. postgresql_mcp_pro-1.0.0/src/postgres_mcp/database_health/index_health_calc.py +345 -0
  31. postgresql_mcp_pro-1.0.0/src/postgres_mcp/database_health/replication_calc.py +165 -0
  32. postgresql_mcp_pro-1.0.0/src/postgres_mcp/database_health/sequence_health_calc.py +164 -0
  33. postgresql_mcp_pro-1.0.0/src/postgres_mcp/database_health/vacuum_health_calc.py +102 -0
  34. postgresql_mcp_pro-1.0.0/src/postgres_mcp/explain/README.md +26 -0
  35. postgresql_mcp_pro-1.0.0/src/postgres_mcp/explain/__init__.py +7 -0
  36. postgresql_mcp_pro-1.0.0/src/postgres_mcp/explain/explain_plan.py +241 -0
  37. postgresql_mcp_pro-1.0.0/src/postgres_mcp/index/dta_calc.py +834 -0
  38. postgresql_mcp_pro-1.0.0/src/postgres_mcp/index/index_opt_base.py +671 -0
  39. postgresql_mcp_pro-1.0.0/src/postgres_mcp/index/llm_opt.py +384 -0
  40. postgresql_mcp_pro-1.0.0/src/postgres_mcp/index/presentation.py +266 -0
  41. postgresql_mcp_pro-1.0.0/src/postgres_mcp/ops_insights.py +621 -0
  42. postgresql_mcp_pro-1.0.0/src/postgres_mcp/server.py +1026 -0
  43. postgresql_mcp_pro-1.0.0/src/postgres_mcp/sql/__init__.py +31 -0
  44. postgresql_mcp_pro-1.0.0/src/postgres_mcp/sql/bind_params.py +816 -0
  45. postgresql_mcp_pro-1.0.0/src/postgres_mcp/sql/extension_utils.py +246 -0
  46. postgresql_mcp_pro-1.0.0/src/postgres_mcp/sql/index.py +52 -0
  47. postgresql_mcp_pro-1.0.0/src/postgres_mcp/sql/safe_sql.py +1059 -0
  48. postgresql_mcp_pro-1.0.0/src/postgres_mcp/sql/sql_driver.py +311 -0
  49. postgresql_mcp_pro-1.0.0/src/postgres_mcp/top_queries/__init__.py +4 -0
  50. postgresql_mcp_pro-1.0.0/src/postgres_mcp/top_queries/top_queries_calc.py +249 -0
  51. postgresql_mcp_pro-1.0.0/tests/Dockerfile.postgres-hypopg +21 -0
  52. postgresql_mcp_pro-1.0.0/tests/README.md +30 -0
  53. postgresql_mcp_pro-1.0.0/tests/conftest.py +29 -0
  54. postgresql_mcp_pro-1.0.0/tests/integration/dta/test_dta_calc_integration.py +1417 -0
  55. postgresql_mcp_pro-1.0.0/tests/integration/test_top_queries_integration.py +181 -0
  56. postgresql_mcp_pro-1.0.0/tests/unit/database_health/test_database_health_tool.py +182 -0
  57. postgresql_mcp_pro-1.0.0/tests/unit/database_health/test_sequence_health_calc.py +75 -0
  58. postgresql_mcp_pro-1.0.0/tests/unit/explain/test_explain_plan.py +477 -0
  59. postgresql_mcp_pro-1.0.0/tests/unit/explain/test_explain_plan_real_db.py +265 -0
  60. postgresql_mcp_pro-1.0.0/tests/unit/explain/test_server.py +131 -0
  61. postgresql_mcp_pro-1.0.0/tests/unit/explain/test_server_integration.py +135 -0
  62. postgresql_mcp_pro-1.0.0/tests/unit/index/test_dta_calc.py +1294 -0
  63. postgresql_mcp_pro-1.0.0/tests/unit/sql/test_db_conn_pool.py +214 -0
  64. postgresql_mcp_pro-1.0.0/tests/unit/sql/test_obfuscate_password.py +104 -0
  65. postgresql_mcp_pro-1.0.0/tests/unit/sql/test_pool_reset.py +288 -0
  66. postgresql_mcp_pro-1.0.0/tests/unit/sql/test_readonly_enforcement.py +87 -0
  67. postgresql_mcp_pro-1.0.0/tests/unit/sql/test_safe_sql.py +788 -0
  68. postgresql_mcp_pro-1.0.0/tests/unit/sql/test_sql_driver.py +367 -0
  69. postgresql_mcp_pro-1.0.0/tests/unit/test_access_mode.py +153 -0
  70. postgresql_mcp_pro-1.0.0/tests/unit/test_execute_sql_guards.py +49 -0
  71. postgresql_mcp_pro-1.0.0/tests/unit/test_lifecycle.py +105 -0
  72. postgresql_mcp_pro-1.0.0/tests/unit/test_ops_insights.py +129 -0
  73. postgresql_mcp_pro-1.0.0/tests/unit/test_transport.py +276 -0
  74. postgresql_mcp_pro-1.0.0/tests/unit/top_queries/test_top_queries_calc.py +254 -0
  75. postgresql_mcp_pro-1.0.0/tests/utils.py +155 -0
  76. postgresql_mcp_pro-1.0.0/uv.lock +1683 -0
@@ -0,0 +1,2 @@
1
+ # Copy to .env for local / integration testing (never commit real credentials).
2
+ DATABASE_URI=postgresql://user:password@localhost:5432/dbname
@@ -0,0 +1,54 @@
1
+ name: PostgreSQL MCP Pro CI
2
+
3
+ on:
4
+ push:
5
+ branches:
6
+ - main
7
+ paths-ignore:
8
+ - "**/README.md"
9
+ - "**/README.en.md"
10
+ - "**/README.zh-CN.md"
11
+ pull_request:
12
+ types: [opened, synchronize, reopened]
13
+ paths-ignore:
14
+ - "**/README.md"
15
+ - "**/README.en.md"
16
+ - "**/README.zh-CN.md"
17
+
18
+ jobs:
19
+ postgresql-mcp-pro-ci:
20
+ runs-on: ubuntu-latest
21
+
22
+ steps:
23
+ - name: Checkout code
24
+ uses: actions/checkout@v4
25
+
26
+ - name: Set up Python
27
+ uses: actions/setup-python@v5
28
+ with:
29
+ python-version: "3.12"
30
+
31
+ - name: Start Docker service
32
+ run: sudo service docker start || true
33
+
34
+ - name: Verify Docker is running
35
+ run: docker info
36
+
37
+ - name: Install uv
38
+ uses: astral-sh/setup-uv@v5
39
+ with:
40
+ version: "0.6.9"
41
+
42
+ - name: Build
43
+ run: uv sync
44
+
45
+ - name: Run Lint
46
+ run: |
47
+ uv run ruff format --check .
48
+ uv run ruff check .
49
+
50
+ - name: Run Check
51
+ run: uv run pyright
52
+
53
+ - name: Run Tests
54
+ run: uv run pytest -v --log-cli-level=INFO
@@ -0,0 +1,117 @@
1
+ name: Release
2
+
3
+ on:
4
+ push:
5
+ tags:
6
+ - "v*"
7
+ workflow_dispatch:
8
+ inputs:
9
+ version:
10
+ description: "Version to release without v prefix (e.g. 1.0.0)"
11
+ required: true
12
+
13
+ permissions:
14
+ contents: write
15
+ packages: write
16
+ id-token: write
17
+
18
+ jobs:
19
+ prepare:
20
+ runs-on: ubuntu-latest
21
+ outputs:
22
+ version: ${{ steps.set-version.outputs.VERSION }}
23
+ steps:
24
+ - name: Set version
25
+ id: set-version
26
+ run: |
27
+ if [[ "${{ github.event_name }}" == "push" && "${{ github.ref_type }}" == "tag" ]]; then
28
+ VERSION="${GITHUB_REF#refs/tags/v}"
29
+ else
30
+ VERSION="${{ github.event.inputs.version }}"
31
+ fi
32
+ if [[ -z "$VERSION" ]]; then
33
+ echo "VERSION is empty" >&2
34
+ exit 1
35
+ fi
36
+ echo "VERSION=$VERSION" >> "$GITHUB_OUTPUT"
37
+
38
+ python-artifacts:
39
+ needs: prepare
40
+ runs-on: ubuntu-latest
41
+ steps:
42
+ - uses: actions/checkout@v4
43
+
44
+ - name: Install uv
45
+ uses: astral-sh/setup-uv@v5
46
+ with:
47
+ version: "0.6.9"
48
+
49
+ - name: Set up Python
50
+ uses: actions/setup-python@v5
51
+ with:
52
+ python-version: "3.12"
53
+
54
+ - name: Sync and build
55
+ run: |
56
+ uv sync --frozen --no-dev
57
+ uv build
58
+
59
+ - name: Upload GitHub Release assets
60
+ uses: softprops/action-gh-release@v2
61
+ with:
62
+ tag_name: v${{ needs.prepare.outputs.version }}
63
+ name: postgresql-mcp-pro v${{ needs.prepare.outputs.version }}
64
+ generate_release_notes: true
65
+ files: |
66
+ dist/*.whl
67
+ dist/*.tar.gz
68
+ fail_on_unmatched_files: true
69
+ env:
70
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
71
+
72
+ - name: Publish to PyPI
73
+ uses: pypa/gh-action-pypi-publish@release/v1
74
+ with:
75
+ packages-dir: dist/
76
+
77
+ docker-image:
78
+ needs: prepare
79
+ runs-on: ubuntu-latest
80
+ steps:
81
+ - uses: actions/checkout@v4
82
+
83
+ - name: Set up QEMU
84
+ uses: docker/setup-qemu-action@v3
85
+ with:
86
+ platforms: arm64,amd64
87
+
88
+ - name: Set up Docker Buildx
89
+ uses: docker/setup-buildx-action@v3
90
+
91
+ - name: Log in to GHCR
92
+ uses: docker/login-action@v3
93
+ with:
94
+ registry: ghcr.io
95
+ username: ${{ github.actor }}
96
+ password: ${{ secrets.GITHUB_TOKEN }}
97
+
98
+ - name: Docker metadata
99
+ id: meta
100
+ uses: docker/metadata-action@v5
101
+ with:
102
+ images: ghcr.io/${{ github.repository_owner }}/postgresql-mcp-pro
103
+ tags: |
104
+ type=raw,value=${{ needs.prepare.outputs.version }}
105
+ type=raw,value=latest
106
+
107
+ - name: Build and push
108
+ uses: docker/build-push-action@v5
109
+ with:
110
+ context: .
111
+ file: Dockerfile
112
+ platforms: linux/amd64,linux/arm64
113
+ push: true
114
+ tags: ${{ steps.meta.outputs.tags }}
115
+ labels: ${{ steps.meta.outputs.labels }}
116
+ cache-from: type=gha
117
+ cache-to: type=gha,mode=max
@@ -0,0 +1,186 @@
1
+ # Byte-compiled / optimized / DLL files
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+
6
+ # C extensions
7
+ *.so
8
+
9
+ # Distribution / packaging
10
+ .Python
11
+ build/
12
+ develop-eggs/
13
+ dist/
14
+ downloads/
15
+ eggs/
16
+ .eggs/
17
+ lib/
18
+ lib64/
19
+ parts/
20
+ sdist/
21
+ var/
22
+ wheels/
23
+ share/python-wheels/
24
+ *.egg-info/
25
+ .installed.cfg
26
+ *.egg
27
+ MANIFEST
28
+
29
+ # PyInstaller
30
+ # Usually these files are written by a python script from a template
31
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
32
+ *.manifest
33
+ *.spec
34
+
35
+ # Installer logs
36
+ pip-log.txt
37
+ pip-delete-this-directory.txt
38
+
39
+ # Unit test / coverage reports
40
+ htmlcov/
41
+ .tox/
42
+ .nox/
43
+ .coverage
44
+ .coverage.*
45
+ .cache
46
+ nosetests.xml
47
+ coverage.xml
48
+ *.cover
49
+ *.py,cover
50
+ .hypothesis/
51
+ .pytest_cache/
52
+ cover/
53
+
54
+ # Translations
55
+ *.mo
56
+ *.pot
57
+
58
+ # Django stuff:
59
+ *.log
60
+ local_settings.py
61
+ db.sqlite3
62
+ db.sqlite3-journal
63
+
64
+ # Flask stuff:
65
+ instance/
66
+ .webassets-cache
67
+
68
+ # Scrapy stuff:
69
+ .scrapy
70
+
71
+ # Sphinx documentation
72
+ docs/_build/
73
+
74
+ # PyBuilder
75
+ .pybuilder/
76
+ target/
77
+
78
+ # Jupyter Notebook
79
+ .ipynb_checkpoints
80
+
81
+ # IPython
82
+ profile_default/
83
+ ipython_config.py
84
+
85
+ # pyenv
86
+ # For a library or package, you might want to ignore these files since the code is
87
+ # intended to run in multiple environments; otherwise, check them in:
88
+ # .python-version
89
+
90
+ # pipenv
91
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
92
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
93
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
94
+ # install all needed dependencies.
95
+ #Pipfile.lock
96
+
97
+ # UV
98
+ # Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
99
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
100
+ # commonly ignored for libraries.
101
+ #uv.lock
102
+
103
+ # poetry
104
+ # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
105
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
106
+ # commonly ignored for libraries.
107
+ # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
108
+ #poetry.lock
109
+
110
+ # pdm
111
+ # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
112
+ #pdm.lock
113
+ # pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
114
+ # in version control.
115
+ # https://pdm.fming.dev/latest/usage/project/#working-with-version-control
116
+ .pdm.toml
117
+ .pdm-python
118
+ .pdm-build/
119
+
120
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
121
+ __pypackages__/
122
+
123
+ # Celery stuff
124
+ celerybeat-schedule
125
+ celerybeat.pid
126
+
127
+ # SageMath parsed files
128
+ *.sage.py
129
+
130
+ # Environments
131
+ .env
132
+ .venv
133
+ env/
134
+ venv/
135
+ ENV/
136
+ env.bak/
137
+ venv.bak/
138
+
139
+ # Spyder project settings
140
+ .spyderproject
141
+ .spyproject
142
+
143
+ # Rope project settings
144
+ .ropeproject
145
+
146
+ # mkdocs documentation
147
+ /site
148
+
149
+ # mypy
150
+ .mypy_cache/
151
+ .dmypy.json
152
+ dmypy.json
153
+
154
+ # Pyre type checker
155
+ .pyre/
156
+
157
+ # pytype static type analyzer
158
+ .pytype/
159
+
160
+ # Cython debug symbols
161
+ cython_debug/
162
+
163
+ # PyCharm
164
+ # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
165
+ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
166
+ # and can be added to the global gitignore or merged into this file. For a more nuclear
167
+ # option (not recommended) you can uncomment the following to ignore the entire idea folder.
168
+ #.idea/
169
+
170
+ # Ruff stuff:
171
+ .ruff_cache/
172
+
173
+ # PyPI configuration file
174
+ .pypirc
175
+
176
+ # Devenv
177
+ .devenv*
178
+ devenv.local.nix
179
+
180
+ # direnv
181
+ .direnv
182
+
183
+ # pre-commit
184
+ .pre-commit-config.yaml
185
+ *.sql
186
+ .DS_Store
@@ -0,0 +1 @@
1
+ 3.12
@@ -0,0 +1,63 @@
1
+ # First, build the application in the `/app` directory.
2
+ # See `Dockerfile` for details.
3
+ FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim AS builder
4
+ ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy
5
+
6
+ # Disable Python downloads, because we want to use the system interpreter
7
+ # across both images. If using a managed Python version, it needs to be
8
+ # copied from the build image into the final image; see `standalone.Dockerfile`
9
+ # for an example.
10
+ ENV UV_PYTHON_DOWNLOADS=0
11
+
12
+ WORKDIR /app
13
+ RUN apt-get update \
14
+ && apt-get install -y libpq-dev gcc \
15
+ && rm -rf /var/lib/apt/lists/*
16
+ RUN --mount=type=cache,target=/root/.cache/uv \
17
+ --mount=type=bind,source=uv.lock,target=uv.lock \
18
+ --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
19
+ uv sync --frozen --no-install-project --no-dev
20
+ ADD . /app
21
+ RUN --mount=type=cache,target=/root/.cache/uv \
22
+ uv sync --frozen --no-dev
23
+
24
+
25
+ FROM python:3.12-slim-bookworm
26
+ # It is important to use the image that matches the builder, as the path to the
27
+ # Python executable must be the same, e.g., using `python:3.11-slim-bookworm`
28
+ # will fail.
29
+
30
+ RUN groupadd -r app && useradd -r -g app app
31
+
32
+ COPY --from=builder --chown=app:app /app /app
33
+
34
+ ENV PATH="/app/.venv/bin:$PATH"
35
+
36
+ ARG TARGETPLATFORM
37
+ ARG BUILDPLATFORM
38
+ LABEL org.opencontainers.image.description="PostgreSQL MCP Pro - Multi-architecture container (${TARGETPLATFORM})"
39
+ LABEL org.opencontainers.image.source="https://github.com/Poiig/postgresql-mcp-pro"
40
+ LABEL org.opencontainers.image.licenses="MIT"
41
+ LABEL org.opencontainers.image.vendor="Poiig"
42
+ LABEL org.opencontainers.image.title="postgresql-mcp-pro"
43
+ LABEL org.opencontainers.image.url="https://github.com/Poiig/postgresql-mcp-pro"
44
+
45
+ # Install runtime system dependencies
46
+ RUN apt-get update && apt-get install -y \
47
+ libpq-dev \
48
+ iputils-ping \
49
+ dnsutils \
50
+ net-tools \
51
+ && rm -rf /var/lib/apt/lists/*
52
+
53
+ COPY docker-entrypoint.sh /app/
54
+ RUN chmod +x /app/docker-entrypoint.sh
55
+
56
+ USER app
57
+
58
+ # Expose HTTP transport port (streamable-http / sse)
59
+ EXPOSE 8000
60
+
61
+ # docker run -it --rm -e DATABASE_URI=... ghcr.io/poiig/postgresql-mcp-pro
62
+ ENTRYPOINT ["/app/docker-entrypoint.sh", "postgresql-mcp-pro"]
63
+ CMD []
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025, Crystal Corp.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,235 @@
1
+ Metadata-Version: 2.5
2
+ Name: postgresql-mcp-pro
3
+ Version: 1.0.0
4
+ Summary: PostgreSQL MCP Pro: index tuning, explain plans, health checks, and safe SQL
5
+ Project-URL: Homepage, https://github.com/Poiig/postgresql-mcp-pro
6
+ Project-URL: Repository, https://github.com/Poiig/postgresql-mcp-pro
7
+ Project-URL: Issues, https://github.com/Poiig/postgresql-mcp-pro/issues
8
+ Author-email: poiig <poiigzhao@126.com>
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Requires-Python: >=3.12
12
+ Requires-Dist: attrs>=25.4.0
13
+ Requires-Dist: humanize>=4.15.0
14
+ Requires-Dist: instructor>=1.14.4
15
+ Requires-Dist: mcp[cli]<2.0,>=1.25.0
16
+ Requires-Dist: pglast<8,>=7.20
17
+ Requires-Dist: psycopg-pool>=3.3.0
18
+ Requires-Dist: psycopg[binary]>=3.3.2
19
+ Description-Content-Type: text/markdown
20
+
21
+ <div align="center">
22
+
23
+ <img src="assets/postgresql-mcp-pro.png" alt="PostgreSQL MCP Pro Logo" width="600"/>
24
+
25
+ [中文](README.md) · [English](README.en.md)
26
+
27
+ <h3>PostgreSQL MCP Pro</h3>
28
+ <p>索引调优 · 执行计划 · 健康检查 · 安全 SQL · 运维洞察</p>
29
+
30
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
31
+ [![PyPI](https://img.shields.io/pypi/v/postgresql-mcp-pro)](https://pypi.org/project/postgresql-mcp-pro/)
32
+ [![GitHub Release](https://img.shields.io/github/v/release/Poiig/postgresql-mcp-pro)](https://github.com/Poiig/postgresql-mcp-pro/releases)
33
+ [![GHCR](https://img.shields.io/badge/GHCR-postgresql--mcp--pro-blue)](https://github.com/Poiig/postgresql-mcp-pro/pkgs/container/postgresql-mcp-pro)
34
+
35
+ </div>
36
+
37
+ ## 这是什么
38
+
39
+ **PostgreSQL MCP Pro**(CLI / PyPI:`postgresql-mcp-pro`)是面向 Cursor / Claude 等 MCP 客户端的 PostgreSQL 助手:能查 schema、跑只读 SQL、看执行计划、做健康检查、给索引建议,并补充表体积、冷索引、活动会话、阻塞等运维能力。
40
+
41
+ 本仓库是 [crystaldba/postgres-mcp](https://github.com/crystaldba/postgres-mcp) 的维护型 fork:默认只读、修好上游依赖坑,并持续合入有价值的修复。
42
+
43
+ | 能力 | 说明 |
44
+ |------|------|
45
+ | 安全默认 | 默认 `--access-mode=restricted`(只读 + SQL 校验);写库需显式 `unrestricted` |
46
+ | 依赖可用 | `pglast>=7.20,<8`,避免上游 PyPI 旧版装不上 |
47
+ | 连接更稳 | 归还连接清理 session / HypoPG;stdio 孤儿进程会关池 |
48
+ | 运维工具 | 库总览、体积排行、重复/冷索引、autovacuum、活动会话、阻塞等 |
49
+
50
+ 制品:
51
+
52
+ - **PyPI**:`pip` / `uvx postgresql-mcp-pro`(推荐本机)
53
+ - **GitHub Release**:wheel / sdist
54
+ - **GHCR**:`ghcr.io/poiig/postgresql-mcp-pro`
55
+
56
+ ---
57
+
58
+ ## 怎么选接入方式
59
+
60
+ | 方式 | 适用 | 命令形态 |
61
+ |------|------|----------|
62
+ | **A. uvx / 本地进程(stdio)** | 本机 Cursor,一人一库,最简单 | `uvx postgresql-mcp-pro` |
63
+ | **B. Docker(stdio)** | 不想装 Python,本机有 Docker | `docker run -i ...` |
64
+ | **C. HTTP(streamable-http)** | 远程 / 多人共用一个服务 | 常驻进程,客户端连 URL |
65
+ | SSE | 旧客户端兼容 | 仍可用,优先用 C |
66
+
67
+ 本机日常开发推荐 **A**;集中部署推荐 **C**(并加 `--stateless-http`)。
68
+
69
+ ---
70
+
71
+ ## A. 用 uvx(推荐本机)
72
+
73
+ 先安装 [uv](https://docs.astral.sh/uv/getting-started/installation/),再在 Cursor `mcp.json`:
74
+
75
+ ```json
76
+ {
77
+ "mcpServers": {
78
+ "postgres": {
79
+ "command": "uvx",
80
+ "args": [
81
+ "postgresql-mcp-pro",
82
+ "--access-mode=restricted"
83
+ ],
84
+ "env": {
85
+ "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
86
+ }
87
+ }
88
+ }
89
+ }
90
+ ```
91
+
92
+ 需要写库时把 `--access-mode=restricted` 改成 `--access-mode=unrestricted`。
93
+
94
+ 已克隆本仓库时:
95
+
96
+ ```bash
97
+ uv sync
98
+ uv run postgresql-mcp-pro --access-mode=restricted
99
+ ```
100
+
101
+ ---
102
+
103
+ ## B. 用 Docker(stdio)
104
+
105
+ ```bash
106
+ docker pull ghcr.io/poiig/postgresql-mcp-pro:latest
107
+ ```
108
+
109
+ Cursor 配置:
110
+
111
+ ```json
112
+ {
113
+ "mcpServers": {
114
+ "postgres": {
115
+ "command": "docker",
116
+ "args": [
117
+ "run", "-i", "--rm",
118
+ "-e", "DATABASE_URI",
119
+ "ghcr.io/poiig/postgresql-mcp-pro:latest",
120
+ "--access-mode=restricted"
121
+ ],
122
+ "env": {
123
+ "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
124
+ }
125
+ }
126
+ }
127
+ }
128
+ ```
129
+
130
+ 容器内会把连接串里的 `localhost` 映射到宿主机(macOS/Windows:`host.docker.internal`)。
131
+
132
+ 也可用密钥文件:
133
+
134
+ ```bash
135
+ docker run -i --rm \
136
+ -v /path/to/database-uri:/run/secrets/database-uri:ro \
137
+ -e DATABASE_URI_FILE=/run/secrets/database-uri \
138
+ ghcr.io/poiig/postgresql-mcp-pro:latest --access-mode=restricted
139
+ ```
140
+
141
+ ---
142
+
143
+ ## C. HTTP:streamable-http(推荐远程)
144
+
145
+ 先在服务器启动(默认监听本机;对局域网开放时请自行加反代 / 鉴权 / TLS,不要裸奔公网):
146
+
147
+ ```bash
148
+ docker run --rm -p 8000:8000 \
149
+ -e DATABASE_URI=postgresql://username:password@host:5432/dbname \
150
+ ghcr.io/poiig/postgresql-mcp-pro:latest \
151
+ --access-mode=restricted \
152
+ --transport=streamable-http \
153
+ --stateless-http \
154
+ --streamable-http-host=0.0.0.0 \
155
+ --streamable-http-port=8000
156
+ ```
157
+
158
+ 本机开发也可用:
159
+
160
+ ```bash
161
+ uv run postgresql-mcp-pro \
162
+ --access-mode=restricted \
163
+ --transport=streamable-http \
164
+ --stateless-http \
165
+ --streamable-http-host=127.0.0.1 \
166
+ --streamable-http-port=8000
167
+ ```
168
+
169
+ 客户端连 `http://<host>:8000/mcp`(以实际 MCP 客户端要求为准)。
170
+
171
+ ### SSE(兼容)
172
+
173
+ ```bash
174
+ uv run postgresql-mcp-pro --transport=sse --sse-host=0.0.0.0 --sse-port=8000
175
+ ```
176
+
177
+ 新部署优先 **streamable-http + `--stateless-http`**。
178
+
179
+ ---
180
+
181
+ ## 常用参数
182
+
183
+ ```bash
184
+ uv run postgresql-mcp-pro --access-mode=unrestricted
185
+ uv run postgresql-mcp-pro --access-mode=restricted --max-rows=500
186
+ ```
187
+
188
+ ---
189
+
190
+ ## 工具一览(节选)
191
+
192
+ | 工具 | 说明 |
193
+ |------|------|
194
+ | `list_schemas` / `list_objects` / `get_object_details` | 浏览 schema |
195
+ | `execute_sql` | 执行 SQL(restricted 下只读校验) |
196
+ | `explain_query` | 执行计划 |
197
+ | `analyze_db_health` / `analyze_query_indexes` / `analyze_workload_indexes` | 健康与索引 |
198
+ | `get_top_queries` | 慢查询(需 `pg_stat_statements`) |
199
+ | `get_database_overview` / `list_table_sizes` | 库总览 / 体积 |
200
+ | `list_duplicate_indexes` / `list_index_usage` | 重复 / 冷索引 |
201
+ | `get_autovacuum_overview` / `get_table_bloat` | 清理与膨胀 |
202
+ | `list_qual_stats` | 谓词统计(需 `pg_qualstats`) |
203
+ | `list_settings` | 关键参数白名单 |
204
+ | `list_active_queries` / `get_blocking_queries` | 活动会话 / 阻塞 |
205
+
206
+ 建议扩展:`pg_stat_statements`、`hypopg`(索引推演)。
207
+
208
+ ---
209
+
210
+ ## 发布与版本
211
+
212
+ 打 tag 触发 [Release workflow](.github/workflows/release.yml):
213
+
214
+ ```bash
215
+ git tag v1.0.0
216
+ git push origin v1.0.0
217
+ ```
218
+
219
+ 产出:
220
+
221
+ - PyPI:`postgresql-mcp-pro`
222
+ - GitHub Release:`postgresql_mcp_pro-*.whl` / `.tar.gz`
223
+ - 镜像:`ghcr.io/poiig/postgresql-mcp-pro:1.0.0` 与 `:latest`
224
+
225
+ 也可在 Actions 里用 `workflow_dispatch` 填版本号手动发版。
226
+
227
+ ---
228
+
229
+ ## 许可与上游
230
+
231
+ - 许可证:[MIT](LICENSE)
232
+ - 上游:[crystaldba/postgres-mcp](https://github.com/crystaldba/postgres-mcp)
233
+ - 本仓库:[Poiig/postgresql-mcp-pro](https://github.com/Poiig/postgresql-mcp-pro)
234
+
235
+ 更细的英文说明见 [README.en.md](README.en.md)。