mcp-data-agent 0.1.0

package/examples/basic/src/index.ts

@@ -0,0 +1,107 @@
+/**
+ * MCP Data Agent — basic integration example
+ * Created by Arslan Habib
+ *
+ * ---------------------------------------------------------------------------
+ * FILE: examples/basic/src/index.ts
+ * PURPOSE:
+ *   End-to-end sketch showing how a host app wires:
+ *     Postgres adapter → createMCPDataAgent → createMcpDataAgentServer → stdio
+ *
+ * HOW TO RUN (from monorepo root):
+ *   1. Copy .env.example → .env and set DATABASE_URL
+ *   2. npm run build
+ *   3. npm start -w @mcp-data-agent/example-basic
+ *
+ * Replace resolveContext() with your real session/auth middleware before
+ * production use. Never accept tenantId from the LLM.
+ * ---------------------------------------------------------------------------
+ */
+
+import {
+  createMCPDataAgent,
+  Permissions,
+  type RequestContext,
+} from "@mcp-data-agent/core";
+import { createMcpDataAgentServer } from "@mcp-data-agent/mcp";
+import { createPostgresAdapter } from "@mcp-data-agent/postgres";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+
+/**
+ * DEMO ONLY — simulates what your auth middleware would return.
+ * In production: read the logged-in user + tenant from the session cookie/JWT.
+ */
+async function resolveContext(): Promise<RequestContext> {
+  return {
+    auth: {
+      userId: process.env.DEMO_USER_ID ?? "demo-user",
+      displayName: "Demo User",
+      roles: ["receptionist"],
+      // Receptionist-style permissions (no revenue/expenses)
+      permissions: [
+        Permissions.DATABASE_SCHEMA,
+        Permissions.DATABASE_QUERY,
+        "members.read",
+        "attendance.read",
+      ],
+    },
+    tenant: {
+      // From session — never from tool arguments
+      tenantId: process.env.DEMO_TENANT_ID ?? "gym_001",
+    },
+    question: process.env.DEMO_QUESTION,
+  };
+}
+
+async function main() {
+  // --- 1) Database adapter (prefer read-only DB credentials) ---
+  const database = createPostgresAdapter({
+    connectionString:
+      process.env.DATABASE_URL ?? "postgres://localhost:5432/mcp_data_agent",
+  });
+
+  // --- 2) Core agent with auth resolution + audit logging ---
+  const agent = createMCPDataAgent({
+    database,
+    resolveContext,
+    audit: (event) => {
+      // Log to stderr so stdout stays free for MCP stdio protocol
+      console.error("[audit]", JSON.stringify(event));
+    },
+  });
+
+  // --- 3) Business context, field protection, custom domain tool ---
+  agent
+    .defineEntity({
+      name: "Member",
+      table: "members",
+      description: "A person registered at the gym",
+      relationships: [
+        { name: "memberships", entity: "Membership", type: "one-to-many" },
+        { name: "attendance", entity: "Attendance", type: "one-to-many" },
+      ],
+    })
+    .protectField({ table: "members", column: "password_hash" })
+    .registerTool({
+      name: "members.statistics",
+      description: "Return basic member statistics for the current tenant",
+      permission: "members.read",
+      handler: async (_input, context) => {
+        // Prefer dedicated domain tools over free-form SQL when possible
+        return {
+          tenantId: context.tenant.tenantId,
+          note: "Wire this to your domain service or a constrained adapter query.",
+        };
+      },
+    });
+
+  // --- 4) Expose tools over MCP stdio for AI assistants ---
+  const server = createMcpDataAgentServer({ agent });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/examples/basic/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "composite": false,
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts"],
+  "references": [
+    { "path": "../../packages/core" },
+    { "path": "../../packages/postgres" },
+    { "path": "../../packages/mcp" }
+  ]
+}

package/package.json

