sapiens-mcp 1.101.0 → 1.102.0

package/dist/registry.js

@@ -221,7 +221,7 @@ export const TOOLS = {
         handler: decupagem,
     },
     sapiens_reference: {
-        description: "O 'popup global de referência' do Sapiens — espelha o modal 'Selecionar Referência' do gerador web: um lugar só pra navegar os bancos e pegar o que vira referência em imagem/vídeo. READ-ONLY. DUAS sub-actions: 'browse' (navega um banco) e 'resolve' (acha UM asset pelo ID citável). RESOLVE: passe handle=<tipo>_<id> (img_… imagem, vid_… vídeo, film_… vídeo programático, trk_… música, comic_… tirinha, char_… personagem — é o ID que o usuário copia no detalhe do item) e o servidor devolve {mine, isPublic, url, title, mediaKind} SE for seu ou público (senão recusa; nunca acessa asset privado de terceiro). Use a url retornada como referência (referenceImageUrls / startImageUrl / endImageUrl). BROWSE + bucket: 'history' (suas imagens recentes, privadas+públicas), 'favorites' (imagens que você curtiu, só as suas), 'videos' (seus vídeos / Meus Vídeos), 'stock_video' (banco de B-roll da casa, público), 'acervo' (stock + comunidade públicos; aceita term=busca e source=all|stock|community), 'characters' (personagens; mode=mine [default, inclui rascunhos] ou public [Explorar]). Paginado (page/limit, default 20, máx 50; use hasMore). Itens normalizados: imagem PRÓPRIA (history/favorites) traz imageId + url (use imageId em sapiens_image sourceImageIds ou sapiens_video startImageId/endImageId; ou a url em referenceImageUrls); acervo e characters são públicos/de terceiros, use a url (characters trazem mainImageUrl + imageUrls + characterId) em referenceImageUrls / startImageUrl / endImageUrl, NÃO em sourceImageIds. Personagens públicos também têm porta dedicada em sapiens_character action=list_public.",
+        description: "O 'popup global de referência' do Sapiens — espelha o modal 'Selecionar Referência' do gerador web: um lugar só pra navegar os bancos e pegar o que vira referência em imagem/vídeo. READ-ONLY. DUAS sub-actions: 'browse' (navega um banco) e 'resolve' (acha UM asset pelo ID citável). RESOLVE: passe handle=<tipo>_<id> (img_… imagem, vid_… vídeo, film_… vídeo programático, trk_… música, comic_… tirinha, char_… personagem — é o ID que o usuário copia no detalhe do item) e o servidor devolve {mine, isPublic, url, title, mediaKind} SE for seu ou público (senão recusa; nunca acessa asset privado de terceiro). Use a url retornada como referência (referenceImageUrls / startImageUrl / endImageUrl). BROWSE + bucket: 'history' (suas imagens recentes, privadas+públicas), 'favorites' (imagens que você curtiu, só as suas), 'videos' (seus vídeos / Meus Vídeos), 'stock_video' (banco de B-roll da casa, público), 'acervo' (stock + comunidade públicos; aceita term=busca e source=all|stock|community), 'characters' (personagens; mode=mine [default, inclui rascunhos] ou public [Explorar]). BUSCA POR SIGNIFICADO: em history e videos, term + semantic=true acha a peça da pessoa pelo sentido mesmo quando o prompt usou outras palavras (volta até limit, do mais parecido pro menos, com score). Paginado (page/limit, default 20, máx 50; use hasMore). Itens normalizados: imagem PRÓPRIA (history/favorites) traz imageId + url (use imageId em sapiens_image sourceImageIds ou sapiens_video startImageId/endImageId; ou a url em referenceImageUrls); acervo e characters são públicos/de terceiros, use a url (characters trazem mainImageUrl + imageUrls + characterId) em referenceImageUrls / startImageUrl / endImageUrl, NÃO em sourceImageIds. Personagens públicos também têm porta dedicada em sapiens_character action=list_public.",
         schema: referenceSchema,
         handler: reference,
     },

package/dist/tools/reference.js

@@ -22,6 +22,10 @@ import { convexAction, convexQuery, getSessionToken } from "../convexClient.js";
  *   - characters personagens; `mode` = 'mine' (default) ou 'public'
  *   - depth map guias de movimento; `shadowSource` = 'house' (banco curado, default) ou 'mine'
  *
+ * `semantic` lê o `term` como descrição e busca por SIGNIFICADO em history,
+ * videos (creationEmbeddings) e pose_map (poseRefs): a prateleira "Pelo
+ * sentido" do picker web, por outra porta porque vetor não pagina como lista.
+ *
  * Cada item volta normalizado:
  *   - imagem PRÓPRIA (history/favorites): `imageId` + `url` → use imageId em
  *     sourceImageIds / startImageId / endImageId, ou url em referenceImageUrls.
