@homespunapps/mcp 1.4.2 → 1.5.0

package/dist/tools.js

@@ -348,13 +348,21 @@ const membersShape = {
 };
 const ingestShape = {
     action: z
-        .enum(["list", "rotate"])
-        .describe("list: the app's inbound catch-hooks, each with its full secret URL, current rule (collection/mode/wake/handshake), and per-status delivery counts (app_id). rotate: mint a fresh secret for one hook and return its new URL once, invalidating the old URL immediately (app_id+name)."),
+        .enum(["list", "rotate", "set_signing_secret", "clear_signing_secret"])
+        .describe("list: the app's inbound catch-hooks, each with its full secret URL, current rule (collection/mode/wake/handshake), and per-status delivery counts (app_id). rotate: mint a fresh URL secret for one hook and return its new URL once, invalidating the old URL immediately (app_id+name). set_signing_secret: provision or rotate a hook's OPT-IN signing secret, distinct from the URL secret (it is what a provider HMACs the body with); omit `secret` to mint one (returned ONCE) or pass `secret` to store a provider-generated value verbatim (never echoed) (app_id+name). clear_signing_secret: remove a hook's signing secret (app_id+name)."),
     app_id: z.string().min(1).describe("The app id."),
     name: z
         .string()
         .optional()
-        .describe("rotate only. The manifest ingest hook name to rotate (an x-homespun-manifest.ingest[].name). See list's `name` field."),
+        .describe("rotate / set_signing_secret / clear_signing_secret. The manifest ingest hook name (an x-homespun-manifest.ingest[].name). See list's `name` field."),
+    secret: z
+        .string()
+        .optional()
+        .describe("set_signing_secret only. A provider-generated signing secret to store verbatim (the Stripe path). Omit to have the relay mint one (the GitHub path), returned ONCE in the response."),
+    grace_seconds: z
+        .number()
+        .optional()
+        .describe("set_signing_secret only. On a rotation, how long the previous secret stays valid so deliveries verify while you update the provider (default 3600, max 86400)."),
 };
 // ===========================================================================
 // Consolidated management tools
