@collage-dam/mcp-server 0.1.0

package/docs/typesense-filter-schema.md

@@ -0,0 +1,262 @@
+# Typesense Filter Schema (reverse-engineered)
+
+This document captures the filter, query, sort, and result shapes that
+Collage's Admin-Frontend issues against its Typesense Cloud cluster. The
+MCP `search_assets` and `search_collections` tools mirror this contract
+verbatim. **There is no upstream documentation** — every clause below
+was reverse-engineered from live frontend code. As field names or
+operators drift, the contract test harness in `tests/contract/` is the
+tripwire.
+
+Source files cited inline use repo-relative paths against the cloned
+Admin-Frontend tree at `/Users/justin/Sites/southleft/collage/Admin-Frontend/`.
+
+## Collections
+
+Three Typesense collections are searchable:
+
+| Collection                    | Domain                          |
+| ----------------------------- | ------------------------------- |
+| `digital_assets`              | Asset rows (file metadata)      |
+| `dam_collections`             | Curated asset collections       |
+| `digital_assets_categories`   | Folders (the category tree)     |
+
+Reference: `Admin-Frontend/mixins/search-common-functions.js:355-395`.
+
+## Workspace scoping (mandatory)
+
+Every query is rewritten upstream to append the workspace clause:
+
+```
+filter = filter.length
+  ? `${filter} && workspace_id: ${workspace_unique_id}`
+  : `workspace_id: ${workspace_unique_id}`
+```
+
+Source: `Admin-Frontend/api/typesense.js:212-215` (also lines 420-422
+on the `search-ids` route). On the MCP side this is enforced at the
+`searchWorkspaceScoped` wrapper in `src/typesense.ts` — tool authors
+cannot omit it by construction.
+
+## Common search params
+
+From `Admin-Frontend/api/typesense.js:252-269`:
+
+```js
+{
+  q: adjustedQuery,            // q.toLowerCase() unless '*'
+  filter_by: filter,
+  sort_by: collectionSortBy,
+  infix: 'always',             // substring matching enabled
+  prefix: true,
+  num_typos: 2,
+  typo_tokens_threshold: 1,
+  // optional: include_fields, group_by, group_limit, ...
+}
+```
+
+`commonSearchParams.query_by` defaults to `'search_name'` on the
+results page (`pages/_workspace_id/dam/search.vue:1418`) and the
+search bar (`components/dam/SearchBarTypeSense.vue:898`). The MCP
+contract widens this to `display_file_name,search_name,description,tags,custom_fields`
+to match the spec's stated query target set.
+
+## Sort schema
+
+`sort_by` is a comma-separated list of `field:direction` pairs, where
+direction is `asc` or `desc`. Validation regex (server-side):
+
+```
+/^[a-zA-Z0-9_]+:(asc|desc)$/
+```
+
+Source: `Admin-Frontend/api/typesense.js:160-189`.
+
+Default sort:
+
+```
+_text_match:desc,modified_at:desc
+```
+
+Source: `pages/_workspace_id/dam/search.vue:1442` and
+`components/dam/SearchBarTypeSense.vue:902`.
+
+`sort_by` may also be a per-collection object — keys are collection
+names, values are sort strings. For `dam_collections` and
+`digital_assets_categories`, the upstream remaps `display_file_name:`
+to `collection_name:` / `folder_name:` and falls back to
+`modified_at:` when sorting by `file_size:` or `file_type:` (which
+those collections lack). See `api/typesense.js:223-249`.
+
+## Filter clauses (`filter_by` syntax)
+
+All filter clauses are joined with ` && ` (Typesense AND). Each
+clause is wrapped in parentheses by the frontend builders — they
+nest naturally because parens are part of the frontend's clause
+emission, not a wrapper added later. The server-side `/search`
+endpoint strips a *single* outer pair of balanced parens
+(`api/typesense.js:194-212`) before appending the workspace clause.
+
+### 1. Tag filter
+
+Source: `mixins/search-common-functions.js:194-224`.
+
+| Operator        | Generated clause                                                   |
+| --------------- | ------------------------------------------------------------------ |
+| include-all-of  | `tags:[\tag1\] && tags:[\tag2\]` (per-tag clauses joined by `&&`)  |
+| include-any-of  | `tags:[\tag1\] \|\| tags:[\tag2\]` (joined by `\|\|`)              |
+| exclude-all-of  | `tags:!=[name1] && tags:!=[name2]`                                 |
+| exclude-any-of  | `tags:!=[name1] \|\| tags:!=[name2]`                               |
+| contains        | `tags:*<substring>*`                                               |
+
+The MCP contract exposes a simplified `tags: string[]` filter that
+emits the `include-any-of` shape (`tags:=[name1, name2]` per
+spec.md §Filter schema). Advanced operator selection is deferred to
+Phase 2.
+
+### 2. File-type filter
+
+Source: `mixins/search-common-functions.js:225-239`.
+
+| Operator | Clause                                                  |
+| -------- | ------------------------------------------------------- |
+| is       | `file_type:=image \|\| file_type:=video` (OR-joined)    |
+| is not   | `file_type:!=image && file_type:!=video` (AND-joined)   |
+
+MCP contract: `file_type: string[]` → `file_type:=[image,video]`
+(Typesense array shorthand for OR-joined `:=`).
+
+### 3. Visibility / permission filter
+
+Source: `mixins/search-common-functions.js:85-89`.
+
+```js
+return ` (visibility${isCondition === isPublic ? ':=' : ':!='}0) `
+```
+
+Visibility is **numeric**: `0` = public, `1` = private. Per spec
+§Filter schema this was confirmed against Phase 2.5 testing.
+
+MCP contract: `visibility: 'public' | 'private' | number` →
+`visibility:=0` / `visibility:=1`.
+
+### 4. Date-range filters
+
+Source: `mixins/search-common-functions.js:148-193`. All upstream
+date filtering is **unix-second** based.
+
+| Field key in request     | Typesense field |
+| ------------------------ | --------------- |
+| `date-added`             | `created_at`    |
+| `last-modified-date`     | `modified_at`   |
+
+Operators emitted:
+
+- `after`  → `created_at:>=<unix>`
+- `before` → `created_at:<=<unix>`
+- `between` (custom range) →
+  `created_at:>=<startUnix> && created_at:<=<endUnix>`
+
+Pre-canned slugs: `30-mins-ago`, `1-day-ago`, `3-days-ago`,
+`1-week-ago`, `1-month-ago`, `custom`.
+
+MCP contract: `created_after`, `created_before`, `modified_after`,
+`modified_before` — each accepts unix-seconds (number) or ISO-8601
+string (coerced to unix).
+
+### 5. Collection-scoped filter (`collage` in frontend)
+
+Source: `mixins/search-common-functions.js:240-249`.
+
+```
+collection_ids:=[<slug>] && is_collection:=1
+```
+
+Multiple collections are joined by `||` (is) or `&&` (is-not). Note
+the `is_collection:=1` companion clause — the upstream filters the
+`digital_assets` index for rows that *are* collection-bearing.
+
+MCP contract: `collection_ids: (string|number)[]` →
+`collection_ids:=[id1,id2]` (single clause; the `is_collection:=1`
+side-clause is omitted in the MCP surface — we surface raw
+membership).
+
+### 6. Category / folder-scoped filter
+
+Source: `pages/_workspace_id/dam/folders/_id/index.vue:2920`:
+
+```js
+const folderFilter = `category_id:=[${folderId}]`
+```
+
+MCP contract: `category_id: string|number` → `category_id:=<id>`.
+
+### 7. Uploaded-by filter
+
+Source: `mixins/search-common-functions.js:318-353`. Emits
+`created_by_id:=<id>` (or `:!=`) per user, joined by `||` for "is"
+and `&&` for "is not", with optional `is_external_upload:=true|false`
+companion clause.
+
+Out of scope for the MCP `search_assets` v1 surface — covered by the
+audit/distribution tooling in Phase 2.
+
+### 8. Custom-field filter
+
+Source: `mixins/search-common-functions.js:255-316`. Emits literal
+clauses like `` custom_fields:=`<field_label>:<value>` `` (note the
+backticks — they are part of the Typesense filter syntax). The MCP
+exposes raw passthrough for now (`custom_fields: string[]`),
+defer-validating the inner shape to the consumer.
+
+## Indexed fields (per `digital_assets`)
+
+From spec.md §Indexed fields and live frontend usage:
+
+```
+id, workspace_id, instances_id, display_file_name, search_name,
+description, file_type, type, thumbnail_file, compress_file,
+video_preview, display_file, file_size, height, width,
+orientation, is_external_upload, visibility, category_id,
+is_collection, collection_ids, created_by, created_by_id,
+created_at, modified_at, tags, custom_fields, breadcrumb
+```
+
+## Surprises worth surfacing
+
+1. **`workspace_id` matched against `workspace_unique_id`, not the
+   workspace database id.** The frontend resolves
+   `workspace_unique_id` via the `/user` endpoint
+   (`api/typesense.js:122-132`). For the MCP we treat
+   `COLLAGE_WORKSPACE_ID` env as the raw id used in the filter —
+   if it turns out Collage's Typesense indexes `workspace_unique_id`
+   rather than the workspace db id, we will need to plumb a
+   one-time resolution at startup. T1 (Tarang) is the trigger to
+   confirm this.
+
+2. **`tags:[\tag\]`** uses an *escaped backslash* before the bracket
+   when matching exact tag names. Frontend sources show `\\\\` in
+   template-literal form which renders to a single backslash in the
+   emitted filter. The MCP avoids this escape entirely by using the
+   array form `tags:=[name1,name2]` which Typesense interprets
+   identically for the include-any-of shape used in the contract.
+
+3. **Visibility is numeric** (not the string `"public"`/`"private"`).
+   Frontend treats `0` = public, `1` = private. Documented in
+   spec.md but worth the second mention because it is easy to get
+   wrong.
+
+4. **`infix: 'always'`** is enabled by default at the upstream
+   middleware. This means a query for "cal" matches "calvin",
+   "local", and "optical". Spec callers should set
+   `infix: 'off'` if they want strict prefix matching.
+
+5. **The frontend sometimes blanks the filter for non-asset
+   collections.** When `tags`, `file-type`, `collage`, or
+   `uploaded-by` filters are present, the frontend skips the
+   `dam_collections` and `digital_assets_categories` searches
+   (`mixins/search-common-functions.js:131-141, 396-413`). The
+   MCP `search_collections` tool deliberately does NOT carry that
+   short-circuit — collection search runs independently of asset
+   filters. If a downstream caller needs the frontend's exact
+   behaviour, they compose the two tool calls themselves.

