ajan-sql 0.1.2 → 0.1.3

package/README.md

@@ -36,8 +36,6 @@
 
 `ajan-sql` is an npm package for running an MCP server over stdio with a PostgreSQL backend.
 
-`ajan-sql` provides schema-aware, read-only PostgreSQL access for MCP and AI workflows.
-
 ## Goals
 
 - Safe, read-only database access for AI agents

package/dist/db/schema.js

@@ -18,10 +18,59 @@ async function listTables(pool) {
 }
 async function describeTable(pool, tableName, schemaName = "public") {
     const result = await pool.query(`
-      select column_name, data_type, is_nullable, column_default
-      from information_schema.columns
-      where table_schema = $1
-        and table_name = $2
+      select
+        c.column_name,
+        c.data_type,
+        c.is_nullable,
+        c.column_default,
+        exists (
+          select 1
+          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
+          where tc.constraint_type = 'PRIMARY KEY'
+            and tc.table_schema = c.table_schema
+            and tc.table_name = c.table_name
+            and kcu.column_name = c.column_name
+        ) as is_primary_key,
+        exists (
+          select 1
+          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
+          where tc.constraint_type in ('PRIMARY KEY', 'UNIQUE')
+            and tc.table_schema = c.table_schema
+            and tc.table_name = c.table_name
+            and kcu.column_name = c.column_name
+        ) as is_unique,
+        fk.target_schema as referenced_schema,
+        fk.target_table as referenced_table,
+        fk.target_column as referenced_column
+      from information_schema.columns c
+      left join (
+        select
+          tc.table_schema as source_schema,
+          tc.table_name as source_table,
+          kcu.column_name as source_column,
+          ccu.table_schema as target_schema,
+          ccu.table_name as target_table,
+          ccu.column_name as target_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'
+      ) fk
+        on fk.source_schema = c.table_schema
+       and fk.source_table = c.table_name
+       and fk.source_column = c.column_name
+      where c.table_schema = $1
+        and c.table_name = $2
       order by ordinal_position
     `, [schemaName, tableName]);
     if (result.rows.length === 0) {
@@ -35,6 +84,15 @@ async function describeTable(pool, tableName, schemaName = "public") {
             dataType: row.data_type,
             isNullable: row.is_nullable === "YES",
             defaultValue: row.column_default,
+            isPrimaryKey: row.is_primary_key,
+            isUnique: row.is_unique,
+            references: row.referenced_schema && row.referenced_table && row.referenced_column
+                ? {
+                    schema: row.referenced_schema,
+                    table: row.referenced_table,
+                    column: row.referenced_column,
+                }
+                : null,
         })),
     };
 }

package/dist/query-runner/index.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.runReadonlyQuery = runReadonlyQuery;
 exports.explainReadonlyQuery = explainReadonlyQuery;
 exports.sampleRows = sampleRows;