@@ -0,0 +1,106 @@
+{
+  "name": "mcp-data-agent",
+  "version": "0.1.0",
+  "description": "MCP Data Agent — open-source MCP framework for securely connecting AI assistants to application databases. Created by Arslan Habib.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "database",
+    "postgresql",
+    "multi-tenant",
+    "rbac",
+    "llm"
+  ],
+  "homepage": "https://github.com/ArslanKhan99/mcp_engine#readme",
+  "bugs": {
+    "url": "https://github.com/ArslanKhan99/mcp_engine/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArslanKhan99/mcp_engine.git"
+  },
+  "license": "MIT",
+  "author": "Arslan Habib (https://github.com/arslanhabib)",
+  "type": "ESM",
+  "main": "index.js",
+  "directories": {
+    "example": "examples"
+  },
+  "workspaces": [
+    "packages/*",
+    "examples/*"
+  ],
+  "scripts": {
+    "build": "npm run build --workspaces --if-present",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -b --pretty",
+    "clean": "npm run clean --workspaces --if-present"
+  },
+  "dependencies": {
+    "assertion-error": "^2.0.1",
+    "cac": "^6.7.14",
+    "chai": "^5.3.3",
+    "check-error": "^2.1.3",
+    "debug": "^4.4.3",
+    "deep-eql": "^5.0.2",
+    "es-module-lexer": "^1.7.0",
+    "esbuild": "^0.25.12",
+    "estree-walker": "^3.0.3",
+    "expect-type": "^1.4.0",
+    "fdir": "^6.5.0",
+    "fsevents": "^2.3.3",
+    "js-tokens": "^9.0.1",
+    "loupe": "^3.2.1",
+    "magic-string": "^0.30.21",
+    "ms": "^2.1.3",
+    "nanoid": "^3.3.19",
+    "pathe": "^2.0.3",
+    "pathval": "^2.0.1",
+    "pg": "^8.23.0",
+    "pg-cloudflare": "^1.4.0",
+    "pg-connection-string": "^2.14.0",
+    "pg-int8": "^1.0.1",
+    "pg-pool": "^3.14.0",
+    "pg-protocol": "^1.16.0",
+    "pg-types": "^2.2.0",
+    "pgpass": "^1.0.5",
+    "picocolors": "^1.1.1",
+    "picomatch": "^4.0.7",
+    "postcss": "^8.5.28",
+    "postgres-array": "^2.0.0",
+    "postgres-bytea": "^1.0.1",
+    "postgres-date": "^1.0.7",
+    "postgres-interval": "^1.2.0",
+    "rollup": "^4.63.3",
+    "siginfo": "^2.0.0",
+    "source-map-js": "^1.2.1",
+    "split2": "^4.2.0",
+    "stackback": "^0.0.2",
+    "std-env": "^3.10.0",
+    "strip-literal": "^3.1.0",
+    "tinybench": "^2.9.0",
+    "tinyexec": "^0.3.2",
+    "tinyglobby": "^0.2.17",
+    "tinypool": "^1.1.1",
+    "tinyrainbow": "^2.0.0",
+    "tinyspy": "^4.0.6",
+    "tsx": "^4.23.13",
+    "undici-types": "^6.21.0",
+    "vite": "^6.4.3",
+    "vite-node": "^3.2.4",
+    "why-is-node-running": "^2.3.0",
+    "xtend": "^4.0.2",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.9"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "creator": "Arslan Habib"
+}

package/packages/core/README.md

@@ -0,0 +1,7 @@
+# @mcp-data-agent/core
+
+Core runtime for **MCP Data Agent**.
+
+**Created by Arslan Habib**
+
+See the root [README](../../README.md) for architecture, security model, and quick start.

package/packages/core/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@mcp-data-agent/core",
+  "version": "0.1.0",
+  "description": "Core runtime for MCP Data Agent — auth, RBAC, tenant isolation, schema, and tools. 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"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-data-agent",
+    "database",
+    "rbac",
+    "multi-tenant"
+  ]
+}

package/packages/core/src/agent.test.ts

