tabulus 0.0.1__tar.gz

tabulus-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,75 @@
+name: CI
+
+on:
+  push:
+    branches: [main, "pivot/**"]
+    tags: ["v*.*.*"]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test:
+    name: Python ${{ matrix.python }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12"]
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_PASSWORD: test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 5s
+          --health-timeout 3s
+          --health-retries 5
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Format check
+        run: ruff format --check .
+
+      - name: Unit tests
+        run: pytest tests/ -v --tb=short
+
+      - name: Integration smoke (live Postgres)
+        env:
+          DATABASE_URL: postgres://postgres:test@localhost:5432/postgres
+        run: |
+          python -c "
+          import asyncio
+          from vigil.config import load
+          from vigil.db import get_pool, list_tables, close_pool
+          async def main():
+              pool = await get_pool(load())
+              await pool.execute('CREATE TABLE smoke (id int)')
+              tables = await list_tables(pool)
+              assert any(t['name'] == 'smoke' for t in tables), 'smoke table missing'
+              print('Integration OK')
+              await close_pool()
+          asyncio.run(main())
+          "

tabulus-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*.*.*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write   # required for PyPI trusted publishing
+
+jobs:
+  build:
+    name: Build wheel + sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build
+        run: python -m build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/tabulus
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish via OIDC (no API token)
+        uses: pypa/gh-action-pypi-publish@release/v1

tabulus-0.0.1/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.venv/
+venv/
+build/
+dist/
+*.whl
+
+.env
+.env.local
+
+.vscode/
+.idea/
+.DS_Store

tabulus-0.0.1/.mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "vigil": {
+      "command": ".venv/bin/vigil",
+      "args": [],
+      "env": {
+        "DATABASE_URL": "postgres://postgres:dev@localhost:5433/postgres",
+        "VIGIL_MAX_ROWS": "100",
+        "VIGIL_SAMPLE_SIZE": "3",
+        "VIGIL_STATEMENT_TIMEOUT_MS": "5000"
+      }
+    }
+  }
+}

