@floomhq/floom-mcp-sync 1.0.0 → 1.0.2

package/README.md

@@ -6,23 +6,31 @@ Tiny MCP server for Floom skills. This package is part of the Floom Version 1 sy
 npx -y @floomhq/floom-mcp-sync
 ```
 
-On startup it reads `~/.floom/config.json`, fetches your own published Floom skills, and writes missing files to `~/.claude/skills/`. The background sync behavior is a Version 1 preview path.
+On startup it reads `~/.floom/config.json`, fetches published, saved, and subscribed library skills, and writes missing files to `~/.claude/skills/`. The background sync behavior is a Version 1 preview path.
 
 Sync stores a machine-local manifest next to the Floom CLI config at `~/.floom/sync-manifest.json`.
 Version 1 sync does not replace existing local Markdown files. Remote updates, existing untracked
 files, and locally edited tracked files are skipped as conflicts. Symlinks are never followed. Move
 or delete the local file to accept the Floom version on the next sync.
 
-The poll uses HTTP `If-None-Match` against `/api/me/skills`, so unchanged responses are 304 with no body. Steady-state polling is ~free on bandwidth. If a Floom-tracked local file is missing after a 304, MCP refetches once without the ETag so Version 1 can recreate missing files without overwriting existing Markdown.
+The poll uses HTTP `If-None-Match` against `/api/v1/me/skills`, so unchanged responses are 304 with no body. Steady-state polling is ~free on bandwidth. If a Floom-tracked local file is missing after a 304, MCP refetches once without the ETag so Version 1 can recreate missing files without overwriting existing Markdown.
 
 Configure the preview poll interval with `FLOOM_SYNC_INTERVAL_MS` (default `60000`, minimum `10000`).
 
 Tools:
 
+- `floom_search_skills(query, library?, type?, limit?)` searches `/api/v1/search` and returns compact skill hits with slug, title, description, library placement, folder, and install URL.
+  - `type`: `knowledge`, `instruction`, `workflow`, or `skill`
+  - `limit`: 1-50
 - `floom_install_skill(slug)` fetches `/s/<slug>.md` and writes it locally.
 - `floom_publish_skill(name, content, description?, visibility?, asset_type?, installs_as?, version?)` publishes Markdown through `/api/skills`.
   - `asset_type`: `knowledge`, `instruction`, `workflow`, or `skill` (default `skill`)
   - `installs_as`: `claude_skill`, `memory`, `rule`, `codex_instruction`, `opencode_instruction`, `cursor_rule`, or `other` (default `claude_skill`)
   - `version`: optional label like `1.0.0` or `v1-preview`
 
-Library management and share-invite tools are planned for a later Floom version.
+- `floom_list_libraries()` lists public Floom libraries.
+- `floom_subscribe_library(slug)` subscribes the signed-in user so the library syncs locally.
+- `floom_unsubscribe_library(slug)` removes that subscription.
+- `floom_move_skill(slug, folder, tags?)` sets the signed-in user's local folder/tags override.
+
+Team workspaces, share invites, and role-based library access are planned for a later Floom version.

package/dist/auto-sync.js

@@ -104,7 +104,7 @@ export async function autoSync(log = (message) => process.stderr.write(`${messag
     const apiUrl = apiUrlFromConfig(cfg);
     let response;
     try {
-        response = await getJsonWithEtag(`${apiUrl}/api/me/skills`, cfg.accessToken, cachedEtag);
+        response = await getJsonWithEtag(`${apiUrl}/api/v1/me/skills`, cfg.accessToken, cachedEtag);
     }
     catch (err) {
         if (err instanceof FloomApiError && err.status === 401) {
@@ -115,7 +115,7 @@ export async function autoSync(log = (message) => process.stderr.write(`${messag
     }
     if (response.status === 304) {
         if (await manifestHasMissingTrackedFile(manifest, root)) {
-            response = await getJsonWithEtag(`${apiUrl}/api/me/skills`, cfg.accessToken, null);
+            response = await getJsonWithEtag(`${apiUrl}/api/v1/me/skills`, cfg.accessToken, null);
         }
         else {
             maybeHeartbeat(log);

package/dist/server.js

@@ -4,12 +4,16 @@ import { stdin, stdout } from "node:process";
 import { autoSync } from "./auto-sync.js";
 import { installSkill } from "./tools/install.js";
 import { publishSkill } from "./tools/publish.js";
-const SERVER_VERSION = "1.0.0";
+import { listLibraries, moveSkill, subscribeLibrary, unsubscribeLibrary, } from "./tools/libraries.js";
+import { searchSkills } from "./tools/search.js";
+const SERVER_VERSION = "1.0.2";
 const DEFAULT_INTERVAL_MS = 60_000;
 const MIN_INTERVAL_MS = 10_000;
 const VERSION_RE = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$/;
 const VISIBILITIES = new Set(["unlisted", "public", "private"]);
 const ASSET_TYPES = new Set(["knowledge", "instruction", "workflow", "skill"]);
+const SEARCH_TYPES = new Set(["knowledge", "instruction", "workflow", "skill"]);
+const FOLDER_RE = /^[a-z0-9][a-z0-9._-]*(\/[a-z0-9][a-z0-9._-]*)*$/;
 const INSTALL_TARGETS = new Set([
     "claude_skill",
     "memory",
@@ -29,7 +33,7 @@ Usage
 
 Behavior
   Starts a stdio MCP server.
-  Syncs your own published Floom skills into ~/.claude/skills/ on startup.
+  Syncs published, saved, and subscribed library skills into ~/.claude/skills/.
   Polls for updates while the MCP process is running.
 
 Options
@@ -90,6 +94,21 @@ function startPolling(intervalMs, state) {
 function toolList() {
     return {
         tools: [
+            {
+                name: "floom_search_skills",
+                description: "Search public Floom skills through the live API.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        query: { type: "string", minLength: 1, maxLength: 120 },
+                        library: { type: "string", minLength: 1, maxLength: 64 },
+                        type: { type: "string", enum: [...SEARCH_TYPES] },
+                        limit: { type: "integer", minimum: 1, maximum: 50 },
+                    },
+                    required: ["query"],
+                    additionalProperties: false,
+                },
+            },
             {
                 name: "floom_install_skill",
                 description: "Fetch a Floom skill by slug and install it into ~/.claude/skills/.",
@@ -120,6 +139,57 @@ function toolList() {
                     additionalProperties: false,
                 },
             },
+            {
+                name: "floom_list_libraries",
+                description: "List public Floom libraries.",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                    additionalProperties: false,
+                },
+            },
+            {
+                name: "floom_subscribe_library",
+                description: "Subscribe the signed-in user to a Floom library so it syncs locally.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        slug: { type: "string", minLength: 1, maxLength: 64 },
+                    },
+                    required: ["slug"],
+                    additionalProperties: false,
+                },
+            },
+            {
+                name: "floom_unsubscribe_library",
+                description: "Unsubscribe the signed-in user from a Floom library.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        slug: { type: "string", minLength: 1, maxLength: 64 },
+                    },
+                    required: ["slug"],
+                    additionalProperties: false,
+                },
+            },
+            {
+                name: "floom_move_skill",
+                description: "Set a signed-in user's local folder/tags override for a Floom skill.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        slug: { type: "string", minLength: 1, maxLength: 128 },
+                        folder: { type: ["string", "null"], maxLength: 256 },
+                        tags: {
+                            type: "array",
+                            items: { type: "string", minLength: 1, maxLength: 64 },
+                            maxItems: 32,
+                        },
+                    },
+                    required: ["slug", "folder"],
+                    additionalProperties: false,
+                },
+            },
         ],
     };
 }
@@ -148,6 +218,13 @@ function enumValue(value, label, allowed, fallback) {
         throw new Error(`Invalid ${label}.`);
     return value;
 }
+function optionalEnumValue(value, label, allowed) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || !allowed.has(value))
+        throw new Error(`Invalid ${label}.`);
+    return value;
+}
 function nullableEnumValue(value, label, allowed, fallback) {
     if (value === undefined)
         return fallback;
@@ -157,6 +234,29 @@ function nullableEnumValue(value, label, allowed, fallback) {
         throw new Error(`Invalid ${label}.`);
     return value;
 }
+function optionalStringArray(value, label, maxItems, maxLength) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.length > maxItems)
+        throw new Error(`Invalid ${label}.`);
+    return value.map((item) => asString(item, label, 1, maxLength));
+}
+function optionalInteger(value, label, min, max) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < min || value > max) {
+        throw new Error(`Invalid ${label}.`);
+    }
+    return value;
+}
+function nullableFolder(value) {
+    if (value === null)
+        return null;
+    const folder = asString(value, "folder", 1, 256);
+    if (!FOLDER_RE.test(folder))
+        throw new Error("Invalid folder.");
+    return folder;
+}
 async function callTool(params) {
     const parsed = asObject(params);
     const name = asString(parsed.name, "tool name", 1, 200);
@@ -164,12 +264,37 @@ async function callTool(params) {
     if (name === "floom_install_skill") {
         return ok(await installSkill(asString(args.slug, "slug", 1, 128)));
     }
+    if (name === "floom_search_skills") {
+        const opts = {};
+        const library = optionalString(args.library, "library", 64);
+        const type = optionalEnumValue(args.type, "type", SEARCH_TYPES);
+        const limit = optionalInteger(args.limit, "limit", 1, 50);
+        if (library !== undefined)
+            opts.library = library;
+        if (type !== undefined)
+            opts.type = type;
+        if (limit !== undefined)
+            opts.limit = limit;
+        return ok(await searchSkills(asString(args.query, "query", 1, 120), opts));
+    }
     if (name === "floom_publish_skill") {
         const version = optionalString(args.version, "version", 64);
         if (version !== undefined && !VERSION_RE.test(version))
             throw new Error("Invalid version.");
         return ok(await publishSkill(asString(args.name, "name", 1, 200), asString(args.content, "content", 1, 500_000), optionalString(args.description, "description", 1000), enumValue(args.visibility, "visibility", VISIBILITIES, "unlisted"), enumValue(args.asset_type, "asset_type", ASSET_TYPES, "skill"), nullableEnumValue(args.installs_as, "installs_as", INSTALL_TARGETS, "claude_skill"), version));
     }
+    if (name === "floom_list_libraries") {
+        return ok(await listLibraries());
+    }
+    if (name === "floom_subscribe_library") {
+        return ok(await subscribeLibrary(asString(args.slug, "slug", 1, 64)));
+    }
+    if (name === "floom_unsubscribe_library") {
+        return ok(await unsubscribeLibrary(asString(args.slug, "slug", 1, 64)));
+    }
+    if (name === "floom_move_skill") {
+        return ok(await moveSkill(asString(args.slug, "slug", 1, 128), nullableFolder(args.folder), optionalStringArray(args.tags, "tags", 32, 64)));
+    }
     throw new Error(`Unknown tool: ${name}`);
 }
 function response(id, result) {

package/dist/tools/search.js

@@ -0,0 +1,66 @@
+import { apiUrlFromConfig, readConfig, DEFAULT_API_URL } from "../lib/config.js";
+import { getJson } from "../lib/api.js";
+export async function searchSkills(query, opts = {}) {
+    const cfg = await readConfig();
+    const apiUrl = cfg ? apiUrlFromConfig(cfg) : (process.env.FLOOM_API_URL ?? DEFAULT_API_URL).replace(/\/$/, "");
+    const params = new URLSearchParams({ q: query });
+    if (opts.library)
+        params.set("library", opts.library);
+    if (opts.type)
+        params.set("type", opts.type);
+    if (opts.limit !== undefined)
+        params.set("limit", String(opts.limit));
+    const payload = await getJson(`${apiUrl}/api/v1/search?${params.toString()}`, cfg?.accessToken);
+    return normalizeSearchResponse(payload, opts.limit ?? 20);
+}
+function normalizeSearchResponse(payload, fallbackLimit) {
+    const rawSkills = Array.isArray(payload.skills) ? payload.skills : [];
+    const rawLibraries = Array.isArray(payload.libraries) ? payload.libraries : [];
+    return {
+        query: typeof payload.query === "string" ? payload.query : "",
+        total: typeof payload.total === "number" ? payload.total : rawSkills.length + rawLibraries.length,
+        limit: typeof payload.limit === "number" ? payload.limit : fallbackLimit,
+        skills: rawSkills.flatMap((skill) => {
+            if (typeof skill.slug !== "string" || skill.slug.length === 0)
+                return [];
+            const libraries = normalizePlacements(skill.libraries);
+            const primary = libraries[0] ?? null;
+            return [{
+                    slug: skill.slug,
+                    title: typeof skill.title === "string" ? skill.title : null,
+                    description: typeof skill.description === "string" ? skill.description : null,
+                    type: isSkillType(skill.asset_type) ? skill.asset_type : "skill",
+                    library: primary?.slug ?? null,
+                    folder: primary?.folder ?? null,
+                    install_url: typeof skill.url === "string" ? skill.url : null,
+                    libraries,
+                }];
+        }),
+        libraries: rawLibraries.flatMap((library) => {
+            if (typeof library.slug !== "string" || library.slug.length === 0)
+                return [];
+            return [{
+                    slug: library.slug,
+                    name: typeof library.name === "string" ? library.name : null,
+                    description: typeof library.description === "string" ? library.description : null,
+                    skill_count: typeof library.skill_count === "number" ? library.skill_count : 0,
+                }];
+        }),
+    };
+}
+function normalizePlacements(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.flatMap((placement) => {
+        if (typeof placement.slug !== "string" || placement.slug.length === 0)
+            return [];
+        return [{
+                slug: placement.slug,
+                name: typeof placement.name === "string" ? placement.name : null,
+                folder: typeof placement.folder === "string" ? placement.folder : null,
+            }];
+    });
+}
+function isSkillType(value) {
+    return value === "knowledge" || value === "instruction" || value === "workflow" || value === "skill";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floomhq/floom-mcp-sync",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Lightweight Floom MCP server for installing, publishing, and startup-syncing skills.",
   "license": "MIT",
   "type": "module",