@@ -0,0 +1,213 @@
+/**
+ * MCP Data Agent — @mcp-data-agent/core
+ * Created by Arslan Habib
+ *
+ * ---------------------------------------------------------------------------
+ * FILE: agent.test.ts
+ * PURPOSE:
+ *   Unit tests for core security behaviors without a real database:
+ *     - Read-only SQL validation
+ *     - Sensitive column redaction (schema + query results)
+ *     - Permission enforcement
+ *     - Rejection of tenantId overrides from tool params
+ *     - Custom tools, entities, and audit hooks
+ *
+ * Uses a mock DatabaseAdapter so tests stay fast and offline.
+ * ---------------------------------------------------------------------------
+ */
+
+import { describe, expect, it, vi } from "vitest";
+import {
+  AuthorizationError,
+  createMCPDataAgent,
+  QueryValidationError,
+  TenantIsolationError,
+  validateReadOnlyQuery,
+} from "./index.js";
+import type { DatabaseAdapter, QueryResult, RequestContext } from "./types.js";
+
+/**
+ * Fake adapter that returns a members table including a sensitive
+ * password_hash column — used to assert redaction works.
+ */
+function mockAdapter(overrides?: Partial<DatabaseAdapter>): DatabaseAdapter {
+  return {
+    name: "mock",
+    getSchema: async () => ({
+      dialect: "mock",
+      inspectedAt: new Date().toISOString(),
+      tables: [
+        {
+          name: "members",
+          schema: "public",
+          columns: [
+            {
+              name: "id",
+              dataType: "number",
+              nativeType: "int",
+              nullable: false,
+              isPrimaryKey: true,
+              isForeignKey: false,
+            },
+            {
+              name: "tenant_id",
+              dataType: "string",
+              nativeType: "text",
+              nullable: false,
+              isPrimaryKey: false,
+              isForeignKey: false,
+            },
+            {
+              name: "password_hash",
+              dataType: "string",
+              nativeType: "text",
+              nullable: false,
+              isPrimaryKey: false,
+              isForeignKey: false,
+            },
+            {
+              name: "email",
+              dataType: "string",
+              nativeType: "text",
+              nullable: false,
+              isPrimaryKey: false,
+              isForeignKey: false,
+            },
+          ],
+        },
+      ],
+    }),
+    // Deliberately returns password_hash so we can assert it is stripped
+    query: async (): Promise<QueryResult> => ({
+      columns: [
+        { name: "email", dataType: "string" },
+        { name: "password_hash", dataType: "string" },
+      ],
+      rows: [{ email: "a@example.com", password_hash: "secret" }],
+      rowCount: 1,
+      truncated: false,
+    }),
+    ...overrides,
+  };
+}
+
+/** Helper: build a RequestContext with the given permissions. */
+function context(perms: string[]): RequestContext {
+  return {
+    auth: {
+      userId: "user-1",
+      permissions: perms,
+    },
+    tenant: { tenantId: "gym_001" },
+  };
+}
+
+describe("validateReadOnlyQuery", () => {
+  it("allows SELECT", () => {
+    const result = validateReadOnlyQuery({
+      sql: "SELECT id FROM members WHERE active = true",
+    });
+    expect(result.sql).toContain("SELECT");
+  });
+
+  it("rejects DELETE", () => {
+    expect(() =>
+      validateReadOnlyQuery({ sql: "DELETE FROM members" }),
+    ).toThrow(QueryValidationError);
+  });
+
+  it("rejects multi-statement", () => {
+    expect(() =>
+      validateReadOnlyQuery({
+        sql: "SELECT 1; DROP TABLE members",
+      }),
+    ).toThrow(QueryValidationError);
+  });
+});
+
+describe("createMCPDataAgent", () => {
+  it("redacts sensitive columns from schema", async () => {
+    const agent = createMCPDataAgent({
+      database: mockAdapter(),
+      resolveContext: () => context(["database.schema"]),
+    });
+
+    const result = await agent.invokeTool<{
+      schema: { tables: Array<{ columns: Array<{ name: string }> }> };
+    }>("database.schema");
+
+    const names = result.schema.tables[0]?.columns.map((c) => c.name) ?? [];
+    expect(names).toContain("email");
+    expect(names).not.toContain("password_hash");
+  });
+
+  it("redacts sensitive columns from query results", async () => {
+    const agent = createMCPDataAgent({
+      database: mockAdapter(),
+      resolveContext: () => context(["database.query"]),
+    });
+
+    const result = await agent.invokeTool<{
+      rows: Array<Record<string, unknown>>;
+    }>("database.query", {
+      sql: "SELECT email, password_hash FROM members",
+    });
+
+    expect(result.rows[0]?.email).toBe("a@example.com");
+    expect(result.rows[0]?.password_hash).toBeUndefined();
+  });
+
+  it("enforces permissions", async () => {
+    // User only has members.read — database.query must be denied
+    const agent = createMCPDataAgent({
+      database: mockAdapter(),
+      resolveContext: () => context(["members.read"]),
+    });
+
+    await expect(
+      agent.invokeTool("database.query", { sql: "SELECT 1" }),
+    ).rejects.toBeInstanceOf(AuthorizationError);
+  });
+
+  it("rejects tenant overrides from tool params", async () => {
+    const agent = createMCPDataAgent({
+      database: mockAdapter(),
+      resolveContext: () => context(["database.query"]),
+    });
+
+    await expect(
+      agent.invokeTool("database.query", {
+        sql: "SELECT 1",
+        tenantId: "gym_002", // attack attempt — must throw
+      }),
+    ).rejects.toBeInstanceOf(TenantIsolationError);
+  });
+
+  it("supports custom tools and entities", async () => {
+    const audit = vi.fn();
+    const agent = createMCPDataAgent({
+      database: mockAdapter(),
+      resolveContext: () => context(["members.read"]),
+      audit,
+    });
+
+    agent.defineEntity({
+      name: "Member",
+      table: "members",
+      description: "A gym member",
+    });
+
+    agent.registerTool({
+      name: "members.search",
+      description: "Search members",
+      permission: "members.read",
+      handler: async () => ({ items: [] }),
+    });
+
+    const result = await agent.invokeTool("members.search", { q: "ada" });
+    expect(result).toEqual({ items: [] });
+    expect(audit).toHaveBeenCalledWith(
+      expect.objectContaining({ tool: "members.search", status: "success" }),
+    );
+  });
+});