tabulus-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WalkingMountain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tabulus-0.0.1/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: tabulus
+Version: 0.0.1
+Summary: Postgres MCP server — agent-first database workbench
+Project-URL: Repository, https://github.com/WalkingMountain/vigilmcp
+Project-URL: Issues, https://github.com/WalkingMountain/vigilmcp/issues
+Author: WalkingMountain
+License: MIT
+License-File: LICENSE
+Keywords: agent,claude,cursor,database,mcp,postgres,sql
+Classifier: Development Status :: 3 - Alpha
+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
+Requires-Python: >=3.11
+Requires-Dist: asyncpg>=0.30
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Vigil
+
+**A Postgres MCP server built for AI agents.**
+
+Vigil is the database workbench for the AI-augmented developer. Connect Claude
+Code, Cursor, or any MCP-compatible client to your Postgres database and let
+the agent introspect the schema, sample data, and write safe queries — without
+copy-pasting schemas into chat windows.
+
+## Why
+
+Every modern dev workflow now includes an AI agent. Every DB GUI was designed
+before that was true. Vigil flips the model: **the agent is a first-class user,
+not a sidebar feature.**
+
+What that means in practice:
+
+- Schema introspection optimized for LLM context windows (compact JSON, foreign
+  keys flattened, sample rows inline).
+- Read-only by default — `INSERT`/`UPDATE`/`DELETE`/`DDL` are rejected at the
+  gateway. Agent can't drop your tables.
+- `EXPLAIN` exposed as a tool so the agent can reason about query plans before
+  proposing optimizations.
+- Statement timeout + row cap enforced server-side. No agent can DOS your
+  database by accident.
+
+## Status
+
+**v0.0.1 — alpha.** Postgres only. Stdio MCP transport only. No GUI yet.
+
+## Install
+
+```bash
+pip install tabulus
+```
+
+## Run
+
+```bash
+export DATABASE_URL=postgres://user:pass@host:5432/dbname
+vigil
+```
+
+Then point your MCP client at the `vigil` command.
+
+### Claude Code (project-level)
+
+Create `.mcp.json` in your project root:
+
+```jsonc
+{
+  "mcpServers": {
+    "vigil": {
+      "command": "vigil",
+      "args": [],
+      "env": {
+        "DATABASE_URL": "postgres://user:pass@host:5432/dbname"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Code in that directory and approve the trust prompt.
+
+### Claude Code (user-level via CLI)
+
+```bash
+claude mcp add vigil "$(which vigil)" --env DATABASE_URL=postgres://user:pass@host:5432/dbname
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp_servers.json`:
+
+```jsonc
+{
+  "mcpServers": {
+    "vigil": {
+      "command": "vigil",
+      "env": { "DATABASE_URL": "postgres://user:pass@host:5432/dbname" }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `list_tables` | All tables with row count estimates + sizes |
+| `describe_schema` | Columns, PK, FKs, indexes, sample rows for a table |
+| `sample_rows` | Random sample from a table |
+| `safe_select` | Run a read-only SELECT (write keywords rejected) |
+| `explain` | Get query plan (EXPLAIN FORMAT JSON) |
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `DATABASE_URL` | — (required) | Postgres connection URL |
+| `VIGIL_MAX_ROWS` | `100` | Hard cap on rows returned by any tool |
+| `VIGIL_SAMPLE_SIZE` | `3` | Sample rows included in `describe_schema` |
+| `VIGIL_STATEMENT_TIMEOUT_MS` | `5000` | Server-side query timeout |
+| `VIGIL_REDACT` | `off` | Set `on` to scrub PII (emails, API keys, JWTs, credit cards, phones, IPs) from `sample_rows`, `safe_select`, and `describe_schema` output before the agent sees it. Recommended for production. |
+| `VIGIL_ALLOW_WRITES` | `false` | Set `true` to disable the write block (NOT recommended) |
+
+## Roadmap
+
+- v0.1 — Postgres parity, polished install
+- v0.2 — SQLite adapter
+- v0.3 — MySQL / MariaDB adapter
+- v0.x — Tauri desktop GUI shell on top of the same core
+- v1.0 — Stable, cross-platform, multi-DB
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

tabulus-0.0.1/README.md

@@ -0,0 +1,118 @@
+# Vigil
+
+**A Postgres MCP server built for AI agents.**
+
+Vigil is the database workbench for the AI-augmented developer. Connect Claude
+Code, Cursor, or any MCP-compatible client to your Postgres database and let
+the agent introspect the schema, sample data, and write safe queries — without
+copy-pasting schemas into chat windows.
+
+## Why
+
+Every modern dev workflow now includes an AI agent. Every DB GUI was designed
+before that was true. Vigil flips the model: **the agent is a first-class user,
+not a sidebar feature.**
+
+What that means in practice:
+
+- Schema introspection optimized for LLM context windows (compact JSON, foreign
+  keys flattened, sample rows inline).
+- Read-only by default — `INSERT`/`UPDATE`/`DELETE`/`DDL` are rejected at the
+  gateway. Agent can't drop your tables.
+- `EXPLAIN` exposed as a tool so the agent can reason about query plans before
+  proposing optimizations.
+- Statement timeout + row cap enforced server-side. No agent can DOS your
+  database by accident.
+
+## Status
+
+**v0.0.1 — alpha.** Postgres only. Stdio MCP transport only. No GUI yet.
+
+## Install
+
+```bash
+pip install tabulus
+```
+
+## Run
+
+```bash
+export DATABASE_URL=postgres://user:pass@host:5432/dbname
+vigil
+```
+
+Then point your MCP client at the `vigil` command.
+
+### Claude Code (project-level)
+
+Create `.mcp.json` in your project root:
+
+```jsonc
+{
+  "mcpServers": {
+    "vigil": {
+      "command": "vigil",
+      "args": [],
+      "env": {
+        "DATABASE_URL": "postgres://user:pass@host:5432/dbname"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Code in that directory and approve the trust prompt.
+
+### Claude Code (user-level via CLI)
+
+```bash
+claude mcp add vigil "$(which vigil)" --env DATABASE_URL=postgres://user:pass@host:5432/dbname
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp_servers.json`:
+
+```jsonc
+{
+  "mcpServers": {
+    "vigil": {
+      "command": "vigil",
+      "env": { "DATABASE_URL": "postgres://user:pass@host:5432/dbname" }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `list_tables` | All tables with row count estimates + sizes |
+| `describe_schema` | Columns, PK, FKs, indexes, sample rows for a table |
+| `sample_rows` | Random sample from a table |
+| `safe_select` | Run a read-only SELECT (write keywords rejected) |
+| `explain` | Get query plan (EXPLAIN FORMAT JSON) |
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `DATABASE_URL` | — (required) | Postgres connection URL |
+| `VIGIL_MAX_ROWS` | `100` | Hard cap on rows returned by any tool |
+| `VIGIL_SAMPLE_SIZE` | `3` | Sample rows included in `describe_schema` |
+| `VIGIL_STATEMENT_TIMEOUT_MS` | `5000` | Server-side query timeout |
+| `VIGIL_REDACT` | `off` | Set `on` to scrub PII (emails, API keys, JWTs, credit cards, phones, IPs) from `sample_rows`, `safe_select`, and `describe_schema` output before the agent sees it. Recommended for production. |
+| `VIGIL_ALLOW_WRITES` | `false` | Set `true` to disable the write block (NOT recommended) |
+
+## Roadmap
+
+- v0.1 — Postgres parity, polished install
+- v0.2 — SQLite adapter
+- v0.3 — MySQL / MariaDB adapter
+- v0.x — Tauri desktop GUI shell on top of the same core
+- v1.0 — Stable, cross-platform, multi-DB
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

tabulus-0.0.1/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "tabulus"
+version = "0.0.1"
+description = "Postgres MCP server — agent-first database workbench"
+authors = [{name = "WalkingMountain"}]
+license = {text = "MIT"}
+requires-python = ">=3.11"
+readme = "README.md"
+keywords = ["postgres", "mcp", "claude", "cursor", "database", "agent", "sql"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Database",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "asyncpg>=0.30",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.7",
+]
+
+[project.scripts]
+vigil = "vigil.cli:main"
+
+[project.urls]
+Repository = "https://github.com/WalkingMountain/vigilmcp"
+Issues = "https://github.com/WalkingMountain/vigilmcp/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vigil"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

tabulus-0.0.1/src/vigil/__init__.py

@@ -0,0 +1,3 @@
+"""Vigil — Postgres MCP server for AI agents."""
+
+__version__ = "0.0.1"

tabulus-0.0.1/src/vigil/cli.py

@@ -0,0 +1,69 @@
+"""CLI entry point — `vigil` command.
+
+Wraps startup errors in friendly messages so the agent / user sees actionable
+hints instead of stack traces.
+"""
+
+import sys
+
+from vigil import __version__
+
+
+def main() -> None:
+    if "--version" in sys.argv or "-V" in sys.argv:
+        print(f"vigil {__version__}")
+        return
+
+    if "--help" in sys.argv or "-h" in sys.argv:
+        print(
+            "vigil — Postgres MCP server for AI agents\n"
+            "\n"
+            "Usage:\n"
+            "  DATABASE_URL=postgres://user:pass@host:5432/dbname vigil\n"
+            "\n"
+            "Environment variables:\n"
+            "  DATABASE_URL              required — Postgres connection string\n"
+            "  VIGIL_MAX_ROWS            default 100 — cap on rows returned\n"
+            "  VIGIL_SAMPLE_SIZE         default 3 — rows in describe_schema sample\n"
+            "  VIGIL_STATEMENT_TIMEOUT_MS  default 5000 — server-side query timeout\n"
+            "  VIGIL_REDACT              default off — set 'on' to scrub PII from output\n"
+            "  VIGIL_ALLOW_WRITES        default false — keep false (read-only)\n"
+            "\n"
+            "Repo: https://github.com/WalkingMountain/vigilmcp"
+        )
+        return
+
+    try:
+        # Defer import so --version/--help don't pay the asyncio + mcp cost
+        from vigil.config import load
+        from vigil.server import main as run_server
+
+        # Fast-fail config validation BEFORE we open the stdio MCP loop —
+        # otherwise the agent waits until first tool call to learn DATABASE_URL
+        # is missing, which makes the failure mode confusing.
+        load()
+        run_server()
+    except RuntimeError as e:
+        # Config errors (missing DATABASE_URL, etc.) — already friendly
+        print(f"vigil: {e}", file=sys.stderr)
+        sys.exit(2)
+    except KeyboardInterrupt:
+        sys.exit(0)
+    except Exception as e:
+        # Last resort — show error class + message, hint at common causes
+        print(
+            f"vigil: unexpected error: {type(e).__name__}: {e}\n"
+            f"\n"
+            f"Common causes:\n"
+            f"  - DATABASE_URL points at an unreachable host\n"
+            f"  - Postgres requires SSL but the URL lacks ?sslmode=require\n"
+            f"  - User in DATABASE_URL lacks CONNECT or USAGE privileges\n"
+            f"\n"
+            f"File an issue: https://github.com/WalkingMountain/vigilmcp/issues",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

tabulus-0.0.1/src/vigil/config.py

@@ -0,0 +1,29 @@
+"""Runtime config from environment variables."""
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Config:
+    database_url: str
+    max_rows: int  # cap on rows returned by any tool
+    sample_size: int  # rows per describe_schema sample
+    statement_timeout_ms: int
+    allow_writes: bool  # default False — agent gets read-only
+
+
+def load() -> Config:
+    url = os.environ.get("DATABASE_URL")
+    if not url:
+        raise RuntimeError(
+            "DATABASE_URL is required. Set to a Postgres connection string "
+            "(postgres://user:pass@host:5432/dbname)."
+        )
+    return Config(
+        database_url=url,
+        max_rows=int(os.environ.get("VIGIL_MAX_ROWS", "100")),
+        sample_size=int(os.environ.get("VIGIL_SAMPLE_SIZE", "3")),
+        statement_timeout_ms=int(os.environ.get("VIGIL_STATEMENT_TIMEOUT_MS", "5000")),
+        allow_writes=os.environ.get("VIGIL_ALLOW_WRITES", "false").lower() == "true",
+    )