package/docs/verified-endpoints.md

@@ -0,0 +1,38 @@
+# Verified Collage API endpoints (historical)
+
+> **Superseded 2026-05-04.** This file is the original Phase-2.5 stub
+> that captured the first 5 endpoints we verified against BREZ. It has
+> been superseded by [`api-field-verification.md`](./api-field-verification.md),
+> which now covers ~22 endpoints across asset, tag, folder, collection,
+> share-link, embed, and search surfaces with full Admin-Frontend
+> citations and per-endpoint contract-test references.
+>
+> Kept for git history continuity. Don't update — extend
+> `api-field-verification.md` instead.
+
+---
+
+## Original Phase-1 surface (kept for reference)
+
+The endpoints below were the first 5 verified against a live workspace
+(BREZ, `workspace_id=1927483178`). All have since been re-verified by
+contract tests in `tests/contract/`:
+
+1. `check-workspace-access` — auth + scoping smoke. Verified by
+   `check-workspace-access.contract.test.ts`.
+2. `digital-assets/category/all-category-list` — folder roots.
+   Originally 402-blocked; resolved 2026-05-01 (missing `workspace_id`
+   query param). Verified by `list-categories.contract.test.ts`. Now
+   walked recursively via `listAllCategoriesRecursive()` to recover
+   the full tree (the upstream returns roots only by design).
+3. `digital-assets/collection/get-all` — collections list. Verified
+   by `list-collections.contract.test.ts`.
+4. `digital-assets/embed-code-list` — embed-code paginator. Verified
+   by `list-embed-codes.contract.test.ts`.
+5. `digital-assets/view-detail` — single-asset full metadata. Body
+   param is `digital_assets_id` (NOT `asset_id`). Verified by
+   `get-asset-details.contract.test.ts`.
+
+For the full current state of every endpoint the MCP server uses —
+including share-link, write-side, and search-proxy endpoints — see
+[`api-field-verification.md`](./api-field-verification.md).

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@collage-dam/mcp-server",
+  "version": "0.1.0",
+  "description": "Model Context Protocol (MCP) server for the Collage Digital Asset Management platform. Exposes Collage workspaces — assets, folders, collections, share links, audit prompts — to AI clients (Claude Desktop, Cursor, ChatGPT) through a typed tool surface.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "collage-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    ".env.example",
+    "docs"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "postbuild": "chmod +x dist/index.js",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest run --exclude 'tests/contract/**' --exclude 'tests/integration/**'",
+    "test:watch": "vitest",
+    "test:integration": "INTEGRATION=1 vitest run tests/contract tests/integration",
+    "smoke": "tsx scripts/smoke-stdio.ts",
+    "prompt": "tsx scripts/dump-prompt.ts",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run lint && npm test && npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "collage",
+    "dam",
+    "digital-asset-management",
+    "claude",
+    "ai-tools"
+  ],
+  "author": "Southleft <hello@southleft.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/southleft/collage-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/southleft/collage-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/southleft/collage-mcp/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.12.1",
+    "ioredis": "^5.10.1",
+    "pino": "^9.6.0",
+    "ulid": "^2.3.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/ioredis": "^4.28.10",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.1.0"
+  }
+}