tabulus 0.0.1__py3-none-any.whl

tabulus-0.0.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+vigil/__init__.py,sha256=lKNOax-_jZ74hoDy3c8JJEj9R5-3lM5iVqY09Nsb_qk,74
+vigil/cli.py,sha256=kzLr8ox4VYFL53_0pEPCD9JGO0KjBaIhOfyfxw21Tck,2550
+vigil/config.py,sha256=LjJn5S_7giqrNbPG7C4bSwimlBNyS2dwHam3tx619EI,967
+vigil/db.py,sha256=kL0VVHEiNYpWbiORCy12qaofy6NaxEyALmhzQa6ZO3g,6149
+vigil/redactor.py,sha256=bxTdaXmZctDB6OlpppLHOISarNiYbtHRix2hyC-3nTQ,4554
+vigil/safety.py,sha256=C6SfTNBVVffD4mvWF8DQjw7xmLwecOwyza0kYUuFCdk,2598
+vigil/server.py,sha256=tTXLKFgJ5xzRgBlsEgupBhW8v_pCuYB1BKavKO1jHbk,4751
+tabulus-0.0.1.dist-info/METADATA,sha256=QshdPfrCMPgpyd7Al1xtpZ9AHHSy229T8Pf93luGTfg,4182
+tabulus-0.0.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+tabulus-0.0.1.dist-info/entry_points.txt,sha256=g3mzzDHgZny8CWWasju_7Yv_ZaMEn6QDVSkLToN-Fo4,41
+tabulus-0.0.1.dist-info/licenses/LICENSE,sha256=MGd2BM-9ImicOx1eDwNQEq1liAkqK12L7Vl1mneinjI,1072
+tabulus-0.0.1.dist-info/RECORD,,

tabulus-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

tabulus-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vigil = vigil.cli:main

tabulus-0.0.1.dist-info/licenses/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.

vigil/__init__.py

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

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()

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",
+    )

vigil/db.py

