@adminforge/ai 0.2.0

package/.turbo/turbo-build.log

@@ -0,0 +1,19 @@
+
+> @adminforge/ai@0.2.0 build /home/runner/work/AdminForge/AdminForge/packages/ai
+> tsup
+
+CLI Building entry: src/cli.ts, src/index.ts
+CLI Using tsconfig: tsconfig.json
+CLI tsup v8.5.1
+CLI Using tsup config: /home/runner/work/AdminForge/AdminForge/packages/ai/tsup.config.ts
+CLI Target: es2022
+CLI Cleaning output folder
+ESM Build start
+ESM dist/cli.js            2.04 KB
+ESM dist/chunk-QNQC6QCL.js 372.00 B
+ESM dist/index.js          10.26 KB
+ESM ⚡️ Build success in 17ms
+DTS Build start
+DTS ⚡️ Build success in 2659ms
+DTS dist/cli.d.ts   13.00 B
+DTS dist/index.d.ts 13.00 B

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @adminforge/ai
+
+## 0.2.0
+
+### Minor Changes
+
+- 473b0a5: Added high-level helpers, CLI migrate command, and media upload support.
+- 9ddaafa: Initial public release of the AdminForge ecosystem. Includes unified core framework and AI orchestration layer.
+
+### Patch Changes
+
+- Updated dependencies [473b0a5]
+- Updated dependencies [9ddaafa]
+  - adminforge@0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AdminForge Contributors
+
+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/dist/chunk-QNQC6QCL.js

@@ -0,0 +1,10 @@
+// ../../node_modules/.pnpm/tsup@8.5.1_jiti@2.7.0_postcss@8.4.31_tsx@4.21.0_typescript@5.9.3/node_modules/tsup/assets/esm_shims.js
+import path from "path";
+import { fileURLToPath } from "url";
+var getFilename = () => fileURLToPath(import.meta.url);
+var getDirname = () => path.dirname(getFilename());
+var __dirname = /* @__PURE__ */ getDirname();
+
+export {
+  __dirname
+};

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/cli.js

@@ -0,0 +1,41 @@
+import {
+  __dirname
+} from "./chunk-QNQC6QCL.js";
+
+// src/cli.ts
+import { Command } from "commander";
+import { generateAgentToken } from "adminforge/next";
+import { spawn } from "child_process";
+import path from "path";
+var program = new Command();
+program.name("adminforge-ai").description("CLI to manage AdminForge AI Orchestration and MCP Server").version("0.2.0");
+program.command("start").description("Start the MCP server on stdio").option("-c, --config <path>", "Path to adminforge.ts", "./adminforge.ts").option("-u, --api-url <url>", "Remote AdminForge API URL (Proxy Mode)").option("-t, --token <token>", "Agent Token for Proxy Mode").option("-d, --db <url>", "Database URL (Local Mode)").action((options) => {
+  console.error("\u{1F680} Starting AdminForge AI MCP Server...");
+  const env = { ...process.env };
+  if (options.config) env.ADMINFORGE_CONFIG_PATH = options.config;
+  if (options.db) env.DATABASE_URL = options.db;
+  if (options.apiUrl) env.ADMINFORGE_API_URL = options.apiUrl;
+  if (options.token) env.ADMINFORGE_TOKEN = options.token;
+  const serverPath = path.join(__dirname, "index.js");
+  const child = spawn("node", [serverPath], {
+    env,
+    stdio: ["inherit", "inherit", "inherit"]
+  });
+  child.on("exit", (code) => {
+    process.exit(code || 0);
+  });
+});
+program.command("token").description("Generate a scoped Agent Token").requiredOption("-u, --user <id>", "User ID").requiredOption("-r, --role <name>", "User Role").requiredOption("-s, --scopes <list>", "Comma-separated scopes (e.g., posts:create,posts:read)").action((options) => {
+  const scopes = options.scopes.split(",").map((s) => s.trim());
+  try {
+    const token = generateAgentToken(options.user, options.role, scopes);
+    console.log("\n\u{1F511} Generated Agent Token:");
+    console.log("-----------------------------------------");
+    console.log(token);
+    console.log("-----------------------------------------");
+    console.log("Keep this token secure. It expires in 10 minutes.");
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+  }
+});
+program.parse();

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/index.js

