@homespunapps/mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lalit Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,167 @@
+# @homespunapps/mcp
+
+A thin **stdio [Model Context Protocol](https://modelcontextprotocol.io) server** for [Homespun](https://github.com/aerolalit/homespun). It lets any MCP client — Claude Desktop, Cursor, Windsurf, Cline, your own host — hand a human a rich interactive UI by URL and get structured data back: forms, approvals, pickers, surveys, dashboards, diff/doc review, multi-step wizards.
+
+It is a wrapper, not a reimplementation: all relay I/O goes through [`@homespunapps/core`](https://www.npmjs.com/package/@homespunapps/core), and config is shared with the [`homespun` CLI](https://www.npmjs.com/package/@homespunapps/cli) (`~/.config/homespun/config.json`) — so the CLI and this server use the **same agent identity**.
+
+## Runtime requirement: Node.js >= 20
+
+The binary is `homespun-mcp`. It speaks MCP over stdio and is meant to be launched by an MCP host, not run interactively.
+
+## Quickstart
+
+No global install needed — point your MCP client at `npx @homespunapps/mcp`. On first use, if no API key is configured, the server auto-registers a fresh agent against the hosted relay and saves the key to the shared CLI store; nothing else to set up.
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "homespun": {
+      "command": "npx",
+      "args": ["-y", "@homespunapps/mcp"]
+    }
+  }
+}
+```
+
+To pin an existing agent key instead of auto-registering, add an `env` block:
+
+```json
+{
+  "mcpServers": {
+    "homespun": {
+      "command": "npx",
+      "args": ["-y", "@homespunapps/mcp"],
+      "env": { "HOMESPUN_API_KEY": "hs_..." }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
+
+```json
+{
+  "mcpServers": {
+    "homespun": {
+      "command": "npx",
+      "args": ["-y", "@homespunapps/mcp"],
+      "env": { "HOMESPUN_API_KEY": "hs_..." }
+    }
+  }
+}
+```
+
+### Generic MCP host
+
+Any client that takes a `command` + `args` + `env` works the same way:
+
+```json
+{
+  "mcpServers": {
+    "homespun": {
+      "command": "npx",
+      "args": ["-y", "@homespunapps/mcp"],
+      "env": {
+        "HOMESPUN_URL": "https://homespun.dev",
+        "HOMESPUN_API_KEY": "hs_..."
+      }
+    }
+  }
+}
+```
+
+If you'd rather install it globally (`npm i -g @homespunapps/mcp`), use `"command": "homespun-mcp"` with no `args`.
+
+## Configuration
+
+All environment variables are optional — the defaults target the hosted relay and auto-register on first use.
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `HOMESPUN_URL` | `https://homespun.dev` | Relay base URL. Set to point at a self-hosted relay. |
+| `HOMESPUN_API_KEY` | _(auto-registered)_ | Agent API key. If unset, the server registers an agent on first use and saves the key to `~/.config/homespun/config.json` (shared with the CLI). |
+| `HOMESPUN_TOKEN` | — | Alias for `HOMESPUN_API_KEY` (for hosts that name secrets `*_TOKEN`). `HOMESPUN_API_KEY` wins if both are set. |
+| `HOMESPUN_AGENT_NAME` | `homespun-mcp` | Display name for the auto-registered agent. |
+| `HOMESPUN_REGISTER_SECRET` | — | Registration secret, only for relays running `REGISTRATION_MODE=secret`. |
+
+Config precedence mirrors the CLI: env vars win over the saved profile, which falls back to the default relay URL.
+
+## Tools
+
+This server has **full parity with the [`homespun` CLI](https://www.npmjs.com/package/@homespunapps/cli)** — every capability the CLI exposes is reachable here.
+
+MCP tools are request/response — there is no long-lived "watch". To receive a human's response you **poll** `get_events` with the cursor from the previous call (optionally with `wait_seconds` to long-poll); to watch a record collection, re-call `list_records` with the prior `since`. Each tool description spells out the pattern for the model.
+
+To keep the tool list compact (a flat 50+ tools would bloat client context and degrade selection), **hot-path nouns stay discrete tools** while **multi-verb management nouns collapse into one tool each with a required `action` enum**.
+
+### Hot-path (discrete) tools
+
+| Tool | What it does |
+| --- | --- |
+| `create_app` | Create an app — inline HTML (`name`+`html`) **or** reuse a saved template (`template_id`). Optional event/input/record schema, participants, tags, icon, callback, `context_key`. Returns `{ app_id, url, urls, title, expires_at }`. **Give `url` to the human.** |
+| `get_app_state` | Fetch an app's metadata (status, title, expiry) without its event log. |
+| `get_events` | Poll the app's append-only event log for what the human did. Pass `since` (cursor) and optional `wait_seconds` (long-poll). |
+| `send_to_app` | Push an event into an open app to update the live UI. |
+| `update_app` | Edit a live app in place (ttl/title/preamble/input_data/metadata/tags/icon). |
+| `upgrade_app` | Re-pin a live app to another version of its template (swap HTML+schemas, same URL). |
+| `list_apps` | Enumerate your apps (filter by status/template_id; paginated). |
+| `delete_app` | Close/delete an app. |
+| `list_records` | List rows in an app's mutable record collection (also the records poll/watch). |
+| `get_record` | Fetch one record row by key. |
+| `upsert_record` | Create/return a record row (dedups on `record_key`). |
+| `update_record` | Update a record row (optional `if_match` optimistic lock). |
+| `delete_record` | Soft-delete a record row (the page sees it live). |
+| `delete_record_collection` | Drop a whole record collection (all rows + the collection row). Destructive, owner-only, requires `confirm: true`. |
+
+### Consolidated tools (one tool, required `action`)
+
+| Tool | Actions |
+| --- | --- |
+| `template` | `create` · `version` · `update` · `search` · `list` · `show` · `get_version` · `delete` · `publish` · `unpublish` · `search_public` · `set_icon` |
+| `template_records` | `list` · `get` · `upsert` · `update` · `delete` · `delete_collection` |
+| `participant` | `list` · `new` · `revoke` |
+| `share` | `list` · `invite` · `set_access` · `revoke` |
+| `attachments` | `upload` · `download` · `show` · `list` · `delete` · `mint_token` · `revoke_token` · `list_tokens` |
+| `taste` | `get` · `set` · `clear` |
+| `key` | `list` · `revoke` |
+| `trash` | `list` · `restore` · `restore_template` · `purge` · `purge_template` |
+| `feedback` | `create` · `list` |
+| `agent` | `whoami` · `claim` · `logout` |
+
+### Single-purpose tools
+
+| Tool | What it does |
+| --- | --- |
+| `run_query` | Read-only SQL over your scoped apps/records/events (`format`: json/csv/tsv/table). |
+| `get_skill` | Fetch the relay's auto-updating `SKILL.md` (unauthenticated) to self-teach the workflow. |
+
+**Attachments** take/return file paths: `upload` reads an absolute `file_path`; `download` writes to an absolute `out_path` (or returns base64 when omitted).
+
+**Events vs records.** Events are an append-only journal — forms, approvals, surveys, pickers. Records are a mutable collection where the current state matters more than the edit history — todo lists, kanban boards, comment threads. Reach for records when the page shows several mutable items.
+
+### Not exposed (and why)
+
+- The CLI's `config show` is replaced by `agent`→`whoami` (resolved relay URL + active profile + whether a key is set; no secrets).
+- `agent register` isn't a tool — the server auto-registers on first use and shares the CLI's key store; `agent`→`claim` binds it to a human afterward.
+- `demo` (the interactive 60-second terminal tour) and the CLI self-updater are terminal/CLI concerns with no agent use; omitted.
+
+## Typical flow
+
+1. `create_app` with your HTML + an `event_schema` declaring the events the page emits → returns a `url`.
+2. Paste the `url` into the conversation and ask the human to open it.
+3. `get_events` with `wait_seconds: 25` in a loop, passing the prior `next_cursor` as `since`, until the awaited event appears.
+4. Optionally `send_to_app` to update the live UI, or use the record tools for mutable collections.
+
+## MCP registry
+
+`server.json` (in this package) carries the metadata for the [official MCP registry](https://registry.modelcontextprotocol.io). Publishing there is a follow-up step for the maintainer.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/capabilities.d.ts

@@ -0,0 +1,9 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare const GUIDE_RESOURCE_URI = "homespun://guide";
+export declare const GUIDE_PROMPT_NAME = "homespun_guide";
+/**
+ * Register the `homespun_guide` prompt and the `homespun://guide` resource on `server`.
+ * `getGuide()` returns the current MCP-flavoured guide markdown (called lazily
+ * on each read so a relay can serve an updated guide without re-registering).
+ */
+export declare function registerGuideCapabilities(server: McpServer, getGuide: () => string | Promise<string>): void;

package/dist/capabilities.js

@@ -0,0 +1,50 @@
+// Register app's MCP prompt + resource on an McpServer.
+//
+// Both the stdio server (packages/mcp/src/server.ts) and the relay's HTTP MCP
+// server call this so an MCP-native client can discover the conceptual guide
+// without a tool call:
+//
+//   - prompt   `homespun_guide`   — surfaces the guide as a prompt the client can
+//                               insert into context ("teach me app").
+//   - resource `homespun://guide`  — the same guide as a readable resource.
+//
+// The guide text is supplied by the host: the relay composes it in-process
+// (MCP-INVOCATION.md + the core extracted from SKILL.md); the stdio server
+// fetches it from the relay over HTTP and falls back to a short pointer when
+// the relay is unreachable at registration time (registration must not block on
+// the network — the get_skill tool is the always-fresh path).
+export const GUIDE_RESOURCE_URI = "homespun://guide";
+export const GUIDE_PROMPT_NAME = "homespun_guide";
+/**
+ * Register the `homespun_guide` prompt and the `homespun://guide` resource on `server`.
+ * `getGuide()` returns the current MCP-flavoured guide markdown (called lazily
+ * on each read so a relay can serve an updated guide without re-registering).
+ */
+export function registerGuideCapabilities(server, getGuide) {
+    server.registerResource(GUIDE_PROMPT_NAME, GUIDE_RESOURCE_URI, {
+        title: "Homespun usage guide",
+        description: "The app conceptual guide for MCP clients: when to use app, events vs records, schema design, the house style, and the round-trip mental model — with MCP tool-call invocation grammar.",
+        mimeType: "text/markdown",
+    }, async () => {
+        const text = await getGuide();
+        return {
+            contents: [
+                { uri: GUIDE_RESOURCE_URI, mimeType: "text/markdown", text },
+            ],
+        };
+    });
+    server.registerPrompt(GUIDE_PROMPT_NAME, {
+        title: "Homespun usage guide",
+        description: "Insert the app usage guide (MCP invocation + conceptual core) into the conversation so the model knows how to drive app's tools.",
+    }, async () => {
+        const text = await getGuide();
+        return {
+            messages: [
+                {
+                    role: "user",
+                    content: { type: "text", text },
+                },
+            ],
+        };
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,65 @@
+import { HomespunClient } from "@homespunapps/core";
+/**
+ * The hosted Homespun relay — the URL fallback when nothing else is set. A
+ * self-hoster overrides it with HOMESPUN_URL or a registered profile.
+ */
+export declare const DEFAULT_RELAY_URL = "https://homespun.dev";
+/**
+ * Profile name used when this server auto-registers a fresh agent. Matches the
+ * CLI's DEFAULT_PROFILE_NAME so the two share the same default identity.
+ */
+export declare const DEFAULT_PROFILE_NAME = "default";
+/** Absolute path to the shared CLI/MCP config file (honours XDG_CONFIG_HOME). */
+export declare function storePath(): string;
+/**
+ * Clear the active saved profile from the shared store (mirrors `homespun agent
+ * logout` for the active-profile case). Removes the profile entry and unsets
+ * `current_profile` so the next resolve falls back to env / the default URL.
+ * Local-only: it does NOT revoke the key on the relay (use the `key` tool's
+ * `revoke` action for that). Idempotent — clearing an empty store is a no-op.
+ * Returns the profile name that was cleared (or null when nothing was active)
+ * and the store path.
+ */
+export declare function clearActiveProfile(): {
+    cleared: boolean;
+    profile: string | null;
+    path: string;
+};
+/** Resolve the relay URL using the same precedence as the CLI. */
+export declare function resolveUrl(): string;
+/**
+ * Describe how the server is currently configured WITHOUT touching the network
+ * — the resolved relay URL, the active profile name, where the key is coming
+ * from, and whether a key is present at all. Backs the `agent` tool's `whoami`
+ * action so an MCP client can introspect its own identity / relay binding the
+ * way `homespun config show` does for the CLI. No secrets are returned (the API key
+ * plaintext is never surfaced — only its source + whether it exists).
+ */
+export declare function describeActiveConfig(): {
+    url: string;
+    profile: string | null;
+    api_key_present: boolean;
+    api_key_source: "env" | "profile" | "none";
+    store_path: string;
+};
+/**
+ * Resolve a ready-to-use HomespunClient.
+ *
+ * First-run setup: if no API key is resolvable from the environment or the
+ * shared store, the server auto-registers a fresh agent against the relay and
+ * persists the key under the `default` profile in the shared store — so the
+ * CLI and any later MCP launch reuse the same identity, and the human never
+ * has to run `homespun agent register` by hand.
+ *
+ * A self-hoster on a `secret`-mode relay (or anyone who prefers explicit
+ * provisioning) sets HOMESPUN_API_KEY / HOMESPUN_TOKEN and the auto-register path is
+ * never taken.
+ *
+ * `opts.agentName` labels the auto-registered agent on the relay.
+ * `opts.registerSecret` is forwarded as the registration secret for
+ * REGISTRATION_MODE=secret relays.
+ */
+export declare function resolveClient(opts?: {
+    agentName?: string;
+    registerSecret?: string;
+}): Promise<HomespunClient>;

package/dist/config.js

@@ -0,0 +1,229 @@
+// Relay config resolution for the MCP server.
+//
+// Mirrors how `@homespunapps/cli` resolves config (see packages/cli/src/config.ts +
+// store.ts) and shares the SAME on-disk store — ${XDG_CONFIG_HOME or
+// ~/.config}/homespun/config.json — so a key obtained via `homespun agent register`
+// is reused here, and a key obtained here (auto-register on first use) is
+// reused by the CLI.
+//
+// Precedence (highest first):
+//   url:    HOMESPUN_URL env  → active profile's url   → DEFAULT_RELAY_URL
+//   apiKey: HOMESPUN_API_KEY  → HOMESPUN_TOKEN  → active profile's api_key
+//
+// HOMESPUN_TOKEN is accepted as an alias for HOMESPUN_API_KEY: MCP host config files
+// (Claude Desktop / Cursor) commonly name secrets "*_TOKEN", and the task
+// brief calls it HOMESPUN_TOKEN. HOMESPUN_API_KEY wins if both are set.
+//
+// The store is read/written WITHOUT a dependency on @homespunapps/cli (it doesn't
+// export its store module). The on-disk shape is kept byte-compatible with
+// the CLI's store.ts so the two stay interchangeable.
+import { readFileSync, writeFileSync, mkdirSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { HomespunClient, registerAgent } from "@homespunapps/core";
+/**
+ * The hosted Homespun relay — the URL fallback when nothing else is set. A
+ * self-hoster overrides it with HOMESPUN_URL or a registered profile.
+ */
+export const DEFAULT_RELAY_URL = "https://homespun.dev";
+/**
+ * Profile name used when this server auto-registers a fresh agent. Matches the
+ * CLI's DEFAULT_PROFILE_NAME so the two share the same default identity.
+ */
+export const DEFAULT_PROFILE_NAME = "default";
+/** Absolute path to the shared CLI/MCP config file (honours XDG_CONFIG_HOME). */
+export function storePath() {
+    const base = process.env.XDG_CONFIG_HOME && process.env.XDG_CONFIG_HOME.trim() !== ""
+        ? process.env.XDG_CONFIG_HOME
+        : join(homedir(), ".config");
+    return join(base, "homespun", "config.json");
+}
+/**
+ * Read the persisted store. Returns an empty store if the file is missing,
+ * unparseable, or malformed — mirrors the CLI's tolerant reader so a corrupt
+ * file degrades to "no saved profile" instead of crashing.
+ */
+function readStore() {
+    let text;
+    try {
+        text = readFileSync(storePath(), "utf8");
+    }
+    catch {
+        return { profiles: {} };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { profiles: {} };
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { profiles: {} };
+    }
+    const obj = parsed;
+    if (!obj["profiles"] || typeof obj["profiles"] !== "object") {
+        return { profiles: {} };
+    }
+    const rawProfiles = obj["profiles"];
+    const profiles = {};
+    for (const [name, raw] of Object.entries(rawProfiles)) {
+        if (raw === null || typeof raw !== "object")
+            continue;
+        const p = raw;
+        const profile = {};
+        if (typeof p["url"] === "string")
+            profile.url = p["url"];
+        if (typeof p["api_key"] === "string")
+            profile.apiKey = p["api_key"];
+        profiles[name] = profile;
+    }
+    const currentProfile = typeof obj["current_profile"] === "string"
+        ? obj["current_profile"]
+        : undefined;
+    return {
+        currentProfile: currentProfile && profiles[currentProfile] !== undefined
+            ? currentProfile
+            : undefined,
+        profiles,
+    };
+}
+/** Serialise a Store to the CLI's on-disk JSON shape (snake_case fields). */
+function serialize(store) {
+    const profilesOut = {};
+    for (const [name, p] of Object.entries(store.profiles)) {
+        const o = {};
+        if (p.url !== undefined)
+            o["url"] = p.url;
+        if (p.apiKey !== undefined)
+            o["api_key"] = p.apiKey;
+        profilesOut[name] = o;
+    }
+    const body = { profiles: profilesOut };
+    if (store.currentProfile !== undefined) {
+        body["current_profile"] = store.currentProfile;
+    }
+    return JSON.stringify(body, null, 2) + "\n";
+}
+/** Upsert one profile and persist (mode 0600). Used by auto-register. */
+function upsertProfile(name, patch, setCurrent) {
+    const store = readStore();
+    const merged = { ...(store.profiles[name] ?? {}), ...patch };
+    store.profiles[name] = merged;
+    if (setCurrent || store.currentProfile === undefined) {
+        store.currentProfile = name;
+    }
+    const path = storePath();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, serialize(store), { mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+/**
+ * Clear the active saved profile from the shared store (mirrors `homespun agent
+ * logout` for the active-profile case). Removes the profile entry and unsets
+ * `current_profile` so the next resolve falls back to env / the default URL.
+ * Local-only: it does NOT revoke the key on the relay (use the `key` tool's
+ * `revoke` action for that). Idempotent — clearing an empty store is a no-op.
+ * Returns the profile name that was cleared (or null when nothing was active)
+ * and the store path.
+ */
+export function clearActiveProfile() {
+    const store = readStore();
+    const path = storePath();
+    const name = store.currentProfile;
+    if (name === undefined || store.profiles[name] === undefined) {
+        return { cleared: true, profile: null, path };
+    }
+    delete store.profiles[name];
+    store.currentProfile = undefined;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, serialize(store), { mode: 0o600 });
+    chmodSync(path, 0o600);
+    return { cleared: true, profile: name, path };
+}
+/** Resolve the relay URL using the same precedence as the CLI. */
+export function resolveUrl() {
+    const store = readStore();
+    const active = store.currentProfile
+        ? store.profiles[store.currentProfile]
+        : undefined;
+    const url = process.env.HOMESPUN_URL ?? active?.url ?? DEFAULT_RELAY_URL;
+    return url.replace(/\/$/, "");
+}
+/**
+ * Describe how the server is currently configured WITHOUT touching the network
+ * — the resolved relay URL, the active profile name, where the key is coming
+ * from, and whether a key is present at all. Backs the `agent` tool's `whoami`
+ * action so an MCP client can introspect its own identity / relay binding the
+ * way `homespun config show` does for the CLI. No secrets are returned (the API key
+ * plaintext is never surfaced — only its source + whether it exists).
+ */
+export function describeActiveConfig() {
+    const store = readStore();
+    const url = resolveUrl();
+    const profile = store.currentProfile ?? null;
+    let source = "none";
+    if ((process.env.HOMESPUN_API_KEY && process.env.HOMESPUN_API_KEY !== "") ||
+        (process.env.HOMESPUN_TOKEN && process.env.HOMESPUN_TOKEN !== "")) {
+        source = "env";
+    }
+    else {
+        const active = store.currentProfile
+            ? store.profiles[store.currentProfile]
+            : undefined;
+        if (active?.apiKey && active.apiKey !== "")
+            source = "profile";
+    }
+    return {
+        url,
+        profile,
+        api_key_present: source !== "none",
+        api_key_source: source,
+        store_path: storePath(),
+    };
+}
+/** Resolve the API key (env → HOMESPUN_TOKEN alias → active profile). */
+function resolveApiKey() {
+    const store = readStore();
+    const active = store.currentProfile
+        ? store.profiles[store.currentProfile]
+        : undefined;
+    const key = process.env.HOMESPUN_API_KEY ??
+        process.env.HOMESPUN_TOKEN ??
+        active?.apiKey;
+    return key && key !== "" ? key : undefined;
+}
+/**
+ * Resolve a ready-to-use HomespunClient.
+ *
+ * First-run setup: if no API key is resolvable from the environment or the
+ * shared store, the server auto-registers a fresh agent against the relay and
+ * persists the key under the `default` profile in the shared store — so the
+ * CLI and any later MCP launch reuse the same identity, and the human never
+ * has to run `homespun agent register` by hand.
+ *
+ * A self-hoster on a `secret`-mode relay (or anyone who prefers explicit
+ * provisioning) sets HOMESPUN_API_KEY / HOMESPUN_TOKEN and the auto-register path is
+ * never taken.
+ *
+ * `opts.agentName` labels the auto-registered agent on the relay.
+ * `opts.registerSecret` is forwarded as the registration secret for
+ * REGISTRATION_MODE=secret relays.
+ */
+export async function resolveClient(opts = {}) {
+    const url = resolveUrl();
+    let apiKey = resolveApiKey();
+    if (apiKey === undefined) {
+        // No key anywhere — provision one and persist it under `default`.
+        const result = await registerAgent({
+            url,
+            name: opts.agentName ?? "homespun-mcp",
+            ...(opts.registerSecret !== undefined && opts.registerSecret !== ""
+                ? { secret: opts.registerSecret }
+                : {}),
+        });
+        upsertProfile(DEFAULT_PROFILE_NAME, { url, apiKey: result.api_key }, true);
+        apiKey = result.api_key;
+    }
+    return new HomespunClient({ url, apiKey });
+}

package/dist/guide.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Extract every `<!-- homespun:core:start -->…<!-- homespun:core:end -->` block from a
+ * SKILL.md body, concatenated in document order (markers removed). Returns the
+ * transport-agnostic conceptual core with no CLI command grammar.
+ */
+export declare function extractCore(skillMarkdown: string): string;
+/**
+ * Build the full MCP guide: the MCP invocation layer followed by the shared
+ * conceptual core extracted from SKILL.md. `mcpInvocation` is the contents of
+ * skills/homespun/MCP-INVOCATION.md; `skillMarkdown` is the contents of SKILL.md.
+ */
+export declare function composeMcpGuide(mcpInvocation: string, skillMarkdown: string): string;

package/dist/guide.js

@@ -0,0 +1,49 @@
+// Compose the MCP-flavoured app guide from the shared conceptual core + the
+// MCP invocation layer.
+//
+// Single source of truth: the conceptual core lives in skills/homespun/SKILL.md
+// between `<!-- homespun:core:start -->` / `<!-- homespun:core:end -->` markers (the
+// CLI invocation grammar lives OUTSIDE those markers, so the CLI document and
+// the MCP guide share the exact same prose for "when to use app / events vs
+// records / schema design / house style / the round-trip mental model"). The
+// MCP invocation layer (tool-call grammar) lives in skills/homespun/MCP-INVOCATION.md.
+//
+// The MCP guide = MCP-INVOCATION.md (with its trailing "the rest is the core"
+// pointer) + every core block extracted from SKILL.md, in document order. No
+// `homespun ...` command grammar leaks into it.
+//
+// This is pure string manipulation so both the relay (which reads the files at
+// boot and serves the result) and any other consumer can share one
+// implementation without dragging in I/O.
+const CORE_START = "<!-- homespun:core:start -->";
+const CORE_END = "<!-- homespun:core:end -->";
+/**
+ * Extract every `<!-- homespun:core:start -->…<!-- homespun:core:end -->` block from a
+ * SKILL.md body, concatenated in document order (markers removed). Returns the
+ * transport-agnostic conceptual core with no CLI command grammar.
+ */
+export function extractCore(skillMarkdown) {
+    const blocks = [];
+    let cursor = 0;
+    for (;;) {
+        const start = skillMarkdown.indexOf(CORE_START, cursor);
+        if (start === -1)
+            break;
+        const afterStart = start + CORE_START.length;
+        const end = skillMarkdown.indexOf(CORE_END, afterStart);
+        if (end === -1)
+            break;
+        blocks.push(skillMarkdown.slice(afterStart, end).trim());
+        cursor = end + CORE_END.length;
+    }
+    return blocks.join("\n\n");
+}
+/**
+ * Build the full MCP guide: the MCP invocation layer followed by the shared
+ * conceptual core extracted from SKILL.md. `mcpInvocation` is the contents of
+ * skills/homespun/MCP-INVOCATION.md; `skillMarkdown` is the contents of SKILL.md.
+ */
+export function composeMcpGuide(mcpInvocation, skillMarkdown) {
+    const core = extractCore(skillMarkdown);
+    return `${mcpInvocation.trim()}\n\n${core}\n`;
+}

package/dist/index.d.ts

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