Merge pull request #4 from surajmandalcell/claude/publish-python-package-RTzUj

Claude/publish python package r tz uj

Author: surajmandalcell

.github/workflows/build.yml

@@ -1,4 +1,4 @@
-name: Postgres MCP CI
+name: pgsql-mcp CI
 
 on:
   push:
@@ -12,7 +12,7 @@ on:
       - "**/README.md"
 
 jobs:
-  postgres-mcp-ci:
+  pgsql-mcp-ci:
     runs-on: ubuntu-latest
 
     steps:

.github/workflows/docker-build-dockerhub.yml

@@ -60,7 +60,7 @@ jobs:
         id: docker_meta
         uses: docker/metadata-action@v5
         with:
-          images: crystaldba/postgres-mcp
+          images: ${{ secrets.DOCKERHUB_USERNAME }}/pgsql-mcp
           tags: |
             type=raw,value=${{ needs.prepare.outputs.version }}
             type=raw,value=latest
@@ -84,5 +84,5 @@ jobs:
           platforms: linux/amd64,linux/arm64
           push: true
           tags: ${{ steps.docker_meta.outputs.tags }}
-          cache-from: type=registry,ref=crystaldba/postgres-mcp:buildcache
-          cache-to: type=registry,ref=crystaldba/postgres-mcp:buildcache,mode=max
+          cache-from: type=registry,ref=${{ secrets.DOCKERHUB_USERNAME }}/pgsql-mcp:buildcache
+          cache-to: type=registry,ref=${{ secrets.DOCKERHUB_USERNAME }}/pgsql-mcp:buildcache,mode=max

.github/workflows/pypi-publish.yml

@@ -0,0 +1,52 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to publish (must match pyproject.toml)"
+        required: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.6.9"
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

CLAUDE.md

@@ -0,0 +1,87 @@
+# CLAUDE.md - Project Guidelines
+
+## Project Overview
+
+**pgsql-mcp** is a PostgreSQL MCP (Model Context Protocol) server providing index tuning, query analysis, explain plans, and database health monitoring.
+
+## Build & Test Commands
+
+```bash
+# Install dependencies
+uv sync
+
+# Run tests
+uv run pytest -v
+
+# Run linting
+uv run ruff format --check .
+uv run ruff check .
+
+# Run type checking
+uv run pyright
+
+# Run the server locally
+uv run pgsql-mcp --help
+```
+
+## Code Style
+
+- Python 3.12+
+- Line length: 150 characters
+- Formatter: ruff/black
+- Type hints required
+- Google-style docstrings
+
+## Architecture
+
+```
+src/postgres_mcp/
+├── __init__.py          # Entry point (main function)
+├── sql/                 # SQL execution & safety
+├── index/               # Index optimization (DTA algorithm)
+├── explain/             # Query plan analysis
+├── database_health/     # Health check modules
+├── migrations/          # Schema migration support
+└── top_queries/         # pg_stat_statements analysis
+```
+
+## Development Rules
+
+### SSOT (Single Source of Truth) - 100% Compliance
+
+1. **Configuration**: All config lives in `pyproject.toml` - no duplicate config files
+2. **Constants**: Define once, import everywhere - no magic strings/numbers scattered in code
+3. **Types**: Single type definition per concept - reuse via imports
+4. **Database schemas**: Schema definitions in one place, reference elsewhere
+5. **Error messages**: Centralized error definitions when used in multiple places
+6. **Version**: Single version in `pyproject.toml` only
+
+### DRY (Don't Repeat Yourself) - 100% Compliance
+
+1. **No copy-paste code**: Extract to functions/classes when logic repeats
+2. **Shared utilities**: Common operations go in dedicated utility modules
+3. **SQL patterns**: Reusable SQL builders instead of string concatenation
+4. **Test fixtures**: Shared fixtures in `conftest.py`, not duplicated per test
+5. **Configuration**: Environment handling in one module, imported by others
+
+### File Hygiene - Always Remove Unnecessary Files
+
+1. **Delete, don't comment**: Remove dead code entirely, don't comment it out
+2. **No orphan files**: Delete files that are no longer imported/used
+3. **No placeholder files**: Remove empty `__init__.py` if not needed for packaging
+4. **Clean imports**: Remove unused imports immediately
+5. **No backup files**: No `.bak`, `.old`, `.backup` files in repo
+6. **No generated files in git**: Add build artifacts to `.gitignore`
+7. **Remove deprecated code**: When replacing functionality, delete the old implementation
+
+### Before Every Commit
+
+- [ ] No duplicate logic exists
+- [ ] No unused imports
+- [ ] No commented-out code
+- [ ] No orphan files
+- [ ] All constants centralized
+- [ ] Types reused via imports
+- [ ] Tests pass: `uv run pytest`
+- [ ] Lint passes: `uv run ruff check .`
+- [ ] Types pass: `uv run pyright`