@@ -534,13 +542,23 @@ const communityShape = {
     action: z
         .enum([
         "publish",
+        "get_config_contract",
+        "install",
         "list_pending",
         "get_submission",
         "approve",
         "reject",
         "set_trust_level",
     ])
-        .describe("publish: publish one of YOUR apps as a community template (app_id; optional title/description/category/tags). PRIVACY: publishing makes the template content AND the captured seed rows (the LIVE rows of every seedOnInstall collection, captured at publish time) PUBLIC to every platform user once approved. Do NOT publish an app whose seedOnInstall collections hold real personal data (names, emails, addresses, messages, anything private): seed data must be example-only. Pass attest_example_only:true to attest you have checked this. The capture (html + manifest + seed rows) lands PENDING review, installable by its returned direct link but not listed until approved; an ESTABLISHED publisher is fast-tracked (the response's expedited/auto_approved tell you which). list_pending / get_submission / approve / reject / set_trust_level are RELAY-OPERATOR-only review actions: list_pending (the review queue, expedited submissions first), get_submission (a submission's full html+manifest+seedRows, by snapshot_id), approve (snapshot_id, lists it in the gallery + supersedes the app's prior approved version), reject (snapshot_id + a required note that lands in the publisher's app feed), set_trust_level (promote/demote a publisher by handle: handle + trust_level 'new'|'established')."),
+        .describe("publish: publish one of YOUR apps as a community template (app_id; optional title/description/category/tags). PRIVACY: publishing makes the template content AND the captured seed rows (the LIVE rows of every seedOnInstall collection, captured at publish time) PUBLIC to every platform user once approved. Do NOT publish an app whose seedOnInstall collections hold real personal data (names, emails, addresses, messages, anything private): seed data must be example-only. Pass attest_example_only:true to attest you have checked this. The capture (html + manifest + seed rows) lands PENDING review, installable by its returned direct link but not listed until approved; an ESTABLISHED publisher is fast-tracked (the response's expedited/auto_approved tell you which). get_config_contract: read a template's install-time config contract by `ref` (a namespaced '<handle>/<slug>' or a snapshot id): its settings_collection, ordered config_steps (each with key/kind/required/secret/choices/default), and connect_steps (inbound hooks the app receives on). An 'upload' step wants a file; pre-upload it with the attachments tool (scope agent) and pass its attachment id. After installing a template with connect_steps, run the `ingest` tool's list action on the new app_id to read its freshly provisioned hook URLs, and wire each into the external service. install: install a template by `ref` for YOU (your owning human becomes the owner). Pass `config` as { stepKey: value } from the contract: a 'config' step's value is a string, an 'upload' step's value is a pre-uploaded attachment id. A required step you omit is rejected. Returns the new app's id, slug, and url; installs always create a fresh private copy. list_pending / get_submission / approve / reject / set_trust_level are RELAY-OPERATOR-only review actions: list_pending (the review queue, expedited submissions first), get_submission (a submission's full html+manifest+seedRows plus external_destinations, the hosts it can send data to or pull data from, by snapshot_id), approve (snapshot_id, lists it in the gallery + supersedes the app's prior approved version), reject (snapshot_id + a required note that lands in the publisher's app feed), set_trust_level (promote/demote a publisher by handle: handle + trust_level 'new'|'established')."),
+    ref: z
+        .string()
+        .optional()
+        .describe("get_config_contract/install only. The template to read or install: a namespaced '<handle>/<slug>' or a community snapshot id."),
+    config: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("install only. The install-time answers as { stepKey: value } from the config contract: a 'config' step's value is a string, an 'upload' step's value is a pre-uploaded attachment id. Omit for a template with no config steps."),
     app_id: z
         .string()
         .optional()
@@ -611,9 +629,13 @@ const communityShape = {
             .string()
             .optional()
             .describe("Optional format hint (<= 120 chars)."),
+        ingestRule: z
+            .string()
+            .optional()
+            .describe("The manifest `ingest` rule this step wires up. Allowed ONLY on a 'connect' step, optional there; publish rejects a name x-homespun-manifest.ingest does not declare. Each install mints that rule its OWN hook URL, which the installer pastes into the external service."),
     }))
         .optional()
-        .describe("publish only. Ordered typed setup steps an installing agent follows after install (up to 20). A 'config'/'upload' step may carry a `key` naming a field of the manifest's settingsCollection that its install-time answer is written into. Read back via get_submission and rendered on the template detail page."),
+        .describe("publish only. Ordered typed setup steps an installing agent follows after install (up to 20). A 'config'/'upload' step may carry a `key` naming a field of the manifest's settingsCollection that its install-time answer is written into; a 'connect' step may carry an `ingestRule` naming a manifest ingest rule it wires up. Read back via get_submission and rendered on the template detail page."),
     derived_from_snapshot_id: z
         .string()
         .optional()