+const schema_1 = require("../db/schema");
 const guard_1 = require("../guard");
 async function runReadonlyQuery(pool, sql, options = {}) {
     const guarded = (0, guard_1.guardReadonlyQuery)(sql, options);
@@ -12,6 +13,8 @@ async function runReadonlyQuery(pool, sql, options = {}) {
     return {
         sql: guarded.sql,
         rowCount: result.rows.length,
+        durationMs: result.durationMs,
+        columns: result.fields.map(toQueryColumn),
         rows: result.rows,
     };
 }
@@ -22,27 +25,54 @@ async function explainReadonlyQuery(pool, sql) {
     const plan = result.rows[0]?.["QUERY PLAN"];
     return {
         sql: guarded.sql,
+        durationMs: result.durationMs,
+        summary: summarizeExplainPlan(plan),
         plan,
     };
 }
-async function sampleRows(pool, tableName, schemaName = "public", limit = 10) {
+async function sampleRows(pool, tableName, schemaName = "public", limit = 10, columns) {
     const defaults = (0, guard_1.getReadonlyDefaults)();
     const safeLimit = Math.min(limit, defaults.maxLimit);
+    const description = await (0, schema_1.describeTable)(pool, tableName, schemaName);
+    if (!description) {
+        throw new Error(`Table not found: ${schemaName}.${tableName}`);
+    }
+    const availableColumns = new Set(description.columns.map((column) => column.name));
+    const selectedColumns = columns && columns.length > 0
+        ? columns.map((column) => {
+            if (!availableColumns.has(column)) {
+                throw new Error(`Unknown column for sample_rows: ${column}`);
+            }
+            return (0, guard_1.quoteIdentifier)(column);
+        })
+        : ["*"];
+    const primaryKeyColumns = description.columns
+        .filter((column) => column.isPrimaryKey)
+        .map((column) => (0, guard_1.quoteIdentifier)(column.name));
     const sql = [
-        "SELECT *",
+        `SELECT ${selectedColumns.join(", ")}`,
         `FROM ${(0, guard_1.quoteIdentifier)(schemaName)}.${(0, guard_1.quoteIdentifier)(tableName)}`,
+        primaryKeyColumns.length > 0
+            ? `ORDER BY ${primaryKeyColumns.join(", ")}`
+            : "",
         `LIMIT ${safeLimit}`,
-    ].join(" ");
+    ]
+        .filter(Boolean)
+        .join(" ");
     return runReadonlyQuery(pool, sql, { defaultLimit: safeLimit });
 }
 async function executeWithReadonlySettings(pool, sql, timeoutMs) {
     const client = await pool.connect();
+    const startedAt = Date.now();
     try {
         await client.query("BEGIN");
         await client.query(`SET LOCAL statement_timeout = '${timeoutMs}ms'`);
         const result = await client.query(sql);
         await client.query("ROLLBACK");
-        return result;
+        return {
+            ...result,
+            durationMs: Date.now() - startedAt,
+        };
     }
     catch (error) {
         await client.query("ROLLBACK").catch(() => undefined);
@@ -52,6 +82,37 @@ async function executeWithReadonlySettings(pool, sql, timeoutMs) {
         client.release();
     }
 }
+function toQueryColumn(field) {
+    return {
+        name: field.name,
+        dataTypeId: field.dataTypeID,
+    };
+}
+function summarizeExplainPlan(plan) {
+    if (!Array.isArray(plan) || plan.length === 0) {
+        return null;
+    }
+    const root = plan[0];
+    const rootPlan = root?.Plan;
+    if (!rootPlan || typeof rootPlan !== "object") {
+        return null;
+    }
+    const childPlans = Array.isArray(rootPlan.Plans) ? rootPlan.Plans : [];
+    return {
+        nodeType: getStringField(rootPlan, "Node Type"),
+        relationName: getStringField(rootPlan, "Relation Name"),
+        planRows: getNumberField(rootPlan, "Plan Rows"),
+        startupCost: getNumberField(rootPlan, "Startup Cost"),
+        totalCost: getNumberField(rootPlan, "Total Cost"),
+        childCount: childPlans.length,
+    };
+}
+function getStringField(plan, key) {
+    return typeof plan[key] === "string" ? plan[key] : null;
+}
+function getNumberField(plan, key) {
+    return typeof plan[key] === "number" ? plan[key] : null;
+}
 function assertRowCount(rowCount, limit) {
     if (rowCount > limit) {
         throw new Error(`Query returned more rows than allowed limit of ${limit}`);

package/dist/tools/schema-tools.js

@@ -14,13 +14,24 @@ function asTextResult(data) {
         ],
     };
 }
+function asStructuredResult(summary, data) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: summary,
+            },
+        ],
+        structuredContent: data,
+    };
+}
 function registerSchemaTools(server, deps) {
     const registerTool = server.registerTool.bind(server);
     registerTool("list_tables", {
         description: "Return all tables in the database.",
     }, async () => {
         const tables = await (0, schema_1.listTables)(deps.pool);
-        return asTextResult(tables);
+        return asStructuredResult(`Listed ${tables.length} tables.`, tables);
     });
     registerTool("describe_table", {
         description: "Return columns and types for a given table.",
@@ -34,13 +45,13 @@ function registerSchemaTools(server, deps) {
         if (!description) {
             throw new Error(`Table not found: ${resolvedSchema}.${name}`);
         }
-        return asTextResult(description);
+        return asStructuredResult(`Described table ${resolvedSchema}.${name} with ${description.columns.length} columns.`, description);
     });
     registerTool("list_relationships", {
         description: "Return foreign key relationships.",
     }, async () => {
         const relationships = await (0, schema_1.listRelationships)(deps.pool);
-        return asTextResult(relationships);
+        return asStructuredResult(`Listed ${relationships.length} foreign key relationships.`, relationships);
     });
     registerTool("run_readonly_query", {
         description: "Execute a safe SELECT query.",
@@ -49,7 +60,7 @@ function registerSchemaTools(server, deps) {
         },
     }, async ({ sql }) => {
         const result = await (0, query_runner_1.runReadonlyQuery)(deps.pool, sql);
-        return asTextResult(result);
+        return asStructuredResult(`Query returned ${result.rowCount} rows in ${result.durationMs}ms.`, result);
     });
     registerTool("explain_query", {
         description: "Return query execution plan.",
@@ -58,7 +69,8 @@ function registerSchemaTools(server, deps) {
         },
     }, async ({ sql }) => {
         const result = await (0, query_runner_1.explainReadonlyQuery)(deps.pool, sql);
-        return asTextResult(result);
+        const rootNode = result.summary?.nodeType ?? "unknown";
+        return asStructuredResult(`Explain plan generated in ${result.durationMs}ms. Root node: ${rootNode}.`, result);
     });
     registerTool("sample_rows", {
         description: "Return example rows from a table.",
@@ -66,9 +78,10 @@ function registerSchemaTools(server, deps) {
             name: zod_1.z.string().min(1),
             schema: zod_1.z.string().min(1).optional(),
             limit: zod_1.z.number().int().positive().max(100).optional(),
+            columns: zod_1.z.array(zod_1.z.string().min(1)).optional(),
         },
-    }, async ({ name, schema, limit }) => {
-        const result = await (0, query_runner_1.sampleRows)(deps.pool, name, schema ?? "public", limit ?? 10);
-        return asTextResult(result);
+    }, async ({ name, schema, limit, columns }) => {
+        const result = await (0, query_runner_1.sampleRows)(deps.pool, name, schema ?? "public", limit ?? 10, columns);
+        return asStructuredResult(`Sampled ${result.rowCount} rows from ${(schema ?? "public")}.${name} in ${result.durationMs}ms.`, result);
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ajan-sql",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "AI-safe MCP server for schema-aware, read-only SQL access.",
   "bin": {
     "ajan-sql": "dist/index.js"