Dockerfile

@@ -37,11 +37,10 @@ ENV PATH="/app/.venv/bin:$PATH"
 
 ARG TARGETPLATFORM
 ARG BUILDPLATFORM
-LABEL org.opencontainers.image.description="Postgres MCP Agent - Multi-architecture container (${TARGETPLATFORM})"
-LABEL org.opencontainers.image.source="https://github.com/crystaldba/postgres-mcp"
-LABEL org.opencontainers.image.licenses="Apache-2.0"
-LABEL org.opencontainers.image.vendor="Crystal DBA"
-LABEL org.opencontainers.image.url="https://www.crystaldba.ai"
+LABEL org.opencontainers.image.description="pgsql-mcp - PostgreSQL MCP Server (${TARGETPLATFORM})"
+LABEL org.opencontainers.image.source="https://github.com/surajmandalcell/postgres-mcp"
+LABEL org.opencontainers.image.licenses="MIT"
+LABEL org.opencontainers.image.vendor="surajmandalcell"
 
 # Install runtime system dependencies
 RUN apt-get update && apt-get install -y \
@@ -57,9 +56,9 @@ RUN chmod +x /app/docker-entrypoint.sh
 # Expose the SSE port
 EXPOSE 8000
 
-# Run the postgres-mcp server
+# Run the pgsql-mcp server
 # Users can pass a database URI or individual connection arguments:
-#   docker run -it --rm postgres-mcp postgres://user:pass@host:port/dbname
-#   docker run -it --rm postgres-mcp -h myhost -p 5432 -U myuser -d mydb
-ENTRYPOINT ["/app/docker-entrypoint.sh", "postgres-mcp"]
+#   docker run -it --rm pgsql-mcp postgres://user:pass@host:port/dbname
+#   docker run -it --rm pgsql-mcp -h myhost -p 5432 -U myuser -d mydb
+ENTRYPOINT ["/app/docker-entrypoint.sh", "pgsql-mcp"]
 CMD []

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025, Crystal Corp.
+Copyright (c) 2025, Suraj Mandal
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

PUBLISHING.md

@@ -0,0 +1,57 @@
+# Publishing to PyPI
+
+This project uses GitHub Actions with PyPI Trusted Publishing (OIDC) for secure, token-free releases.
+
+## One-Time Setup on PyPI
+
+1. Go to https://pypi.org/manage/account/publishing/
+2. Add a new pending publisher with these values:
+
+| Field | Value |
+|-------|-------|
+| **PyPI Project Name** | `pgsql-mcp` |
+| **Owner** | `surajmandalcell` |
+| **Repository name** | `pgsql-mcp` |
+| **Workflow name** | `pypi-publish.yml` |
+| **Environment name** | `pypi` |
+
+3. In your GitHub repository, create the environment:
+   - Go to Settings → Environments → New environment
+   - Name: `pypi`
+   - Optionally add protection rules (required reviewers, etc.)
+
+## Publishing a Release
+
+### Option 1: GitHub Release (Recommended)
+
+```bash
+# 1. Update version in pyproject.toml
+# 2. Commit and push
+git add pyproject.toml
+git commit -m "Bump version to X.Y.Z"
+git push
+
+# 3. Create and push a tag
+git tag -a vX.Y.Z -m "Release vX.Y.Z"
+git push --tags
+
+# 4. Create GitHub release (triggers the workflow)
+gh release create vX.Y.Z --title "pgsql-mcp vX.Y.Z" --notes "Release notes here"
+```
+
+### Option 2: Manual Workflow Dispatch
+
+1. Go to Actions → "Publish to PyPI" → Run workflow
+2. Click "Run workflow"
+
+### Option 3: Local Build and Upload (Manual)
+
+```bash
+# Build
+uv build
+
+# Upload (requires PyPI API token)
+uv publish
+# or
+twine upload dist/*
+```

