@nestcorehq/mcp-server 1.6.0 → 1.8.0

package/src/sdk/nestcore.client.ts

@@ -157,7 +157,24 @@ export class NestCoreClient {
         'are limited to the user who created the project. Browsing and row edits work for every workspace member; ' +
         'ask the project owner to run this operation.';
     }
-    throw new ApiError(text, response.status);
+    const body = errorBody as Record<string, unknown>;
+    const code = typeof body.code === 'string' ? body.code : undefined;
+    if (code === 'AGENT_PROJECT_RESTRICTED') {
+      text += '. This is an Agent project (one PC running NestCore Agent); it only holds the agent schema, agent-* buckets and the agent functions. Use an App project for app data.';
+    } else if (code === 'PROJECT_PAUSED') {
+      text += '. The project is paused (plan limit or owner): reads work in Studio, everything else waits until it is resumed or the plan is upgraded.';
+    } else if (code === 'CREDITS_EXHAUSTED') {
+      text += body.reason === 'spend_cap'
+        ? ". The workspace's monthly AI credit cap is reached: raise or clear it (nestcore_set_credit_cap), add the project's own provider key, or wait for next month."
+        : '. The workspace has no AI credit left: buy a pack (nestcore_buy_credits gives a checkout link for a human to pay) or add the project\'s own provider key.';
+      if (typeof body.buyUrl === 'string') text += ` Buy credit: ${body.buyUrl}`;
+      text += ' Do not retry the call until one of these is done.';
+    } else if (code === 'QUOTA_EXCEEDED' && (body.reason === 'ai_collections' || body.quota === 'ai_collections')) {
+      text += '. The project has as many AI collections as its plan allows (Free 3, Starter 20, Pro 100): delete one or upgrade the plan.';
+      if (typeof body.upgradeUrl === 'string') text += ` Upgrade: ${body.upgradeUrl}`;
+    }
+    // Keep the API's own code and structured fields (e.g. QUOTA_EXCEEDED's kind/reason/upgradeUrl).
+    throw new ApiError(text, response.status, code, body);
   }
 
   /**
@@ -307,18 +324,62 @@ export class NestCoreClient {
 
   // ─── Projects ───
 
-  async createProject(data: { name: string; description?: string }) {
+  async createProject(data: {
+    name: string;
+    description?: string;
+    kind?: 'app' | 'agent';
+    agent?: { deviceName: string; os: string; agentVersion?: string; createdByClient?: string };
+  }) {
     return this.request<Record<string, unknown>>('POST', EP.PROJECTS.CREATE, data);
   }
 
-  async listProjects() {
-    return this.request<unknown[]>('GET', EP.PROJECTS.LIST);
+  async listProjects(kind?: 'app' | 'agent') {
+    return this.request<unknown[]>('GET', EP.PROJECTS.LIST, undefined, kind ? { query: { kind } } : undefined);
+  }
+
+  /** Can this workspace create one more project of a kind? Carries the upgrade link when not. */
+  async getProjectEligibility(kind: 'app' | 'agent' = 'app') {
+    return this.request<Record<string, unknown>>('GET', EP.PROJECTS.ELIGIBILITY, undefined, { query: { kind } });
+  }
+
+  /** Pause a project, or resume it (resuming is checked against the plan). */
+  async setProjectStatus(projectId: string, status: 'active' | 'paused') {
+    return this.request<Record<string, unknown>>('POST', EP.PROJECTS.STATUS(projectId), { status });
+  }
+
+  // ─── Workspace AI credit ───
+
+  /** Balance, monthly cap, this month's spend, availability, packs, margin and the recent ledger. */
+  async getCredits() {
+    return this.request<Record<string, unknown>>('GET', EP.BILLING.CREDITS);
+  }
+
+  /** A Stripe Checkout URL (one-time payment) for a credit pack; nothing is charged until a human pays it. */
+  async createCreditCheckout(pack: string, ref?: string) {
+    return this.request<{ url: string; pack: Record<string, unknown>; ref: string | null }>(
+      'POST', EP.BILLING.CREDITS_CHECKOUT, ref ? { pack, ref } : { pack },
+    );
+  }
+
+  /** Set the workspace's monthly cap on credit spend (USD), or clear it with null. Returns the new summary. */
+  async setCreditCap(monthlyCapUsd: number | null) {
+    return this.request<Record<string, unknown>>('PUT', EP.BILLING.CREDITS_CAP, { monthlyCapUsd });
   }
 
   async getProject(projectId: string) {
     return this.request<Record<string, unknown>>('GET', EP.PROJECTS.GET(projectId));
   }
 