@@ -41,8 +45,8 @@ export const referenceSchema = z.object({
         // proíbe quebrar quem está atrasado. O servidor aceita os dois.
         .enum(["history", "favorites", "videos", "stock_video", "acervo", "characters", "depth_map", "pose_map", "deepshadow"])
         .optional()
-        .describe("Só 'browse': qual banco navegar: 'history' (suas imagens recentes), 'favorites' (as que você curtiu), " +
-        "'videos' (seus vídeos), 'stock_video' (Banco de Vídeo da casa: clipes/B-roll prontos, aceita term/orientation/loopOnly), " +
+        .describe("Só 'browse': qual banco navegar: 'history' (suas imagens recentes; com term+semantic acha pelo significado), " +
+        "'favorites' (as que você curtiu), 'videos' (seus vídeos; idem), 'stock_video' (Banco de Vídeo da casa: clipes/B-roll prontos, aceita term/orientation/loopOnly), " +
         "'acervo' (stock + comunidade públicos de IMAGEM), 'characters' (personagens), " +
         "'depth_map' (guias de movimento: os SEUS com shadowSource='mine', ou o banco curado da casa por default), " +
         "'pose_map' (seu banco privado de POSE: mapa de profundidade de corpo num quadro parado, aceita term/orientation/people/hasObject/objeto/favoritesOnly/collection/sort, mais semantic e similarTo pra busca por sentido)."),
@@ -111,9 +115,11 @@ export const referenceSchema = z.object({
     semantic: z
         .boolean()
         .optional()
-        .describe("Só bucket 'pose_map': lê o `term` como DESCRIÇÃO da cena em vez de palavra-chave. " +
-        "É o caminho pra pedido que nenhuma tag cobre ('alguém se protegendo do vento', " +
-        "'caindo de costas apoiado num braço'). Frase inteira funciona melhor que palavra solta."),
+        .describe("Buckets 'history', 'videos' e 'pose_map': lê o `term` como DESCRIÇÃO em vez de palavra-chave, e acha " +
+        "pelo SIGNIFICADO. Em history/videos acha a peça da pessoa mesmo quando o prompt usou outras palavras " +
+        "('praia ao entardecer' acha 'golden hour beach'); em pose_map, o pedido que nenhuma tag cobre " +
+        "('alguém se protegendo do vento', 'caindo de costas apoiado num braço'). Frase inteira funciona melhor " +
+        "que palavra solta. Sem paginação: volta até `limit` (máx 50), do mais parecido pro menos, com `score`."),
     similarTo: z
         .string()
         .optional()
@@ -180,6 +186,45 @@ export async function reference(args) {
                         "o que os braços fazem) em vez da cena, ou use browse com people/hasObject.",
             };
         }
+        // A mesma porta de sentido pras SUAS imagens e vídeos (creationEmbeddings):
+        // o `term` vira vetor e volta a vizinhança, no shape dos itens do browse.
+        if ((args.bucket === "history" || args.bucket === "videos") && args.semantic && args.term?.trim()) {
+            const video = args.bucket === "videos";
+            const res = await convexAction("creationEmbeddings:mcpSearchByMeaning", {
+                sessionToken,
+                term: args.term,
+                type: video ? "VIDEO" : "IMAGE",
+                limit: args.limit,
+            });
+            const itens = (res?.items ?? []).map((r) => ({
+                refKind: video ? "video" : "image",
+                imageId: r.imageId,
+                url: r.url,
+                thumbnailUrl: r.posterUrl ?? null,
+                title: r.seoTitle ?? null,
+                prompt: r.prompt ?? null,
+                model: r.model ?? null,
+                aspectRatio: r.aspectRatio ?? null,
+                isPublic: !!r.isPublic,
+                createdAt: r.createdAt ?? null,
+                source: args.bucket,
+                score: r.score,
+            }));
+            return {
+                bucket: args.bucket,
+                modo: "sentido",
+                count: itens.length,
+                items: itens,
+                note: itens.length
+                    ? "Peças SUAS por significado, da mais parecida pra menos (`score`). " +
+                        (video
+                            ? "Cada item é um vídeo seu (imageId reusável em sapiens_video)."
+                            : "Use o imageId em sapiens_image sourceImageIds ou sapiens_video startImageId/endImageId, ou a url em referenceImageUrls.")
+                    : `Nada do seu acervo chegou perto de "${args.term}" por significado. Tente descrever o que aparece na ` +
+                        "peça, ou browse com o mesmo `term` sem semantic (pedaço de palavra). Peça muito recente pode ainda " +
+                        "não estar no índice: ela entra alguns segundos depois de pronta.",
+            };
+        }
         const res = await convexAction("mcpReferences:referenceBrowse", {
             sessionToken,
             bucket: args.bucket,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sapiens-mcp",
-  "version": "1.101.0",
+  "version": "1.102.0",
   "mcpName": "com.sapiensinteticos/sapiens",
   "description": "MCP server pra operar o Sapiens Sintéticos (sapiensinteticos.com) pelo Claude Code: gerar imagem, escrever artigo, voz, música e mais, na sua conta. Login pelo código de sapiensinteticos.com/conectar-claude. mcprush.com-bd2545268b8471cdb213c674",
   "type": "module",