@provenedge/realize-mcp 0.1.0

package/README.md

@@ -0,0 +1,84 @@
+# @provenedge/realize-mcp
+
+MCP server for the [ProvenEdge](https://provenedge.com) Realization Engine. Connects AI agents (Claude Code, Cursor, Windsurf, etc.) to your entities, records, views, relationships, and documents via the [Model Context Protocol](https://modelcontextprotocol.io).
+
+## Quick Start
+
+No install needed — just configure your AI client:
+
+**Claude Code** (`.mcp.json` in project root or `~/.claude/.mcp.json` globally):
+
+```json
+{
+  "mcpServers": {
+    "provenedge": {
+      "command": "npx",
+      "args": ["-y", "@provenedge/realize-mcp"],
+      "env": {
+        "SCAFFOLD_API_URL": "https://api.provenedge.com",
+        "SCAFFOLD_API_KEY": "pe_live_..."
+      }
+    }
+  }
+}
+```
+
+Then restart your AI agent to pick up the new server.
+
+## Getting an API Key
+
+1. Log in to your ProvenEdge workspace
+2. Go to **Settings > API Keys**
+3. Create a key with **READ** or **READ_WRITE** scope
+4. Copy the key (it's only shown once)
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `SCAFFOLD_API_KEY` | Yes | Your API key (`pe_live_...`) |
+| `SCAFFOLD_API_URL` | No | API base URL (defaults to `http://localhost:4000`) |
+
+## Available Tools
+
+27 tools across these categories:
+
+| Category | Tools | Scope |
+|---|---|---|
+| **Entities** | list, get, create, update, delete, stats | READ / READ_WRITE |
+| **Fields** | list, add, update, delete | READ / READ_WRITE |
+| **Records** | list, get, create, update, delete, search | READ / READ_WRITE |
+| **Views** | list, get, create, execute, delete | READ / READ_WRITE |
+| **Relationships** | list, create, get_related, link, unlink | READ / READ_WRITE |
+| **Notes** | list, add | READ / READ_WRITE |
+| **Import** | csv | READ_WRITE |
+| **Audit** | get_audit_log | READ |
+| **Profile** | get_profile, get_storage_usage | READ |
+| **Documents** | list_documents | READ |
+
+## Supported Clients
+
+| Client | Config Location |
+|---|---|
+| **Claude Code** | `.mcp.json` in project root or `~/.claude/.mcp.json` |
+| **Cursor** | Settings > MCP Servers or `~/.cursor/mcp.json` |
+| **Windsurf** | Settings > MCP |
+| **Continue** | `~/.continue/config.json` under `mcpServers` |
+| **Cline** | Settings > MCP Servers |
+
+## Pin a Version
+
+```json
+"args": ["-y", "@provenedge/realize-mcp@0.1.0"]
+```
+
+## Security
+
+- API keys authenticate as USER role (never elevated, even if the user has ADMIN/SUPERADMIN)
+- READ keys can only read data; READ_WRITE keys can modify data
+- Keys can be revoked instantly from the web UI
+- Rate limited: 100 requests/minute per key
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,434 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+var API_URL = process.env.SCAFFOLD_API_URL || "http://localhost:4000";
+var API_KEY = process.env.SCAFFOLD_API_KEY;
+if (!API_KEY) {
+  process.stderr.write(
+    "Error: SCAFFOLD_API_KEY is required. Create one at your Scaffold web UI under API Keys.\n"
+  );
+  process.exit(1);
+}
+async function api(method, path, opts) {
+  const url = new URL(path, API_URL);
+  if (opts?.query) {
+    for (const [k, v] of Object.entries(opts.query)) {
+      if (v !== void 0 && v !== "") url.searchParams.set(k, v);
+    }
+  }
+  try {
+    const res = await fetch(url.toString(), {
+      method,
+      headers: {
+        Authorization: `Bearer ${API_KEY}`,
+        ...opts?.body ? { "Content-Type": "application/json" } : {}
+      },
+      body: opts?.body ? JSON.stringify(opts.body) : void 0
+    });
+    const raw = await res.text();
+    let data;
+    try {
+      data = JSON.parse(raw);
+    } catch {
+      data = raw;
+    }
+    if (!res.ok) {
+      const msg = typeof data === "object" && data !== null && "error" in data ? String(data.error) : raw;
+      return { ok: false, error: msg, status: res.status };
+    }
+    return { ok: true, data };
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
+  }
+}
+function success(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+function error(message) {
+  return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+}
+function respond(result) {
+  return result.ok ? success(result.data) : error(result.error);
+}
+var server = new McpServer({
+  name: "provenedge-scaffold",
+  version: "1.0.0"
+});
+server.tool(
+  "list_entities",
+  "List all entity types in the workspace. Returns names, slugs, field counts, and descriptions.",
+  {},
+  async () => respond(await api("GET", "/entities"))
+);
+server.tool(
+  "get_entity",
+  "Get the full schema for an entity type including every field definition, table settings, and form layout.",
+  { slug: z.string().describe("Entity slug (URL-safe identifier, e.g. 'contacts')") },
+  async ({ slug }) => respond(await api("GET", `/entities/${slug}`))
+);
+server.tool(
+  "create_entity",
+  "Create a new entity type with optional initial fields. Returns the created entity definition.",
+  {
+    name: z.string().describe("Entity name (alphanumeric + underscores only, e.g. 'contacts')"),
+    label: z.string().describe("Display label (e.g. 'Contacts')"),
+    description: z.string().optional().describe("Entity description"),
+    icon: z.string().optional().describe("Tabler icon name (e.g. 'IconUsers')"),
+    iconColor: z.string().optional().describe("Icon color hex (e.g. '#4c6ef5')"),
+    fields: z.record(z.record(z.unknown())).optional().describe(
+      "Initial fields as { fieldName: { label, fieldType, required?, ... } }. fieldType: text, longText, number, email, phone, url, currency, singleSelect, multiSelect, checkbox, date, time, address, location"
+    )
+  },
+  async ({ name, label, description, icon, iconColor, fields }) => {
+    const body = { name, label };
+    if (description) body.description = description;
+    if (icon) body.icon = icon;
+    if (iconColor) body.iconColor = iconColor;
+    if (fields) body.fields = fields;
+    return respond(await api("POST", "/entities", { body }));
+  }
+);
+server.tool(
+  "update_entity",
+  "Update an entity's metadata (label, icon, description, enabled state).",
+  {
+    slug: z.string().describe("Entity slug"),
+    label: z.string().optional(),
+    icon: z.string().optional(),
+    iconColor: z.string().optional(),
+    description: z.string().optional(),
+    enabled: z.boolean().optional(),
+    priority: z.number().optional().describe("Display order priority")
+  },
+  async ({ slug, ...updates }) => {
+    const body = Object.fromEntries(Object.entries(updates).filter(([, v]) => v !== void 0));
+    return respond(await api("PATCH", `/entities/${slug}`, { body }));
+  }
+);
+server.tool(
+  "delete_entity",
+  "Delete an entity type and all its records. This is destructive and cannot be undone.",
+  { slug: z.string().describe("Entity slug") },
+  async ({ slug }) => respond(await api("DELETE", `/entities/${slug}`))
+);
+server.tool(
+  "get_entity_stats",
+  "Get record and relationship counts for an entity.",
+  { slug: z.string().describe("Entity slug") },
+  async ({ slug }) => respond(await api("GET", `/entities/${slug}/stats`))
+);
+server.tool(
+  "list_fields",
+  "List all fields defined on an entity schema.",
+  { entitySlug: z.string().describe("Entity slug") },
+  async ({ entitySlug }) => respond(await api("GET", `/entities/${entitySlug}/fields`))
+);
+server.tool(
+  "add_field",
+  "Add a new field to an entity schema.",
+  {
+    entitySlug: z.string().describe("Entity slug"),
+    name: z.string().describe("Field name (alphanumeric + underscores, e.g. 'email_address')"),
+    definition: z.record(z.unknown()).describe(
+      "Field definition object. Required keys: 'label' (string), 'fieldType' (one of: text, longText, number, email, phone, url, currency, singleSelect, multiSelect, checkbox, date, time, address, location). Optional: required (bool), unique (bool), default (any), options (array of {value, label, color} for select fields), maxLength/minLength (number), minimum/maximum (number), currency: {code, symbol, decimalPlaces, displayCommas}"
+    )
+  },
+  async ({ entitySlug, name, definition }) => respond(await api("POST", `/entities/${entitySlug}/fields`, { body: { name, definition } }))
+);
+server.tool(
+  "update_field",
+  "Update a field definition on an entity (label, required, options, etc.).",
+  {
+    entitySlug: z.string().describe("Entity slug"),
+    fieldName: z.string().describe("Field name to update"),
+    definition: z.record(z.unknown()).describe("Partial field definition with properties to update")
+  },
+  async ({ entitySlug, fieldName, definition }) => respond(await api("PATCH", `/entities/${entitySlug}/fields/${fieldName}`, { body: { definition } }))
+);
+server.tool(
+  "delete_field",
+  "Remove a field from an entity schema. Records keep existing data but the field is hidden.",
+  {
+    entitySlug: z.string().describe("Entity slug"),
+    fieldName: z.string().describe("Field name to delete")
+  },
+  async ({ entitySlug, fieldName }) => respond(await api("DELETE", `/entities/${entitySlug}/fields/${fieldName}`))
+);
+server.tool(
+  "list_records",
+  "List records for an entity with optional filtering, sorting, search, and pagination.",
+  {
+    entitySlug: z.string().describe("Entity slug"),
+    page: z.number().optional().describe("Page number (default 1)"),
+    pageSize: z.number().optional().describe("Records per page, 1-200 (default 25)"),
+    sort: z.string().optional().describe("Field name to sort by"),
+    sortDir: z.enum(["asc", "desc"]).optional().describe("Sort direction (default 'asc')"),
+    search: z.string().optional().describe("Full-text search query"),
+    filter: z.string().optional().describe(
+      'JSON filter object with MongoDB-style operators. Example: {"status": {"$eq": "active"}, "amount": {"$gt": "100"}}. Operators: $eq, $ne, $contains, $gt, $lt, $gte, $lte'
+    ),
+    fields: z.string().optional().describe("Comma-separated field names to include in response")
+  },
+  async ({ entitySlug, page, pageSize, sort, sortDir, search, filter, fields }) => respond(
+    await api("GET", `/entities/${entitySlug}/records`, {
+      query: {
+        page: page?.toString(),
+        pageSize: pageSize?.toString(),
+        sort,
+        sortDir,
+        search,
+        filter,
+        fields
+      }
+    })
+  )
+);
+server.tool(
+  "get_record",
+  "Get a single record by ID with all field data.",
+  {
+    entitySlug: z.string().describe("Entity slug"),
+    recordId: z.string().describe("Record ID")
+  },
+  async ({ entitySlug, recordId }) => respond(await api("GET", `/entities/${entitySlug}/records/${recordId}`))
+);
+server.tool(
+  "create_record",
+  "Create a new record for an entity. Pass field values as key-value pairs in data.",
+  {
+    entitySlug: z.string().describe("Entity slug"),
+    data: z.record(z.unknown()).describe("Record data as { fieldName: value }. Field names must match the entity schema.")
+  },
+  async ({ entitySlug, data }) => respond(await api("POST", `/entities/${entitySlug}/records`, { body: { data } }))
+);
+server.tool(
+  "update_record",
+  "Update an existing record. Only include fields you want to change.",
+  {
+    entitySlug: z.string().describe("Entity slug"),
+    recordId: z.string().describe("Record ID"),
+    data: z.record(z.unknown()).describe("Partial record data with fields to update")
+  },
+  async ({ entitySlug, recordId, data }) => respond(await api("PATCH", `/entities/${entitySlug}/records/${recordId}`, { body: { data } }))
+);
+server.tool(
+  "delete_record",
+  "Delete a single record by ID.",
+  {
+    entitySlug: z.string().describe("Entity slug"),
+    recordId: z.string().describe("Record ID")
+  },
+  async ({ entitySlug, recordId }) => respond(await api("DELETE", `/entities/${entitySlug}/records/${recordId}`))
+);
+server.tool(
+  "search_records",
+  "Full-text search across all fields of an entity.",
+  {
+    entitySlug: z.string().describe("Entity slug"),
+    query: z.string().describe("Search query text")
+  },
+  async ({ entitySlug, query }) => respond(await api("GET", `/entities/${entitySlug}/records/search`, { query: { q: query } }))
+);
+server.tool(
+  "list_views",
+  "List all saved views the current user has access to.",
+  {},
+  async () => respond(await api("GET", "/views"))
+);
+server.tool(
+  "get_view",
+  "Get a saved view definition including its field selection, filters, sort, and parameters.",
+  { viewId: z.string().describe("View ID") },
+  async ({ viewId }) => respond(await api("GET", `/views/${viewId}`))
+);
+server.tool(
+  "create_view",
+  "Create a saved view with field selection, filters, sorting, and optional parameters.",
+  {
+    name: z.string().describe("View name"),
+    entityId: z.string().describe("Base entity ID (not slug \u2014 get from list_entities)"),
+    description: z.string().optional(),
+    icon: z.string().optional(),
+    isShared: z.boolean().optional().describe("Whether other users can see this view"),
+    config: z.record(z.unknown()).describe(
+      "View configuration object with: baseEntityId (string), fields (array of {entityId, fieldName, label, relationshipId?, subField?}), filters? (array of {fieldName, operator, value, entityId?}), sort? ({field, direction: 'asc'|'desc'}), parameters? (array of {name, label, fieldType, required?, defaultValue?})"
+    )
+  },
+  async ({ name, entityId, description, icon, isShared, config }) => {
+    const body = { name, entityId, config };
+    if (description) body.description = description;
+    if (icon) body.icon = icon;
+    if (isShared !== void 0) body.isShared = isShared;
+    return respond(await api("POST", "/views", { body }));
+  }
+);
+server.tool(
+  "execute_view",
+  "Execute a saved view and return the matching records with pagination.",
+  {
+    viewId: z.string().describe("View ID"),
+    page: z.number().optional().describe("Page number (default 1)"),
+    pageSize: z.number().optional().describe("Records per page (default 25)"),
+    viewParams: z.string().optional().describe("JSON object of parameter name \u2192 value for parameterized views")
+  },
+  async ({ viewId, page, pageSize, viewParams }) => respond(
+    await api("GET", `/views/${viewId}/execute`, {
+      query: {
+        page: page?.toString(),
+        pageSize: pageSize?.toString(),
+        viewParams
+      }
+    })
+  )
+);
+server.tool(
+  "delete_view",
+  "Delete a saved view.",
+  { viewId: z.string().describe("View ID") },
+  async ({ viewId }) => respond(await api("DELETE", `/views/${viewId}`))
+);
+server.tool(
+  "list_relationships",
+  "List all relationships for an entity (both as source and target).",
+  { entitySlug: z.string().describe("Entity slug") },
+  async ({ entitySlug }) => respond(await api("GET", `/entities/${entitySlug}/relationships`))
+);
+server.tool(
+  "create_relationship",
+  "Create a relationship between two entity types.",
+  {
+    entitySlug: z.string().describe("Source entity slug"),
+    targetEntityId: z.string().describe("Target entity ID"),
+    name: z.string().describe("Relationship name (alphanumeric)"),
+    label: z.string().describe("Display label (e.g. 'Assigned To')"),
+    reverseLabel: z.string().describe("Reverse label (e.g. 'Assigned Contacts')"),
+    cardinality: z.enum(["ONE_TO_MANY", "MANY_TO_MANY"]).describe("Relationship cardinality")
+  },
+  async ({ entitySlug, ...body }) => respond(await api("POST", `/entities/${entitySlug}/relationships`, { body }))
+);
+server.tool(
+  "get_related_records",
+  "Get records linked to a specific record through a relationship.",
+  {
+    entitySlug: z.string().describe("Entity slug"),
+    recordId: z.string().describe("Source record ID"),
+    relationshipId: z.string().describe("Relationship ID")
+  },
+  async ({ entitySlug, recordId, relationshipId }) => respond(await api("GET", `/entities/${entitySlug}/records/${recordId}/related/${relationshipId}`))
+);
+server.tool(
+  "link_records",
+  "Link one or more records to a source record through a relationship.",
+  {
+    entitySlug: z.string().describe("Source entity slug"),
+    recordId: z.string().describe("Source record ID"),
+    relationshipId: z.string().describe("Relationship ID"),
+    targetRecordIds: z.array(z.string()).describe("Array of target record IDs to link")
+  },
+  async ({ entitySlug, recordId, relationshipId, targetRecordIds }) => respond(
+    await api("POST", `/entities/${entitySlug}/records/${recordId}/related/${relationshipId}`, {
+      body: { targetRecordIds }
+    })
+  )
+);
+server.tool(
+  "unlink_records",
+  "Remove a link between two records in a relationship.",
+  {
+    entitySlug: z.string().describe("Source entity slug"),
+    recordId: z.string().describe("Source record ID"),
+    relationshipId: z.string().describe("Relationship ID"),
+    targetRecordId: z.string().describe("Target record ID to unlink")
+  },
+  async ({ entitySlug, recordId, relationshipId, targetRecordId }) => respond(
+    await api(
+      "DELETE",
+      `/entities/${entitySlug}/records/${recordId}/related/${relationshipId}/${targetRecordId}`
+    )
+  )
+);
+server.tool(
+  "list_notes",
+  "List all notes on a record, newest first.",
+  {
+    entitySlug: z.string().describe("Entity slug"),
+    recordId: z.string().describe("Record ID")
+  },
+  async ({ entitySlug, recordId }) => respond(await api("GET", `/entities/${entitySlug}/records/${recordId}/notes`))
+);
+server.tool(
+  "add_note",
+  "Add a text note to a record.",
+  {
+    entitySlug: z.string().describe("Entity slug"),
+    recordId: z.string().describe("Record ID"),
+    content: z.string().min(1).max(1e4).describe("Note text content")
+  },
+  async ({ entitySlug, recordId, content }) => respond(await api("POST", `/entities/${entitySlug}/records/${recordId}/notes`, { body: { content } }))
+);
+server.tool(
+  "import_csv",
+  "Import records from CSV data into an entity. Optionally creates the entity if it doesn't exist.",
+  {
+    entitySlug: z.string().describe("Target entity slug"),
+    csvContent: z.string().describe("Raw CSV content (headers in first row)"),
+    delimiter: z.string().optional().describe("Column delimiter (default ',')"),
+    createIfMissing: z.boolean().optional().describe("Auto-create entity from CSV headers if it doesn't exist")
+  },
+  async ({ entitySlug, csvContent, delimiter, createIfMissing }) => {
+    const body = { entitySlug, csvContent };
+    if (delimiter) body.delimiter = delimiter;
+    if (createIfMissing !== void 0) body.createIfMissing = createIfMissing;
+    return respond(await api("POST", "/import/csv", { body }));
+  }
+);
+server.tool(
+  "get_audit_log",
+  "Get the audit log for an entity showing create, update, and delete history.",
+  {
+    entitySlug: z.string().describe("Entity slug"),
+    recordId: z.string().optional().describe("Optional record ID to filter to a specific record"),
+    page: z.number().optional(),
+    pageSize: z.number().optional()
+  },
+  async ({ entitySlug, recordId, page, pageSize }) => {
+    const path = recordId ? `/entities/${entitySlug}/records/${recordId}/audit` : `/entities/${entitySlug}/audit`;
+    return respond(
+      await api("GET", path, {
+        query: { page: page?.toString(), pageSize: pageSize?.toString() }
+      })
+    );
+  }
+);
+server.tool(
+  "get_profile",
+  "Get the current user's profile (name, email, role, storage usage).",
+  {},
+  async () => respond(await api("GET", "/profile"))
+);
+server.tool(
+  "get_storage_usage",
+  "Get the current user's file storage usage and limits.",
+  {},
+  async () => respond(await api("GET", "/profile/storage"))
+);
+server.tool(
+  "list_documents",
+  "List all documents uploaded by the current user.",
+  {},
+  async () => respond(await api("GET", "/documents"))
+);
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write(`ProvenEdge MCP server running \u2014 API: ${API_URL}
+`);
+}
+main().catch((e) => {
+  process.stderr.write(`Fatal: ${e}
+`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@provenedge/realize-mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "private": false,
+  "description": "MCP server for ProvenEdge Realization Engine — connect AI agents to your entities, records, views, and documents",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "provenedge",
+    "realization-engine",
+    "ai",
+    "claude",
+    "cursor"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/provenedge/app-scaffold.git",
+    "directory": "packages/mcp-server"
+  },
+  "homepage": "https://provenedge.com",
+  "bin": {
+    "realize-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3"
+  }
+}