+  /**
+   * Project branches (Production + Development). `projectId` may be the
+   * Production project or any of its branches; `sub` is appended to
+   * `/projects/:id/branches` (e.g. `/development/promote`).
+   */
+  async branches<T = Record<string, unknown>>(method: 'GET' | 'POST' | 'DELETE', projectId: string, sub = '', body?: unknown): Promise<T> {
+    const res = await this.request<{ data?: T } & Record<string, unknown>>(method, `/projects/${encodeURIComponent(projectId)}/branches${sub}`, body);
+    return (res && 'data' in res ? res.data : res) as T;
+  }
+
   async updateProject(projectId: string, data: Record<string, unknown>) {
     return this.request<Record<string, unknown>>('PATCH', EP.PROJECTS.UPDATE(projectId), data);
   }

package/src/tools/branches.tools.ts

@@ -0,0 +1,124 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import type { ToolContext } from './index.js';
+import { formatErrorResponse } from '../utils/errors.js';
+import { requireProjectId } from '../utils/validators.js';
+
+const json = (data: unknown) => ({ content: [{ type: 'text' as const, text: JSON.stringify(data, null, 2) }] });
+
+type Branch = { id: string; branch: 'production' | 'development'; slug: string; provisioning_status: string; pending_changes: number };
+type BranchList = { enabled: boolean; production_id: string; branches: Branch[] };
+
+/**
+ * Project branches. Every App project has Production (the live project, its
+ * existing id) and Development (its own project id, URL, keys and database:
+ * Production's schema and config, none of its data). Work on Development by
+ * making its id the active project; promote reviewed changes to Production.
+ */
+export function registerBranchTools(server: McpServer, ctx: ToolContext): void {
+  const projectOf = (projectId?: string) => requireProjectId(projectId, ctx.session.getSession().currentProjectId);
+
+  server.registerTool('nestcore_list_branches', {
+    description:
+      "A project's branches: Production (the live app) and Development (safe copy: same schema and config, its own data, users, URL and keys). " +
+      'Returns each branch id, slug, setup status, database/file size and the number of schema changes waiting to be promoted. ' +
+      'To work on Development, call nestcore_set_active_project with the development branch id: every other tool then targets it. ' +
+      'Prefer Development for schema experiments; never test destructive SQL on Production.',
+    inputSchema: { projectId: z.string().optional().describe('Project or branch id (default: active project)') },
+  }, async ({ projectId }) => {
+    try {
+      await ctx.session.ensureAuthenticated();
+      return json(await ctx.apiClient.branches<BranchList>('GET', projectOf(projectId)));
+    } catch (error) {
+      return formatErrorResponse(error);
+    }
+  });
+
+  server.registerTool('nestcore_create_branch', {
+    description:
+      'Create the Development branch of a project if it has none (idempotent). Copies schema and config from Production (tables, RLS, functions, ' +
+      'buckets, auth settings, env vars with their values); never copies rows, end users or files. Jobs and webhooks start disabled. Takes a few seconds.',
+    inputSchema: { projectId: z.string().optional() },
+  }, async ({ projectId }) => {
+    try {
+      await ctx.session.ensureAuthenticated();
+      return json(await ctx.apiClient.branches('POST', projectOf(projectId), '/development'));
+    } catch (error) {
+      return formatErrorResponse(error);
+    }
+  });
+
+  server.registerTool('nestcore_reset_branch', {
+    description:
+      "Rebuild Development from Production: drops Development's database and re-clones Production's schema; ALL Development rows, end users and files " +
+      'are deleted and unpromoted changes discarded. URL, keys, env vars and functions are kept. Production is not touched. ' +
+      'Destructive for Development: only with the user\'s explicit request. Pass confirm: true.',
+    inputSchema: {
+      projectId: z.string().optional(),
+      confirm: z.literal(true).describe('Must be true: reset deletes all Development data'),
+    },
+  }, async ({ projectId }) => {
+    try {
+      await ctx.session.ensureAuthenticated();
+      const res = await ctx.apiClient.branches<Branch>('POST', projectOf(projectId), '/development/reset', { confirm: true });
+      ctx.schemaService.invalidate(res.id);
+      return json(res);
+    } catch (error) {
+      return formatErrorResponse(error);
+    }
+  });
+
+  server.registerTool('nestcore_branch_changes', {
+    description:
+      'Schema changes recorded on Development and not yet promoted (DDL from the SQL editor, table editor, RLS, realtime, CLI or MCP), in order. ' +
+      '`destructive: true` marks DROP / RENAME / type changes / RLS off. Data changes (INSERT/UPDATE/DELETE) are never recorded or promoted.',
+    inputSchema: { projectId: z.string().optional() },
+  }, async ({ projectId }) => {
+    try {
+      await ctx.session.ensureAuthenticated();
+      return json(await ctx.apiClient.branches('GET', projectOf(projectId), '/development/changes'));
+    } catch (error) {
+      return formatErrorResponse(error);
+    }
+  });
+
+  server.registerTool('nestcore_promote_branch', {
+    description:
+      'Promote Development to Production. Without apply: true it only PREVIEWS (pending schema changes, functions, buckets, jobs, env vars missing on ' +
+      'Production, auth-setting differences, and whether Production drifted). With apply: true (workspace admins) the schema changes run on Production in ONE ' +
+      'transaction (any failure rolls all back), then functions, new buckets and new jobs (created disabled) are copied. Env vars and auth settings are only ' +
+      'copied when asked. Production data is never touched. ALWAYS show the preview to the user and get their explicit go-ahead before apply: true; ' +
+      'destructive changes also need confirmDestructive and drift needs acknowledgeDrift, both only with the user\'s say-so.',
+    inputSchema: {
+      projectId: z.string().optional(),
+      apply: z.boolean().optional().describe('false/omitted = preview only'),
+      changeIds: z.array(z.string()).optional().describe('Subset of pending change ids (default: all)'),
+      includeEnvVars: z.boolean().optional().describe('Also add env vars missing on Production (Development values)'),
+      includeAuthSettings: z.boolean().optional().describe("Replace Production's auth settings with Development's"),
+      confirmDestructive: z.boolean().optional(),
+      acknowledgeDrift: z.boolean().optional(),
+    },
+  }, async ({ projectId, apply, changeIds, includeEnvVars, includeAuthSettings, confirmDestructive, acknowledgeDrift }) => {
+    try {
+      await ctx.session.ensureAuthenticated();
+      const id = projectOf(projectId);
+      const preview = await ctx.apiClient.branches<any>('GET', id, '/development/promote');
+      if (!apply) return json({ preview: true, ...preview });
+      const cfg = preview.config ?? {};
+      const result = await ctx.apiClient.branches<any>('POST', id, '/development/promote', {
+        change_ids: changeIds ?? (preview.changes ?? []).map((c: { id: string }) => c.id),
+        functions: (cfg.functions ?? []).map((f: { name: string }) => f.name),
+        buckets: (cfg.buckets ?? []).map((b: { name: string }) => b.name),
+        jobs: (cfg.jobs ?? []).filter((j: { status: string }) => j.status === 'new').map((j: { name: string }) => j.name),
+        env_vars: includeEnvVars ? (cfg.env_vars ?? []).map((e: { name: string }) => e.name) : [],
+        auth_settings: !!includeAuthSettings,
+        confirm_destructive: !!confirmDestructive,
+        acknowledge_drift: !!acknowledgeDrift,
+      });
+      ctx.schemaService.invalidate(preview.production_id);
+      return json(result);
+    } catch (error) {
+      return formatErrorResponse(error);
+    }
+  });
+}

