formback-mcp 1.0.0

package/README.md

@@ -0,0 +1,96 @@
+# @formback/mcp
+
+MCP (Model Context Protocol) server for [FormBack](https://formback.email) — manage your forms and submissions directly from AI assistants like Claude, Cursor, and others.
+
+## Installation
+
+```bash
+npm install -g @formback/mcp
+# or use directly with npx
+npx @formback/mcp
+```
+
+## Setup
+
+### 1. Get your API key
+
+Go to your [FormBack Dashboard](https://formback.email/dashboard) → Settings → API Keys → Create Key.
+
+### 2. Configure your AI assistant
+
+#### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "formback": {
+      "command": "npx",
+      "args": ["@formback/mcp"],
+      "env": {
+        "FORMBACK_API_KEY": "fb_your_key_here"
+      }
+    }
+  }
+}
+```
+
+#### Cursor
+
+Add to `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "formback": {
+      "command": "npx",
+      "args": ["@formback/mcp"],
+      "env": {
+        "FORMBACK_API_KEY": "fb_your_key_here"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_forms` | List all your forms with submission counts |
+| `create_form` | Create a new form (name, redirect URL, email notifications, webhook) |
+| `get_form` | Get form details by ID |
+| `update_form` | Update form settings |
+| `delete_form` | Delete a form and all its submissions |
+| `get_submissions` | Get form submissions with pagination |
+| `delete_submission` | Delete a specific submission |
+| `get_stats` | Account stats: plan, usage, limits |
+
+## Example Prompts
+
+- "List all my forms"
+- "Create a contact form called 'Website Contact' with email notifications"
+- "Show me the latest submissions for my contact form"
+- "How many submissions did I get this month?"
+- "Delete the test form"
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `FORMBACK_API_KEY` | Yes | — | Your FormBack API key |
+| `FORMBACK_API_URL` | No | `https://api.formback.email` | API base URL |
+
+## Development
+
+```bash
+cd mcp
+npm install
+npm run build
+npm test
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,89 @@
+/**
+ * FormBack API Client
+ */
+export interface FormBackConfig {
+    apiKey: string;
+    apiUrl: string;
+}
+export interface Form {
+    id: string;
+    name: string;
+    redirectUrl: string | null;
+    emailNotify: boolean;
+    webhookUrl: string | null;
+    createdAt: string;
+    updatedAt: string;
+    _count?: {
+        submissions: number;
+    };
+}
+export interface Submission {
+    id: string;
+    formId: string;
+    data: Record<string, unknown>;
+    meta: Record<string, unknown>;
+    createdAt: string;
+}
+export interface Pagination {
+    page: number;
+    limit: number;
+    total: number;
+    pages: number;
+}
+export interface Account {
+    email: string;
+    plan: string;
+    limits: Record<string, number>;
+    usage: {
+        forms: number;
+        submissions: number;
+    };
+}
+export declare class FormBackApiError extends Error {
+    statusCode: number;
+    constructor(statusCode: number, message: string);
+}
+export declare class FormBackClient {
+    private apiKey;
+    private apiUrl;
+    constructor(config: FormBackConfig);
+    private request;
+    listForms(): Promise<{
+        forms: Form[];
+    }>;
+    createForm(data: {
+        name: string;
+        redirectUrl?: string;
+        emailNotify?: boolean;
+        webhookUrl?: string;
+    }): Promise<{
+        form: Form;
+    }>;
+    getForm(id: string): Promise<{
+        form: Form;
+    }>;
+    updateForm(id: string, data: {
+        name?: string;
+        redirectUrl?: string;
+        emailNotify?: boolean;
+        webhookUrl?: string;
+    }): Promise<{
+        form: Form;
+    }>;
+    deleteForm(id: string): Promise<{
+        ok: boolean;
+    }>;
+    getSubmissions(formId: string, params?: {
+        page?: number;
+        limit?: number;
+    }): Promise<{
+        submissions: Submission[];
+        pagination: Pagination;
+    }>;
+    deleteSubmission(id: string): Promise<{
+        ok: boolean;
+    }>;
+    getAccount(): Promise<{
+        account: Account;
+    }>;
+}

package/dist/client.js

@@ -0,0 +1,72 @@
+/**
+ * FormBack API Client
+ */
+export class FormBackApiError extends Error {
+    statusCode;
+    constructor(statusCode, message) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = 'FormBackApiError';
+    }
+}
+export class FormBackClient {
+    apiKey;
+    apiUrl;
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.apiUrl = config.apiUrl.replace(/\/$/, '');
+    }
+    async request(method, path, body) {
+        const url = `${this.apiUrl}${path}`;
+        const headers = {
+            'Authorization': `ApiKey ${this.apiKey}`,
+            'Content-Type': 'application/json',
+        };
+        const res = await fetch(url, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok) {
+            const data = await res.json().catch(() => ({ error: res.statusText }));
+            throw new FormBackApiError(res.status, data.error || `HTTP ${res.status}`);
+        }
+        return res.json();
+    }
+    async listForms() {
+        return this.request('GET', '/api/forms');
+    }
+    async createForm(data) {
+        return this.request('POST', '/api/forms', {
+            name: data.name,
+            redirectUrl: data.redirectUrl,
+            emailNotify: data.emailNotify,
+            webhookUrl: data.webhookUrl,
+        });
+    }
+    async getForm(id) {
+        return this.request('GET', `/api/forms/${id}`);
+    }
+    async updateForm(id, data) {
+        return this.request('PATCH', `/api/forms/${id}`, data);
+    }
+    async deleteForm(id) {
+        return this.request('DELETE', `/api/forms/${id}`);
+    }
+    async getSubmissions(formId, params) {
+        const query = new URLSearchParams();
+        if (params?.page)
+            query.set('page', String(params.page));
+        if (params?.limit)
+            query.set('limit', String(params.limit));
+        const qs = query.toString();
+        return this.request('GET', `/api/forms/${formId}/submissions${qs ? `?${qs}` : ''}`);
+    }
+    async deleteSubmission(id) {
+        return this.request('DELETE', `/api/submissions/${id}`);
+    }
+    async getAccount() {
+        return this.request('GET', '/api/account');
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * FormBack MCP Server
+ *
+ * Provides AI assistants with tools to manage forms and submissions via FormBack API.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+/**
+ * FormBack MCP Server
+ *
+ * Provides AI assistants with tools to manage forms and submissions via FormBack API.
+ */
+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 { FormBackClient } from './client.js';
+import { TOOLS, handleToolCall } from './tools.js';
+const API_KEY = process.env.FORMBACK_API_KEY;
+const API_URL = process.env.FORMBACK_API_URL || 'https://api.formback.email';
+if (!API_KEY) {
+    console.error('Error: FORMBACK_API_KEY environment variable is required.');
+    console.error('Get your API key at https://formback.email/dashboard');
+    process.exit(1);
+}
+const client = new FormBackClient({ apiKey: API_KEY, apiUrl: API_URL });
+const server = new Server({ name: 'formback', version: '1.0.0' }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS,
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args = {} } = request.params;
+    const result = await handleToolCall(client, name, args);
+    return {
+        content: [{ type: 'text', text: result }],
+    };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EACL,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEnD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;AAC7C,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,4BAA4B,CAAC;AAE7E,IAAI,CAAC,OAAO,EAAE,CAAC;IACb,OAAO,CAAC,KAAK,CAAC,2DAA2D,CAAC,CAAC;IAC3E,OAAO,CAAC,KAAK,CAAC,sDAAsD,CAAC,CAAC;IACtE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;AAExE,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,EACtC,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,CAChC,CAAC;AAEF,MAAM,CAAC,iBAAiB,CAAC,sBAAsB,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;IAC5D,KAAK,EAAE,KAAK;CACb,CAAC,CAAC,CAAC;AAEJ,MAAM,CAAC,iBAAiB,CAAC,qBAAqB,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;IAChE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IACtD,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,IAA+B,CAAC,CAAC;IACnF,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;KACnD,CAAC;AACJ,CAAC,CAAC,CAAC;AAEH,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/tools.d.ts

@@ -0,0 +1,17 @@
+/**
+ * MCP Tool definitions for FormBack
+ */
+import { FormBackClient } from './client.js';
+export interface Tool {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+export declare const TOOLS: Tool[];
+type ToolArgs = Record<string, unknown>;
+export declare function handleToolCall(client: FormBackClient, name: string, args: ToolArgs): Promise<string>;
+export {};

package/dist/tools.js

@@ -0,0 +1,160 @@
+/**
+ * MCP Tool definitions for FormBack
+ */
+import { FormBackApiError } from './client.js';
+export const TOOLS = [
+    {
+        name: 'list_forms',
+        description: 'List all forms for the authenticated user. Returns form names, IDs, and submission counts.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'create_form',
+        description: 'Create a new form. Returns the created form with its unique ID and endpoint URL.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Name of the form' },
+                redirect_url: { type: 'string', description: 'URL to redirect after submission (optional)' },
+                email_notify: { type: 'boolean', description: 'Send email notifications on submission (default: true)' },
+                webhook_url: { type: 'string', description: 'Webhook URL to call on submission (optional)' },
+            },
+            required: ['name'],
+        },
+    },
+    {
+        name: 'get_form',
+        description: 'Get details of a specific form by ID, including submission count.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                form_id: { type: 'string', description: 'Form ID' },
+            },
+            required: ['form_id'],
+        },
+    },
+    {
+        name: 'update_form',
+        description: 'Update form settings (name, redirect URL, email notifications, webhook URL).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                form_id: { type: 'string', description: 'Form ID' },
+                name: { type: 'string', description: 'New name' },
+                redirect_url: { type: 'string', description: 'New redirect URL' },
+                email_notify: { type: 'boolean', description: 'Enable/disable email notifications' },
+                webhook_url: { type: 'string', description: 'New webhook URL' },
+            },
+            required: ['form_id'],
+        },
+    },
+    {
+        name: 'delete_form',
+        description: 'Delete a form and all its submissions. This action is irreversible.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                form_id: { type: 'string', description: 'Form ID to delete' },
+            },
+            required: ['form_id'],
+        },
+    },
+    {
+        name: 'get_submissions',
+        description: 'Get submissions for a form with pagination. Returns submission data and metadata.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                form_id: { type: 'string', description: 'Form ID' },
+                page: { type: 'number', description: 'Page number (default: 1)' },
+                limit: { type: 'number', description: 'Items per page (default: 50, max: 100)' },
+            },
+            required: ['form_id'],
+        },
+    },
+    {
+        name: 'delete_submission',
+        description: 'Delete a specific submission by ID.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                submission_id: { type: 'string', description: 'Submission ID to delete' },
+            },
+            required: ['submission_id'],
+        },
+    },
+    {
+        name: 'get_stats',
+        description: 'Get account statistics: plan, form count, submission usage this month, and limits.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+];
+export async function handleToolCall(client, name, args) {
+    try {
+        switch (name) {
+            case 'list_forms': {
+                const { forms } = await client.listForms();
+                if (forms.length === 0)
+                    return 'No forms found. Create one with create_form.';
+                return JSON.stringify(forms, null, 2);
+            }
+            case 'create_form': {
+                const { form } = await client.createForm({
+                    name: args.name,
+                    redirectUrl: args.redirect_url,
+                    emailNotify: args.email_notify,
+                    webhookUrl: args.webhook_url,
+                });
+                return JSON.stringify(form, null, 2);
+            }
+            case 'get_form': {
+                const { form } = await client.getForm(args.form_id);
+                return JSON.stringify(form, null, 2);
+            }
+            case 'update_form': {
+                const { form_id, ...updates } = args;
+                const { form } = await client.updateForm(form_id, {
+                    name: updates.name,
+                    redirectUrl: updates.redirect_url,
+                    emailNotify: updates.email_notify,
+                    webhookUrl: updates.webhook_url,
+                });
+                return JSON.stringify(form, null, 2);
+            }
+            case 'delete_form': {
+                await client.deleteForm(args.form_id);
+                return 'Form deleted successfully.';
+            }
+            case 'get_submissions': {
+                const result = await client.getSubmissions(args.form_id, {
+                    page: args.page,
+                    limit: args.limit,
+                });
+                return JSON.stringify(result, null, 2);
+            }
+            case 'delete_submission': {
+                await client.deleteSubmission(args.submission_id);
+                return 'Submission deleted successfully.';
+            }
+            case 'get_stats': {
+                const { account } = await client.getAccount();
+                return JSON.stringify({
+                    email: account.email,
+                    plan: account.plan,
+                    forms: account.usage.forms,
+                    submissions_this_month: account.usage.submissions,
+                    limits: account.limits,
+                }, null, 2);
+            }
+            default:
+                return `Unknown tool: ${name}`;
+        }
+    }
+    catch (error) {
+        if (error instanceof FormBackApiError) {
+            return `Error (${error.statusCode}): ${error.message}`;
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "formback-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for FormBack \u2014 manage forms and submissions from AI assistants",
+  "type": "module",
+  "bin": {
+    "formback-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:live": "tsx tests/test-live.ts"
+  },
+  "keywords": [
+    "mcp",
+    "formback",
+    "forms",
+    "ai"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "tsx": "^4.7.0",
+    "vitest": "^2.0.0",
+    "@types/node": "^22.0.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,137 @@
+/**
+ * FormBack API Client
+ */
+
+export interface FormBackConfig {
+  apiKey: string;
+  apiUrl: string;
+}
+
+export interface Form {
+  id: string;
+  name: string;
+  redirectUrl: string | null;
+  emailNotify: boolean;
+  webhookUrl: string | null;
+  createdAt: string;
+  updatedAt: string;
+  _count?: { submissions: number };
+}
+
+export interface Submission {
+  id: string;
+  formId: string;
+  data: Record<string, unknown>;
+  meta: Record<string, unknown>;
+  createdAt: string;
+}
+
+export interface Pagination {
+  page: number;
+  limit: number;
+  total: number;
+  pages: number;
+}
+
+export interface Account {
+  email: string;
+  plan: string;
+  limits: Record<string, number>;
+  usage: { forms: number; submissions: number };
+}
+
+export class FormBackApiError extends Error {
+  constructor(
+    public statusCode: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'FormBackApiError';
+  }
+}
+
+export class FormBackClient {
+  private apiKey: string;
+  private apiUrl: string;
+
+  constructor(config: FormBackConfig) {
+    this.apiKey = config.apiKey;
+    this.apiUrl = config.apiUrl.replace(/\/$/, '');
+  }
+
+  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const url = `${this.apiUrl}${path}`;
+    const headers: Record<string, string> = {
+      'Authorization': `ApiKey ${this.apiKey}`,
+      'Content-Type': 'application/json',
+    };
+
+    const res = await fetch(url, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+
+    if (!res.ok) {
+      const data = await res.json().catch(() => ({ error: res.statusText }));
+      throw new FormBackApiError(
+        res.status,
+        (data as { error?: string }).error || `HTTP ${res.status}`,
+      );
+    }
+
+    return res.json() as Promise<T>;
+  }
+
+  async listForms(): Promise<{ forms: Form[] }> {
+    return this.request('GET', '/api/forms');
+  }
+
+  async createForm(data: {
+    name: string;
+    redirectUrl?: string;
+    emailNotify?: boolean;
+    webhookUrl?: string;
+  }): Promise<{ form: Form }> {
+    return this.request('POST', '/api/forms', {
+      name: data.name,
+      redirectUrl: data.redirectUrl,
+      emailNotify: data.emailNotify,
+      webhookUrl: data.webhookUrl,
+    });
+  }
+
+  async getForm(id: string): Promise<{ form: Form }> {
+    return this.request('GET', `/api/forms/${id}`);
+  }
+
+  async updateForm(
+    id: string,
+    data: { name?: string; redirectUrl?: string; emailNotify?: boolean; webhookUrl?: string },
+  ): Promise<{ form: Form }> {
+    return this.request('PATCH', `/api/forms/${id}`, data);
+  }
+
+  async deleteForm(id: string): Promise<{ ok: boolean }> {
+    return this.request('DELETE', `/api/forms/${id}`);
+  }
+
+  async getSubmissions(
+    formId: string,
+    params?: { page?: number; limit?: number },
+  ): Promise<{ submissions: Submission[]; pagination: Pagination }> {
+    const query = new URLSearchParams();
+    if (params?.page) query.set('page', String(params.page));
+    if (params?.limit) query.set('limit', String(params.limit));
+    const qs = query.toString();
+    return this.request('GET', `/api/forms/${formId}/submissions${qs ? `?${qs}` : ''}`);
+  }
+
+  async deleteSubmission(id: string): Promise<{ ok: boolean }> {
+    return this.request('DELETE', `/api/submissions/${id}`);
+  }
+
+  async getAccount(): Promise<{ account: Account }> {
+    return this.request('GET', '/api/account');
+  }
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+
+/**
+ * FormBack MCP Server
+ *
+ * Provides AI assistants with tools to manage forms and submissions via FormBack API.
+ */
+
+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 { FormBackClient } from './client.js';
+import { TOOLS, handleToolCall } from './tools.js';
+
+const API_KEY = process.env.FORMBACK_API_KEY;
+const API_URL = process.env.FORMBACK_API_URL || 'https://api.formback.email';
+
+if (!API_KEY) {
+  console.error('Error: FORMBACK_API_KEY environment variable is required.');
+  console.error('Get your API key at https://formback.email/dashboard');
+  process.exit(1);
+}
+
+const client = new FormBackClient({ apiKey: API_KEY, apiUrl: API_URL });
+
+const server = new Server(
+  { name: 'formback', version: '1.0.0' },
+  { capabilities: { tools: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS,
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args = {} } = request.params;
+  const result = await handleToolCall(client, name, args as Record<string, unknown>);
+  return {
+    content: [{ type: 'text' as const, text: result }],
+  };
+});
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/src/tools.ts

@@ -0,0 +1,188 @@
+/**
+ * MCP Tool definitions for FormBack
+ */
+
+import { FormBackClient, FormBackApiError } from './client.js';
+
+export interface Tool {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+}
+
+export const TOOLS: Tool[] = [
+  {
+    name: 'list_forms',
+    description: 'List all forms for the authenticated user. Returns form names, IDs, and submission counts.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'create_form',
+    description: 'Create a new form. Returns the created form with its unique ID and endpoint URL.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Name of the form' },
+        redirect_url: { type: 'string', description: 'URL to redirect after submission (optional)' },
+        email_notify: { type: 'boolean', description: 'Send email notifications on submission (default: true)' },
+        webhook_url: { type: 'string', description: 'Webhook URL to call on submission (optional)' },
+      },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'get_form',
+    description: 'Get details of a specific form by ID, including submission count.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        form_id: { type: 'string', description: 'Form ID' },
+      },
+      required: ['form_id'],
+    },
+  },
+  {
+    name: 'update_form',
+    description: 'Update form settings (name, redirect URL, email notifications, webhook URL).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        form_id: { type: 'string', description: 'Form ID' },
+        name: { type: 'string', description: 'New name' },
+        redirect_url: { type: 'string', description: 'New redirect URL' },
+        email_notify: { type: 'boolean', description: 'Enable/disable email notifications' },
+        webhook_url: { type: 'string', description: 'New webhook URL' },
+      },
+      required: ['form_id'],
+    },
+  },
+  {
+    name: 'delete_form',
+    description: 'Delete a form and all its submissions. This action is irreversible.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        form_id: { type: 'string', description: 'Form ID to delete' },
+      },
+      required: ['form_id'],
+    },
+  },
+  {
+    name: 'get_submissions',
+    description: 'Get submissions for a form with pagination. Returns submission data and metadata.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        form_id: { type: 'string', description: 'Form ID' },
+        page: { type: 'number', description: 'Page number (default: 1)' },
+        limit: { type: 'number', description: 'Items per page (default: 50, max: 100)' },
+      },
+      required: ['form_id'],
+    },
+  },
+  {
+    name: 'delete_submission',
+    description: 'Delete a specific submission by ID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        submission_id: { type: 'string', description: 'Submission ID to delete' },
+      },
+      required: ['submission_id'],
+    },
+  },
+  {
+    name: 'get_stats',
+    description: 'Get account statistics: plan, form count, submission usage this month, and limits.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+];
+
+type ToolArgs = Record<string, unknown>;
+
+export async function handleToolCall(
+  client: FormBackClient,
+  name: string,
+  args: ToolArgs,
+): Promise<string> {
+  try {
+    switch (name) {
+      case 'list_forms': {
+        const { forms } = await client.listForms();
+        if (forms.length === 0) return 'No forms found. Create one with create_form.';
+        return JSON.stringify(forms, null, 2);
+      }
+
+      case 'create_form': {
+        const { form } = await client.createForm({
+          name: args.name as string,
+          redirectUrl: args.redirect_url as string | undefined,
+          emailNotify: args.email_notify as boolean | undefined,
+          webhookUrl: args.webhook_url as string | undefined,
+        });
+        return JSON.stringify(form, null, 2);
+      }
+
+      case 'get_form': {
+        const { form } = await client.getForm(args.form_id as string);
+        return JSON.stringify(form, null, 2);
+      }
+
+      case 'update_form': {
+        const { form_id, ...updates } = args;
+        const { form } = await client.updateForm(form_id as string, {
+          name: updates.name as string | undefined,
+          redirectUrl: updates.redirect_url as string | undefined,
+          emailNotify: updates.email_notify as boolean | undefined,
+          webhookUrl: updates.webhook_url as string | undefined,
+        });
+        return JSON.stringify(form, null, 2);
+      }
+
+      case 'delete_form': {
+        await client.deleteForm(args.form_id as string);
+        return 'Form deleted successfully.';
+      }
+
+      case 'get_submissions': {
+        const result = await client.getSubmissions(args.form_id as string, {
+          page: args.page as number | undefined,
+          limit: args.limit as number | undefined,
+        });
+        return JSON.stringify(result, null, 2);
+      }
+
+      case 'delete_submission': {
+        await client.deleteSubmission(args.submission_id as string);
+        return 'Submission deleted successfully.';
+      }
+
+      case 'get_stats': {
+        const { account } = await client.getAccount();
+        return JSON.stringify(
+          {
+            email: account.email,
+            plan: account.plan,
+            forms: account.usage.forms,
+            submissions_this_month: account.usage.submissions,
+            limits: account.limits,
+          },
+          null,
+          2,
+        );
+      }
+
+      default:
+        return `Unknown tool: ${name}`;
+    }
+  } catch (error) {
+    if (error instanceof FormBackApiError) {
+      return `Error (${error.statusCode}): ${error.message}`;
+    }
+    throw error;
+  }
+}

package/tests/mcp.test.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { FormBackClient, FormBackApiError } from '../src/client.js';
+import { handleToolCall } from '../src/tools.js';
+
+// Mock fetch globally
+const mockFetch = vi.fn();
+vi.stubGlobal('fetch', mockFetch);
+
+function mockResponse(data: unknown, status = 200) {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    statusText: status === 200 ? 'OK' : 'Error',
+    json: () => Promise.resolve(data),
+  };
+}
+
+const client = new FormBackClient({
+  apiKey: 'fb_test123',
+  apiUrl: 'https://api.formback.email',
+});
+
+beforeEach(() => {
+  mockFetch.mockReset();
+});
+
+describe('FormBackClient', () => {
+  it('sends correct auth header', async () => {
+    mockFetch.mockResolvedValue(mockResponse({ forms: [] }));
+    await client.listForms();
+    expect(mockFetch).toHaveBeenCalledWith(
+      'https://api.formback.email/api/forms',
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          Authorization: 'ApiKey fb_test123',
+        }),
+      }),
+    );
+  });
+
+  it('throws FormBackApiError on non-ok response', async () => {
+    mockFetch.mockResolvedValue(mockResponse({ error: 'Invalid API key' }, 401));
+    await expect(client.listForms()).rejects.toThrow(FormBackApiError);
+    await expect(client.listForms()).rejects.toThrow('Invalid API key');
+  });
+
+  it('creates form with correct body', async () => {
+    mockFetch.mockResolvedValue(mockResponse({ form: { id: '1', name: 'Test' } }, 201));
+    await client.createForm({ name: 'Test', webhookUrl: 'https://hook.io' });
+    const call = mockFetch.mock.calls[0];
+    expect(call[0]).toBe('https://api.formback.email/api/forms');
+    expect(call[1].method).toBe('POST');
+    expect(JSON.parse(call[1].body)).toEqual({
+      name: 'Test',
+      redirectUrl: undefined,
+      emailNotify: undefined,
+      webhookUrl: 'https://hook.io',
+    });
+  });
+
+  it('gets submissions with pagination', async () => {
+    mockFetch.mockResolvedValue(
+      mockResponse({ submissions: [], pagination: { page: 2, limit: 10, total: 0, pages: 0 } }),
+    );
+    await client.getSubmissions('form1', { page: 2, limit: 10 });
+    expect(mockFetch.mock.calls[0][0]).toBe(
+      'https://api.formback.email/api/forms/form1/submissions?page=2&limit=10',
+    );
+  });
+});
+
+describe('handleToolCall', () => {
+  it('list_forms returns forms', async () => {
+    mockFetch.mockResolvedValue(
+      mockResponse({
+        forms: [{ id: '1', name: 'Contact', _count: { submissions: 5 } }],
+      }),
+    );
+    const result = await handleToolCall(client, 'list_forms', {});
+    const parsed = JSON.parse(result);
+    expect(parsed).toHaveLength(1);
+    expect(parsed[0].name).toBe('Contact');
+  });
+
+  it('list_forms empty returns message', async () => {
+    mockFetch.mockResolvedValue(mockResponse({ forms: [] }));
+    const result = await handleToolCall(client, 'list_forms', {});
+    expect(result).toContain('No forms found');
+  });
+
+  it('create_form passes args correctly', async () => {
+    mockFetch.mockResolvedValue(mockResponse({ form: { id: '2', name: 'New' } }));
+    const result = await handleToolCall(client, 'create_form', {
+      name: 'New',
+      redirect_url: 'https://thanks.com',
+    });
+    expect(JSON.parse(result).name).toBe('New');
+  });
+
+  it('get_form returns form', async () => {
+    mockFetch.mockResolvedValue(mockResponse({ form: { id: '1', name: 'Test' } }));
+    const result = await handleToolCall(client, 'get_form', { form_id: '1' });
+    expect(JSON.parse(result).id).toBe('1');
+  });
+
+  it('update_form sends updates', async () => {
+    mockFetch.mockResolvedValue(mockResponse({ form: { id: '1', name: 'Updated' } }));
+    const result = await handleToolCall(client, 'update_form', {
+      form_id: '1',
+      name: 'Updated',
+    });
+    expect(JSON.parse(result).name).toBe('Updated');
+  });
+
+  it('delete_form returns success', async () => {
+    mockFetch.mockResolvedValue(mockResponse({ ok: true }));
+    const result = await handleToolCall(client, 'delete_form', { form_id: '1' });
+    expect(result).toContain('deleted');
+  });
+
+  it('get_submissions with pagination', async () => {
+    mockFetch.mockResolvedValue(
+      mockResponse({
+        submissions: [{ id: 's1', data: { email: 'test@test.com' } }],
+        pagination: { page: 1, limit: 50, total: 1, pages: 1 },
+      }),
+    );
+    const result = await handleToolCall(client, 'get_submissions', { form_id: '1' });
+    const parsed = JSON.parse(result);
+    expect(parsed.submissions).toHaveLength(1);
+    expect(parsed.pagination.total).toBe(1);
+  });
+
+  it('delete_submission returns success', async () => {
+    mockFetch.mockResolvedValue(mockResponse({ ok: true }));
+    const result = await handleToolCall(client, 'delete_submission', { submission_id: 's1' });
+    expect(result).toContain('deleted');
+  });
+
+  it('get_stats returns account info', async () => {
+    mockFetch.mockResolvedValue(
+      mockResponse({
+        account: {
+          email: 'test@test.com',
+          plan: 'free',
+          limits: { forms: 3, submissions: 100 },
+          usage: { forms: 1, submissions: 42 },
+        },
+      }),
+    );
+    const result = await handleToolCall(client, 'get_stats', {});
+    const parsed = JSON.parse(result);
+    expect(parsed.plan).toBe('free');
+    expect(parsed.submissions_this_month).toBe(42);
+  });
+
+  it('handles API errors gracefully', async () => {
+    mockFetch.mockResolvedValue(mockResponse({ error: 'Form not found' }, 404));
+    const result = await handleToolCall(client, 'get_form', { form_id: 'bad' });
+    expect(result).toContain('404');
+    expect(result).toContain('Form not found');
+  });
+
+  it('handles auth errors', async () => {
+    mockFetch.mockResolvedValue(mockResponse({ error: 'Invalid API key' }, 401));
+    const result = await handleToolCall(client, 'list_forms', {});
+    expect(result).toContain('401');
+    expect(result).toContain('Invalid API key');
+  });
+
+  it('unknown tool returns error message', async () => {
+    const result = await handleToolCall(client, 'nonexistent', {});
+    expect(result).toContain('Unknown tool');
+  });
+});

package/tests/test-live.ts

@@ -0,0 +1,130 @@
+#!/usr/bin/env tsx
+
+/**
+ * Live integration test for FormBack MCP tools against production API.
+ *
+ * Usage: FORMBACK_API_KEY=fb_xxx tsx tests/test-live.ts
+ */
+
+import { FormBackClient } from '../src/client.js';
+import { handleToolCall } from '../src/tools.js';
+
+const API_KEY = process.env.FORMBACK_API_KEY;
+const API_URL = process.env.FORMBACK_API_URL || 'https://api.formback.email';
+
+if (!API_KEY) {
+  console.error('Set FORMBACK_API_KEY to run live tests');
+  process.exit(1);
+}
+
+const client = new FormBackClient({ apiKey: API_KEY, apiUrl: API_URL });
+
+let passed = 0;
+let failed = 0;
+
+function assert(condition: boolean, msg: string) {
+  if (condition) {
+    console.log(`  ✅ ${msg}`);
+    passed++;
+  } else {
+    console.error(`  ❌ ${msg}`);
+    failed++;
+  }
+}
+
+async function run() {
+  console.log('🧪 FormBack MCP Live Tests\n');
+  console.log(`API: ${API_URL}\n`);
+
+  // 1. Get stats
+  console.log('📊 get_stats');
+  const stats = await handleToolCall(client, 'get_stats', {});
+  const statsObj = JSON.parse(stats);
+  assert(!!statsObj.email, `Account email: ${statsObj.email}`);
+  assert(!!statsObj.plan, `Plan: ${statsObj.plan}`);
+
+  // 2. Create form
+  console.log('\n📝 create_form');
+  const createResult = await handleToolCall(client, 'create_form', {
+    name: `MCP Test ${Date.now()}`,
+    redirect_url: 'https://example.com/thanks',
+    email_notify: false,
+  });
+  const form = JSON.parse(createResult);
+  assert(!!form.id, `Created form: ${form.id}`);
+  assert(form.name.startsWith('MCP Test'), `Name: ${form.name}`);
+  const formId = form.id;
+
+  // 3. List forms
+  console.log('\n📋 list_forms');
+  const listResult = await handleToolCall(client, 'list_forms', {});
+  const forms = JSON.parse(listResult);
+  assert(Array.isArray(forms), `Got ${forms.length} forms`);
+  assert(forms.some((f: { id: string }) => f.id === formId), 'New form in list');
+
+  // 4. Get form
+  console.log('\n🔍 get_form');
+  const getResult = await handleToolCall(client, 'get_form', { form_id: formId });
+  const fetched = JSON.parse(getResult);
+  assert(fetched.id === formId, 'Fetched correct form');
+
+  // 5. Update form
+  console.log('\n✏️ update_form');
+  const updateResult = await handleToolCall(client, 'update_form', {
+    form_id: formId,
+    name: 'MCP Updated',
+    webhook_url: 'https://hook.example.com',
+  });
+  const updated = JSON.parse(updateResult);
+  assert(updated.name === 'MCP Updated', 'Name updated');
+
+  // 6. Get submissions (should be empty)
+  console.log('\n📨 get_submissions');
+  const subsResult = await handleToolCall(client, 'get_submissions', { form_id: formId });
+  const subs = JSON.parse(subsResult);
+  assert(subs.pagination.total === 0, 'No submissions yet');
+
+  // 7. Submit data via form endpoint
+  console.log('\n📤 Submit test data');
+  const submitRes = await fetch(`${API_URL}/f/${formId}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ name: 'Test User', email: 'test@mcp.io', message: 'Hello from MCP test' }),
+  });
+  assert(submitRes.ok || submitRes.status === 302 || submitRes.status === 303, `Submit status: ${submitRes.status}`);
+
+  // 8. Get submissions again
+  console.log('\n📨 get_submissions (after submit)');
+  const subsResult2 = await handleToolCall(client, 'get_submissions', { form_id: formId });
+  const subs2 = JSON.parse(subsResult2);
+  assert(subs2.pagination.total >= 1, `Submissions: ${subs2.pagination.total}`);
+
+  // 9. Delete submission if exists
+  if (subs2.submissions.length > 0) {
+    console.log('\n🗑️ delete_submission');
+    const delSubResult = await handleToolCall(client, 'delete_submission', {
+      submission_id: subs2.submissions[0].id,
+    });
+    assert(delSubResult.includes('deleted'), 'Submission deleted');
+  }
+
+  // 10. Delete form
+  console.log('\n🗑️ delete_form');
+  const delResult = await handleToolCall(client, 'delete_form', { form_id: formId });
+  assert(delResult.includes('deleted'), 'Form deleted');
+
+  // 11. Verify deleted
+  console.log('\n🔍 get_form (deleted — expect error)');
+  const gone = await handleToolCall(client, 'get_form', { form_id: formId });
+  assert(gone.includes('404') || gone.includes('not found'), 'Form gone');
+
+  // Summary
+  console.log(`\n${'='.repeat(40)}`);
+  console.log(`Results: ${passed} passed, ${failed} failed`);
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+run().catch((err) => {
+  console.error('Fatal:', err);
+  process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['tests/**/*.test.ts'],
+  },
+});