@mapled/mcp 0.1.0

package/README.md

@@ -0,0 +1,42 @@
+# @mapled/mcp
+
+MCP server for [Mapled](https://mapled.io) — a hosted headless CMS built for sites created with AI. Connect it to Claude, Cursor, or any MCP-capable agent, and the agent can model collections, fill in content, and wire the site up end to end.
+
+## Setup
+
+Create a token in Mapled: project → Integrations → **Connect with AI**. Then add the server to your agent's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "mapled": {
+      "command": "npx",
+      "args": ["-y", "@mapled/mcp"],
+      "env": { "MAPLED_MCP_TOKEN": "mcp_live_…" }
+    }
+  }
+}
+```
+
+For Claude Code:
+
+```bash
+claude mcp add mapled -e MAPLED_MCP_TOKEN=mcp_live_… -- npx -y @mapled/mcp
+```
+
+The token is scoped to one project. Set `MAPLED_API_URL` only if you're not on the default `https://api.mapled.io`.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `get_schema` | Read the project's collections and fields |
+| `create_collection` | Add a collection or single |
+| `add_field` | Add a field (short_text, long_text, rich_text, slug, image, number, boolean, date) |
+| `add_records` | Insert draft records |
+| `list_records` | Read a collection's draft records |
+| `create_form` / `list_forms` | Set up public forms with spam protection |
+| `get_connection` | Delivery key + API URL for wiring the site (`@mapled/next`) |
+| `configure_revalidation` | Point the publish webhook at the site, get the signing secret |
+
+Agents write drafts only — publishing stays with humans in the Mapled app, and nothing changes on the live site until someone presses Publish.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createApiClient, createTools } from "./tools.js";
+/** Mapled MCP server. Auth and scope come from the environment:
+    MAPLED_MCP_TOKEN — the project token from Connect with AI (required)
+    MAPLED_API_URL   — API origin (default https://api.mapled.io) */
+const token = process.env.MAPLED_MCP_TOKEN;
+if (!token) {
+    console.error("MAPLED_MCP_TOKEN is missing. Create one in Mapled: project → Integrations → Connect with AI.");
+    process.exit(1);
+}
+const baseUrl = process.env.MAPLED_API_URL ?? "https://api.mapled.io";
+const server = new McpServer({ name: "mapled", version: "0.1.0" });
+const api = createApiClient(baseUrl, token);
+for (const tool of createTools(api)) {
+    // The SDK's generic inference recurses on our union of shapes; the
+    // runtime contract is identical, so erase the generics here.
+    server.tool(tool.name, tool.description, tool.schema, async (args) => {
+        try {
+            const result = await tool.handler(args);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: err instanceof Error ? err.message : "Mapled request failed.",
+                    },
+                ],
+            };
+        }
+    });
+}
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/tools.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+/** Tool definitions for the Mapled agent API. Kept transport-agnostic so
+    they can be unit-tested without a live MCP session. */
+export type ApiClient = {
+    request: (method: "GET" | "POST" | "PATCH", path: string, body?: unknown) => Promise<unknown>;
+};
+export declare function createApiClient(baseUrl: string, token: string): ApiClient;
+export declare const FIELD_TYPES: readonly ["short_text", "long_text", "rich_text", "slug", "image", "number", "boolean", "date"];
+export type ToolDef = {
+    name: string;
+    description: string;
+    schema: z.ZodRawShape;
+    handler: (args: never) => Promise<unknown>;
+};
+export declare function createTools(api: ApiClient): ToolDef[];

package/dist/tools.js

