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

.github/workflows/ci.yml

@@ -87,6 +87,12 @@ 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'
+              # altimate_change end
               - 'packages/drivers/src/**'
               - 'packages/opencode/src/altimate/native/connections/**'
               - 'packages/opencode/test/altimate/drivers-e2e.test.ts'
@@ -512,6 +518,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,41 @@ 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"]
+    }
+  }
+}
+```
+
+The server exposes exactly `warehouse_list`, `schema_inspect`, `sql_execute`, `sql_check`, and `sql_materialize`. 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.
+
+<!-- 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 () => {