@@ -0,0 +1,196 @@
+"""Postgres connection pool + schema introspection.
+
+LLM-friendly schema output: compact JSON, sample rows inline, foreign keys
+flattened. Goal is to fit a 50-table schema into one prompt without truncation.
+"""
+
+import asyncpg
+from typing import Any
+
+from vigil.config import Config
+from vigil.redactor import maybe_redact
+
+
+_pool: asyncpg.Pool | None = None
+
+
+async def get_pool(config: Config) -> asyncpg.Pool:
+    global _pool
+    if _pool is None:
+        _pool = await asyncpg.create_pool(
+            config.database_url,
+            min_size=1,
+            max_size=4,
+            command_timeout=config.statement_timeout_ms / 1000.0,
+            server_settings={
+                "default_transaction_read_only": "off" if config.allow_writes else "on",
+                "statement_timeout": str(config.statement_timeout_ms),
+            },
+        )
+    return _pool
+
+
+async def close_pool() -> None:
+    global _pool
+    if _pool is not None:
+        await _pool.close()
+        _pool = None
+
+
+async def list_tables(pool: asyncpg.Pool, schema: str | None = None) -> list[dict[str, Any]]:
+    """List tables. For tables Postgres hasn't ANALYZEd yet (reltuples < 0),
+    fall back to a live COUNT(*) so the agent never sees `-1` row counts."""
+    sql = """
+        SELECT
+            n.nspname     AS schema,
+            c.relname     AS name,
+            c.reltuples::bigint AS row_estimate,
+            pg_size_pretty(pg_total_relation_size(c.oid)) AS size,
+            obj_description(c.oid, 'pg_class') AS comment
+        FROM pg_class c
+        JOIN pg_namespace n ON n.oid = c.relnamespace
+        WHERE c.relkind IN ('r', 'p', 'v', 'm')
+          AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+          AND ($1::text IS NULL OR n.nspname = $1)
+        ORDER BY n.nspname, c.relname
+    """
+    rows = await pool.fetch(sql, schema)
+    result = [dict(r) for r in rows]
+    for row in result:
+        if row["row_estimate"] is None or row["row_estimate"] < 0:
+            try:
+                count = await pool.fetchval(
+                    f'SELECT COUNT(*) FROM "{row["schema"]}"."{row["name"]}"'
+                )
+                row["row_estimate"] = int(count)
+                row["row_estimate_exact"] = True
+            except Exception:
+                row["row_estimate"] = None
+    return result
+
+
+async def describe_table(
+    pool: asyncpg.Pool,
+    qualified: str,
+    sample_size: int,
+) -> dict[str, Any]:
+    """Return columns, indexes, foreign keys, and a small sample."""
+    schema, table = _split_qualified(qualified)
+
+    columns = await pool.fetch(
+        """
+        SELECT
+            column_name AS name,
+            data_type AS type,
+            is_nullable = 'YES' AS nullable,
+            column_default AS default,
+            character_maximum_length AS max_length
+        FROM information_schema.columns
+        WHERE table_schema = $1 AND table_name = $2
+        ORDER BY ordinal_position
+        """,
+        schema,
+        table,
+    )
+
+    primary_key = await pool.fetch(
+        """
+        SELECT a.attname AS column
+        FROM pg_index i
+        JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = ANY(i.indkey)
+        WHERE i.indrelid = ($1 || '.' || $2)::regclass AND i.indisprimary
+        """,
+        schema,
+        table,
+    )
+
+    foreign_keys = await pool.fetch(
+        """
+        SELECT
+            kcu.column_name AS from_column,
+            ccu.table_schema || '.' || ccu.table_name AS to_table,
+            ccu.column_name AS to_column
+        FROM information_schema.table_constraints tc
+        JOIN information_schema.key_column_usage kcu
+          ON tc.constraint_name = kcu.constraint_name
+         AND tc.table_schema = kcu.table_schema
+        JOIN information_schema.constraint_column_usage ccu
+          ON ccu.constraint_name = tc.constraint_name
+         AND ccu.table_schema = tc.table_schema
+        WHERE tc.constraint_type = 'FOREIGN KEY'
+          AND tc.table_schema = $1
+          AND tc.table_name = $2
+        """,
+        schema,
+        table,
+    )
+
+    indexes = await pool.fetch(
+        """
+        SELECT indexname AS name, indexdef AS definition
+        FROM pg_indexes
+        WHERE schemaname = $1 AND tablename = $2
+        """,
+        schema,
+        table,
+    )
+
+    sample = await pool.fetch(
+        f'SELECT * FROM "{schema}"."{table}" LIMIT $1',
+        sample_size,
+    )
+
+    return {
+        "table": f"{schema}.{table}",
+        "columns": [dict(c) for c in columns],
+        "primary_key": [r["column"] for r in primary_key],
+        "foreign_keys": [dict(f) for f in foreign_keys],
+        "indexes": [dict(i) for i in indexes],
+        "sample_rows": maybe_redact([dict(s) for s in sample]),
+    }
+
+
+async def sample_rows(
+    pool: asyncpg.Pool,
+    qualified: str,
+    limit: int,
+) -> list[dict[str, Any]]:
+    schema, table = _split_qualified(qualified)
+    rows = await pool.fetch(
+        f'SELECT * FROM "{schema}"."{table}" ORDER BY random() LIMIT $1',
+        limit,
+    )
+    return maybe_redact([dict(r) for r in rows])
+
+
+async def safe_select(
+    pool: asyncpg.Pool,
+    sql: str,
+    max_rows: int,
+) -> dict[str, Any]:
+    # Wrap with LIMIT enforcement (subquery prevents user-supplied LIMIT bypass)
+    wrapped = f"SELECT * FROM ({sql}) _vigil_q LIMIT {int(max_rows)}"
+    rows = await pool.fetch(wrapped)
+    return {
+        "row_count": len(rows),
+        "rows": maybe_redact([dict(r) for r in rows]),
+        "truncated": len(rows) == max_rows,
+    }
+
+
+async def explain(pool: asyncpg.Pool, sql: str) -> dict[str, Any]:
+    plan = await pool.fetchval(f"EXPLAIN (FORMAT JSON, ANALYZE FALSE) {sql}")
+    return {"plan": plan}
+
+
+def _split_qualified(qualified: str) -> tuple[str, str]:
+    """Parse `schema.table` or bare `table` (assumes public)."""
+    if "." in qualified:
+        schema, table = qualified.split(".", 1)
+    else:
+        schema, table = "public", qualified
+    # Reject injection vectors
+    for part in (schema, table):
+        if not all(c.isalnum() or c == "_" for c in part):
+            raise ValueError(f"Invalid identifier: {part!r}")
+    return schema, table