package/src/tools/credits.tools.ts

@@ -0,0 +1,68 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import type { ToolContext } from './index.js';
+import { formatErrorResponse } from '../utils/errors.js';
+
+const json = (data: unknown) => ({ content: [{ type: 'text' as const, text: JSON.stringify(data, null, 2) }] });
+
+/**
+ * Workspace AI credit (prepaid). A project's own provider key always wins; without one,
+ * the workspace's credit pays for AI calls at the platform's key plus the margin.
+ * Credit is per workspace, shared by all its projects.
+ */
+export function registerCreditTools(server: McpServer, ctx: ToolContext): void {
+  server.registerTool('nestcore_get_credits', {
+    description:
+      "The workspace's AI credit: balance (USD), monthly cap (null = none), this month's spend, available (credit can pay for a call now), " +
+      'active (credit was ever bought; a workspace that never bought credit is never charged), margin %, the credit packs for sale and the recent ledger. ' +
+      "Credit only pays for AI calls of projects without their own provider key.",
+    inputSchema: {},
+  }, async () => {
+    try {
+      await ctx.session.ensureAuthenticated();
+      return json(await ctx.apiClient.getCredits());
+    } catch (error) {
+      return formatErrorResponse(error);
+    }
+  });
+
+  server.registerTool('nestcore_set_credit_cap', {
+    description:
+      "Set the workspace's monthly cap on AI credit spend in USD (0 to 100000), or pass null to remove the cap. " +
+      'Calls paid from credit fail with CREDITS_EXHAUSTED (reason spend_cap) once the month reaches it. Needs the workspace admin role. Returns the new summary.',
+    inputSchema: {
+      monthlyCapUsd: z.number().min(0).max(100_000).nullable().describe('USD per month, or null for no cap'),
+    },
+  }, async ({ monthlyCapUsd }) => {
+    try {
+      await ctx.session.ensureAuthenticated();
+      return json(await ctx.apiClient.setCreditCap(monthlyCapUsd));
+    } catch (error) {
+      return formatErrorResponse(error);
+    }
+  });
+
+  server.registerTool('nestcore_buy_credits', {
+    description:
+      'Create a Stripe Checkout link for an AI credit pack (one-time payment) for a HUMAN to open and pay in a browser. ' +
+      'This does NOT charge anything or add credit by itself: the credit lands only after the person pays and Stripe confirms. ' +
+      'Never tell the user the purchase is done; give them the URL and check nestcore_get_credits afterwards. ' +
+      'Pack ids come from nestcore_get_credits (e.g. credits_5, credits_10, credits_25). Needs the workspace admin role.',
+    inputSchema: {
+      pack: z.string().regex(/^[a-z0-9_-]{1,40}$/).describe('Credit pack id from nestcore_get_credits'),
+    },
+  }, async ({ pack }) => {
+    try {
+      await ctx.session.ensureAuthenticated();
+      const res = await ctx.apiClient.createCreditCheckout(pack, 'mcp');
+      return json({
+        checkoutUrl: res.url,
+        pack: res.pack,
+        paid: false,
+        next: 'Give this URL to the user to open and pay in a browser. No credit is added until the payment completes; nestcore_get_credits shows the new balance then.',
+      });
+    } catch (error) {
+      return formatErrorResponse(error);
+    }
+  });
+}