README.md

@@ -1,7 +1,7 @@
-# Postgres MCP
+# pgsql-mcp
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![PyPI - Version](https://img.shields.io/pypi/v/postgres-mcp)](https://pypi.org/project/postgres-mcp/)
+[![PyPI - Version](https://img.shields.io/pypi/v/pgsql-mcp)](https://pypi.org/project/pgsql-mcp/)
 
 A PostgreSQL MCP server with index tuning, explain plans, health checks, and safe SQL execution.
 
@@ -24,7 +24,7 @@ For Claude Code or cloud-based IDEs, add to your MCP configuration:
   "mcpServers": {
     "postgres": {
       "command": "uvx",
-      "args": ["postgres-mcp", "--access-mode=unrestricted"],
+      "args": ["pgsql-mcp", "--access-mode=unrestricted"],
       "env": {
         "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
       }
@@ -41,7 +41,7 @@ For Claude Code or cloud-based IDEs, add to your MCP configuration:
 ```bash
 docker run -p 8000:8000 \
   -e DATABASE_URI=postgresql://username:password@localhost:5432/dbname \
-  crystaldba/postgres-mcp --access-mode=unrestricted --transport=sse
+  pgsql-mcp --access-mode=unrestricted --transport=sse
 ```
 
 2. Add to your MCP config (`mcp.json` for Cursor, `mcp_config.json` for Windsurf):
@@ -69,7 +69,7 @@ docker run -p 8000:8000 \
       "args": [
         "run", "-i", "--rm",
         "-e", "DATABASE_URI",
-        "crystaldba/postgres-mcp",
+        "pgsql-mcp",
         "--access-mode=unrestricted"
       ],
       "env": {
@@ -80,32 +80,32 @@ docker run -p 8000:8000 \
 }
 ```
 
-### Docker MCP Platform
+### Docker
 
 ```bash
-docker pull crystaldba/postgres-mcp
+docker pull pgsql-mcp
 ```
 
 Run with stdio:
 ```bash
 docker run -i --rm \
   -e DATABASE_URI=postgresql://username:password@localhost:5432/dbname \
-  crystaldba/postgres-mcp --access-mode=unrestricted
+  pgsql-mcp --access-mode=unrestricted
 ```
 
 Run with SSE:
 ```bash
 docker run -p 8000:8000 \
   -e DATABASE_URI=postgresql://username:password@localhost:5432/dbname \
-  crystaldba/postgres-mcp --access-mode=unrestricted --transport=sse
+  pgsql-mcp --access-mode=unrestricted --transport=sse
 ```
 
 ### Python Installation
 
 ```bash
-pipx install postgres-mcp
+pipx install pgsql-mcp
 # or
-uv pip install postgres-mcp
+uv pip install pgsql-mcp
 ```
 
 ## Access Modes

assets/postgres-mcp-pro.png

@@ -62,7 +62,7 @@ in
 
   enterShell = ''
     hello
-    echo "Crystal DBA Agent Development Environment"
+    echo "pgsql-mcp Development Environment"
   '';
 
   # https://devenv.sh/tasks/