airgap-db-bridge 1.0.3__tar.gz

airgap_db_bridge-1.0.3/.github/workflows/ci.yml

@@ -0,0 +1,201 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main, develop]
+    tags: ['v*']
+  pull_request:
+    branches: [master, main, develop]
+  release:
+    types: [published]
+
+jobs:
+  lint:
+    name: Lint (ruff)
+    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"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          pip install -U pip
+          pip install ruff==0.6.9
+
+      - name: Run ruff check
+        run: ruff check src/postgresql_mcp
+
+      - name: Run ruff format check
+        run: ruff format --check src/postgresql_mcp
+
+  typecheck:
+    name: Type Check (mypy)
+    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"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          pip install -U pip
+          pip install -e .[dev]
+
+      - name: Run mypy
+        run: mypy src/postgresql_mcp
+
+  test:
+    name: Test (pytest)
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+    env:
+      DB_BRIDGE_TEST_DSN: postgresql://postgres:***@localhost:5432/postgres
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          pip install -U pip
+          pip install -e .[dev]
+
+      - name: Wait for PostgreSQL
+        run: |
+          for i in {1..30}; do
+            if pg_isready -h localhost -p 5432 -U postgres; then
+              echo "PostgreSQL is ready"
+              break
+            fi
+            sleep 1
+          done
+
+      - name: Run tests
+        run: pytest tests --cov=postgresql_mcp --cov-report=xml --cov-report=term-missing
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: false
+          name: db-bridge-coverage
+
+  build:
+    name: Build Package
+    runs-on: ubuntu-latest
+    needs: [lint, typecheck, test]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "pip"
+
+      - name: Install build dependencies
+        run: |
+          pip install -U pip build hatch
+
+      - name: Build package
+        run: python -m build
+
+      - name: Verify package
+        run: |
+          pip install dist/*.whl
+          airgap-db-bridge --help
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7
+
+  publish:
+      name: Publish to PyPI
+      runs-on: ubuntu-latest
+      needs: [build]
+      if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+      permissions:
+        id-token: write
+        contents: read
+      environment: pypi
+      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
+
+  docker:
+    name: Build Docker Image
+    runs-on: ubuntu-latest
+    needs: [build]
+    if: github.event_name == 'release' && github.event.action == 'published'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/airgap-fleet/db-bridge
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=sha
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

airgap_db_bridge-1.0.3/.gitignore

@@ -0,0 +1,74 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+
+# Test artifacts
+.coverage
+coverage.xml
+htmlcov/
+.pytest_cache/
+
+# Type checking
+.mypy_cache/
+
+# Ruff
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Build artifacts
+*.dxt
+*.lock
+
+# Environment
+.env
+.env.*
+
+# Obsidian Vault - NEVER COMMIT PERSONAL DATA
+.obsidian/
+00_Master/
+01_Obi-Wan/
+02_Sub-Agents/
+03_Context/
+04_Daily_Logs/
+05_Skills/
+05_Studies/
+Anakin/
+July 2026/
+AFaaS_MASTER_PACKAGE.md
+BUSINESS_MODEL.md
+AgentComms.md
+INDEX.md
+Skill Map.md
+Chat Logs/
+Decisions Log.md
+"C:\Users\brook\reindex.py"
+*.sqlite
+*.db
+check_db.py
+fix_*.py
+reindex_*.py
+run_*.py
+seed_*.py
+temp.txt
+test_verification.py
+to-patch.md

airgap_db_bridge-1.0.3/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-08-22
+
+### Added
+- FastMCP 3.x transport layer with stdio, SSE, and HTTP transports
+- Bearer token authentication via TokenVerifier (compatible with Obsidian/Filesystem MCPs)
+- Health check endpoint (`/health`) and server info endpoint (`/info`)
+- Structured logging with structlog (JSON output, log levels)
+- Pydantic v2 configuration via pydantic-settings (environment variable support)
+- Lifespan management for connection pool initialization/cleanup
+- Synchronous core module (no FastMCP dependencies) with async API
+- 6 database tools: query, execute, list_tables, describe_table, run_migration, explain_analyze
+- Parameterized query support for SQL injection prevention
+- Read-only mode for secure deployments
+- Connection pooling with configurable size
+- Comprehensive unit test suite (39 tests, 78% coverage)
+- Integration test suite (marked for manual execution with PostgreSQL)
+- Multi-stage Dockerfile with non-root user
+- Docker Compose for local development
+- GitHub Actions CI/CD pipeline
+- Full type safety with mypy strict mode
+- 75%+ test coverage requirement
+- **Stateless protocol (2026-07-28 / SEP-2575): no global session state, explicit config per request**
+- **`create_core(config)` factory — fresh instance per request**
+- **DXT bundle for one-click installation in Claude Desktop**
+
+### Changed
+- **BREAKING**: Core rewritten as synchronous module with async facade
+- **BREAKING**: Server uses FastMCP 3.x (was 2.x)
+- **BREAKING**: Authentication changed to TokenVerifier (was none)
+- **BREAKING**: Configuration via pydantic-settings/env vars (was python-dotenv)
+- Updated dependencies: asyncpg 0.29+, pydantic 2.10+, pydantic-settings 2.6+, structlog 25.1+
+- Removed global `_core` singleton — stateless per-request instantiation
+
+### Security
+- Parameterized queries only (no string interpolation)
+- Read-only mode blocks write operations
+- Connection pooling with least privilege
+- Bearer token authentication for all transports
+- Audit logging for all operations
+
+## [0.1.0] - 2026-08-07
+
+### Added
+- Initial release

airgap_db_bridge-1.0.3/Dockerfile

@@ -0,0 +1,65 @@
+# Multi-stage Dockerfile for DB Bridge
+# ==============================================================================
+# Stage 1: Builder - Install dependencies and build package
+# ==============================================================================
+FROM python:3.12-slim AS builder
+
+WORKDIR /app
+
+# Install build dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    libpq-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install uv for fast dependency management
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+# Copy project files
+COPY pyproject.toml ./
+COPY src/ ./src/
+
+# Install dependencies and build package
+RUN uv pip install --system --no-cache-dir -e .
+
+# ==============================================================================
+# Stage 2: Runtime - Minimal runtime image
+# ==============================================================================
+FROM python:3.12-slim AS runtime
+
+WORKDIR /app
+
+# Install runtime dependencies only
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libpq5 \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/* \
+    && groupadd -r mcp && useradd -r -g mcp -u 10001 -s /sbin/nologin mcp
+
+# Copy installed package from builder
+COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
+COPY --from=builder /usr/local/bin/db-bridge /usr/local/bin/db-bridge
+
+# Create non-root user and set ownership
+RUN chown -R mcp:mcp /app
+
+USER mcp
+
+# Environment variables
+ENV DB_BRIDGE_TRANSPORT=stdio \
+    DB_BRIDGE_LOG_LEVEL=INFO \
+    DB_BRIDGE_POOL_MIN_SIZE=1 \
+    DB_BRIDGE_POOL_MAX_SIZE=10 \
+    DB_BRIDGE_QUERY_TIMEOUT=30 \
+    PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD python -c "import postgresql_mcp; print('healthy')" || exit 1
+
+# Expose ports for SSE/HTTP transports
+EXPOSE 8000
+
+# Entry point
+ENTRYPOINT ["db-bridge"]

airgap_db_bridge-1.0.3/PKG-INFO

@@ -0,0 +1,302 @@
+Metadata-Version: 2.5
+Name: airgap-db-bridge
+Version: 1.0.3
+Summary: Bridge your AI assistant to PostgreSQL databases — query, execute, migrate, and analyze without cloud dependencies
+Author-email: AFaaS Team <team@afaas.co.uk>
+License: MIT
+Keywords: bridge,database,fastmcp,postgresql
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: asyncpg>=0.29
+Requires-Dist: fastmcp<4.0,>=3.4
+Requires-Dist: pydantic-settings>=2.6
+Requires-Dist: pydantic>=2.10
+Requires-Dist: structlog>=25.1
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: uv>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Airgap DB Bridge
+
+Bridge your AI assistant to PostgreSQL databases — query, execute, migrate, and analyze without cloud dependencies.
+
+## Features
+
+- **6 Database Tools**: Query, Execute, List Tables, Describe Table, Run Migration, Explain Analyze
+- **Security First**: Parameterized queries only, read-only mode, connection pooling, audit logging
+- **Production Ready**: Async connection pooling, configurable timeouts, structured logging
+- **Developer Experience**: Type-safe Pydantic models, comprehensive tests, MCP Inspector compatible
+
+## Installation
+
+### From PyPI (when published)
+```bash
+pip install airgap-db-bridge
+```
+
+### From Source
+```bash
+git clone https://github.com/airgap-fleet/db-bridge.git
+cd db-bridge
+pip install -e .
+```
+
+### Docker
+```bash
+docker pull ghcr.io/airgap-fleet/db-bridge:latest
+```
+
+## Quick Start
+
+### 1. Configure Environment
+```bash
+cp .env.example .env
+# Edit .env with your PostgreSQL connection details
+```
+
+### 2. Run Server
+```bash
+# Direct execution
+airgap-db-bridge
+
+# Or with Docker Compose (includes PostgreSQL)
+docker-compose up -d
+```
+
+### 3. Configure MCP Client
+Add to your MCP client configuration (Claude Desktop, Cursor, VS Code, etc.):
+```json
+{
+  "mcpServers": {
+    "postgresql": {
+      "command": "airgap-db-bridge",
+      "env": {
+        "DB_BRIDGE_DSN": "postgresql://user:***@localhost:5432/db"
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+| Environment Variable | Default | Description |
+|---------------------|---------|-------------|
+| `DB_BRIDGE_DSN` | `postgresql://postgres:***@localhost:5432/postgres` | PostgreSQL connection string |
+| `DB_BRIDGE_POOL_SIZE` | `10` | Connection pool size (1-100) |
+| `DB_BRIDGE_READ_ONLY` | `false` | Enable read-only mode (blocks write operations) |
+| `DB_BRIDGE_QUERY_TIMEOUT` | `30.0` | Query timeout in seconds (0-300) |
+| `DB_BRIDGE_LOG_LEVEL` | `INFO` | Structured logging level |
+
+## Tools Reference
+
+| Tool | Description | Parameters | Read-Only Safe |
+|------|-------------|------------|----------------|
+| `query` | Execute parameterized SELECT query | `sql` (string), `params` (array, optional) | ✅ |
+| `execute` | Execute INSERT/UPDATE/DELETE | `sql` (string), `params` (array, optional) | ❌ |
+| `list_tables` | List tables in a schema | `schema` (string, default: "public") | ✅ |
+| `describe_table` | Get table structure (columns, indexes, constraints) | `table` (string), `schema` (string, default: "public") | ✅ |
+| `run_migration` | Run DDL statements in transaction | `sql` (string) | ❌ |
+| `explain_analyze` | Get query execution plan with costs | `sql` (string), `params` (array, optional) | ✅ |
+
+## Usage Examples
+
+### Query Data
+```json
+{
+  "tool": "query",
+  "arguments": {
+    "sql": "SELECT * FROM users WHERE age > $1 AND active = $2",
+    "params": [18, true]
+  }
+}
+```
+
+### Insert Data
+```json
+{
+  "tool": "execute",
+  "arguments": {
+    "sql": "INSERT INTO users (name, email, age) VALUES ($1, $2, $3)",
+    "params": ["John Doe", "john@example.com", 30]
+  }
+}
+```
+
+### List Tables
+```json
+{
+  "tool": "list_tables",
+  "arguments": {
+    "schema": "public"
+  }
+}
+```
+
+### Describe Table Structure
+```json
+{
+  "tool": "describe_table",
+  "arguments": {
+    "table": "users",
+    "schema": "public"
+  }
+}
+```
+
+### Run Migration
+```json
+{
+  "tool": "run_migration",
+  "arguments": {
+    "sql": "CREATE TABLE products (id SERIAL PRIMARY KEY, name TEXT NOT NULL, price DECIMAL(10,2)); CREATE INDEX idx_products_name ON products(name);"
+  }
+}
+```
+
+### Analyze Query Plan
+```json
+{
+  "tool": "explain_analyze",
+  "arguments": {
+    "sql": "SELECT * FROM users JOIN orders ON users.id = orders.user_id WHERE users.id = $1",
+    "params": [1]
+  }
+}
+```
+
+## Security Model
+
+### Parameterized Queries Only
+All SQL execution uses parameterized queries (`$1`, `$2`, etc.). String concatenation or interpolation is **not supported** — this prevents SQL injection by design.
+
+### Read-Only Mode
+Set `DB_BRIDGE_READ_ONLY=true` to disable:
+- `execute` (INSERT/UPDATE/DELETE)
+- `run_migration` (DDL)
+
+Read operations (`query`, `list_tables`, `describe_table`, `explain_analyze`) remain available.
+
+### Connection Pooling
+- Configurable pool size (1-100 connections)
+- Automatic connection lifecycle management
+- Query timeout enforcement
+
+### Audit Logging
+All operations are logged with structured JSON including:
+- Operation type and parameters (sanitized)
+- Execution time
+- Row counts affected
+- Error details (if any)
+
+## Development
+
+### Prerequisites
+- Python 3.11+
+- PostgreSQL 14+ (for local development)
+- uv (recommended) or pip
+
+### Setup
+```bash
+# Install uv if not present
+pip install uv
+
+# Create virtual environment and install dependencies
+uv sync --dev
+
+# Run tests
+uv run pytest
+
+# Type check
+uv run mypy src/postgresql_mcp
+
+# Lint and format
+uv run ruff check .
+uv run ruff format .
+```
+
+### Running Tests with Local PostgreSQL
+```bash
+# Start PostgreSQL (Docker)
+docker run -d --name pg-test -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres:16
+
+# Run tests
+DB_BRIDGE_TEST_DSN=postgresql://postgres:***@localhost:5432/postgres uv run pytest
+
+# Cleanup
+docker rm -f pg-test
+```
+
+### MCP Inspector
+```bash
+npx @modelcontextprotocol/inspector uv run airgap-db-bridge
+```
+
+## Architecture
+
+```
+db-bridge/
+├── src/postgresql_mcp/
+│   ├── __init__.py          # Package exports
+│   ├── models.py            # Pydantic models (requests/responses/config)
+│   ├── core.py              # Business logic (asyncpg, zero FastMCP imports)
+│   └── server.py            # FastMCP app, tool registration, lifespan
+├── tests/
+│   ├── conftest.py          # Test fixtures and setup
+│   ├── test_models.py       # Model validation tests
+│   ├── test_core.py         # Core business logic tests
+│   └── test_tools.py        # MCP tool integration tests
+├── .github/workflows/ci.yml # CI/CD pipeline
+├── Dockerfile               # Multi-stage container build
+├── docker-compose.yml       # Local development stack
+├── pyproject.toml           # Project configuration (hatch)
+└── README.md                # This file
+```
+
+### Design Principles
+
+1. **Separation of Concerns**: `core.py` contains zero FastMCP imports — fully testable in isolation
+2. **Type Safety**: Pydantic v2 for all boundaries, mypy strict mode
+3. **Async First**: asyncpg for non-blocking database operations
+4. **Security by Default**: Parameterized queries, read-only mode, least privilege
+5. **Observability**: Structured JSON logging, execution timing, audit trails
+
+## CI/CD Pipeline
+
+The GitHub Actions workflow (`.github/workflows/ci.yml`) runs on every push/PR:
+
+1. **Lint** — ruff check + format
+2. **Type Check** — mypy strict
+3. **Test** — pytest with PostgreSQL service, coverage ≥90%
+4. **Build** — hatch build + twine verify
+5. **Publish** — PyPI on release (trusted publishing)
+6. **Docker** — Multi-platform image on release
+
+## License
+
+MIT License — see LICENSE file for details.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make changes with tests
+4. Ensure CI passes (lint, typecheck, test, coverage)
+5. Submit a pull request
+
+## Support
+
+- Issues: GitHub Issues
+- Documentation: This README + inline docstrings
+- MCP Specification: https://modelcontextprotocol.io