@@ -1205,7 +1227,7 @@ export const TOOLS = [
     // ----- consolidated management tools --------------------------------------
     {
         name: "ingest",
-        description: "Manage a v2 app's inbound catch-hooks (inbound-webhooks). A catch-hook lets an EXTERNAL system (Stripe, Zapier, Make, Home Assistant, an email router) POST JSON to a secret URL that writes into a declared collection, so the app receives data even with no agent online. Hooks are DECLARED IN THE MANIFEST (x-homespun-manifest.ingest) and materialized at deploy, so this tool has no create/delete: use it to READ BACK the URL and rotate a leaked one. ONE tool with an `action` enum: list (the app's hooks, each with its full secret URL, current rule collection/mode/wake/handshake, and per-status delivery counts) | rotate (mint a fresh secret for one hook by name and return its NEW url once; the old url stops working immediately, no redeploy needed). After deploying a manifest that declares a hook, run list and tell the owner the exact url to paste into the external system.",
+        description: "Manage a v2 app's inbound catch-hooks (inbound-webhooks). A catch-hook lets an EXTERNAL system (Stripe, Zapier, Make, Home Assistant, an email router) POST JSON to a secret URL that writes into a declared collection, so the app receives data even with no agent online. Hooks are DECLARED IN THE MANIFEST (x-homespun-manifest.ingest) and materialized at deploy, so this tool has no create/delete: use it to READ BACK the URL, rotate a leaked one, and manage the opt-in signing secret. ONE tool with an `action` enum: list (the app's hooks, each with its full secret URL, current rule collection/mode/wake/handshake, per-status delivery counts, and signing-secret state) | rotate (mint a fresh URL secret for one hook by name and return its NEW url once; the old url stops working immediately, no redeploy needed) | set_signing_secret (provision/rotate a hook's signing secret, a DIFFERENT secret from the URL: what a provider HMACs the body with; omit `secret` to mint one returned ONCE, or pass `secret` to store a provider value verbatim, never echoed) | clear_signing_secret (remove it). Signature verification ships DARK for now: nothing verifies a signature yet. After deploying a manifest that declares a hook, run list and tell the owner the exact url to paste into the external system.",
         inputSchema: ingestShape,
         // Consolidated tool: read action (list) + a mutating one (rotate). Marked
         // destructive (not read-only) because rotate invalidates the old URL, which
@@ -1234,6 +1256,23 @@ export const TOOLS = [
                         }
                         return jsonResult(await client.rotateIngestHook(appId, String(args["name"])));
                     }
+                    case "set_signing_secret": {
+                        if (str(args, "name") === undefined) {
+                            return invalidArgs("set_signing_secret requires `name`");
+                        }
+                        const secret = str(args, "secret");
+                        const grace = args["grace_seconds"];
+                        return jsonResult(await client.setIngestSigningSecret(appId, String(args["name"]), {
+                            ...(secret !== undefined ? { secret } : {}),
+                            ...(typeof grace === "number" ? { graceSeconds: grace } : {}),
+                        }));
+                    }
+                    case "clear_signing_secret": {
+                        if (str(args, "name") === undefined) {
+                            return invalidArgs("clear_signing_secret requires `name`");
+                        }
+                        return jsonResult(await client.clearIngestSigningSecret(appId, String(args["name"])));
+                    }
                     default:
                         return invalidArgs(`unknown ingest action '${action}'`);
                 }