vigil/redactor.py

@@ -0,0 +1,96 @@
+"""PII / secret redactor for tool output before LLM sees it.
+
+Database tools (sample_rows, safe_select, describe_schema's sample_rows)
+return rows from user tables. Those rows often contain customer emails,
+API keys, JWTs, credit cards, SSNs, phone numbers, IPs. Without redaction
+that data ships to Anthropic on every query — brand-killing leak.
+
+Sentinel format: `[REDACTED:type]` — preserves enough structure for the
+LLM to reason ("Stripe call failed with [REDACTED:api_key]") without
+leaking the value.
+
+Conservative philosophy: false positives are cheap, false negatives kill.
+
+Off by default — set VIGIL_REDACT=on to enable.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import Any
+
+
+_PATTERNS: list[tuple[str, re.Pattern[str]]] = [
+    # ── JWT (eyJ... three segments) ─────────────────────────────────────────
+    ("jwt", re.compile(r"\beyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+")),
+    # ── Vendor API keys with distinctive prefixes ───────────────────────────
+    ("anthropic_key", re.compile(r"\bsk-ant-[A-Za-z0-9_-]{20,}")),
+    ("openai_key", re.compile(r"\bsk-(?:proj-)?[A-Za-z0-9]{20,}")),
+    ("stripe_key", re.compile(r"\b(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]{20,}")),
+    ("github_token", re.compile(r"\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}")),
+    ("slack_token", re.compile(r"\bxox[bpars]-[A-Za-z0-9-]{20,}")),
+    ("aws_access_key", re.compile(r"\bAKIA[0-9A-Z]{16}\b")),
+    ("google_api_key", re.compile(r"\bAIza[0-9A-Za-z_-]{35}\b")),
+    # ── Bearer / Authorization headers ──────────────────────────────────────
+    ("bearer_token", re.compile(r"(?i)bearer\s+[A-Za-z0-9._~+/-]{20,}={0,2}")),
+    # ── Credit card (13-19 digits, common groupings) ────────────────────────
+    ("credit_card", re.compile(r"\b(?:\d[ -]*?){13,19}\b")),
+    # ── SSN (US) ────────────────────────────────────────────────────────────
+    ("ssn", re.compile(r"\b\d{3}-\d{2}-\d{4}\b")),
+    # ── Email ───────────────────────────────────────────────────────────────
+    (
+        "email",
+        re.compile(
+            r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?"
+            r"(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)+\b"
+        ),
+    ),
+    # ── Phone (international + US, conservative) ────────────────────────────
+    (
+        "phone",
+        re.compile(
+            r"(?<![A-Za-z0-9])\+?\d{1,3}[\s.-]?\(?\d{2,4}\)?"
+            r"[\s.-]?\d{3,4}[\s.-]?\d{3,4}(?![A-Za-z0-9])"
+        ),
+    ),
+    # ── IPv4 ────────────────────────────────────────────────────────────────
+    ("ipv4", re.compile(r"\b(?:\d{1,3}\.){3}\d{1,3}\b")),
+    # ── IPv6 (handles :: compression, blocks Class::Path false matches) ─────
+    (
+        "ipv6",
+        re.compile(r"(?<![A-Za-z0-9:])(?:[A-Fa-f0-9]{0,4}:){2,}[A-Fa-f0-9]{0,4}(?![A-Za-z0-9:])"),
+    ),
+]
+
+
+def is_enabled() -> bool:
+    return os.environ.get("VIGIL_REDACT", "off").lower() in ("on", "true", "1", "yes")
+
+
+def redact_string(s: str) -> str:
+    """Replace sensitive substrings with `[REDACTED:type]` sentinels. Idempotent."""
+    if not isinstance(s, str) or not s:
+        return s
+    out = s
+    for kind, pattern in _PATTERNS:
+        out = pattern.sub(f"[REDACTED:{kind}]", out)
+    return out
+
+
+def redact_value(v: Any) -> Any:
+    """Recursively redact str / list / dict / tuple. Dict KEYS NOT redacted."""
+    if isinstance(v, str):
+        return redact_string(v)
+    if isinstance(v, dict):
+        return {k: redact_value(val) for k, val in v.items()}
+    if isinstance(v, list):
+        return [redact_value(item) for item in v]
+    if isinstance(v, tuple):
+        return tuple(redact_value(item) for item in v)
+    return v
+
+
+def maybe_redact(v: Any) -> Any:
+    """No-op when VIGIL_REDACT is off, redact otherwise."""
+    return redact_value(v) if is_enabled() else v

vigil/safety.py

@@ -0,0 +1,95 @@
+"""SQL safety — read-only enforcement.
+
+Rejects any statement that could mutate data or schema. Default mode for the
+agent: SELECT + EXPLAIN only. Writes only enabled when VIGIL_ALLOW_WRITES=true
+AND the human operator opts in per-statement (future approval flow).
+"""
+
+import re
+
+_FORBIDDEN_KEYWORDS = {
+    "INSERT",
+    "UPDATE",
+    "DELETE",
+    "DROP",
+    "TRUNCATE",
+    "ALTER",
+    "CREATE",
+    "GRANT",
+    "REVOKE",
+    "COMMENT",
+    "REINDEX",
+    "VACUUM",
+    "ANALYZE",
+    "CLUSTER",
+    "COPY",
+    "DO",
+    "CALL",
+    "MERGE",
+    "REPLACE",
+    "RENAME",
+    "REFRESH",
+    "LOCK",
+    "NOTIFY",
+    "LISTEN",
+    "UNLISTEN",
+    "SET",
+    "RESET",
+    "DISCARD",
+    "PREPARE",
+    "EXECUTE",
+    "DEALLOCATE",
+    "BEGIN",
+    "COMMIT",
+    "ROLLBACK",
+    "SAVEPOINT",
+    "RELEASE",
+    "START",
+}
+
+# Statements that are always allowed in read-only mode
+_ALLOWED_LEADS = {"SELECT", "WITH", "EXPLAIN", "SHOW", "TABLE", "VALUES"}
+
+
+class UnsafeSQLError(ValueError):
+    """Raised when a query would mutate state in read-only mode."""
+
+
+def normalize(sql: str) -> str:
+    """Strip comments and collapse whitespace for keyword inspection."""
+    # Strip /* ... */ block comments
+    sql = re.sub(r"/\*.*?\*/", " ", sql, flags=re.DOTALL)
+    # Strip -- line comments
+    sql = re.sub(r"--[^\n]*", " ", sql)
+    return " ".join(sql.split())
+
+
+def assert_read_only(sql: str) -> None:
+    """Raise UnsafeSQLError if sql contains any mutating keyword.
+
+    Approach: tokenize on word boundaries, reject if any forbidden keyword
+    appears at statement-leading position OR after a semicolon.
+    """
+    cleaned = normalize(sql)
+    if not cleaned:
+        raise UnsafeSQLError("Empty statement")
+
+    # Split on semicolons (multi-statement). Reject anything that isn't a
+    # single read-only statement.
+    statements = [s.strip() for s in cleaned.split(";") if s.strip()]
+    if len(statements) > 1:
+        raise UnsafeSQLError("Multiple statements not allowed in read-only mode")
+
+    stmt = statements[0]
+    first_word = stmt.split(None, 1)[0].upper()
+    if first_word not in _ALLOWED_LEADS:
+        raise UnsafeSQLError(
+            f"Statement must start with one of {sorted(_ALLOWED_LEADS)} "
+            f"in read-only mode (got {first_word!r})"
+        )
+
+    # Defense-in-depth: scan for any forbidden keyword anywhere
+    upper_tokens = set(re.findall(r"\b[A-Z]+\b", stmt.upper()))
+    forbidden_hits = upper_tokens & _FORBIDDEN_KEYWORDS
+    if forbidden_hits:
+        raise UnsafeSQLError(f"Forbidden keyword(s) in read-only mode: {sorted(forbidden_hits)}")

vigil/server.py

@@ -0,0 +1,155 @@
+"""MCP server entry point.
+
+Exposes 5 tools over stdio:
+- list_tables
+- describe_schema
+- sample_rows
+- safe_select
+- explain
+
+Used by Claude Code / Cursor / any MCP client.
+"""
+
+import asyncio
+import json
+from typing import Any
+
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import TextContent, Tool
+
+from vigil.config import load
+from vigil.db import (
+    close_pool,
+    describe_table,
+    explain,
+    get_pool,
+    list_tables,
+    safe_select,
+    sample_rows,
+)
+from vigil.safety import UnsafeSQLError, assert_read_only
+
+
+server = Server("vigil")
+
+
+@server.list_tools()
+async def list_available_tools() -> list[Tool]:
+    return [
+        Tool(
+            name="list_tables",
+            description="List all tables in the database with row count estimates and sizes.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "schema": {
+                        "type": "string",
+                        "description": "Optional schema name to filter (e.g., 'public').",
+                    }
+                },
+            },
+        ),
+        Tool(
+            name="describe_schema",
+            description=(
+                "Describe a table: columns, types, primary key, foreign keys, indexes, "
+                "and a small sample of rows. The single most useful tool for an agent "
+                "trying to understand the data model."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "table": {
+                        "type": "string",
+                        "description": "Table name, optionally schema-qualified (e.g., 'public.users').",
+                    }
+                },
+                "required": ["table"],
+            },
+        ),
+        Tool(
+            name="sample_rows",
+            description="Return a random sample of rows from a table.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "table": {"type": "string"},
+                    "limit": {"type": "integer", "default": 10},
+                },
+                "required": ["table"],
+            },
+        ),
+        Tool(
+            name="safe_select",
+            description=(
+                "Run a read-only SELECT query. INSERT/UPDATE/DELETE/DDL are rejected. "
+                "Results are capped at the server's max_rows setting (default 100)."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "sql": {
+                        "type": "string",
+                        "description": "A SELECT/WITH/EXPLAIN/SHOW statement.",
+                    }
+                },
+                "required": ["sql"],
+            },
+        ),
+        Tool(
+            name="explain",
+            description="Return the query plan for a SELECT statement (EXPLAIN FORMAT JSON).",
+            inputSchema={
+                "type": "object",
+                "properties": {"sql": {"type": "string"}},
+                "required": ["sql"],
+            },
+        ),
+    ]
+
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
+    config = load()
+    pool = await get_pool(config)
+
+    try:
+        if name == "list_tables":
+            result = await list_tables(pool, arguments.get("schema"))
+        elif name == "describe_schema":
+            result = await describe_table(pool, arguments["table"], config.sample_size)
+        elif name == "sample_rows":
+            limit = min(int(arguments.get("limit", 10)), config.max_rows)
+            result = await sample_rows(pool, arguments["table"], limit)
+        elif name == "safe_select":
+            sql = arguments["sql"]
+            assert_read_only(sql)
+            result = await safe_select(pool, sql, config.max_rows)
+        elif name == "explain":
+            sql = arguments["sql"]
+            assert_read_only(sql)
+            result = await explain(pool, sql)
+        else:
+            return [TextContent(type="text", text=f"Unknown tool: {name}")]
+
+        return [TextContent(type="text", text=json.dumps(result, default=str, indent=2))]
+
+    except UnsafeSQLError as e:
+        return [TextContent(type="text", text=f"Rejected by safety policy: {e}")]
+    except Exception as e:
+        return [TextContent(type="text", text=f"Error: {type(e).__name__}: {e}")]
+
+
+async def run() -> None:
+    async with stdio_server() as (read, write):
+        await server.run(read, write, server.create_initialization_options())
+    await close_pool()
+
+
+def main() -> None:
+    asyncio.run(run())
+
+
+if __name__ == "__main__":
+    main()