ajan-sql 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bora Kilicoglu
+
+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.

package/README.md

@@ -0,0 +1,121 @@
+# ajan-sql
+
+AI-safe MCP server for schema-aware, read-only SQL access.
+
+## Overview
+
+`ajan-sql` is an npm package for running an MCP server over stdio with a PostgreSQL backend.
+
+The project is designed as:
+
+> psql + schema awareness + AI-safe guard layer
+
+## Goals
+
+- Safe, read-only database access for AI agents
+- Schema inspection and table discovery
+- Reliable PostgreSQL query execution with strict guardrails
+- Simple, maintainable implementation
+
+## Tech Stack
+
+- Node.js
+- TypeScript
+- MCP TypeScript SDK v1.x
+- PostgreSQL via `pg`
+
+## Security Model
+
+All executed queries must follow these rules:
+
+- `SELECT` only
+- Reject `INSERT`
+- Reject `UPDATE`
+- Reject `DELETE`
+- Reject `DROP`
+- Reject `ALTER`
+- Reject `TRUNCATE`
+- Enforce `LIMIT` with a default of `100`
+- Enforce query timeout with a maximum of `5` seconds
+- Enforce maximum result size
+- Reject multi-statement SQL
+- Reject SQL comments
+
+These rules should never be bypassed.
+
+## Available MCP Tools
+
+- `list_tables`
+- `describe_table`
+- `list_relationships`
+- `run_readonly_query`
+- `explain_query`
+- `sample_rows`
+
+## Available MCP Resources
+
+- `schema://snapshot`
+- `schema://table/{name}`
+
+## Local Usage
+
+Start the server with a PostgreSQL connection string:
+
+```bash
+DATABASE_URL=postgres://USER:PASSWORD@HOST:PORT/DB npm run dev
+```
+
+Or build and run the compiled server:
+
+```bash
+npm run build
+DATABASE_URL=postgres://USER:PASSWORD@HOST:PORT/DB npm start
+```
+
+## Client Configuration
+
+For MCP clients that launch local stdio servers, point the command to the built CLI and provide `DATABASE_URL`:
+
+```json
+{
+  "mcpServers": {
+    "ajan-sql": {
+      "command": "node",
+      "args": ["/absolute/path/to/ajan-sql/dist/index.js"],
+      "env": {
+        "DATABASE_URL": "postgres://USER:PASSWORD@HOST:PORT/DB"
+      }
+    }
+  }
+}
+```
+
+## Integration Testing
+
+The repository supports local PostgreSQL integration testing during development, but any Docker compose files or seeded local test databases can remain untracked and machine-local.
+
+## Development Principles
+
+- Keep functions small and composable
+- Avoid side effects
+- Route all DB logic through `db/`
+- Route all query execution through `query-runner`
+- Route all validation through `guard`
+- Prefer simple working code over abstraction
+- Prioritize correctness, safety, and clarity
+
+## CLI Behavior
+
+The CLI will:
+
+- Start the MCP server over stdio
+- Read `DATABASE_URL` from the environment
+- Fail fast if `DATABASE_URL` is missing
+
+## Status
+
+Early development. Schema inspection, readonly query execution, query explain, and sample row tools are implemented. The CLI is publish-ready for npm packaging, and current package version is `0.1.0`.
+
+## License
+
+MIT

package/dist/config.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRequiredEnv = getRequiredEnv;
+exports.getAppConfig = getAppConfig;
+const DEFAULT_DB_POOL_MAX = 10;
+function getRequiredEnv(name) {
+    const value = process.env[name]?.trim();
+    if (!value) {
+        throw new Error(`Missing required environment variable: ${name}`);
+    }
+    return value;
+}
+function getAppConfig() {
+    return {
+        databaseUrl: getRequiredEnv("DATABASE_URL"),
+        dbPoolMax: DEFAULT_DB_POOL_MAX,
+    };
+}

package/dist/db/pool.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDbPool = createDbPool;
+exports.closeDbPool = closeDbPool;
+const pg_1 = require("pg");
+function createDbPool(options) {
+    return new pg_1.Pool({
+        connectionString: options.connectionString,
+        max: options.max,
+    });
+}
+async function closeDbPool(pool) {
+    await pool.end();
+}