@@ -1580,7 +1619,7 @@ export const TOOLS = [
     },
     {
         name: "community",
-        description: "Publish an app you own as a COMMUNITY TEMPLATE, and (relay operators only) review submissions. ONE tool with an `action` enum: publish | list_pending | get_submission | approve | reject. publish captures your live app (html + manifest + the seed rows of its seedOnInstall collections + listing metadata) into a PENDING template - installable by the returned direct link but NOT listed in the public gallery until an operator approves it; you must have a verified email and at most a few pending submissions at once. PRIVACY: an approved template's content AND its captured seed rows become PUBLIC to every platform user, so never publish an app whose seedOnInstall collections hold real personal data - seed data must be example-only. Pass attest_example_only:true to attest you checked this. Optionally give the template a per-publisher `slug` (namespaced id <your-handle>/<slug>) and a semver `version` (default 1.0.0): a republish under the same slug must bump the version. The review actions are limited to the relay's configured community reviewers: list_pending (the queue), get_submission (a submission's full content by snapshot_id), approve (list it in the gallery; a re-publish supersedes your app's prior approved version), reject (with a required note that lands in the publisher's app feed).",
+        description: "Publish an app you own as a COMMUNITY TEMPLATE, install a template into your own account, and (relay operators only) review submissions. ONE tool with an `action` enum: publish | get_config_contract | install | list_pending | get_submission | approve | reject | set_trust_level. publish captures your live app (html + manifest + the seed rows of its seedOnInstall collections + listing metadata) into a PENDING template - installable by the returned direct link but NOT listed in the public gallery until an operator approves it; you must have a verified email and at most a few pending submissions at once. PRIVACY: an approved template's content AND its captured seed rows become PUBLIC to every platform user, so never publish an app whose seedOnInstall collections hold real personal data - seed data must be example-only. Pass attest_example_only:true to attest you checked this. Optionally give the template a per-publisher `slug` (namespaced id <your-handle>/<slug>) and a semver `version` (default 1.0.0): a republish under the same slug must bump the version. get_config_contract reads what a template needs at install (its settings collection + ordered config/upload steps) by `ref`; install creates a fresh PRIVATE copy of a template for YOUR owning human, passing the answers as `config` (a 'config' value is a string, an 'upload' value is a pre-uploaded attachment id from the attachments tool). The review actions are limited to the relay's configured community reviewers: list_pending (the queue), get_submission (a submission's full content by snapshot_id), approve (list it in the gallery; a re-publish supersedes your app's prior approved version), reject (with a required note that lands in the publisher's app feed).",
         inputSchema: communityShape,
         // Consolidated tool: read actions (list_pending/get_submission) + mutating
         // ones (publish/approve/reject). Hint reflects the most-privileged action.
@@ -1618,6 +1657,24 @@ export const TOOLS = [
                             attestExampleOnly: bool(args, "attest_example_only"),
                         }));
                     }
+                    case "get_config_contract": {
+                        const ref = str(args, "ref");
+                        if (ref === undefined) {
+                            return invalidArgs("get_config_contract requires `ref`");
+                        }
+                        return jsonResult(await client.getCommunityConfigContract(ref));
+                    }
+                    case "install": {
+                        const ref = str(args, "ref");
+                        if (ref === undefined) {
+                            return invalidArgs("install requires `ref`");
+                        }
+                        const cfg = args["config"];
+                        const config = cfg !== null && typeof cfg === "object" && !Array.isArray(cfg)
+                            ? cfg
+                            : undefined;
+                        return jsonResult(await client.installCommunityTemplate(ref, config));
+                    }
                     case "list_pending": {
                         const opts = {};
                         if (args["limit"] !== undefined)

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.4.2";
+export declare const VERSION = "1.5.0";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Single source of the package version, reported in the MCP server's
 // serverInfo. Kept in sync with package.json by the release tooling.
-export const VERSION = "1.4.2";
+export const VERSION = "1.5.0";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@homespunapps/mcp",
-  "mcpName": "io.github.aerolalit/homespun",
-  "version": "1.4.2",
+  "mcpName": "dev.homespun/homespun",
+  "version": "1.5.0",
   "description": "Model Context Protocol (stdio) server for Homespun: lets any MCP client (Claude Desktop, Cursor, …) hand a human a rich interactive UI by URL and get structured data back.",
   "license": "MIT",
   "type": "module",
@@ -46,7 +46,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.20.0",
-    "@homespunapps/core": "^1.4.2",
+    "@homespunapps/core": "^1.5.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/server.json

@@ -1,16 +1,16 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
-  "name": "io.github.aerolalit/homespun",
+  "name": "dev.homespun/homespun",
   "title": "Homespun",
   "description": "Hand a human a rich interactive UI by URL and get structured data back, from any MCP client.",
-  "version": "1.4.2",
-  "websiteUrl": "https://homespun.dev",
+  "version": "1.5.0",
+  "websiteUrl": "https://docs.homespun.dev",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@homespunapps/mcp",
-      "version": "1.4.2",
+      "version": "1.5.0",
       "transport": {
         "type": "stdio"
       },
@@ -41,5 +41,10 @@
         }
       ]
     }
-  ]
+  ],
+  "repository": {
+    "url": "https://github.com/homespunapps/homespun",
+    "source": "github",
+    "subfolder": "packages/mcp"
+  }
 }