package/src/tools/index.ts

@@ -27,11 +27,13 @@ import { registerLoggingTools } from './logging.tools.js';
 import { registerAdminTools } from './admin.tools.js';
 import { registerSmtpTools } from './smtp.tools.js';
 import { registerIntegrationTools } from './integrations.tools.js';
+import { registerCreditTools } from './credits.tools.js';
 import { registerDashboardTools } from './dashboard.tools.js';
 import { registerBackgroundJobsTools } from './background-jobs.tools.js';
 import { registerRealtimeTools } from './realtime.tools.js';
 import { registerAnalyticsTools } from './analytics.tools.js';
 import { registerMigrationTools } from './migration.tools.js';
+import { registerBranchTools } from './branches.tools.js';
 import { registerProjectIntelligenceTools } from './project-intelligence.tools.js';
 import { registerProjectIntelligencePrompts } from '../prompts/project-intelligence.prompts.js';
 
@@ -47,10 +49,12 @@ export function registerAllTools(server: McpServer, ctx: ToolContext): void {
   registerAdminTools(server, ctx);
   registerSmtpTools(server, ctx);
   registerIntegrationTools(server, ctx);
+  registerCreditTools(server, ctx);
   registerDashboardTools(server, ctx);
   registerRealtimeTools(server, ctx);
   registerAnalyticsTools(server, ctx);
   registerMigrationTools(server, ctx);
+  registerBranchTools(server, ctx);
   registerProjectIntelligenceTools(server, ctx);
   registerProjectIntelligencePrompts(server, ctx);
 }

