omnibase-mcp 0.1.26 → 0.1.30

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## [0.1.30](https://github.com/itsJeremyMax/omnibase/compare/omnibase-mcp-v0.1.29...omnibase-mcp-v0.1.30) (2026-04-08)
+
+
+### Bug Fixes
+
+* use DEB822 format for arm64 cross-compile apt sources on Ubuntu 24.04 ([cb87ce1](https://github.com/itsJeremyMax/omnibase/commit/cb87ce1e0bf64874ab6b378034ce5e3d0f0e8790))
+
+## [0.1.29](https://github.com/itsJeremyMax/omnibase/compare/omnibase-mcp-v0.1.28...omnibase-mcp-v0.1.29) (2026-04-08)
+
+
+### Bug Fixes
+
+* remove malformed Microsoft apt source before arm64 cross-compile, downgrade @types/node to ^22 ([2148c44](https://github.com/itsJeremyMax/omnibase/commit/2148c4486e379225b0b8370df9145091965a01d5))
+* set CGO include paths for unixodbc on macOS Apple Silicon ([ab1a54c](https://github.com/itsJeremyMax/omnibase/commit/ab1a54cbf40ae044094e8b92031b3b261abd78a6))
+
+## [0.1.28](https://github.com/itsJeremyMax/omnibase/compare/omnibase-mcp-v0.1.27...omnibase-mcp-v0.1.28) (2026-04-08)
+
+
+### Features
+
+* add omnibase logo and banner ([f307f34](https://github.com/itsJeremyMax/omnibase/commit/f307f34be387883df6e0c24c722412d08b69c467))
+
+
+### Bug Fixes
+
+* install unixodbc-dev headers for ODBC driver builds in CI ([0402b0d](https://github.com/itsJeremyMax/omnibase/commit/0402b0da1d04e6c1601cbc19aed4ea09782bd3bf))
+* relax get_table_stats assertion for MySQL, update dependencies ([f0fe54b](https://github.com/itsJeremyMax/omnibase/commit/f0fe54ba93c043399b18c2c09fcbdae29c30fd61))
+* sidecar version file path, 10 bug fixes, README redesign, integration tests ([054cefd](https://github.com/itsJeremyMax/omnibase/commit/054cefd1d01a9d50d5d47e0f12b3a1eb025910cc))
+* sync package.json version ranges with lockfile ([ee75a54](https://github.com/itsJeremyMax/omnibase/commit/ee75a5426a724c25cf2420d51017e44d79ac35c8))
+
+## [0.1.27](https://github.com/itsJeremyMax/omnibase/compare/omnibase-mcp-v0.1.26...omnibase-mcp-v0.1.27) (2026-04-02)
+
+
+### Features
+
+* add reviewer-suggested MCP tool enhancements ([b2d948d](https://github.com/itsJeremyMax/omnibase/commit/b2d948d920d31cc7b5808d89da0166b42e5fc0a0))
+* dynamic driver plugin architecture ([a9786d3](https://github.com/itsJeremyMax/omnibase/commit/a9786d3ae1bea9ccf3f8729ca1bd62cb522a82f2))
+
+
+### Bug Fixes
+
+* add --help flag and error on unknown CLI commands ([c9fc15c](https://github.com/itsJeremyMax/omnibase/commit/c9fc15c5172e4ea03acc30630bee41fbe3f8cf3f))
+* decouple release pipeline from release-please output ([c442629](https://github.com/itsJeremyMax/omnibase/commit/c4426294cff06ec2ad3c3df88077881e32afa894))
+* harden driver system with audit fixes, checksum verification, and bug fixes ([c39b1f8](https://github.com/itsJeremyMax/omnibase/commit/c39b1f8ee1b4744dec9559958cb29465e1a42392))
+* update go base image to 1.26 to match sidecar go.mod requirement ([#37](https://github.com/itsJeremyMax/omnibase/issues/37)) ([b56603a](https://github.com/itsJeremyMax/omnibase/commit/b56603aaf21ce634e4e4ad2300c135fcf31047fc))
+
 ## [0.1.26](https://github.com/itsJeremyMax/omnibase/compare/omnibase-mcp-v0.1.25...omnibase-mcp-v0.1.26) (2026-03-31)
 
 

package/README.md

@@ -1,19 +1,12 @@
-# Omnibase
+<p align="center">
+  <img src="assets/banner.svg" alt="Omnibase" width="100%" />
+</p>
 
-Give your AI agent secure access to any database. PostgreSQL, MySQL, SQLite, and [50+ more](https://github.com/xo/usql) through a single MCP server. Works with Claude Code, OpenCode, GitHub Copilot, Cursor, and any MCP-compatible client.
+Give your AI agent secure access to every database. PostgreSQL, MySQL, SQLite, ClickHouse, SQL Server, and [50+ more](https://github.com/xo/usql) through a single MCP server. Works with Claude Code, OpenCode, GitHub Copilot, Cursor, and any MCP-compatible client.
 
-```yaml
-# omnibase.config.yaml — all options: https://github.com/itsJeremyMax/omnibase#configuration-reference
-connections:
-  prod:
-    dsn: $DATABASE_URL     # credentials stay in your environment
-    permission: read-only   # read-only | read-write | admin
-```
-
-```
-You: "What tables have the most NULL values?"
-Agent: [calls get_table_stats] → shows null percentages per column across all tables
-```
+- **One server, every database.** Connect Postgres, MySQL, ClickHouse, and SQL Server side by side. Your agent picks the right one.
+- **Secure by default.** Read-only permissions, query classification, credential isolation. Agents get guardrails, not footguns.
+- **Shareable config.** One YAML file defines connections, permissions, and custom tools. Commit it, and your whole team gets the same agent capabilities.
 
 ## Get Started
 
@@ -47,18 +40,22 @@ Add to your MCP config (`.mcp.json`):
 npx omnibase-mcp init
 ```
 
-Edit `omnibase.config.yaml` with your database connection ([all options](#configuration-reference), [more examples](examples/)):
+Edit `omnibase.config.yaml` with your database connections ([full configuration guide](docs/configuration.md)):
 
 ```yaml
 connections:
-  my-db:
-    dsn: "pg://myuser:mypassword@localhost:5432/mydb"
+  app:
+    dsn: pg://localhost:5432/myapp    # or $DATABASE_URL from env
     permission: read-write
+  analytics:
+    dsn: clickhouse://localhost:9000/analytics
+    permission: read-write
+  warehouse:
+    dsn: mysql://user:pass@localhost:3306/warehouse
+    permission: read-only
 ```
 
-DSNs starting with `$` resolve from environment variables (e.g. `dsn: $DATABASE_URL`).
-
-That's it. Your agent now has access to 13 database tools, plus any [custom tools](#custom-tools) you define.
+That's it. Your agent now has access to 14 database tools, plus any [custom tools](docs/custom-tools.md) you define.
 
 <details>
 <summary>Install from source (contributors)</summary>
@@ -67,21 +64,129 @@ That's it. Your agent now has access to 13 database tools, plus any [custom tool
 git clone https://github.com/itsJeremyMax/omnibase.git
 cd omnibase
 pnpm install
-pnpm run build
+pnpm build
 ```
 
 Then point your MCP client at `node dist/src/index.js` with `cwd` set to your project directory.
 
 </details>
 
-## What Your Agent Gets
+## What Your Agent Can Do
+
+### Understand any codebase's data model in seconds
+
+```
+You: "I just joined this project. Walk me through the data model."
+```
+
+Your agent connects to `app`, `analytics`, and `warehouse`, discovers tables across all three, traces foreign key relationships, and returns a complete summary: table names, column types, row counts, and how everything connects. What used to take hours of reading migration files takes seconds.
+
+*Tools used: list_connections, list_tables, get_schema, get_relationships*
+
+<details>
+<summary>What you'd do manually</summary>
+
+```sql
+-- Connect to each database separately, then run:
+
+-- app (Postgres)
+SELECT table_name FROM information_schema.tables WHERE table_schema = 'public';
+SELECT column_name, data_type, is_nullable FROM information_schema.columns WHERE table_name = '...';
+SELECT tc.table_name, kcu.column_name, ccu.table_name AS foreign_table
+  FROM information_schema.table_constraints tc
+  JOIN information_schema.key_column_usage kcu ON tc.constraint_name = kcu.constraint_name
+  JOIN information_schema.constraint_column_usage ccu ON tc.constraint_name = ccu.constraint_name
+  WHERE tc.constraint_type = 'FOREIGN KEY';
+SELECT schemaname, relname, n_live_tup FROM pg_stat_user_tables;
+
+-- analytics (ClickHouse — different syntax)
+SELECT name FROM system.tables WHERE database = currentDatabase();
+SELECT name, type, is_in_primary_key FROM system.columns WHERE table = '...';
+-- ClickHouse doesn't have foreign keys, so no FK query available
+
+-- warehouse (MySQL — yet another syntax)
+SELECT table_name FROM information_schema.tables WHERE table_schema = DATABASE();
+SELECT column_name, data_type, is_nullable FROM information_schema.columns WHERE table_name = '...';
+SELECT table_name, column_name, referenced_table_name, referenced_column_name
+  FROM information_schema.key_column_usage WHERE referenced_table_name IS NOT NULL;
+
+-- Then manually stitch the results together across all three
+```
+
+</details>
+
+### Query across databases
+
+```
+You: "Compare our product inventory in warehouse with what customers
+      actually ordered last quarter in app. What's sitting on shelves?"
+```
+
+Your agent queries `warehouse` (MySQL) for current stock levels, pulls last quarter's order volumes from `app` (Postgres), and joins the results by SKU. It identifies 34 products with over 500 units in stock but fewer than 10 orders. You can't write a single query for this because the data lives in two different database engines.
+
+*Tools used: list_connections, get_schema, execute_sql (across app and warehouse)*
+
+<details>
+<summary>What you'd do manually</summary>
+
+```sql
+-- Terminal 1: warehouse (MySQL)
+SELECT sku, product_name, quantity_on_hand
+  FROM inventory
+  WHERE quantity_on_hand > 0;
+-- Copy results to a spreadsheet or temp file
+
+-- Terminal 2: app (Postgres)
+SELECT p.sku, SUM(oi.quantity) AS units_ordered
+  FROM order_items oi
+  JOIN products p ON oi.product_id = p.id
+  JOIN orders o ON oi.order_id = o.id
+  WHERE o.ordered_at >= NOW() - INTERVAL '3 months'
+  GROUP BY p.sku;
+-- Copy results to the same spreadsheet
+
+-- Manually match SKUs across both result sets
+-- Filter to high-stock, low-order items
+-- Reformat into something useful
+```
+
+</details>
+
+### Debug with live data
+
+```
+You: "The /api/orders endpoint is returning wrong totals. Figure out why."
+```
+
+Your agent reads the route handler, queries the orders table in `app`, then checks `analytics` and finds the pre-computed totals are out of sync. It traces the mismatch to a missing category, updates the analytics table, hits the endpoint again, and confirms the response is now correct.
+
+*Tools used: get_schema, execute_sql (across app and analytics)*
+
+### Investigate production issues safely
+
+```
+You: "Failed payments spiked 3x in the last hour. What's going on?"
+```
+
+Your agent explores the payments schema on `warehouse` (read-only), runs analytics on the last hour of transactions, and identifies that all failures share a single payment provider and error code. Not a single row modified. The connection is read-only, so the agent couldn't write even if it tried.
+
+*Tools used: get_schema, execute_sql (read-only on warehouse), get_distinct_values*
+
+[More use cases →](docs/use-cases.md)
+
+## Built-in Tools
+
+Your agent gets 14 tools out of the box, covering schema exploration, parameterized queries, and execution plan analysis.
+
+<details>
+<summary>All 14 tools</summary>
 
 ### Discover
 
 | Tool | What it does |
 |------|-------------|
 | `list_connections` | See all configured databases and their status |
-| `test_connection` | Ping a specific database — returns latency and driver error on failure |
+| `test_connection` | Ping a specific database. Returns latency and driver error on failure |
 | `list_tables` | Quick overview with row counts |
 | `get_schema` | Summary or detailed column/index/FK info |
 | `search_schema` | Find tables and columns by keyword |
@@ -115,225 +220,71 @@ Then point your MCP client at `node dist/src/index.js` with `cwd` set to your pr
 |------|-------------|
 | `query_history` | View recent query execution history with filtering by connection, status, and pagination |
 
-### Custom Tools
+</details>
+
+## Custom Tools
 
-Define your own MCP tools as SQL templates in your config. Custom tools are registered alongside built-in tools and go through the same security pipeline.
+Define SQL templates as MCP tools your whole team can use. Add them to your config and commit. Every agent on the project gets the same capabilities, no code required.
 
 ```yaml
 tools:
   get_active_users:
-    connection: my-db
+    connection: app
     description: "Get all active users"
     sql: "SELECT * FROM users WHERE active = true"
-    max_rows: 100
-
-  find_orders_by_status:
-    connection: my-db
-    description: "Find orders filtered by status"
-    permission: read-write
-    parameters:
-      status:
-        type: enum
-        description: "Order status"
-        values: [pending, shipped, delivered, cancelled]
-      min_amount:
-        type: number
-        description: "Minimum order amount"
-        required: false
-        default: 0
-    sql: >
-      SELECT * FROM orders
-      WHERE status = {status}
-        AND total >= {min_amount}
-```
-
-Custom tools are registered as `custom_<name>` (e.g., `custom_get_active_users`). Parameters use `{param_name}` placeholders that are substituted as parameterized queries (not string interpolation) to prevent SQL injection.
-
-**Auto-generated descriptions:** If you omit the `description` field, it will be derived from leading `-- ` comment lines in your SQL template.
-
-**Parameter types:** `string`, `number`, `boolean`, `enum`
-
-**Optional overrides per tool:** `permission`, `max_rows`, `timeout` (fall back to connection/default values)
-
-**Multi-statement tools:** Use `steps` instead of `sql` to run multiple statements within a transaction. Mark one step with `return: true` to control which result goes back to the agent (defaults to the last step). If any step fails, the entire transaction is rolled back.
-
-```yaml
-tools:
-  user_activity_report:
-    connection: my-db
-    description: "Generate user activity report"
-    parameters:
-      days:
-        type: number
-        description: "Days to look back"
-        required: false
-        default: 30
-    steps:
-      - sql: |
-          CREATE TEMP TABLE recent_activity AS
-          SELECT user_id, COUNT(*) as action_count
-          FROM events
-          WHERE created_at > datetime('now', '-' || {days} || ' days')
-          GROUP BY user_id
-      - sql: |
-          SELECT u.name, u.email, COALESCE(ra.action_count, 0) as actions
-          FROM users u
-          LEFT JOIN recent_activity ra ON ra.user_id = u.id
-          ORDER BY actions DESC
-        return: true
 ```
 
-**Tool composition:** Use `compose` to build pipelines where each step can call another custom tool or run inline SQL. Results from earlier steps are available to later steps via `{step_name.column}` references, which expand to comma-separated values.
+Chain tools together with `compose` to build multi-step pipelines:
 
 ```yaml
 tools:
-  get_active_user_ids:
-    connection: my-db
-    description: "Get active user IDs"
-    sql: "SELECT id FROM users WHERE active = true"
-
   active_user_orders:
-    connection: my-db
+    connection: app
     description: "Get orders for all active users"
     compose:
-      - tool: get_active_user_ids
+      - tool: get_active_users
         as: users
       - sql: "SELECT * FROM orders WHERE user_id IN ({users.id})"
         as: orders
 ```
 
-Steps run sequentially and the last step's result is returned. Tool-ref steps can pass arguments via `args`, and inline SQL steps can reference results from any prior step. Circular dependencies between composed tools are detected at validation time.
-
-**Hot reload:** The server watches your config file and reloads custom tools automatically when it changes. No restart needed.
-
-**CLI management:**
-
-```bash
-npx omnibase-mcp tools list       # list all custom tools
-npx omnibase-mcp tools add        # interactive wizard to add a tool
-npx omnibase-mcp tools remove     # interactive wizard to remove a tool
-npx omnibase-mcp tools validate   # validate custom tool definitions
-npx omnibase-mcp tools test       # dry-run a tool with sample arguments
-npx omnibase-mcp status           # ping all connections, show health dashboard
-npx omnibase-mcp audit tail       # live tail the query audit log
-npx omnibase-mcp audit search <q> # search audit log by keyword
-npx omnibase-mcp audit clear      # clear the audit log
-npx omnibase-mcp upgrade          # upgrade to latest version
-npx omnibase-mcp upgrade --dry-run          # check for updates and show changelog
-npx omnibase-mcp upgrade --version 0.1.20   # switch to a specific version
-npx omnibase-mcp upgrade --allow-major      # allow major version changes
-npx omnibase-mcp --version        # print current version
-```
-
-Updates to a new major version (or downgrades across a major version boundary) require the `--allow-major` flag. The CLI also checks for updates in the background and shows a notice after commands when a newer version is available. Set `NO_UPDATE_NOTIFIER=1` to suppress this.
-
-## What Makes This Different
-
-**Every query is inspected before it reaches your database.**
-
-Omnibase parses and classifies each SQL statement. A `DELETE FROM users` without a WHERE clause gets flagged. A `pg_read_file('/etc/passwd')` gets blocked. A `WITH x AS (UPDATE ...) SELECT ...` is correctly identified as a write, not a read.
-
-This isn't just read-only mode. It's:
-
-- **Dangerous function blocking** across all engines — `pg_read_file`, `xp_cmdshell`, `LOAD_FILE`, `lo_export`, and dozens more
-- **Sensitive table protection** — `pg_shadow`, `mysql.user`, `sys.sql_logins` are inaccessible, even with schema-qualified names
-- **Permission levels per connection** — read-only, read-write, admin. The agent's access is independent of the database user's privileges
-- **Schema-aware validation** — `validate_query` checks that tables and columns actually exist, resolves aliases, catches fake columns in INSERT lists, and warns about bulk operations
-- **Write impact estimation** — before running an UPDATE or DELETE, see how many rows would be affected
-- **Portable parameterized queries** — use `?` everywhere, Omnibase translates to `$1` (Postgres), `:1` (Oracle), `@p1` (SQL Server) automatically
+Custom tools live in `omnibase.config.yaml` alongside your connections. Commit it to your repo and your team shares the same tools, permissions, and database access.
 
-## Configuration Reference
+[Full custom tools guide →](docs/custom-tools.md)
 
-### DSN formats
+## Configuration
 
 | Database | DSN |
 |----------|-----|
-| SQLite | `sqlite:./path/to/db.db` |
 | PostgreSQL | `pg://user:pass@host:5432/dbname` |
-| MySQL | `my://user:pass@host:3306/dbname` |
+| MySQL | `mysql://user:pass@host:3306/dbname` |
+| ClickHouse | `clickhouse://host:9000/dbname` |
+| SQLite | `sqlite:./path/to/db.db` |
 | SQL Server | `mssql://user:pass@host/dbname` |
-| Oracle | `or://user:pass@host:1521/sid` |
-
-Any [usql-compatible DSN](https://github.com/xo/usql#database-support) works. DSNs starting with `$` resolve from environment variables.
-
-### Connection options
-
-```yaml
-connections:
-  my-db:
-    dsn: $DATABASE_URL          # required
-    permission: read-only       # read-only | read-write | admin (default: read-only)
-    timeout: 30000              # query timeout in ms (default: 30000)
-    max_rows: 500               # max rows returned per query (default: 500)
-    max_value_length: 500       # truncate column values longer than this (default: 500)
-    allow_all_pragmas: false    # allow all SQLite PRAGMAs (default: false)
-    read_only_tables:           # optional — protect specific tables from writes
-      - users
-      - audit_log
-    schema_filter:              # optional — limit visible schemas/tables
-      schemas: [public]
-
-# Optional — override built-in defaults
-defaults:
-  permission: read-only         # default permission for connections that don't specify one
-  timeout: 30000                # default query timeout in ms
-  max_rows: 500                 # default max rows returned per query
-```
-
-### Schema hints
-
-Omnibase embeds table and column names directly in tool descriptions so your AI agent sees the schema without needing to call `get_schema` first. This is enabled by default and updates automatically when a schema is fetched.
-
-```yaml
-schema_hints: true   # embed table/column names in tool descriptions (default: true)
-```
-
-### Audit logging
-
-Log every query to a local file for debugging and compliance. The `query_history` MCP tool lets agents view their own query history. By default, the last 10,000 entries are retained and older entries are automatically pruned.
-
-```yaml
-audit:
-  enabled: true
-  path: ./.omnibase/audit.log     # default: .omnibase/audit.log next to config file
-  format: jsonl                    # jsonl (default) or text
-  max_entries: 10000               # 0 = unlimited (default: 10000)
-```
 
-The audit log defaults to `.omnibase/audit.log` in the same directory as your config file, so each project gets its own log. By default, the last 10,000 entries are retained and older entries are automatically pruned.
+Any [usql-compatible DSN](https://github.com/xo/usql#database-support) works. [Full configuration guide →](docs/configuration.md)
 
-### Config discovery
+## Security
 
-1. `OMNIBASE_CONFIG` environment variable
-2. `./omnibase.config.yaml` in working directory
-3. `~/.config/omnibase/config.yaml`
+Every query is parsed and classified before it reaches your database. Your agent never sees credentials, can't run dangerous functions, and respects the permission level you set.
 
-### Permission levels
+- Credentials never reach agents. DSNs resolve server-side
+- Read-only by default. Explicit opt-in for writes
+- Dangerous functions blocked across all engines
+- Multi-statement queries rejected
+- Table names validated against schema cache
 
-| Level | SELECT | INSERT/UPDATE/DELETE | CREATE/ALTER/DROP |
-|-------|--------|---------------------|-------------------|
-| `read-only` | Yes | No | No |
-| `read-write` | Yes | Yes | No |
-| `admin` | Yes | Yes | Yes |
+[Security deep dive & architecture →](docs/security.md)
 
-## Architecture
+## CLI
 
-```
-MCP Client (Claude Code, OpenCode, GitHub Copilot, Cursor)
-        |  MCP Protocol (stdio)
-        v
-Omnibase MCP Server (TypeScript)
-  - Permission enforcement, query analysis, schema caching, output formatting
-        |  JSON-RPC over stdin/stdout
-        v
-Go Sidecar (usql driver packages)
-  - Native database connections, parameterized queries, schema introspection
-        |  Native drivers
-        v
-Any Database
+```bash
+npx omnibase-mcp status           # health dashboard
+npx omnibase-mcp tools list       # list custom tools
+npx omnibase-mcp upgrade          # upgrade to latest
 ```
 
-The TypeScript server handles agent-facing concerns. The Go sidecar handles database concerns. Adding a new database driver only requires changes in Go.
+[Full CLI reference →](docs/cli.md)
 
 ## Development
 
@@ -341,23 +292,13 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, testing, and conventions.
 
 ```bash
 pnpm test                          # unit tests
-pnpm run test:integration          # cross-database tests (needs Docker)
+pnpm test:integration              # cross-database tests (needs Docker)
 cd sidecar && go test ./... -v     # Go sidecar tests
 ```
 
-## Security
-
-- Credentials never reach agents — DSNs resolve server-side, agents see connection names only
-- Read-only by default — every connection requires explicit opt-in for writes
-- SQL parsed and classified before execution — unrecognized statements default to "write" (fail safe)
-- Multi-statement queries rejected — prevents `SELECT 1; DROP TABLE users`
-- Dangerous functions blocked — filesystem access, OS execution, credential exposure across all engines
-- Table names validated against schema cache — prevents SQL injection in tool parameters
-- Sidecar auto-recovery — if the Go process crashes, it respawns transparently on the next call
-
 ## License
 
-Apache 2.0 — see [LICENSE](LICENSE)
+Apache 2.0. See [LICENSE](LICENSE)
 
 ## Disclaimer