feat(mcp): altimate-code mcp serve exposes data tools to MCP clients without an LLM

.github/workflows/ci.yml

@@ -87,6 +87,20 @@ jobs:
               - '.github/workflows/ci.yml'
             # altimate_change end
             drivers:
+              # altimate_change start — run real MCP drivers for MCP/tool-only changes
+              - 'packages/opencode/src/altimate/mcp-server/**'
+              - 'packages/opencode/test/altimate/mcp-server/**'
+              - 'packages/opencode/src/altimate/tools/schema-inspect.ts'
+              - 'packages/opencode/src/altimate/tools/schema-values.ts'
+              # The tools the MCP server exposes; server.test.ts is their only real-driver run.
+              - 'packages/opencode/src/altimate/tools/warehouse-list.ts'
+              - 'packages/opencode/src/altimate/tools/warehouse-add.ts'
+              - 'packages/opencode/src/altimate/tools/sql-execute.ts'
+              - 'packages/opencode/src/altimate/tools/sql-check.ts'
+              - 'packages/opencode/src/altimate/tools/sql-materialize.ts'
+              - 'packages/opencode/src/altimate/tools/answer-commit*.ts'
+              - 'packages/opencode/src/tool/truncate.ts'
+              # altimate_change end
               - 'packages/drivers/src/**'
               - 'packages/opencode/src/altimate/native/connections/**'
               - 'packages/opencode/test/altimate/drivers-e2e.test.ts'
@@ -512,6 +526,14 @@ jobs:
         env:
           ALTIMATE_DUCKDB_E2E: "1"
 
+      # Same reason as above: the in-process MCP server tests use real SQLite/DuckDB drivers, which the
+      # whole-package run replaces with module mocks, so they run in their own process.
+      - name: Run MCP server tests (real drivers, no mocks)
+        run: bun test --timeout 90000 test/altimate/mcp-server/server.test.ts
+        working-directory: packages/opencode
+        env:
+          ALTIMATE_MCP_E2E: "1"
+
       - name: Run Docker driver E2E (MySQL, SQL Server, Redshift)
         run: bun test test/altimate/drivers-docker-e2e.test.ts
         working-directory: packages/opencode

docs/docs/configure/mcp-servers.md

@@ -6,6 +6,43 @@ description: "Configure Model Context Protocol (MCP) servers in Altimate Code to
 
 altimate supports the Model Context Protocol (MCP) for connecting to external tool servers.
 
+## Use Altimate Code tools from another MCP client
+
+Run `altimate-code mcp serve` to expose data tools over stdio. Your MCP client's model handles reasoning; this server runs tools directly without calling a model.
+
+Add this entry to your MCP client's configuration (for example, Claude Code's `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "altimate-code": {
+      "command": "altimate-code",
+      "args": ["mcp", "serve", "--connections", "/absolute/path/to/connections.json"]
+    }
+  }
+}
+```
+
+By default the server exposes `warehouse_list`, `warehouse_add`, `sql_execute`, `sql_materialize` and `answer_commit`. Pass `tables` to `sql_execute` to get those tables' columns and value profiles in the same call as its queries. Start with `--all-tools` to also expose `schema_inspect` and `sql_check`. Without `--connections`, the server reads the usual connection sources and re-reads them while none are configured, so a connections file written mid-session, or a connection added with `warehouse_add`, is picked up without a restart. A connections file is a JSON object keyed by connection name:
+
+```json
+{
+  "local": { "type": "sqlite", "path": "./analytics.sqlite" }
+}
+```
+
+Relative database paths resolve beside this file. With `--connections`, this file is the only source of connections: global and project `connections.json` files and `ALTIMATE_CODE_CONN_*` overrides are ignored. Omit `--connections` to use normal connection discovery: global and project `.altimate-code/connections.json` files, followed by `ALTIMATE_CODE_CONN_*` environment overrides. Set your client's working directory to the project when using project discovery.
+
+At startup the server lists each connection's name and type in its instructions, read from configuration only: it does not connect to remote or server databases or run queries on them. For local SQLite and DuckDB files (not behind an SSH tunnel) it also lists table names from one catalog query (no row counts); a file with more than 40 tables is noted as such instead. Call `warehouse_list` for columns and sample rows. Listing tools use catalog row estimates where available (including DuckDB); SQLite listings omit row counts. They never count rows by scanning each table.
+
+<!-- altimate_change start — MCP read-only limits and private output lifecycle -->
+
+Source writes are refused by default. Without `--allow-write`, source queries request database-enforced read-only execution on PostgreSQL, SQLite and DuckDB. For other connection types, read-only is enforced by SQL classification only; stored functions with side effects are not blocked — use a read-only database user. The server prints this caveat on stderr at startup and includes it in `warehouse_list` for each affected connection. Add `--allow-write` to enable SQL write permissions; existing hard safety blocks still apply. `sql_materialize` always requires a read-only source query and writes only into the server session's temporary `scratch` warehouse. Scratch tables disappear when the server exits. Large results may include a local spill file path that your client can open with any file reader. Spill files use a private directory and are deleted when the server exits. Local `tool_output.max_lines` and `tool_output.max_bytes` settings control output limits; remote agent configuration is not loaded.
+
+<!-- altimate_change end -->
+
+The server writes only MCP protocol messages to stdout and sends logs to stderr. It does not initialize telemetry and honors `ALTIMATE_TELEMETRY_DISABLED`.
+
 ## Local MCP Servers
 
 Run an MCP server as a local subprocess:

packages/drivers/src/mongodb.ts

@@ -42,6 +42,9 @@ type MqlCommand =
   | "dropCollection"
   | "createIndex"
   | "listIndexes"
+  // altimate_change start — scalar database catalog counts
+  | "dbStats"
+  // altimate_change end
   | "listCollections"
   | "ping"
 
@@ -514,7 +517,7 @@ export async function connect(config: ConnectionConfig): Promise<Connector> {
       maxResultBytes?: number,
       signal?: AbortSignal,
     ): Promise<ConnectorResult> {
-      async function readCursor(cursor: any): Promise<Record<string, unknown>[]> {
+      async function readCursor(cursor: any, rowLimit?: number): Promise<Record<string, unknown>[]> {
         const consume = createResultByteBudget(maxResultBytes)
         let stopped = false
         let failure: unknown
@@ -539,7 +542,7 @@ export async function connect(config: ConnectionConfig): Promise<Connector> {
           })
           const read = async () => {
             if (stopped) throw failure
-            if (maxResultBytes === undefined && maxTimeMS === undefined && !signal) return cursor.toArray()
+            if (rowLimit === undefined && maxResultBytes === undefined && maxTimeMS === undefined && !signal) return cursor.toArray()
             // One document per round trip made a 127k-document read take ~10 minutes. A reply
             // batch is still bounded (a server reply never exceeds 16 MiB) and the byte budget
             // stops the read at the first document past the cap.
@@ -548,6 +551,7 @@ export async function connect(config: ConnectionConfig): Promise<Connector> {
               if (stopped) throw failure
               if (maxResultBytes === undefined) {
                 docs.push(doc)
+                if (rowLimit !== undefined && docs.length >= rowLimit) break
                 continue
               }
               const serialized = Object.fromEntries(
@@ -605,17 +609,20 @@ export async function connect(config: ConnectionConfig): Promise<Connector> {
         return { columns: ["ok"], rows: [[result.ok]], row_count: 1, truncated: false }
       }
 
+      // altimate_change start — catalog discovery consumes only a bounded cursor, never the metadata cache
+      if (cmd === "dbStats") {
+        const stats = await db.command({ dbStats: 1, ...withMaxTime(maxTimeMS) })
+        return { columns: ["collections"], rows: [[stats.collections]], row_count: 1, truncated: false }
+      }
       if (cmd === "listCollections") {
-        const collections = await readCollections(db, maxTimeMS)
-        const matches = parsed.filter
-          ? await db.listCollections(parsed.filter, {
-            nameOnly: true, authorizedCollections: true, ...withMaxTime(maxTimeMS),
-          }).toArray()
-          : collections
+        const matches = await readCursor(db.listCollections(parsed.filter ?? {}, {
+          nameOnly: true, authorizedCollections: true, batchSize: Math.min(effectiveLimit + 1, 501), ...withMaxTime(maxTimeMS),
+        }), effectiveLimit + 1)
         const rows = matches.slice(0, effectiveLimit)
-          .map((collection: { name: string; type: string }) => [collection.name, collection.type])
+          .map((collection) => [collection.name, collection.type])
         return { columns: ["name", "type"], rows, row_count: rows.length, truncated: matches.length > effectiveLimit }
       }
+      // altimate_change end
 
       if (!MONGO_COLLECTION_READS.has(cmd)) clearMetadata()
 

packages/drivers/test/mongodb-catalog-bounds.test.ts

@@ -0,0 +1,74 @@
+// altimate_change start — schema discovery never materializes all collection metadata
+import { expect, mock, test } from "bun:test"
+import { connect } from "../src/mongodb"
+import { restoreModuleMocksAfterTests } from "./module-mock"
+
+await restoreModuleMocksAfterTests("mongodb")
+
+test("two million MongoDB collections stop at 501 and close the cursor", async () => {
+  let fetched = 0
+  let closed = 0
+  const options: unknown[] = []
+  const commands: unknown[] = []
+  mock.module("mongodb", () => ({
+    default: {
+      MongoClient: class {
+        async connect() {}
+        async close() {}
+        db() {
+          return {
+            databaseName: "large",
+            command: async (command: unknown) => {
+              commands.push(command)
+              return { collections: 2_000_000 }
+            },
+            listCollections: (_filter: unknown, opts: unknown) => {
+              options.push(opts)
+              return {
+                async toArray() {
+                  throw new Error("unbounded collection fetch")
+                },
+                async close() {
+                  closed++
+                },
+                async *[Symbol.asyncIterator]() {
+                  for (let i = 0; i < 2_000_000; i++) {
+                    fetched++
+                    yield { name: `c${i}`, type: "collection" }
+                  }
+                },
+              }
+            },
+          }
+        }
+      },
+    },
+  }))
+  const connector = await connect({ type: "mongodb" })
+  await connector.connect()
+  try {
+    const start = performance.now()
+    const result = await connector.execute(
+      JSON.stringify({ command: "listCollections", database: "large" }),
+      500,
+      undefined,
+      { readOnly: true, queryTimeoutMs: 1000 },
+    )
+    expect(result.rows).toHaveLength(500)
+    expect(result.truncated).toBe(true)
+    expect(fetched).toBe(501)
+    expect(closed).toBe(1)
+    expect(performance.now() - start).toBeLessThan(1000)
+    expect(options[0]).toMatchObject({ nameOnly: true, authorizedCollections: true, batchSize: 501, maxTimeMS: 1000 })
+    const counts = await connector.execute(JSON.stringify({ command: "dbStats", database: "large" }), 1, undefined, {
+      readOnly: true,
+      queryTimeoutMs: 1000,
+    })
+    expect(counts.rows).toEqual([[2_000_000]])
+    expect(fetched).toBe(501)
+    expect(commands).toEqual([{ dbStats: 1, maxTimeMS: 1000 }])
+  } finally {
+    await connector.close()
+  }
+})
+// altimate_change end

packages/drivers/test/mongodb-unit.test.ts

@@ -37,15 +37,22 @@ async function fakeMongo(
                 return { databases: Object.keys(collections).map((name) => ({ name })) }
               },
             }),
-            listCollections: (filter: { name?: string }, options: unknown) => ({
-              toArray: async () => {
+            // altimate_change start — model listCollections as a cursor, including bounded consumption
+            listCollections: (filter: { name?: string }, options: unknown) => {
+              const rows = () => {
                 collectionLists.push({ database, options })
                 if (metadata.error) throw metadata.error
                 return (collections[database] ?? [])
                   .filter((name) => !filter.name || name === filter.name)
                   .map((name) => ({ name, type: "collection" }))
-              },
-            }),
+              }
+              return {
+                toArray: async () => rows(),
+                async *[Symbol.asyncIterator]() { yield* rows() },
+                async close() {},
+              }
+            },
+            // altimate_change end
             createCollection: async (name: string) => {
               collections[database] ??= []
               collections[database].push(name)
@@ -174,7 +181,9 @@ describe("MongoDB read namespace validation", () => {
     expect(await connector.execute(JSON.stringify({ command: "listCollections", database: "archive" }))).toEqual({
       columns: ["name", "type"], rows: [], row_count: 0, truncated: false,
     })
-    expect(databaseLists).toEqual([{ nameOnly: true, authorizedDatabases: true, maxTimeMS: 120_000 }])
+    // altimate_change start — an empty bounded cursor needs no unbounded metadata validation
+    expect(databaseLists).toEqual([])
+    // altimate_change end
   })
 
   test("metadata failures cannot become an empty read", async () => {