package/src/tools/project.tools.ts

@@ -1,19 +1,53 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import type { ToolContext } from './index.js';
-import { formatErrorResponse } from '../utils/errors.js';
+import { formatErrorResponse, ValidationError } from '../utils/errors.js';
 import { requireProjectId } from '../utils/validators.js';
 
 export function registerProjectTools(server: McpServer, ctx: ToolContext): void {
 
   // ─── Create Project ───
   server.registerTool('nestcore_create_project', {
-    description: 'Create a new NestCore project with a dedicated database. Returns project details including API keys.',
-    inputSchema: { name: z.string().min(3).max(120), description: z.string().max(500).optional() },
-  }, async ({ name, description }) => {
+    description:
+      'Create a new NestCore project with a dedicated database. Returns project details including API keys. ' +
+      'kind "app" (default) is a backend for an app; kind "agent" is the private backend of ONE PC running NestCore Agent ' +
+      '(needs agent.deviceName and agent.os) and only ever holds the agent schema, agent-* buckets and the agent functions. ' +
+      'The kind cannot be changed later. Check nestcore_get_project_eligibility first: on the free plan the one project is an app OR an agent.',
+    inputSchema: {
+      name: z.string().min(3).max(120),
+      description: z.string().max(500).optional(),
+      kind: z.enum(['app', 'agent']).optional(),
+      agent: z.object({
+        deviceName: z.string().min(1).max(80),
+        os: z.string().min(1).max(40),
+        agentVersion: z.string().max(32).optional(),
+      }).optional(),
+    },
+  }, async ({ name, description, kind, agent }) => {
+    try {
+      await ctx.session.ensureAuthenticated();
+      if (kind === 'agent' && !agent) {
+        throw new ValidationError('An agent project needs agent: { deviceName, os } (the PC it belongs to).');
+      }
+      const result = await ctx.apiClient.createProject({ name, description, kind, ...(kind === 'agent' && agent ? { agent } : {}) });
+      return {
+        content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
+      };
+    } catch (error) {
+      return formatErrorResponse(error);
+    }
+  });
+
+  // ─── Project Eligibility ───
+  server.registerTool('nestcore_get_project_eligibility', {
+    description:
+      'Can this workspace create one more project of a kind ("app" or "agent")? Returns { allowed, plan, used, limit, reason?, upgradeUrl }. ' +
+      'When allowed is false, give the user the upgradeUrl instead of trying to create the project.',
+    inputSchema: { kind: z.enum(['app', 'agent']).optional() },
+  }, async ({ kind }) => {
     try {
       await ctx.session.ensureAuthenticated();
-      const result = await ctx.apiClient.createProject({ name, description });
+      const result = await ctx.apiClient.getProjectEligibility(kind ?? 'app');
       return {
         content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
       };
@@ -24,12 +58,33 @@ export function registerProjectTools(server: McpServer, ctx: ToolContext): void
 
   // ─── List Projects ───
   server.registerTool('nestcore_list_projects', {
-    description: 'List all projects for the authenticated admin user.',
-    inputSchema: {},
-  }, async () => {
+    description:
+      'List all projects for the authenticated admin user. Each project has kind ("app" | "agent") and status ' +
+      '("active" | "paused" | "compromised"; paused projects reject writes and data-plane calls with 423 PROJECT_PAUSED). Optionally filter by kind.',
+    inputSchema: { kind: z.enum(['app', 'agent']).optional() },
+  }, async ({ kind }) => {
+    try {
+      await ctx.session.ensureAuthenticated();
+      const result = await ctx.apiClient.listProjects(kind);
+      return {
+        content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
+      };
+    } catch (error) {
+      return formatErrorResponse(error);
+    }
+  });
+
+  // ─── Pause / Resume Project ───
+  server.registerTool('nestcore_set_project_status', {
+    description:
+      'Pause a project (API, realtime and relay go off; nothing is deleted) or resume it. Resuming counts against the plan\'s project limit ' +
+      'and returns QUOTA_EXCEEDED with an upgradeUrl when the plan is full. A "compromised" project (kill switch) cannot be resumed here.',
+    inputSchema: { projectId: z.string().optional(), status: z.enum(['active', 'paused']) },
+  }, async ({ projectId, status }) => {
     try {
       await ctx.session.ensureAuthenticated();
-      const result = await ctx.apiClient.listProjects();
+      const id = requireProjectId(projectId, ctx.session.getSession().currentProjectId);
+      const result = await ctx.apiClient.setProjectStatus(id, status);
       return {
         content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
       };

package/src/utils/errors.ts

@@ -34,14 +34,30 @@ export class SafetyError extends McpError {
 
 export class ApiError extends McpError {
   public readonly statusCode: number;
+  /**
+   * The API's error body (QUOTA_EXCEEDED carries quota/plan/limit/usage/kind/reason/upgradeUrl;
+   * CREDITS_EXHAUSTED carries reason/balanceUsd/monthlyCapUsd/spentThisMonthUsd/buyUrl).
+   */
+  public readonly details?: Record<string, unknown>;
 
-  constructor(message: string, statusCode: number) {
-    super(message, 'API_ERROR');
+  /**
+   * `apiCode` is the platform's own code when it sent one, e.g. QUOTA_EXCEEDED,
+   * CREDITS_EXHAUSTED, AGENT_PROJECT_RESTRICTED, NOT_AN_AGENT_PROJECT or PROJECT_PAUSED.
+   */
+  constructor(message: string, statusCode: number, apiCode?: string, details?: Record<string, unknown>) {
+    super(message, apiCode ?? 'API_ERROR');
     this.name = 'ApiError';
     this.statusCode = statusCode;
+    this.details = details;
   }
 }
 
+/** Fields of an API error body worth handing to the model (never the raw body). */
+const API_DETAIL_FIELDS = [
+  'quota', 'plan', 'limit', 'usage', 'kind', 'reason', 'upgradeUrl', 'status',
+  'balanceUsd', 'monthlyCapUsd', 'spentThisMonthUsd', 'buyUrl',
+] as const;
+
 export class ProjectContextError extends McpError {
   constructor(message: string = 'No active project. Use nestcore_set_active_project first or provide projectId.') {
     super(message, 'PROJECT_CONTEXT_ERROR');
@@ -63,6 +79,22 @@ export function formatErrorResponse(error: unknown): { content: Array<{ type: 't
     };
   }
 
+  if (error instanceof ApiError) {
+    const details: Record<string, unknown> = {};
+    for (const k of API_DETAIL_FIELDS) if (error.details?.[k] !== undefined) details[k] = error.details[k];
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          error: error.message,
+          code: error.code,
+          statusCode: error.statusCode,
+          ...(Object.keys(details).length ? { details } : {}),
+        }, null, 2),
+      }],
+    };
+  }
+
   if (error instanceof McpError) {
     return {
       content: [{