@typeroll/mcp-server 0.7.7 → 0.7.8

package/README.md

@@ -1,20 +1,46 @@
 # @typeroll/mcp-server
 
 Model Context Protocol server for the [Typeroll](https://typeroll.com)
-public API. Lets Claude Code (or any MCP-compatible client) manage a
-Typeroll site through the same tool surface a human agency would use:
-read and write pages, partials, collections, media, redirects, versions;
-trigger deploys; mint preview links.
+public API. Lets Claude (Desktop / claude.ai / Code) manage a Typeroll
+site through the same tool surface a human agency would use: read and
+write pages, partials, collections, media, redirects, versions; trigger
+deploys; mint preview links.
 
 The server is a **thin transport adapter** — every tool wraps one HTTP
-endpoint of the Typeroll REST API. Auth happens at the API layer with
-a site-scoped key; the MCP just carries the bearer through.
+endpoint of the Typeroll REST API. Auth happens at the API layer with a
+site- or org-scoped key; the MCP just carries the bearer through.
 
-## Quick start
+## Two ways to connect
 
-1. **Create an API key** in your Typeroll portal at
-   `/app/sites/{siteId}/settings/api-keys`. The key is shown once at
-   creation — copy it somewhere safe.
+- **Hosted (Claude Desktop / claude.ai) — paste a URL.** No CLI, no
+  Node.js install. In Claude open **Settings → Connectors → Add custom
+  connector** and paste `https://app.typeroll.com/api/mcp`
+  (or `https://<your-self-hosted-portal>/mcp`). Claude opens a consent
+  page; paste your Typeroll API key there.
+- **Stdio (Claude Code) — one `claude mcp add` command.** Best for local
+  dev / agency staff already in a terminal. Instructions below.
+
+This npm package is the stdio transport. The hosted endpoint ships as
+part of the Typeroll portal itself — same tool surface, same package
+under the hood.
+
+## Key scopes
+
+- **Org-scoped key** (created at `/app/settings/api-keys`) — one
+  credential covers every site in your org *and* every site shared into
+  your org. The default for the hosted Claude connector. Stdio works too
+  if you set `TYPEROLL_SITE_ID` so the install binds to one site.
+- **Site-scoped key** (created at `/app/sites/{siteId}/settings/api-keys`) —
+  tighter blast radius for a single-site credential, e.g. one you'd
+  hand to a customer for a self-managed site.
+
+Both look like `typeroll_live_…`; revoke either from the portal and any
+client using it stops working immediately.
+
+## Stdio quick start (Claude Code)
+
+1. **Create an API key** in your Typeroll portal — see the two scope
+   options above. Org-scoped is the right default.
 
 2. **Add the server to Claude Code.** Drop this into `~/.claude.json`
    (or your local `.claude/config.json`):
@@ -46,13 +72,13 @@ a site-scoped key; the MCP just carries the bearer through.
    Claude will call `get_site`, `list_pages`, `list_partials`,
    `list_collections` in sequence and report back.
 
-## Environment variables
+## Environment variables (stdio)
 
 | Var             | Required | Description |
 |-----------------|----------|-------------|
 | `TYPEROLL_API_URL`  | yes      | Base URL of your Typeroll portal. |
-| `TYPEROLL_API_KEY`  | yes      | A `typeroll_live_…` bearer token from the API keys page. |
-| `TYPEROLL_SITE_ID`  | no       | Pin the server to a specific site. Defaults to autodetect (calls `GET /v1/sites` — per-site keys return exactly one). |
+| `TYPEROLL_API_KEY`  | yes      | A `typeroll_live_…` bearer token. |
+| `TYPEROLL_SITE_ID`  | sometimes | Pin to a specific site. Required when using an org-scoped key over stdio (the install can only target one site at a time); auto-detected for site-scoped keys. |
 
 ## What the agent should read first
 

package/dist/index.js

@@ -3,49 +3,31 @@
 //
 // Reads two env vars at startup:
 //   TYPEROLL_API_URL  — base URL of the portal (e.g. https://app.typeroll.com)
-//   TYPEROLL_API_KEY  — a typeroll_live_... bearer token from /app/sites/{id}/settings/api-keys
+//   TYPEROLL_API_KEY  — a typeroll_live_... bearer token from the portal
 //
 // Optionally:
 //   TYPEROLL_SITE_ID  — pre-set the site id. If omitted we discover it by
-//                   calling GET /v1/sites at startup (the v1 keys are
-//                   per-site so that endpoint always returns exactly one).
-//
-// Each tool wraps a single REST endpoint. The MCP server itself does no
-// business logic — that all lives in the portal. This keeps the package
-// boring to maintain and lets the customer's self-hosted portal serve the
-// same MCP without needing two implementations to stay in sync.
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+//                   calling GET /v1/sites at startup. For site-scoped keys
+//                   that endpoint always returns exactly one. For org-scoped
+//                   keys (introduced for the hosted MCP connector) it can
+//                   return many — in that case TYPEROLL_SITE_ID is required
+//                   so this stdio invocation maps onto one specific site.
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { TyperollClient } from './client.js';
 import { runInstallSkillsCli } from './install-skills.js';
-import { pageTools } from './tools/pages.js';
-import { partialTools } from './tools/partials.js';
-import { collectionTools } from './tools/collections.js';
-import { mediaTools } from './tools/media.js';
-import { redirectTools } from './tools/redirects.js';
-import { formTools } from './tools/forms.js';
-import { searchTools } from './tools/search.js';
-import { bulkTools } from './tools/bulk.js';
-import { versionTools } from './tools/versions.js';
-import { deployTools } from './tools/deploy.js';
-import { previewTools } from './tools/preview.js';
-import { blockTypeTools } from './tools/block-types.js';
-import { pageBlockTools } from './tools/page-blocks.js';
-import { settingsTools } from './tools/settings.js';
-import { siteTools } from './tools/sites.js';
-const VERSION = '0.7.7';
+import { buildServer } from './server.js';
+const VERSION = '0.7.8';
 async function resolveSiteId(client) {
     const fromEnv = process.env.TYPEROLL_SITE_ID?.trim();
     if (fromEnv)
         return fromEnv;
-    // Per-site keys → exactly one site. We fetch it so the agent doesn't
-    // have to know its own site id ahead of time.
     const res = await client.rootGet('sites');
     if (!res.sites || res.sites.length === 0) {
         throw new Error('No sites returned for this API key. Check the key is valid.');
     }
     if (res.sites.length > 1) {
-        throw new Error(`This key authorises ${res.sites.length} sites; set TYPEROLL_SITE_ID to pick one.`);
+        throw new Error(`This key authorises ${res.sites.length} sites; set TYPEROLL_SITE_ID to pick one. ` +
+            'Org-scoped keys span multiple sites — stdio currently binds to one at a time.');
     }
     return res.sites[0].id;
 }
@@ -54,8 +36,6 @@ function bail(message) {
     process.exit(1);
 }
 async function main() {
-    // Subcommand dispatch. These run without any of the MCP-server env-var
-    // validation below, since they don't talk to the portal.
     const argv = process.argv.slice(2);
     if (argv[0] === 'install-skills') {
         const code = await runInstallSkillsCli(argv.slice(1));
@@ -85,41 +65,11 @@ async function main() {
     catch (e) {
         bail(`Failed to discover site: ${e instanceof Error ? e.message : String(e)}`);
     }
-    const deps = { client, siteId };
-    const server = new McpServer({ name: 'typeroll', version: VERSION }, { capabilities: { tools: {} } });
-    const allTools = [
-        ...siteTools,
-        ...pageTools,
-        ...partialTools,
-        ...blockTypeTools,
-        ...pageBlockTools,
-        ...collectionTools,
-        ...mediaTools,
-        ...redirectTools,
-        ...formTools,
-        ...settingsTools,
-        ...searchTools,
-        ...bulkTools,
-        ...versionTools,
-        ...deployTools,
-        ...previewTools,
-    ];
-    // The SDK's registerTool signature has very deep generic constraints
-    // (ZodRawShape × AnySchema × annotations) that TypeScript can't unify
-    // when we iterate heterogeneous tools at runtime. We cast the bag once
-    // here and rely on our own ToolDef contract for type safety.
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const register = server.registerTool.bind(server);
-    for (const tool of allTools) {
-        register(tool.name, {
-            description: tool.description,
-            ...(tool.inputSchema ? { inputSchema: tool.inputSchema } : {}),
-        }, 
-        // The SDK's callback gets the args object (when inputSchema is set) or
-        // no args (when it isn't). Both are valid for our handler signature.
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        async (args) => tool.handler(args ?? {}, deps));
-    }
+    const server = buildServer({
+        client,
+        fixedSiteId: siteId,
+        info: { name: 'typeroll', version: VERSION },
+    });
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/server.js

@@ -0,0 +1,129 @@
+// Transport-agnostic MCP server builder. Wraps an McpServer instance with
+// the full Typeroll tool surface and either binds it to a single fixed site
+// (stdio, site-scoped HTTP) or makes it multi-site (org-scoped HTTP).
+//
+// In multi-site mode every tool's input schema gains a required `site_id`
+// argument; the handler wrapper validates that the id is in the allowed
+// list AND that the share's permission level covers the operation (read
+// vs write). This is the plumbing the hosted MCP plan calls out as
+// safety-critical when one connector can touch many sites.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { pageTools } from './tools/pages.js';
+import { partialTools } from './tools/partials.js';
+import { collectionTools } from './tools/collections.js';
+import { mediaTools } from './tools/media.js';
+import { redirectTools } from './tools/redirects.js';
+import { formTools } from './tools/forms.js';
+import { searchTools } from './tools/search.js';
+import { bulkTools } from './tools/bulk.js';
+import { versionTools } from './tools/versions.js';
+import { deployTools } from './tools/deploy.js';
+import { previewTools } from './tools/preview.js';
+import { blockTypeTools } from './tools/block-types.js';
+import { pageBlockTools } from './tools/page-blocks.js';
+import { settingsTools } from './tools/settings.js';
+import { siteTools } from './tools/sites.js';
+import { fail } from './tools/helpers.js';
+const PERM_RANK = { read: 0, write: 1, admin: 2 };
+/**
+ * Classify a tool by name into the minimum permission needed. We keep this
+ * conservative — anything that mutates is `write`. The MCP route's per-call
+ * gate then checks `effect <= sitePermission`.
+ *
+ * Naming convention is followed by all 16 tool files: read paths are
+ * `list_*` / `read_*` / `get_*` / `preview_*` / `search_*`; everything else
+ * mutates.
+ */
+function effectFor(name) {
+    if (name.startsWith('list_') ||
+        name.startsWith('read_') ||
+        name.startsWith('get_') ||
+        name.startsWith('batch_read_') ||
+        name.startsWith('preview_') ||
+        name.startsWith('search_')) {
+        return 'read';
+    }
+    return 'write';
+}
+const DEFAULT_INFO = { name: 'typeroll', version: '0.7.8' };
+export function buildServer(options) {
+    if (!options.fixedSiteId && !options.allowedSites) {
+        throw new Error('buildServer: either fixedSiteId or allowedSites must be provided');
+    }
+    if (options.fixedSiteId && options.allowedSites) {
+        throw new Error('buildServer: provide only one of fixedSiteId / allowedSites');
+    }
+    const server = new McpServer(options.info ?? DEFAULT_INFO, {
+        capabilities: { tools: {} },
+    });
+    const allTools = [
+        ...siteTools,
+        ...pageTools,
+        ...partialTools,
+        ...blockTypeTools,
+        ...pageBlockTools,
+        ...collectionTools,
+        ...mediaTools,
+        ...redirectTools,
+        ...formTools,
+        ...settingsTools,
+        ...searchTools,
+        ...bulkTools,
+        ...versionTools,
+        ...deployTools,
+        ...previewTools,
+    ];
+    // SDK's registerTool has deeply-nested generics we can't unify across a
+    // heterogeneous tool list at compile time — same shrug as stdio's index.ts.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const register = server.registerTool.bind(server);
+    const isMultiSite = !!options.allowedSites;
+    const allowedById = new Map((options.allowedSites ?? []).map((s) => [s.siteId, s]));
+    for (const tool of allTools) {
+        const effect = effectFor(tool.name);
+        let schema = tool.inputSchema;
+        if (isMultiSite) {
+            // Append site_id to the tool's existing input schema. We mutate a copy
+            // so we don't pollute the imported ToolDef.
+            const siteIdField = {
+                site_id: z
+                    .string()
+                    .describe(`Required. The id of the site this call targets. Use list_sites to discover ids; available sites for this connection: ${(options.allowedSites ?? []).map((s) => s.siteId).join(', ') || '(none)'}.`),
+            };
+            schema = { ...(tool.inputSchema ?? {}), ...siteIdField };
+        }
+        register(tool.name, {
+            description: tool.description,
+            ...(schema ? { inputSchema: schema } : {}),
+        }, 
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        async (args) => {
+            const rawArgs = args ?? {};
+            let siteId;
+            if (isMultiSite) {
+                const provided = typeof rawArgs.site_id === 'string' ? rawArgs.site_id.trim() : '';
+                if (!provided) {
+                    return fail(new Error('site_id is required. This connector covers multiple sites; pick one from list_sites.'));
+                }
+                const match = allowedById.get(provided);
+                if (!match) {
+                    return fail(new Error(`site_id "${provided}" is not accessible by this connection. Use list_sites to see allowed ids.`));
+                }
+                if (PERM_RANK[match.permission] < PERM_RANK[effect]) {
+                    return fail(new Error(`Tool "${tool.name}" requires ${effect} permission on site "${provided}"; this connection has ${match.permission}.`));
+                }
+                siteId = provided;
+                // Strip site_id from the args we pass downstream so individual
+                // tool schemas (which don't declare it) don't reject the call.
+                delete rawArgs.site_id;
+            }
+            else {
+                siteId = options.fixedSiteId;
+            }
+            const deps = { client: options.client, siteId };
+            return tool.handler(rawArgs, deps);
+        });
+    }
+    return server;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.7.7",
+  "version": "0.7.8",
   "description": "Model Context Protocol server for the Typeroll public API. Use with Claude Code or any MCP-compatible client to manage a Typeroll site.",
   "license": "MIT",
   "repository": {
@@ -15,6 +15,12 @@
     "typeroll-mcp": "dist/index.js"
   },
   "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./server": "./src/server.ts",
+    "./client": "./src/client.ts",
+    "./tools/helpers": "./src/tools/helpers.ts"
+  },
   "files": [
     "dist",
     "AGENTS.md",

package/skills/README.md

@@ -41,17 +41,20 @@ ln -s "$PWD/skills/tr-migrate-wp.md" ~/.claude/skills/
 
 | File | When it triggers | What it does |
 |---|---|---|
-| `tr-blog.md`           | "add a blog", "set up news", "article section"      | Collection schema → seed items → listing page → per-article pages → nav update → deploy. |
-| `tr-forms.md`          | "contact form", "add a form", "booking form"        | Form definition → embed HTML with signed token → inline JS feedback → deploy. |
-| `tr-directory.md`      | Building a directory site, importing structured data | Schema → items → per-item URLs via `route_template` → listing page → preview → deploy. |
-| `tr-seo.md`            | "SEO", "meta descriptions", "structured data"       | Audit → fix titles/descriptions → OG images → JSON-LD → robots.txt → deploy. |
+| `tr-blog.md`              | "add a blog", "set up news", "article/podcast section" | Collection schema with `item_template_html` + `route_template` → seed items → listing page with marker block → deploy. **No per-article `create_page` needed** — items materialise their own URLs. |
+| `tr-forms.md`             | "contact form", "add a form", "booking form"           | Form definition → embed HTML with signed token → inline JS feedback → deploy. |
+| `tr-directory.md`         | Building a directory site, importing structured data   | Schema → items → per-item URLs via `route_template` → listing page → preview → deploy. |
+| `tr-collection-template.md` | Rich per-item detail pages: audio players, chapter lists, guest cards, image galleries — anything needing loops/nested data | Pre-render HTML into `*_html` fields when Mustache's `{{field}}` / `{{#field}}` aren't enough. Concrete recipes per pattern. |
+| `tr-page-template.md`     | Several pages share structure (category landings, service-detail variants) | Partials + `<x-include>` for HTML mode; formal `PageTemplate` via `set_page_template` for block mode. Refactor existing duplication. |
+| `tr-seo.md`               | "SEO", "meta descriptions", "structured data"          | Audit → fix titles/descriptions → OG images → JSON-LD → robots.txt → deploy. |
 
 ### Importera innehåll
 
 | File | When it triggers | What it does |
 |---|---|---|
-| `tr-migrate-wp.md`     | "migrate from WordPress", a wp-json URL is mentioned | Walks the WP REST, rebuilds each page in the target's design, transfers media, sets redirects, leaves everything as drafts for review. |
-| `tr-import-url.md`     | "import from Squarespace/Wix/Webflow", any non-WP URL| Fetch → clean → adapt to target design → media transfer → draft pages → redirects → deploy. |
+| `tr-migrate-wp.md`     | "migrate from WordPress", a wp-json URL is mentioned     | Walks the WP REST, rebuilds each page in the target's design, transfers media, sets redirects, leaves everything as drafts for review. |
+| `tr-migrate-astro.md`  | "migrate an Astro site", "import from src/content"       | Lifts Astro Content Collections (`src/content/*`) into Typeroll collections — zod schema → field list, frontmatter → field values, markdown body → richtext field. Translates standalone `src/pages/*` into Typeroll pages, maps `src/layouts` chunks into partials. |
+| `tr-import-url.md`     | "import from Squarespace/Wix/Webflow", any non-WP URL    | Fetch → clean → adapt to target design → media transfer → draft pages → redirects → deploy. |
 
 ## Prerequisites for every skill