package/dist/db/schema.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listTables = listTables;
+exports.describeTable = describeTable;
+exports.listRelationships = listRelationships;
+async function listTables(pool) {
+    const result = await pool.query(`
+      select table_schema, table_name
+      from information_schema.tables
+      where table_type = 'BASE TABLE'
+        and table_schema not in ('information_schema', 'pg_catalog')
+      order by table_schema, table_name
+    `);
+    return result.rows.map((row) => ({
+        schema: row.table_schema,
+        name: row.table_name,
+    }));
+}
+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
+      order by ordinal_position
+    `, [schemaName, tableName]);
+    if (result.rows.length === 0) {
+        return null;
+    }
+    return {
+        schema: schemaName,
+        name: tableName,
+        columns: result.rows.map((row) => ({
+            name: row.column_name,
+            dataType: row.data_type,
+            isNullable: row.is_nullable === "YES",
+            defaultValue: row.column_default,
+        })),
+    };
+}
+async function listRelationships(pool) {
+    const result = await pool.query(`
+      select
+        tc.constraint_name,
+        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'
+      order by
+        tc.table_schema,
+        tc.table_name,
+        tc.constraint_name,
+        kcu.ordinal_position
+    `);
+    return result.rows.map((row) => ({
+        constraintName: row.constraint_name,
+        sourceSchema: row.source_schema,
+        sourceTable: row.source_table,
+        sourceColumn: row.source_column,
+        targetSchema: row.target_schema,
+        targetTable: row.target_table,
+        targetColumn: row.target_column,
+    }));
+}

package/dist/guard/index.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getReadonlyDefaults = getReadonlyDefaults;
+exports.guardReadonlyQuery = guardReadonlyQuery;
+exports.quoteIdentifier = quoteIdentifier;
+const DEFAULT_LIMIT = 100;
+const MAX_LIMIT = 100;
+const MAX_TIMEOUT_MS = 5_000;
+const MAX_RESULT_BYTES = 1_000_000;
+const BLOCKED_KEYWORDS = [
+    "insert",
+    "update",
+    "delete",
+    "drop",
+    "alter",
+    "truncate",
+];
+function getReadonlyDefaults() {
+    return {
+        defaultLimit: DEFAULT_LIMIT,
+        maxLimit: MAX_LIMIT,
+        timeoutMs: MAX_TIMEOUT_MS,
+        maxResultBytes: MAX_RESULT_BYTES,
+    };
+}
+function guardReadonlyQuery(sql, options = {}) {
+    const defaults = getReadonlyDefaults();
+    const defaultLimit = options.defaultLimit ?? defaults.defaultLimit;
+    const maxLimit = options.maxLimit ?? defaults.maxLimit;
+    const timeoutMs = Math.min(options.timeoutMs ?? defaults.timeoutMs, defaults.timeoutMs);
+    const maxResultBytes = options.maxResultBytes ?? defaults.maxResultBytes;
+    const normalizedSql = normalizeSql(sql);
+    assertSingleStatement(normalizedSql);
+    assertNoSqlComments(normalizedSql);
+    assertSelectOnly(normalizedSql);
+    assertNoBlockedKeywords(normalizedSql);
+    const limitMatch = normalizedSql.match(/\blimit\s+(\d+)\b/i);
+    const parsedLimit = limitMatch ? Number.parseInt(limitMatch[1], 10) : null;
+    if (parsedLimit !== null && parsedLimit > maxLimit) {
+        throw new Error(`Query LIMIT exceeds maximum allowed value of ${maxLimit}`);
+    }
+    return {
+        sql: parsedLimit === null ? `${normalizedSql} LIMIT ${defaultLimit}` : normalizedSql,
+        limit: parsedLimit ?? defaultLimit,
+        timeoutMs,
+        maxResultBytes,
+    };
+}
+function quoteIdentifier(identifier) {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(identifier)) {
+        throw new Error(`Invalid SQL identifier: ${identifier}`);
+    }
+    return `"${identifier.replace(/"/g, "\"\"")}"`;
+}
+function normalizeSql(sql) {
+    const trimmed = sql.trim().replace(/;+$/, "").trim();
+    if (!trimmed) {
+        throw new Error("SQL query is required");
+    }
+    return trimmed;
+}
+function assertSingleStatement(sql) {
+    if (sql.includes(";")) {
+        throw new Error("Only a single SQL statement is allowed");
+    }
+}
+function assertNoSqlComments(sql) {
+    if (sql.includes("--") || sql.includes("/*") || sql.includes("*/")) {
+        throw new Error("SQL comments are not allowed");
+    }
+}
+function assertSelectOnly(sql) {
+    if (!/^select\b/i.test(sql)) {
+        throw new Error("Only SELECT queries are allowed");
+    }
+}
+function assertNoBlockedKeywords(sql) {
+    const scrubbedSql = sql.replace(/'(?:''|[^'])*'/g, "''");
+    for (const keyword of BLOCKED_KEYWORDS) {
+        const pattern = new RegExp(`\\b${keyword}\\b`, "i");
+        if (pattern.test(scrubbedSql)) {
+            throw new Error(`Blocked SQL keyword detected: ${keyword.toUpperCase()}`);
+        }
+    }
+}

