mcp-data-agent 0.1.0

package/packages/mcp/src/server.ts

@@ -0,0 +1,170 @@
+/**
+ * MCP Data Agent — @mcp-data-agent/mcp
+ * Created by Arslan Habib
+ *
+ * ---------------------------------------------------------------------------
+ * FILE: server.ts
+ * PURPOSE:
+ *   Bridges MCPDataAgent tools to the Model Context Protocol so AI assistants
+ *   (Cursor, Claude Desktop, custom MCP clients) can call them.
+ *
+ * WHAT IT DOES:
+ *   - Creates an McpServer (official TypeScript SDK v2)
+ *   - Registers database_schema and database_query MCP tools
+ *   - Optionally mirrors custom agent tools (dots → underscores in names)
+ *   - Returns JSON text content (or structured errors) to the client
+ *
+ * AUTH / TENANT:
+ *   Still resolved by agent.resolveContext on every invoke — MCP args never
+ *   supply tenantId.
+ * ---------------------------------------------------------------------------
+ */
+
+import type { MCPDataAgent } from "@mcp-data-agent/core";
+import { McpDataAgentError } from "@mcp-data-agent/core";
+import { McpServer } from "@modelcontextprotocol/server";
+import * as z from "zod/v4";
+
+/** Options for createMcpDataAgentServer(). */
+export interface CreateMcpServerOptions {
+  /** Fully configured MCPDataAgent instance. */
+  agent: MCPDataAgent;
+  /** MCP server name shown to clients. */
+  name?: string;
+  /** MCP server version shown to clients. */
+  version?: string;
+  /**
+   * When true, register every custom tool currently on the agent.
+   * Register custom tools BEFORE calling this factory.
+   */
+  includeCustomTools?: boolean;
+}
+
+/** Wrap successful tool output as MCP text content (JSON). */
+function toTextResult(data: unknown) {
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(data, null, 2),
+      },
+    ],
+  };
+}
+
+/** Wrap failures as MCP error content with a stable error code when possible. */
+function toErrorResult(error: unknown) {
+  const message =
+    error instanceof Error ? error.message : "Unknown tool execution error";
+  const code =
+    error instanceof McpDataAgentError ? error.code : "TOOL_EXECUTION_ERROR";
+  return {
+    isError: true as const,
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify({ error: code, message }, null, 2),
+      },
+    ],
+  };
+}
+
+/**
+ * Build an MCP server that exposes MCP Data Agent tools to AI assistants.
+ * Connect it with StdioServerTransport or an HTTP transport in the host app.
+ */
+export function createMcpDataAgentServer(
+  options: CreateMcpServerOptions,
+): McpServer {
+  const {
+    agent,
+    name = "mcp-data-agent",
+    version = "0.1.0",
+    includeCustomTools = true,
+  } = options;
+
+  const server = new McpServer({ name, version });
+
+  // --- Built-in: safe schema for the authenticated user ---
+  server.registerTool(
+    "database_schema",
+    {
+      description:
+        "Return a safe, redacted database schema and business entities for the authenticated user.",
+      inputSchema: z.object({}),
+    },
+    async () => {
+      try {
+        const result = await agent.invokeTool("database.schema", {});
+        return toTextResult(result);
+      } catch (error) {
+        return toErrorResult(error);
+      }
+    },
+  );
+
+  // --- Built-in: validated read-only SQL ---
+  server.registerTool(
+    "database_query",
+    {
+      description:
+        "Execute a validated read-only SQL SELECT. Tenant isolation and permissions are enforced by the host application session — do not pass tenantId.",
+      inputSchema: z.object({
+        sql: z.string().describe("Read-only SELECT (or WITH … SELECT) SQL"),
+        params: z
+          .array(z.unknown())
+          .optional()
+          .describe("Bound parameters for the query"),
+        limit: z
+          .number()
+          .int()
+          .positive()
+          .max(1000)
+          .optional()
+          .describe("Maximum rows to return"),
+      }),
+    },
+    async ({ sql, params, limit }) => {
+      try {
+        const result = await agent.invokeTool("database.query", {
+          sql,
+          params,
+          limit,
+        });
+        return toTextResult(result);
+      } catch (error) {
+        return toErrorResult(error);
+      }
+    },
+  );
+
+  // --- Custom tools registered on the agent (e.g. members.statistics) ---
+  if (includeCustomTools) {
+    for (const tool of agent.listTools()) {
+      // Skip built-ins already registered above under MCP-friendly names
+      if (tool.name === "database.schema" || tool.name === "database.query") {
+        continue;
+      }
+      // MCP tool names typically use underscores: members.statistics → members_statistics
+      const mcpName = tool.name.replace(/\./g, "_");
+      server.registerTool(
+        mcpName,
+        {
+          description: tool.description,
+          // Passthrough object: domain tools define their own shapes
+          inputSchema: z.object({}).passthrough(),
+        },
+        async (args) => {
+          try {
+            const result = await agent.invokeTool(tool.name, args);
+            return toTextResult(result);
+          } catch (error) {
+            return toErrorResult(error);
+          }
+        },
+      );
+    }
+  }
+
+  return server;
+}