@@ -0,0 +1,283 @@
+import "./chunk-QNQC6QCL.js";
+
+// src/index.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+import { createDbClient } from "adminforge";
+import { createController } from "adminforge/next";
+import { verifyAgentToken } from "adminforge/next";
+
+// src/orchestrator.ts
+import { z } from "zod";
+var ContentAgent = class {
+  constructor(config, db) {
+    this.config = config;
+    this.db = db;
+  }
+  config;
+  db;
+  /**
+   * 1. Validate: Deterministic check against Zod schema
+   */
+  async validate(collectionName, data) {
+    const collection = this.getCollection(collectionName);
+    const shape = {};
+    for (const [name, field] of Object.entries(collection.fields)) {
+      shape[name] = field.validation;
+    }
+    const schema = z.object(shape);
+    const result = schema.safeParse(data);
+    if (!result.success) {
+      return {
+        valid: false,
+        errors: result.error.errors.map((e) => ({
+          path: e.path.join("."),
+          message: e.message
+        }))
+      };
+    }
+    return { valid: true, data: result.data };
+  }
+  /**
+   * 2. Resolve: Handle relations (names -> IDs)
+   */
+  async resolveRelations(collectionName, data) {
+    const collection = this.getCollection(collectionName);
+    const resolvedData = { ...data };
+    const unresolved = [];
+    for (const [name, field] of Object.entries(collection.fields)) {
+      if (field.type === "relation") {
+        const val = data[name];
+        if (typeof val === "string" && val.length > 0 && !/^[a-z0-9]{25}$/.test(val)) {
+          const targetCollection = field.ui.props?.to || field.db.references?.model;
+          if (!targetCollection) continue;
+          const targetCollectionDef = this.config.collections.find((c) => c.name === targetCollection);
+          if (!targetCollectionDef) continue;
+          console.error(`[Orchestrator] Resolving relation for ${name}: "${val}"...`);
+          const searchFields = ["name", "title", "label"].filter((f) => targetCollectionDef.fields[f]);
+          const orQuery = searchFields.map((f) => ({
+            [f]: {
+              contains: val,
+              mode: "insensitive"
+            }
+          }));
+          if (orQuery.length === 0) {
+            unresolved.push(name);
+            continue;
+          }
+          const results = await this.db.findMany(targetCollection, {
+            where: { OR: orQuery },
+            take: 1
+          });
+          if (results.length > 0) {
+            resolvedData[name] = results[0].id;
+          } else {
+            unresolved.push(name);
+          }
+        }
+      }
+    }
+    return { resolvedData, unresolved };
+  }
+  /**
+   * 3. Orchestrate: The main loop
+   */
+  async execute(prompt, collectionName, session) {
+    const collection = this.getCollection(collectionName);
+    console.error(`[ContentAgent] Orchestrating ${collectionName} for prompt: "${prompt}"`);
+    return {
+      status: "ready"
+    };
+  }
+  /**
+   * Helper to enrich the schema with AI hints for the agent.
+   */
+  getEnrichedSchema(collectionName) {
+    const collection = this.getCollection(collectionName);
+    return Object.entries(collection.fields).map(([name, field]) => ({
+      name,
+      type: field.type,
+      required: field.meta?.required ?? false
+    }));
+  }
+  getCollection(name) {
+    const collection = this.config.collections.find((c) => c.name === name);
+    if (!collection) throw new Error(`Collection ${name} not found`);
+    return collection;
+  }
+};
+
+// src/index.ts
+import path from "path";
+import fs from "fs";
+console.log = (...args) => console.error(...args);
+var CONFIG_PATH_ENV = process.env.ADMINFORGE_CONFIG_PATH;
+async function loadConfig() {
+  const cwd = process.cwd();
+  const fallbacks = [
+    CONFIG_PATH_ENV,
+    "/home/yuzaga/Code/AdminForge/apps/example/src/config/adminforge.ts",
+    "./apps/example/src/config/adminforge.ts",
+    "../../apps/example/src/config/adminforge.ts"
+  ].filter(Boolean);
+  let resolvedPath = null;
+  for (const p of fallbacks) {
+    const absolute = path.isAbsolute(p) ? p : path.resolve(cwd, p);
+    if (fs.existsSync(absolute)) {
+      resolvedPath = absolute;
+      break;
+    }
+  }
+  if (!resolvedPath) throw new Error("Could not find adminforge.ts config file.");
+  const importPath = path.isAbsolute(resolvedPath) ? `file://${resolvedPath}` : resolvedPath;
+  const mod = await import(importPath);
+  return { config: mod.config, path: resolvedPath };
+}
+var server = new Server(
+  { name: "adminforge-ai", version: "0.3.0" },
+  { capabilities: { tools: {} } }
+);
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "get_form_schema",
+        description: "Returns schema + AI hints for a collection. REQUIRES TOKEN.",
+        inputSchema: {
+          type: "object",
+          properties: { collection: { type: "string" }, token: { type: "string" } },
+          required: ["collection", "token"]
+        }
+      },
+      {
+        name: "list_records",
+        description: "Lists records from a collection. REQUIRES TOKEN.",
+        inputSchema: {
+          type: "object",
+          properties: { collection: { type: "string" }, limit: { type: "number" }, token: { type: "string" } },
+          required: ["collection", "token"]
+        }
+      },
+      {
+        name: "search_records",
+        description: "Search records in a collection by keyword. REQUIRES TOKEN.",
+        inputSchema: {
+          type: "object",
+          properties: { collection: { type: "string" }, query: { type: "string" }, token: { type: "string" } },
+          required: ["collection", "query", "token"]
+        }
+      },
+      {
+        name: "create_record",
+        description: "Creates record in AdminForge. REQUIRES TOKEN.",
+        inputSchema: {
+          type: "object",
+          properties: { collection: { type: "string" }, data: { type: "object" }, token: { type: "string" } },
+          required: ["collection", "data", "token"]
+        }
+      },
+      {
+        name: "update_record",
+        description: "Updates an existing record. REQUIRES TOKEN.",
+        inputSchema: {
+          type: "object",
+          properties: { collection: { type: "string" }, id: { type: "string" }, data: { type: "object" }, token: { type: "string" } },
+          required: ["collection", "id", "data", "token"]
+        }
+      },
+      {
+        name: "delete_record",
+        description: "Deletes a record. REQUIRES TOKEN.",
+        inputSchema: {
+          type: "object",
+          properties: { collection: { type: "string" }, id: { type: "string" }, token: { type: "string" } },
+          required: ["collection", "id", "token"]
+        }
+      },
+      {
+        name: "upload_media",
+        description: "Uploads a file (base64) to the media directory. REQUIRES TOKEN.",
+        inputSchema: {
+          type: "object",
+          properties: { filename: { type: "string" }, base64: { type: "string" }, token: { type: "string" } },
+          required: ["filename", "base64", "token"]
+        }
+      }
+    ]
+  };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  const token = args.token || process.env.ADMINFORGE_TOKEN;
+  if (!token) {
+    throw new Error("Unauthorized: Missing token");
+  }
+  const agentSession = verifyAgentToken(token);
+  const { config, path: configPath } = await loadConfig();
+  const db = createDbClient(config);
+  const agent = new ContentAgent(config, db);
+  const securityContext = { agent: agentSession, source: "agent" };
+  switch (name) {
+    case "get_form_schema": {
+      const col = args.collection;
+      const fields = agent.getEnrichedSchema(col);
+      return { content: [{ type: "text", text: JSON.stringify({ collection: col, fields }, null, 2) }] };
+    }
+    case "list_records": {
+      const col = args.collection;
+      const limit = args.limit || 50;
+      const results = await db.findMany(col, { take: limit });
+      return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
+    }
+    case "search_records": {
+      const col = args.collection;
+      const query = args.query;
+      const collection = config.collections.find((c) => c.name === col);
+      const controller = createController(collection, db, securityContext);
+      const results = await controller.list({ search: query });
+      return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
+    }
+    case "create_record": {
+      const col = args.collection;
+      const collection = config.collections.find((c) => c.name === col);
+      const controller = createController(collection, db, securityContext);
+      const result = await controller.create(args.data);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    case "update_record": {
+      const col = args.collection;
+      const id = args.id;
+      const collection = config.collections.find((c) => c.name === col);
+      const controller = createController(collection, db, securityContext);
+      const result = await controller.update(id, args.data);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    case "delete_record": {
+      const col = args.collection;
+      const id = args.id;
+      const collection = config.collections.find((c) => c.name === col);
+      const controller = createController(collection, db, securityContext);
+      const result = await controller.delete(id);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    case "upload_media": {
+      const filename = args.filename;
+      const base64 = args.base64;
+      const buffer = Buffer.from(base64, "base64");
+      const configDir = path.dirname(configPath);
+      const uploadDir = path.resolve(configDir, "../../public/uploads");
+      if (!fs.existsSync(uploadDir)) fs.mkdirSync(uploadDir, { recursive: true });
+      const fullPath = path.join(uploadDir, filename);
+      fs.writeFileSync(fullPath, buffer);
+      return { content: [{ type: "text", text: JSON.stringify({ url: `/uploads/${filename}`, status: "uploaded" }, null, 2) }] };
+    }
+    default:
+      throw new Error(`Tool ${name} not found`);
+  }
+});
+var transport = new StdioServerTransport();
+server.connect(transport).catch(console.error);

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@adminforge/ai",
+  "version": "0.2.0",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/YuZaGa/AdminForge.git",
+    "directory": "packages/ai"
+  },
+  "type": "module",
+  "bin": {
+    "adminforge-ai": "./dist/cli.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.1",
+    "commander": "^12.1.0",
+    "zod": "^3.24.0",
+    "adminforge": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.1",
+    "tsx": "^4.19.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/cli.js"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,69 @@
+import { Command } from "commander";
+import { generateAgentToken } from "adminforge/next";
+import { spawn } from "child_process";
+import path from "path";
+import fs from "fs";
+
+const program = new Command();
+
+program
+  .name("adminforge-ai")
+  .description("CLI to manage AdminForge AI Orchestration and MCP Server")
+  .version("0.2.0");
+
+/**
+ * Command: Start the MCP Server
+ */
+program
+  .command("start")
+  .description("Start the MCP server on stdio")
+  .option("-c, --config <path>", "Path to adminforge.ts", "./adminforge.ts")
+  .option("-u, --api-url <url>", "Remote AdminForge API URL (Proxy Mode)")
+  .option("-t, --token <token>", "Agent Token for Proxy Mode")
+  .option("-d, --db <url>", "Database URL (Local Mode)")
+  .action((options) => {
+    console.error("🚀 Starting AdminForge AI MCP Server...");
+    
+    // Prepare environment
+    const env = { ...process.env };
+    if (options.config) env.ADMINFORGE_CONFIG_PATH = options.config;
+    if (options.db) env.DATABASE_URL = options.db;
+    if (options.apiUrl) env.ADMINFORGE_API_URL = options.apiUrl;
+    if (options.token) env.ADMINFORGE_TOKEN = options.token;
+
+    // Run the MCP server process
+    const serverPath = path.join(__dirname, "index.js");
+    const child = spawn("node", [serverPath], {
+      env,
+      stdio: ["inherit", "inherit", "inherit"],
+    });
+
+    child.on("exit", (code) => {
+      process.exit(code || 0);
+    });
+  });
+
+/**
+ * Command: Generate Token
+ */
+program
+  .command("token")
+  .description("Generate a scoped Agent Token")
+  .requiredOption("-u, --user <id>", "User ID")
+  .requiredOption("-r, --role <name>", "User Role")
+  .requiredOption("-s, --scopes <list>", "Comma-separated scopes (e.g., posts:create,posts:read)")
+  .action((options) => {
+    const scopes = options.scopes.split(",").map((s: string) => s.trim());
+    try {
+      const token = generateAgentToken(options.user, options.role, scopes);
+      console.log("\n🔑 Generated Agent Token:");
+      console.log("-----------------------------------------");
+      console.log(token);
+      console.log("-----------------------------------------");
+      console.log("Keep this token secure. It expires in 10 minutes.");
+    } catch (error: any) {
+      console.error(`Error: ${error.message}`);
+    }
+  });
+
+program.parse();

package/src/index.ts

@@ -0,0 +1,210 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { createDbClient } from "adminforge";
+import { createController } from "adminforge/next";
+import { verifyAgentToken, type SecurityContext } from "adminforge/next";
+import { ContentAgent } from "./orchestrator.js";
+import path from "path";
+import fs from "fs";
+
+// --- GLOBAL STDOUT PROTECTION ---
+console.log = (...args) => console.error(...args);
+
+/**
+ * --- Configuration & State ---
+ */
+const CONFIG_PATH_ENV = process.env.ADMINFORGE_CONFIG_PATH;
+async function loadConfig() {
+  const cwd = process.cwd();
+  const fallbacks = [
+    CONFIG_PATH_ENV,
+    "/home/yuzaga/Code/AdminForge/apps/example/src/config/adminforge.ts",
+    "./apps/example/src/config/adminforge.ts",
+    "../../apps/example/src/config/adminforge.ts",
+  ].filter(Boolean) as string[];
+
+  let resolvedPath: string | null = null;
+  for (const p of fallbacks) {
+    const absolute = path.isAbsolute(p) ? p : path.resolve(cwd, p);
+    if (fs.existsSync(absolute)) {
+      resolvedPath = absolute;
+      break;
+    }
+  }
+
+  if (!resolvedPath) throw new Error("Could not find adminforge.ts config file.");
+  const importPath = path.isAbsolute(resolvedPath) ? `file://${resolvedPath}` : resolvedPath;
+  const mod = await import(importPath);
+  return { config: mod.config, path: resolvedPath };
+}
+
+/**
+ * --- MCP Server Implementation ---
+ */
+const server = new Server(
+  { name: "adminforge-ai", version: "0.3.0" },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "get_form_schema",
+        description: "Returns schema + AI hints for a collection. REQUIRES TOKEN.",
+        inputSchema: {
+          type: "object",
+          properties: { collection: { type: "string" }, token: { type: "string" } },
+          required: ["collection", "token"],
+        },
+      },
+      {
+        name: "list_records",
+        description: "Lists records from a collection. REQUIRES TOKEN.",
+        inputSchema: {
+          type: "object",
+          properties: { collection: { type: "string" }, limit: { type: "number" }, token: { type: "string" } },
+          required: ["collection", "token"],
+        },
+      },
+      {
+        name: "search_records",
+        description: "Search records in a collection by keyword. REQUIRES TOKEN.",
+        inputSchema: {
+          type: "object",
+          properties: { collection: { type: "string" }, query: { type: "string" }, token: { type: "string" } },
+          required: ["collection", "query", "token"],
+        },
+      },
+      {
+        name: "create_record",
+        description: "Creates record in AdminForge. REQUIRES TOKEN.",
+        inputSchema: {
+          type: "object",
+          properties: { collection: { type: "string" }, data: { type: "object" }, token: { type: "string" } },
+          required: ["collection", "data", "token"],
+        },
+      },
+      {
+        name: "update_record",
+        description: "Updates an existing record. REQUIRES TOKEN.",
+        inputSchema: {
+          type: "object",
+          properties: { collection: { type: "string" }, id: { type: "string" }, data: { type: "object" }, token: { type: "string" } },
+          required: ["collection", "id", "data", "token"],
+        },
+      },
+      {
+        name: "delete_record",
+        description: "Deletes a record. REQUIRES TOKEN.",
+        inputSchema: {
+          type: "object",
+          properties: { collection: { type: "string" }, id: { type: "string" }, token: { type: "string" } },
+          required: ["collection", "id", "token"],
+        },
+      },
+      {
+        name: "upload_media",
+        description: "Uploads a file (base64) to the media directory. REQUIRES TOKEN.",
+        inputSchema: {
+          type: "object",
+          properties: { filename: { type: "string" }, base64: { type: "string" }, token: { type: "string" } },
+          required: ["filename", "base64", "token"],
+        },
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  const token = (args as any).token || process.env.ADMINFORGE_TOKEN;
+  
+  if (!token) {
+    throw new Error("Unauthorized: Missing token");
+  }
+
+  // --- DB TOOLS ---
+  const agentSession = verifyAgentToken(token!);
+  const { config, path: configPath } = await loadConfig();
+  const db = createDbClient(config);
+  const agent = new ContentAgent(config, db);
+
+  const securityContext: SecurityContext = { agent: agentSession, source: "agent" };
+
+  switch (name) {
+    case "get_form_schema": {
+      const col = (args as any).collection;
+      const fields = agent.getEnrichedSchema(col);
+      return { content: [{ type: "text", text: JSON.stringify({ collection: col, fields }, null, 2) }] };
+    }
+
+    case "list_records": {
+      const col = (args as any).collection;
+      const limit = (args as any).limit || 50;
+      const results = await db.findMany(col, { take: limit });
+      return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
+    }
+
+    case "search_records": {
+      const col = (args as any).collection;
+      const query = (args as any).query;
+      const collection = config.collections.find((c: any) => c.name === col)!;
+      const controller = createController(collection, db, securityContext);
+      const results = await controller.list({ search: query });
+      return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
+    }
+
+    case "create_record": {
+      const col = (args as any).collection;
+      const collection = config.collections.find((c: any) => c.name === col)!;
+      const controller = createController(collection, db, securityContext);
+      const result = await controller.create((args as any).data);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+
+    case "update_record": {
+      const col = (args as any).collection;
+      const id = (args as any).id;
+      const collection = config.collections.find((c: any) => c.name === col)!;
+      const controller = createController(collection, db, securityContext);
+      const result = await controller.update(id, (args as any).data);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+
+    case "delete_record": {
+      const col = (args as any).collection;
+      const id = (args as any).id;
+      const collection = config.collections.find((c: any) => c.name === col)!;
+      const controller = createController(collection, db, securityContext);
+      const result = await controller.delete(id);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+
+    case "upload_media": {
+      const filename = (args as any).filename;
+      const base64 = (args as any).base64;
+      const buffer = Buffer.from(base64, "base64");
+      
+      // Resolve upload directory relative to config
+      const configDir = path.dirname(configPath);
+      const uploadDir = path.resolve(configDir, "../../public/uploads");
+      
+      if (!fs.existsSync(uploadDir)) fs.mkdirSync(uploadDir, { recursive: true });
+      const fullPath = path.join(uploadDir, filename);
+      fs.writeFileSync(fullPath, buffer);
+      
+      return { content: [{ type: "text", text: JSON.stringify({ url: `/uploads/${filename}`, status: "uploaded" }, null, 2) }] };
+    }
+
+    default:
+      throw new Error(`Tool ${name} not found`);
+  }
+});
+
+const transport = new StdioServerTransport();
+server.connect(transport).catch(console.error);

package/src/orchestrator.ts

@@ -0,0 +1,127 @@
+import { type AdminForgeConfig, type CollectionDefinition } from "adminforge";
+import { type DbClient } from "adminforge";
+import { createController } from "adminforge/next";
+import { z } from "zod";
+
+/**
+ * --- ContentAgent Orchestrator ---
+ * A deterministic state machine for AI-assisted content creation.
+ */
+export class ContentAgent {
+  constructor(
+    private config: AdminForgeConfig,
+    private db: DbClient
+  ) {}
+
+  /**
+   * 1. Validate: Deterministic check against Zod schema
+   */
+  async validate(collectionName: string, data: Record<string, any>) {
+    const collection = this.getCollection(collectionName);
+    
+    // Build validation schema from core field definitions
+    const shape: Record<string, z.ZodTypeAny> = {};
+    for (const [name, field] of Object.entries(collection.fields)) {
+      shape[name] = field.validation;
+    }
+    const schema = z.object(shape);
+
+    const result = schema.safeParse(data);
+    
+    if (!result.success) {
+      return {
+        valid: false,
+        errors: result.error.errors.map(e => ({
+          path: e.path.join("."),
+          message: e.message
+        }))
+      };
+    }
+
+    return { valid: true, data: result.data };
+  }
+
+  /**
+   * 2. Resolve: Handle relations (names -> IDs)
+   */
+  async resolveRelations(collectionName: string, data: Record<string, any>) {
+    const collection = this.getCollection(collectionName);
+    const resolvedData = { ...data };
+    const unresolved: string[] = [];
+
+    for (const [name, field] of Object.entries(collection.fields) as [string, any][]) {
+      if (field.type === "relation") {
+        const val = data[name];
+        
+        // If it's a raw string (not an ID), try to resolve it
+        if (typeof val === "string" && val.length > 0 && !/^[a-z0-9]{25}$/.test(val)) {
+          const targetCollection = field.ui.props?.to || field.db.references?.model;
+          if (!targetCollection) continue;
+
+          const targetCollectionDef = this.config.collections.find(c => c.name === targetCollection);
+          if (!targetCollectionDef) continue;
+
+          console.error(`[Orchestrator] Resolving relation for ${name}: "${val}"...`);
+          
+          // Build a safe query based on known common search fields
+          const searchFields = ["name", "title", "label"].filter(f => targetCollectionDef.fields[f]);
+          const orQuery = searchFields.map(f => ({ 
+            [f]: { 
+              contains: val,
+              mode: "insensitive" 
+            } 
+          }));
+
+          if (orQuery.length === 0) {
+            unresolved.push(name);
+            continue;
+          }
+
+          const results = await this.db.findMany(targetCollection, {
+            where: { OR: orQuery },
+            take: 1,
+          });
+
+          if (results.length > 0) {
+            resolvedData[name] = (results[0] as any).id;
+          } else {
+            unresolved.push(name);
+          }
+        }
+      }
+    }
+
+    return { resolvedData, unresolved };
+  }
+
+  /**
+   * 3. Orchestrate: The main loop
+   */
+  async execute(prompt: string, collectionName: string, session: any) {
+    const collection = this.getCollection(collectionName);
+    console.error(`[ContentAgent] Orchestrating ${collectionName} for prompt: "${prompt}"`);
+
+    return {
+      status: "ready"
+    };
+  }
+
+  /**
+   * Helper to enrich the schema with AI hints for the agent.
+   */
+  getEnrichedSchema(collectionName: string) {
+    const collection = this.getCollection(collectionName);
+
+    return Object.entries(collection.fields).map(([name, field]: [string, any]) => ({
+      name,
+      type: field.type,
+      required: field.meta?.required ?? false,
+    }));
+  }
+
+  private getCollection(name: string): CollectionDefinition {
+    const collection = this.config.collections.find((c) => c.name === name);
+    if (!collection) throw new Error(`Collection ${name} not found`);
+    return collection;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["node"]
+  },
+  "include": ["src"]
+}

package/tsup.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts", "src/cli.ts"],
+  format: ["esm"],
+  dts: true,
+  clean: true,
+  shims: true,
+  outDir: "dist",
+  target: "es2022",
+});