@homespunapps/mcp 1.0.0

package/dist/index.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// `homespun-mcp` — a thin stdio Model Context Protocol server wrapping Homespun.
+//
+// Speaks MCP over stdio so any MCP client (Claude Desktop, Cursor, …) can use
+// Homespun: create apps, push updates, and poll for the human's response. All
+// relay I/O goes through @homespunapps/core (no duplicated transport logic), and
+// config is shared with the `homespun` CLI (~/.config/homespun/config.json) — so the
+// CLI and this server use the same agent identity.
+//
+// Config (all optional — sensible defaults; auto-registers an agent on first
+// use if no key is found):
+//   HOMESPUN_URL              relay base URL (default https://homespun.dev)
+//   HOMESPUN_API_KEY          agent API key (or use the shared CLI store)
+//   HOMESPUN_TOKEN            alias for HOMESPUN_API_KEY (for MCP host "*_TOKEN" config)
+//   HOMESPUN_AGENT_NAME       label for the auto-registered agent
+//   HOMESPUN_REGISTER_SECRET  registration secret (REGISTRATION_MODE=secret relays)
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { buildServer } from "./server.js";
+import { VERSION } from "./version.js";
+async function main() {
+    // --version / --help are answered locally without starting the transport, so
+    // a human poking at the binary gets a useful response instead of a hung
+    // stdio session waiting for JSON-RPC.
+    const argv = process.argv.slice(2);
+    if (argv.includes("--version") || argv.includes("-v")) {
+        process.stdout.write(`homespun-mcp ${VERSION}\n`);
+        return;
+    }
+    if (argv.includes("--help") || argv.includes("-h")) {
+        process.stdout.write(HELP);
+        return;
+    }
+    const server = buildServer({
+        agentName: process.env.HOMESPUN_AGENT_NAME,
+        registerSecret: process.env.HOMESPUN_REGISTER_SECRET,
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Stdio MCP servers run until the host closes stdin; keep the process alive.
+    // The transport resolves connect() immediately, so without this the event
+    // loop would otherwise stay open only because of the stdin reader — which is
+    // the intended behaviour. Nothing more to do here.
+}
+const HELP = `homespun-mcp ${VERSION} — Homespun Model Context Protocol server (stdio)
+
+Run by an MCP client over stdio; not meant to be invoked interactively. Add it
+to your MCP client config, e.g. Claude Desktop / Cursor:
+
+  {
+    "mcpServers": {
+      "homespun": {
+        "command": "npx",
+        "args": ["-y", "@homespunapps/mcp"],
+        "env": { "HOMESPUN_API_KEY": "hs_..." }
+      }
+    }
+  }
+
+Environment:
+  HOMESPUN_URL              Relay base URL (default https://homespun.dev)
+  HOMESPUN_API_KEY          Agent API key. If unset, the server auto-registers an
+  HOMESPUN_TOKEN            agent on first use and saves the key to the shared CLI
+                        store (~/.config/homespun/config.json). HOMESPUN_TOKEN is an
+                        alias for HOMESPUN_API_KEY.
+  HOMESPUN_AGENT_NAME       Display name for the auto-registered agent.
+  HOMESPUN_REGISTER_SECRET  Registration secret (REGISTRATION_MODE=secret relays).
+
+Tools exposed: deploy_app, list_rows, get_row, upsert_row, update_row,
+delete_row, get_feed_events, apps, members, attachments, taste, key,
+feedback, agent, get_skill.
+
+See https://github.com/aerolalit/homespun for docs.
+`;
+main().catch((e) => {
+    process.stderr.write(`homespun-mcp: fatal: ${e instanceof Error ? (e.stack ?? e.message) : String(e)}\n`);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,18 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { HomespunClient } from "@homespunapps/core";
+export interface BuildServerOptions {
+    /** Display name for the auto-registered agent (when no key is configured). */
+    agentName?: string;
+    /** Registration secret for REGISTRATION_MODE=secret relays. */
+    registerSecret?: string;
+    /**
+     * Inject a pre-built client (tests). When set, the lazy resolver is skipped
+     * entirely and no network/store access happens.
+     */
+    client?: HomespunClient;
+}
+/**
+ * Construct (but do not connect) the Homespun MCP server. Call `.connect(transport)`
+ * on the returned server to start serving.
+ */
+export declare function buildServer(opts?: BuildServerOptions): McpServer;

package/dist/server.js

@@ -0,0 +1,98 @@
+// Builds the Homespun MCP server: registers every tool from ./tools.ts against an
+// McpServer and wires each handler to a lazily-resolved HomespunClient.
+//
+// The HomespunClient is resolved ONCE, on the first tool call, then cached — so the
+// (potentially network-touching) auto-register-on-first-use path runs lazily,
+// not at process start. This keeps `initialize` / `tools/list` fast and offline
+// (an MCP host can enumerate the tools without the relay being reachable), and
+// only the first actual tool call provisions a key if needed.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { resolveClient, resolveUrl } from "./config.js";
+import { TOOLS } from "./tools.js";
+import { VERSION } from "./version.js";
+import { fetchMcpGuide } from "./skill.js";
+import { registerGuideCapabilities } from "./capabilities.js";
+/**
+ * Construct (but do not connect) the Homespun MCP server. Call `.connect(transport)`
+ * on the returned server to start serving.
+ */
+export function buildServer(opts = {}) {
+    const server = new McpServer({
+        name: "homespun",
+        version: VERSION,
+    });
+    // Lazily resolve + memoise the client. A failed resolution is not cached, so
+    // a transient error (e.g. relay unreachable during auto-register) can be
+    // retried on the next tool call.
+    let clientPromise;
+    const getClient = () => {
+        if (opts.client)
+            return Promise.resolve(opts.client);
+        if (clientPromise === undefined) {
+            clientPromise = resolveClient({
+                agentName: opts.agentName,
+                registerSecret: opts.registerSecret,
+            }).catch((e) => {
+                clientPromise = undefined;
+                throw e;
+            });
+        }
+        return clientPromise;
+    };
+    // MCP consumers get the MCP-flavoured guide (tool-call grammar), not the
+    // CLI-grammar SKILL.md. get_skill fetches /skills/homespun/MCP.md from the
+    // configured relay; everything else keeps its CLI defaults (the stdio server
+    // reads identity from the shared CLI config store).
+    const toolEnv = {
+        getSkill: (versionOnly) => fetchMcpGuide(resolveUrl(), { version: versionOnly }),
+    };
+    // Conceptual guide as an MCP prompt + resource. Fetched from the relay lazily
+    // on read; a relay-unreachable read surfaces a short pointer to get_skill
+    // rather than failing registration.
+    registerGuideCapabilities(server, async () => {
+        try {
+            const { markdown } = await fetchMcpGuide(resolveUrl());
+            return markdown ?? "";
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            return ("# app\n\nThe app guide could not be fetched from the relay " +
+                `(${message}).\n\nCall the \`get_skill\` tool to retrieve it once the ` +
+                "relay is reachable.\n");
+        }
+    });
+    for (const tool of TOOLS) {
+        server.registerTool(tool.name, {
+            // `title` (top-level, display name) + `annotations` (the ToolAnnotations
+            // behavioural hints, which also carry a title) both flow into tools/list
+            // so MCP hosts / Anthropic's connector directory can classify the tool.
+            title: tool.annotations.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            annotations: tool.annotations,
+        }, async (args) => {
+            let client;
+            try {
+                client = await getClient();
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: "config_error",
+                                message,
+                                hint: "Set HOMESPUN_API_KEY (or HOMESPUN_TOKEN), or ensure the relay at HOMESPUN_URL is reachable so the server can auto-register an agent.",
+                            }, null, 2),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            return tool.handler(client, args, toolEnv);
+        });
+    }
+    return server;
+}

package/dist/skill.d.ts

@@ -0,0 +1,24 @@
+/**
+ * GET the relay's full SKILL.md markdown. `version: true` instead fetches just
+ * the relay's reported skill version (the "is my local copy stale?" probe).
+ * Throws on a non-2xx or network failure with a message the tool layer can
+ * surface.
+ */
+export declare function fetchSkill(relayUrl: string, opts?: {
+    version?: boolean;
+}): Promise<{
+    markdown?: string;
+    version?: string;
+}>;
+/**
+ * GET the relay's MCP-flavoured guide (the conceptual core + MCP tool-call
+ * invocation grammar) from GET /skills/homespun/MCP.md, or just its version from
+ * GET /skills/homespun/MCP.md/version. This is what an MCP consumer should read
+ * (not the CLI-grammar SKILL.md). Served unauthenticated, same as the skill.
+ */
+export declare function fetchMcpGuide(relayUrl: string, opts?: {
+    version?: boolean;
+}): Promise<{
+    markdown?: string;
+    version?: string;
+}>;

package/dist/skill.js

@@ -0,0 +1,82 @@
+// Fetch the relay's auto-updating SKILL.md over plain HTTP.
+//
+// Mirrors `homespun skill show|version` (packages/cli/src/commands/skill.ts): the
+// relay serves its skill at GET /skills/homespun/SKILL.md and the version at GET
+// /skills/homespun/SKILL.md/version. Both routes are UNAUTHENTICATED — no API key
+// needed — so an MCP client can self-teach the Homespun workflow before (or without)
+// provisioning a key. We don't go through HomespunClient here precisely because no
+// auth is required and the skill routes are exempt from the version-skew check.
+import { VERSION } from "./version.js";
+/**
+ * GET the relay's full SKILL.md markdown. `version: true` instead fetches just
+ * the relay's reported skill version (the "is my local copy stale?" probe).
+ * Throws on a non-2xx or network failure with a message the tool layer can
+ * surface.
+ */
+export async function fetchSkill(relayUrl, opts = {}) {
+    const base = relayUrl.replace(/\/$/, "");
+    if (opts.version) {
+        const target = base + "/skills/homespun/SKILL.md/version";
+        const res = await fetchOrThrow(target);
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch {
+            body = null;
+        }
+        const version = body !== null &&
+            typeof body === "object" &&
+            typeof body.version === "string"
+            ? body.version
+            : "0.0.0";
+        return { version };
+    }
+    const target = base + "/skills/homespun/SKILL.md";
+    const res = await fetchOrThrow(target);
+    const markdown = await res.text();
+    return { markdown };
+}
+/**
+ * GET the relay's MCP-flavoured guide (the conceptual core + MCP tool-call
+ * invocation grammar) from GET /skills/homespun/MCP.md, or just its version from
+ * GET /skills/homespun/MCP.md/version. This is what an MCP consumer should read
+ * (not the CLI-grammar SKILL.md). Served unauthenticated, same as the skill.
+ */
+export async function fetchMcpGuide(relayUrl, opts = {}) {
+    const base = relayUrl.replace(/\/$/, "");
+    if (opts.version) {
+        const res = await fetchOrThrow(base + "/skills/homespun/MCP.md/version");
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch {
+            body = null;
+        }
+        const version = body !== null &&
+            typeof body === "object" &&
+            typeof body.version === "string"
+            ? body.version
+            : "0.0.0";
+        return { version };
+    }
+    const res = await fetchOrThrow(base + "/skills/homespun/MCP.md");
+    const markdown = await res.text();
+    return { markdown };
+}
+async function fetchOrThrow(url) {
+    let res;
+    try {
+        res = await fetch(url, { headers: { "x-homespun-cli-version": VERSION } });
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new Error(`could not reach ${url}: ${msg}`, { cause: e });
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`relay returned ${res.status} for ${url}${body ? ": " + body.slice(0, 200) : ""}`);
+    }
+    return res;
+}

package/dist/tools.d.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import type { HomespunClient } from "@homespunapps/core";
+/**
+ * A structured MCP tool result (text content + optional error flag). The
+ * index signature keeps it structurally assignable to the SDK's
+ * CallToolResult (which carries an open `[x: string]: unknown`).
+ */
+export interface ToolResult {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Host-supplied capabilities for the handful of tools that aren't pure
+ * HomespunClient wrappers. The stdio server leaves this undefined and the
+ * handlers fall back to the CLI config store + a network skill fetch; the
+ * relay's HTTP MCP server injects an `env` so those tools resolve against the
+ * relay itself (no CLI config on disk, no self-HTTP loop for the skill).
+ *
+ * This is the single seam that keeps the TOOLS array transport-agnostic and
+ * reusable by BOTH servers — every other tool is already a thin HomespunClient
+ * call and needs nothing from the host.
+ */
+export interface ToolEnv {
+    /** `agent` action=whoami — describe the active identity (no secrets). */
+    describeConfig?: () => Record<string, unknown>;
+    /** `agent` action=logout — clear the locally-saved profile. */
+    clearProfile?: () => Record<string, unknown>;
+    /**
+     * `get_skill` — return the MCP-flavoured skill markdown + its version. The
+     * relay passes its in-process renderer; the stdio server fetches it over
+     * HTTP from the relay's /skills route.
+     */
+    getSkill?: (versionOnly: boolean) => Promise<{
+        markdown?: string;
+        version?: string;
+    }>;
+}
+/** One registered tool: name, human/LLM description, Zod input shape, handler. */
+export interface ToolDef {
+    name: string;
+    description: string;
+    inputSchema: z.ZodRawShape;
+    annotations: ToolAnnotations;
+    handler: (client: HomespunClient, args: Record<string, unknown>, env?: ToolEnv) => Promise<ToolResult>;
+}
+export declare const TOOLS: ToolDef[];