package/packages/mcp/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "composite": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.test.ts", "dist"],
+  "references": [{ "path": "../core" }]
+}

package/packages/postgres/README.md

@@ -0,0 +1,7 @@
+# @mcp-data-agent/postgres
+
+PostgreSQL adapter for **MCP Data Agent**.
+
+**Created by Arslan Habib**
+
+Prefer a **read-only** database role for analytical access. Enable RLS policies that read `current_setting('app.tenant_id', true)`.

package/packages/postgres/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@mcp-data-agent/postgres",
+  "version": "0.1.0",
+  "description": "PostgreSQL adapter for MCP Data Agent. Created by Arslan Habib.",
+  "author": {
+    "name": "Arslan Habib"
+  },
+  "creator": "Arslan Habib",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@mcp-data-agent/core": "0.1.0",
+    "pg": "^8.13.0"
+  },
+  "devDependencies": {
+    "@mcp-data-agent/core": "*",
+    "@types/pg": "^8.11.11",
+    "pg": "^8.14.1"
+  },
+  "keywords": [
+    "mcp-data-agent",
+    "postgresql",
+    "postgres",
+    "database-adapter"
+  ]
+}

package/packages/postgres/src/adapter.ts

@@ -0,0 +1,358 @@
+/**
+ * MCP Data Agent — @mcp-data-agent/postgres
+ * Created by Arslan Habib
+ *
+ * ---------------------------------------------------------------------------
+ * FILE: adapter.ts
+ * PURPOSE:
+ *   PostgreSQL implementation of DatabaseAdapter. Responsibilities:
+ *     1) Inspect information_schema → normalized DatabaseSchema
+ *     2) Run validated read-only queries inside a READ ONLY transaction
+ *     3) Set session GUCs (app.tenant_id, app.user_id) for Postgres RLS
+ *
+ * SECURITY:
+ *   Prefer a read-only DB role. Enable RLS policies that read
+ *   current_setting('app.tenant_id', true) so tenant isolation is enforced
+ *   at the database layer, not only in application code.
+ * ---------------------------------------------------------------------------
+ */
+
+import type {
+  ColumnDataType,
+  DatabaseAdapter,
+  DatabaseSchema,
+  QueryRequest,
+  QueryResult,
+  RequestContext,
+  TableSchema,
+} from "@mcp-data-agent/core";
+import {
+  ConfigurationError,
+  getTenantColumn,
+  TenantIsolationError,
+} from "@mcp-data-agent/core";
+import pg from "pg";
+
+const { Pool } = pg;
+
+/** Configuration for createPostgresAdapter / PostgresAdapter. */
+export interface PostgresAdapterOptions {
+  /** Connection string. Prefer env vars (DATABASE_URL) in production. */
+  connectionString?: string;
+  /** Reuse an existing pg Pool owned by the host app. */
+  pool?: pg.Pool;
+  /** Passed to `new Pool(...)` when connectionString is not set. */
+  poolConfig?: pg.PoolConfig;
+  /** Schemas to inspect. Default: ["public"]. */
+  schemas?: string[];
+  /**
+   * When true (default), require tenant context and set app.tenant_id /
+   * app.user_id session variables for RLS policies.
+   */
+  enforceTenant?: boolean;
+}
+
+/**
+ * Maps PostgreSQL udt_name values to the framework's normalized ColumnDataType.
+ * Keeps AI-facing schema DB-agnostic.
+ */
+function mapDataType(udtName: string): ColumnDataType {
+  switch (udtName) {
+    case "int2":
+    case "int4":
+    case "int8":
+    case "numeric":
+    case "float4":
+    case "float8":
+    case "money":
+      return "number";
+    case "bool":
+      return "boolean";
+    case "date":
+      return "date";
+    case "timestamp":
+    case "timestamptz":
+    case "time":
+    case "timetz":
+      return "datetime";
+    case "json":
+    case "jsonb":
+      return "json";
+    case "bytea":
+      return "binary";
+    case "text":
+    case "varchar":
+    case "bpchar":
+    case "uuid":
+    case "citext":
+      return "string";
+    default:
+      return "unknown";
+  }
+}
+
+/**
+ * PostgreSQL DatabaseAdapter.
+ * Implements getSchema() and query() for @mcp-data-agent/core.
+ */
+export class PostgresAdapter implements DatabaseAdapter {
+  readonly name = "postgres";
+  private readonly pool: pg.Pool;
+  private readonly schemas: string[];
+  private readonly enforceTenant: boolean;
+  /** True when this adapter created the pool and must close it. */
+  private readonly ownsPool: boolean;
+
+  constructor(options: PostgresAdapterOptions = {}) {
+    // Prefer an injected pool (host apps often share one across services)
+    if (options.pool) {
+      this.pool = options.pool;
+      this.ownsPool = false;
+    } else if (options.connectionString || options.poolConfig) {
+      this.pool = new Pool(
+        options.connectionString
+          ? { connectionString: options.connectionString }
+          : options.poolConfig,
+      );
+      this.ownsPool = true;
+    } else {
+      throw new ConfigurationError(
+        "PostgresAdapter requires connectionString, poolConfig, or an existing pool",
+      );
+    }
+    this.schemas = options.schemas ?? ["public"];
+    this.enforceTenant = options.enforceTenant ?? true;
+  }
+
+  /**
+   * Reads tables, columns, primary keys, and foreign keys from
+   * information_schema and returns a normalized DatabaseSchema.
+   */
+  async getSchema(): Promise<DatabaseSchema> {
+    const client = await this.pool.connect();
+    try {
+      // --- Base tables in configured schemas ---
+      const tablesResult = await client.query<{
+        table_schema: string;
+        table_name: string;
+      }>(
+        `
+        SELECT table_schema, table_name
+        FROM information_schema.tables
+        WHERE table_type = 'BASE TABLE'
+          AND table_schema = ANY($1::text[])
+        ORDER BY table_schema, table_name
+        `,
+        [this.schemas],
+      );
+
+      // --- Columns with native Postgres types ---
+      const columnsResult = await client.query<{
+        table_schema: string;
+        table_name: string;
+        column_name: string;
+        is_nullable: string;
+        udt_name: string;
+        ordinal_position: number;
+      }>(
+        `
+        SELECT table_schema, table_name, column_name, is_nullable, udt_name, ordinal_position
+        FROM information_schema.columns
+        WHERE table_schema = ANY($1::text[])
+        ORDER BY table_schema, table_name, ordinal_position
+        `,
+        [this.schemas],
+      );
+
+      // --- Primary key columns ---
+      const pkResult = await client.query<{
+        table_schema: string;
+        table_name: string;
+        column_name: string;
+      }>(
+        `
+        SELECT tc.table_schema, tc.table_name, kcu.column_name
+        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 = ANY($1::text[])
+        `,
+        [this.schemas],
+      );
+
+      // --- Foreign key relationships ---
+      const fkResult = await client.query<{
+        table_schema: string;
+        table_name: string;
+        column_name: string;
+        foreign_table_name: string;
+        foreign_column_name: string;
+      }>(
+        `
+        SELECT
+          tc.table_schema,
+          tc.table_name,
+          kcu.column_name,
+          ccu.table_name AS foreign_table_name,
+          ccu.column_name AS foreign_column_name
+        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'
+          AND tc.table_schema = ANY($1::text[])
+        `,
+        [this.schemas],
+      );
+
+      // Index PK/FK for fast lookup while assembling ColumnSchema objects
+      const pkSet = new Set(
+        pkResult.rows.map(
+          (r) => `${r.table_schema}.${r.table_name}.${r.column_name}`,
+        ),
+      );
+      const fkMap = new Map(
+        fkResult.rows.map((r) => [
+          `${r.table_schema}.${r.table_name}.${r.column_name}`,
+          { table: r.foreign_table_name, column: r.foreign_column_name },
+        ]),
+      );
+
+      // Group columns by table
+      const columnsByTable = new Map<string, TableSchema["columns"]>();
+      for (const col of columnsResult.rows) {
+        const key = `${col.table_schema}.${col.table_name}`;
+        const list = columnsByTable.get(key) ?? [];
+        const full = `${col.table_schema}.${col.table_name}.${col.column_name}`;
+        const fk = fkMap.get(full);
+        list.push({
+          name: col.column_name,
+          dataType: mapDataType(col.udt_name),
+          nativeType: col.udt_name,
+          nullable: col.is_nullable === "YES",
+          isPrimaryKey: pkSet.has(full),
+          isForeignKey: Boolean(fk),
+          ...(fk ? { references: fk } : {}),
+        });
+        columnsByTable.set(key, list);
+      }
+
+      const tables: TableSchema[] = tablesResult.rows.map((t) => {
+        const key = `${t.table_schema}.${t.table_name}`;
+        const columns = columnsByTable.get(key) ?? [];
+        const primaryKey = columns.filter((c) => c.isPrimaryKey).map((c) => c.name);
+        return {
+          name: t.table_name,
+          schema: t.table_schema,
+          columns,
+          ...(primaryKey.length ? { primaryKey } : {}),
+        };
+      });
+
+      return {
+        dialect: "postgresql",
+        inspectedAt: new Date().toISOString(),
+        tables,
+      };
+    } finally {
+      // Always return the client to the pool
+      client.release();
+    }
+  }
+
+  /**
+   * Executes a (already validated) read-only query.
+   * Opens BEGIN READ ONLY, sets tenant/user GUCs, applies statement_timeout,
+   * runs the query with bound params, then commits.
+   */
+  async query(
+    request: QueryRequest,
+    context: RequestContext,
+  ): Promise<QueryResult> {
+    if (this.enforceTenant) {
+      if (!context.tenant?.tenantId) {
+        throw new TenantIsolationError();
+      }
+    }
+
+    const client = await this.pool.connect();
+    const started = Date.now();
+    try {
+      // READ ONLY transaction: DB rejects writes even if SQL slipped through
+      await client.query("BEGIN READ ONLY");
+
+      if (this.enforceTenant) {
+        // Local-to-transaction GUCs for RLS:
+        //   current_setting('app.tenant_id', true)
+        await client.query(`SELECT set_config('app.tenant_id', $1, true)`, [
+          context.tenant.tenantId,
+        ]);
+        await client.query(`SELECT set_config('app.user_id', $1, true)`, [
+          context.auth.userId,
+        ]);
+      }
+
+      if (request.timeoutMs) {
+        await client.query(`SET LOCAL statement_timeout = $1`, [
+          request.timeoutMs,
+        ]);
+      }
+
+      // Always use bound parameters — never interpolate AI text into SQL
+      const result = await client.query(request.sql, request.params ?? []);
+      await client.query("COMMIT");
+
+      // Apply row limit in memory as a second safety net
+      const limit = request.limit ?? result.rowCount ?? 0;
+      const rows = result.rows.slice(0, limit).map((row) => {
+        const record: Record<string, unknown> = {};
+        for (const [key, value] of Object.entries(row)) {
+          record[key] = value;
+        }
+        return record;
+      });
+
+      return {
+        columns: result.fields.map((f) => ({
+          name: f.name,
+          dataType: "unknown" as const,
+        })),
+        rows,
+        rowCount: rows.length,
+        truncated: (result.rowCount ?? 0) > rows.length,
+        executionMs: Date.now() - started,
+      };
+    } catch (error) {
+      try {
+        await client.query("ROLLBACK");
+      } catch {
+        // Ignore rollback errors; rethrow the original failure
+      }
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+
+  /** Closes the pool only if this adapter created it. */
+  async close(): Promise<void> {
+    if (this.ownsPool) {
+      await this.pool.end();
+    }
+  }
+}
+
+/** Convenience factory: createPostgresAdapter({ connectionString }). */
+export function createPostgresAdapter(
+  options: PostgresAdapterOptions,
+): PostgresAdapter {
+  return new PostgresAdapter(options);
+}
+
+/** Re-export for host apps writing RLS policies. */
+export { getTenantColumn };

package/packages/postgres/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * MCP Data Agent — @mcp-data-agent/postgres
+ * Created by Arslan Habib
+ *
+ * ---------------------------------------------------------------------------
+ * FILE: index.ts
+ * PURPOSE:
+ *   Public entry point for the PostgreSQL adapter package.
+ *
+ *     import { createPostgresAdapter } from "@mcp-data-agent/postgres";
+ * ---------------------------------------------------------------------------
+ */
+
+export {
+  createPostgresAdapter,
+  getTenantColumn,
+  PostgresAdapter,
+} from "./adapter.js";
+export type { PostgresAdapterOptions } from "./adapter.js";

package/packages/postgres/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "composite": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.test.ts", "dist"],
+  "references": [{ "path": "../core" }]
+}

package/tsconfig.base.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "strict": true,
+    "noImplicitOverride": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "forceConsistentCasingInFileNames": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "composite": true,
+    "rootDir": "src",
+    "outDir": "dist"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./packages/core" },
+    { "path": "./packages/postgres" },
+    { "path": "./packages/mcp" }
+  ]
+}

package/vitest.config.ts

@@ -0,0 +1,14 @@
+// MCP Data Agent — Created by Arslan Habib
+//
+// FILE: vitest.config.ts
+// PURPOSE: Vitest config for package unit tests (colocated *.test.ts files).
+
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    // Pick up tests colocated with package source
+    include: ["packages/*/src/**/*.test.ts"],
+    environment: "node",
+  },
+});