package/dist/index.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const config_1 = require("./config");
+const pool_1 = require("./db/pool");
+const server_1 = require("./server");
+async function main() {
+    const config = (0, config_1.getAppConfig)();
+    const pool = (0, pool_1.createDbPool)({
+        connectionString: config.databaseUrl,
+        max: config.dbPoolMax,
+    });
+    const server = (0, server_1.createAjanServer)({ pool });
+    const transport = new stdio_js_1.StdioServerTransport();
+    const shutdown = async () => {
+        await (0, pool_1.closeDbPool)(pool);
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    await server.connect(transport);
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`[ajan-sql] ${message}`);
+    process.exit(1);
+});

package/dist/query-runner/index.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runReadonlyQuery = runReadonlyQuery;
+exports.explainReadonlyQuery = explainReadonlyQuery;
+exports.sampleRows = sampleRows;
+const guard_1 = require("../guard");
+async function runReadonlyQuery(pool, sql, options = {}) {
+    const guarded = (0, guard_1.guardReadonlyQuery)(sql, options);
+    const result = await executeWithReadonlySettings(pool, guarded.sql, guarded.timeoutMs);
+    assertRowCount(result.rows.length, guarded.limit);
+    assertResultSize(result.rows, guarded.maxResultBytes);
+    return {
+        sql: guarded.sql,
+        rowCount: result.rows.length,
+        rows: result.rows,
+    };
+}
+async function explainReadonlyQuery(pool, sql) {
+    const guarded = (0, guard_1.guardReadonlyQuery)(sql);
+    const explainSql = `EXPLAIN (FORMAT JSON) ${guarded.sql}`;
+    const result = await executeWithReadonlySettings(pool, explainSql, guarded.timeoutMs);
+    const plan = result.rows[0]?.["QUERY PLAN"];
+    return {
+        sql: guarded.sql,
+        plan,
+    };
+}
+async function sampleRows(pool, tableName, schemaName = "public", limit = 10) {
+    const defaults = (0, guard_1.getReadonlyDefaults)();
+    const safeLimit = Math.min(limit, defaults.maxLimit);
+    const sql = [
+        "SELECT *",
+        `FROM ${(0, guard_1.quoteIdentifier)(schemaName)}.${(0, guard_1.quoteIdentifier)(tableName)}`,
+        `LIMIT ${safeLimit}`,
+    ].join(" ");
+    return runReadonlyQuery(pool, sql, { defaultLimit: safeLimit });
+}
+async function executeWithReadonlySettings(pool, sql, timeoutMs) {
+    const client = await pool.connect();
+    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;
+    }
+    catch (error) {
+        await client.query("ROLLBACK").catch(() => undefined);
+        throw error;
+    }
+    finally {
+        client.release();
+    }
+}
+function assertRowCount(rowCount, limit) {
+    if (rowCount > limit) {
+        throw new Error(`Query returned more rows than allowed limit of ${limit}`);
+    }
+}
+function assertResultSize(rows, maxResultBytes) {
+    const resultBytes = Buffer.byteLength(JSON.stringify(rows), "utf8");
+    if (resultBytes > maxResultBytes) {
+        throw new Error(`Query result exceeds maximum allowed size of ${maxResultBytes} bytes`);
+    }
+}