@@ -0,0 +1,126 @@
+import { z } from "zod";
+export function createApiClient(baseUrl, token) {
+    return {
+        async request(method, path, body) {
+            const res = await fetch(`${baseUrl}${path}`, {
+                method,
+                headers: {
+                    authorization: `Bearer ${token}`,
+                    ...(body !== undefined ? { "content-type": "application/json" } : {}),
+                },
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+            });
+            const payload = (await res.json().catch(() => null));
+            if (!res.ok) {
+                throw new Error(payload?.error?.message ?? `Mapled API error (${res.status}).`);
+            }
+            return payload;
+        },
+    };
+}
+export const FIELD_TYPES = [
+    "short_text",
+    "long_text",
+    "rich_text",
+    "slug",
+    "image",
+    "number",
+    "boolean",
+    "date",
+];
+export function createTools(api) {
+    return [
+        {
+            name: "get_schema",
+            description: "Read the project's full content schema: collections with their fields.",
+            schema: {},
+            handler: async () => api.request("GET", "/v1/agent/schema"),
+        },
+        {
+            name: "create_collection",
+            description: "Create a collection (many records of one shape) or a single (exactly one record, e.g. a homepage).",
+            schema: {
+                displayName: z.string().min(1).max(120),
+                kind: z.enum(["collection", "single"]).optional(),
+            },
+            handler: async (args) => api.request("POST", "/v1/agent/collections", {
+                displayName: args.displayName,
+                kind: args.kind ?? "collection",
+            }),
+        },
+        {
+            name: "add_field",
+            description: "Add a field to a collection. Types: short_text, long_text, rich_text, slug, image, number, boolean, date.",
+            schema: {
+                collectionKey: z.string().min(1).max(120),
+                displayName: z.string().min(1).max(120),
+                type: z.enum(FIELD_TYPES),
+                required: z.boolean().optional(),
+                helpText: z.string().max(500).optional(),
+            },
+            handler: async (args) => api.request("POST", `/v1/agent/collections/${encodeURIComponent(args.collectionKey)}/fields`, {
+                displayName: args.displayName,
+                type: args.type,
+                required: args.required ?? false,
+                helpText: args.helpText,
+            }),
+        },
+        {
+            name: "add_records",
+            description: "Insert up to 100 records into a collection. Each record maps field keys to values.",
+            schema: {
+                collectionKey: z.string().min(1).max(120),
+                records: z.array(z.record(z.string(), z.unknown())).min(1).max(100),
+            },
+            handler: async (args) => api.request("POST", `/v1/agent/collections/${encodeURIComponent(args.collectionKey)}/records`, { records: args.records }),
+        },
+        {
+            name: "create_form",
+            description: "Create a form the site can post submissions to. Returns the public submit endpoint; submissions are posted as flat JSON with the project delivery key in the X-Mapled-Key header. Include an empty hidden _gotcha honeypot field in the HTML form.",
+            schema: {
+                displayName: z.string().min(1).max(80),
+                key: z
+                    .string()
+                    .regex(/^[a-z][a-z0-9-]{0,63}$/)
+                    .optional(),
+                spamProtection: z.boolean().optional(),
+            },
+            handler: async (args) => api.request("POST", "/v1/agent/forms", args),
+        },
+        {
+            name: "list_forms",
+            description: "List the project's forms (key, name, spam protection).",
+            schema: {},
+            handler: async () => api.request("GET", "/v1/agent/forms"),
+        },
+        {
+            name: "list_records",
+            description: "List a collection's draft records (id, title, data).",
+            schema: {
+                collectionKey: z.string().min(1).max(120),
+            },
+            handler: async (args) => api.request("GET", `/v1/agent/collections/${encodeURIComponent(args.collectionKey)}/records`),
+        },
+        {
+            name: "get_connection",
+            description: "Get what the site needs to read published Mapled content: the delivery key and API URL. " +
+                "Wire-up: npm install @mapled/next, put the key in the site's env as MAPLED_KEY, then " +
+                'createClient({ key: process.env.MAPLED_KEY! }).getRecords("<collection>") in server components. ' +
+                "Content appears on the site only after a human presses Publish in Mapled.",
+            schema: {},
+            handler: async () => api.request("GET", "/v1/agent/connection"),
+        },
+        {
+            name: "configure_revalidation",
+            description: "Point Mapled's publish webhook at the site so published changes appear instantly. " +
+                "Pass the site's public revalidate URL (with @mapled/next: mount createRevalidateHandler " +
+                "from \"@mapled/next/server\" at /api/mapled/revalidate and pass that URL here). " +
+                "Returns the signing secret — store it in the site's env as MAPLED_WEBHOOK_SECRET. " +
+                "Local and private URLs are rejected; use the deployed site's URL.",
+            schema: {
+                url: z.string().min(8).max(2048),
+            },
+            handler: async (args) => api.request("PATCH", "/v1/agent/webhook", { url: args.url }),
+        },
+    ];
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@mapled/mcp",
+  "version": "0.1.0",
+  "description": "Mapled MCP server: lets AI agents build schema and content for one Mapled project.",
+  "license": "MIT",
+  "homepage": "https://mapled.io",
+  "keywords": [
+    "mapled",
+    "mcp",
+    "model-context-protocol",
+    "cms",
+    "headless-cms",
+    "ai-agents"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "module",
+  "bin": {
+    "mapled-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0",
+    "vitest": "^3.2.0"
+  }
+}