@floomhq/floom-mcp-sync 1.0.6 → 1.0.8

package/README.md

@@ -1,42 +1,73 @@
 # Floom MCP Sync
 
-Tiny MCP server for Floom skills. This package is part of the Floom Version 1 synchronization preview.
+Lightweight MCP server for Floom skills. The launch path is CLI-first; MCP gives agents a small search/get/status/sync surface and keeps full skill content out of always-on context.
 
 ```bash
 npx -y @floomhq/floom-mcp-sync
 ```
 
-On startup it reads `~/.floom/config.json`, fetches published, saved, and followed library skills, and writes missing files to the configured local skills directory. Account-backed sync requires `npx -y @floomhq/floom login`. Public and unlisted shared-link installs still work through `floom_install_skill` without an account. The background sync behavior is a Version 1 preview path.
+On startup it reads `~/.floom/config.json`, fetches the signed-in user's sync set from `/api/v1/me/skills`, and writes native skill packages:
 
-Targets:
+```text
+<skills-dir>/
+  <slug>/
+    SKILL.md
+    references/
+    examples/
+    scripts/
+    assets/
+```
+
+`references/`, `examples/`, `scripts/`, and `assets/` are optional and only appear when the synced package includes supporting files. Search results stay compact. Full `SKILL.md` content loads only when an agent calls `floom_get_skill` or when local sync writes the package.
+
+## Setup
+
+Claude Code:
+
+```json
+{
+  "mcpServers": {
+    "floom": {
+      "command": "npx",
+      "args": ["-y", "@floomhq/floom-mcp-sync"],
+      "env": {
+        "FLOOM_SKILLS_DIR": "~/.claude/skills"
+      }
+    }
+  }
+}
+```
+
+Codex:
+
+```toml
+[mcp_servers.floom]
+command = "npx"
+args = ["-y", "@floomhq/floom-mcp-sync"]
+
+[mcp_servers.floom.env]
+FLOOM_SKILLS_DIR = "~/.codex/skills"
+```
+
+Directory resolution order is `FLOOM_SKILLS_DIR`, `CLAUDE_SKILLS_DIR`, `CODEX_SKILLS_DIR`, then `~/.claude/skills`.
+
+## Sync Behavior
 
-- default: Claude Code, `~/.claude/skills/`
-- Codex: `FLOOM_TARGET=codex npx -y @floomhq/floom-mcp-sync`, `~/.codex/skills/`
-- direct override: `FLOOM_SKILLS_DIR=/path/to/skills npx -y @floomhq/floom-mcp-sync`
+Sync stores a machine-local manifest next to the Floom CLI config at `~/.floom/sync-manifest.json`. The manifest records each package file path, slug, SHA-256 hash, and sync time, which lets MCP detect unchanged files, missing files, local edits, and blocked paths.
 
-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.
+Version 1 sync does not replace existing local 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/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.
+The poll uses HTTP `If-None-Match` against `/api/v1/me/skills`, so unchanged responses are `304` with no body. 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 files.
 
 Configure the preview poll interval with `FLOOM_SYNC_INTERVAL_MS` (default `60000`, minimum `10000`).
 
-Tools:
+## 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. Public and unlisted skills do not require an account.
-- `floom_publish_skill(name, content, description?, visibility?, asset_type?, installs_as?, version?)` publishes Markdown through `/api/skills` for the signed-in Floom account.
-  - `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`
+- `floom_search_skills(query, library?, type?, limit?)` searches `/api/v1/search` and returns compact hits: slug, title, description, type, library placement, folder, and install URL.
+- `floom_get_skill(slug)` fetches full skill content from `/api/v1/skills/<slug>` on demand.
+- `floom_status()` reports the local manifest, tracked file counts, and drift counts.
+- `floom_sync()` runs one foreground sync.
 
-- `floom_list_libraries()` lists public Floom libraries.
-- `floom_subscribe_library(slug)` follows a library for the signed-in user so the library syncs locally.
-- `floom_unsubscribe_library(slug)` unfollows that library.
-- `floom_move_skill(slug, folder, tags?)` sets the signed-in user's local folder/tags override.
+`type` is `knowledge`, `instruction`, `workflow`, or `skill`. `limit` is 1-50.
 
-Team workspaces, share invites, and role-based library access are planned for a later Floom version.
+MCP does not expose the full library as context. It does not publish, mutate libraries, manage teams, or handle marketplace workflows.