package/dist/resources/schema-resources.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSchemaResources = registerSchemaResources;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const schema_1 = require("../db/schema");
+function registerSchemaResources(server, deps) {
+    server.registerResource("schema-snapshot", "schema://snapshot", {
+        description: "Snapshot of tables and foreign key relationships.",
+        mimeType: "application/json",
+    }, async (uri) => {
+        const [tables, relationships] = await Promise.all([
+            (0, schema_1.listTables)(deps.pool),
+            (0, schema_1.listRelationships)(deps.pool),
+        ]);
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: JSON.stringify({ tables, relationships }, null, 2),
+                    mimeType: "application/json",
+                },
+            ],
+        };
+    });
+    server.registerResource("schema-table", new mcp_js_1.ResourceTemplate("schema://table/{name}", {
+        list: async () => {
+            const tables = await (0, schema_1.listTables)(deps.pool);
+            return {
+                resources: tables.map((table) => ({
+                    uri: `schema://table/${table.name}`,
+                    name: `${table.schema}.${table.name}`,
+                })),
+            };
+        },
+        complete: {
+            name: async (value) => {
+                const tables = await (0, schema_1.listTables)(deps.pool);
+                return tables
+                    .map((table) => table.name)
+                    .filter((tableName) => tableName.startsWith(value));
+            },
+        },
+    }), {
+        description: "Schema details for a single table.",
+        mimeType: "application/json",
+    }, async (uri, params) => {
+        const tableName = Array.isArray(params.name) ? params.name[0] : params.name;
+        if (!tableName) {
+            throw new Error("Table name is required");
+        }
+        const description = await (0, schema_1.describeTable)(deps.pool, tableName);
+        if (!description) {
+            throw new Error(`Table not found: ${tableName}`);
+        }
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: JSON.stringify(description, null, 2),
+                    mimeType: "application/json",
+                },
+            ],
+        };
+    });
+}

package/dist/server.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAjanServer = createAjanServer;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const schema_resources_1 = require("./resources/schema-resources");
+const schema_tools_1 = require("./tools/schema-tools");
+function createAjanServer(options) {
+    const server = new mcp_js_1.McpServer({
+        name: "ajan-sql",
+        version: "0.1.0",
+    });
+    (0, schema_tools_1.registerSchemaTools)(server, { pool: options.pool });
+    (0, schema_resources_1.registerSchemaResources)(server, { pool: options.pool });
+    return server;
+}

package/dist/tools/schema-tools.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSchemaTools = registerSchemaTools;
+const zod_1 = require("zod");
+const schema_1 = require("../db/schema");
+const query_runner_1 = require("../query-runner");
+function asTextResult(data) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+}
+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);
+    });
+    registerTool("describe_table", {
+        description: "Return columns and types for a given table.",
+        inputSchema: {
+            name: zod_1.z.string().min(1),
+            schema: zod_1.z.string().min(1).optional(),
+        },
+    }, async ({ name, schema }) => {
+        const resolvedSchema = schema ?? "public";
+        const description = await (0, schema_1.describeTable)(deps.pool, name, resolvedSchema);
+        if (!description) {
+            throw new Error(`Table not found: ${resolvedSchema}.${name}`);
+        }
+        return asTextResult(description);
+    });
+    registerTool("list_relationships", {
+        description: "Return foreign key relationships.",
+    }, async () => {
+        const relationships = await (0, schema_1.listRelationships)(deps.pool);
+        return asTextResult(relationships);
+    });
+    registerTool("run_readonly_query", {
+        description: "Execute a safe SELECT query.",
+        inputSchema: {
+            sql: zod_1.z.string().min(1),
+        },
+    }, async ({ sql }) => {
+        const result = await (0, query_runner_1.runReadonlyQuery)(deps.pool, sql);
+        return asTextResult(result);
+    });
+    registerTool("explain_query", {
+        description: "Return query execution plan.",
+        inputSchema: {
+            sql: zod_1.z.string().min(1),
+        },
+    }, async ({ sql }) => {
+        const result = await (0, query_runner_1.explainReadonlyQuery)(deps.pool, sql);
+        return asTextResult(result);
+    });
+    registerTool("sample_rows", {
+        description: "Return example rows from a table.",
+        inputSchema: {
+            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(),
+        },
+    }, async ({ name, schema, limit }) => {
+        const result = await (0, query_runner_1.sampleRows)(deps.pool, name, schema ?? "public", limit ?? 10);
+        return asTextResult(result);
+    });
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "ajan-sql",
+  "version": "0.1.0",
+  "description": "AI-safe MCP server for schema-aware, read-only SQL access.",
+  "bin": {
+    "ajan-sql": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "docs:build": "vitepress build docs",
+    "docs:dev": "vitepress dev docs",
+    "docs:preview": "vitepress preview docs",
+    "prepublishOnly": "npm run build && npm test",
+    "prepare": "husky",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "postgres",
+    "postgresql",
+    "sql",
+    "ai",
+    "cli"
+  ],
+  "author": "Bora Kilicoglu",
+  "license": "MIT",
+  "type": "commonjs",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.18.0",
+    "pg": "^8.16.3",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/pg": "^8.15.6",
+    "husky": "^9.1.7",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.0",
+    "vitepress": "^1.6.4",
+    "vitest": "^3.2.0"
+  }
+}