afpnews-mcp-server 2.1.0 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "afpnews-mcp-server",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "",
   "main": "src/index.ts",
   "type": "module",

package/src/__tests__/format-media.test.ts

@@ -4,11 +4,13 @@ import { extractRenditions, formatMediaDocument, formatMediaDocumentsAsJson, for
 // Fixture bagItem reprenant la structure réelle AFP
 const FIXTURE_BAG_ITEM = [{
   medias: [
-    { role: 'Thumbnail',  sizeInBytes: 33590,   width: 320,  height: 213,  href: 'https://example.com/thumb.jpg',   type: 'Photo' },
-    { role: 'Preview',    sizeInBytes: 340621,  width: 1200, height: 800,  href: 'https://example.com/prev.jpg',    type: 'Photo' },
-    { role: 'Preview_B',  sizeInBytes: 596996,  width: 1800, height: 1200, href: 'https://example.com/prev_b.jpg',  type: 'Photo' },
-    { role: 'HighDef',    sizeInBytes: 5126566, width: 3429, height: 2286, href: 'https://example.com/hd.jpg',      type: 'Photo' },
-    { role: 'Quicklook',  sizeInBytes: 14055,   width: 245,  height: 164,  href: 'https://example.com/quick.jpg',  type: 'Photo' },
+    { role: 'Thumbnail',   sizeInBytes: 33590,   width: 320,  height: 213,  href: 'https://example.com/thumb.jpg',   type: 'Photo' },
+    { role: 'Preview',     sizeInBytes: 340621,  width: 1200, height: 800,  href: 'https://example.com/prev.jpg',    type: 'Photo' },
+    { role: 'Preview_B',   sizeInBytes: 596996,  width: 1800, height: 1200, href: 'https://example.com/prev_b.jpg',  type: 'Photo' },
+    { role: 'HighDef',     sizeInBytes: 5126566, width: 3429, height: 2286, href: 'https://example.com/hd.jpg',      type: 'Photo' },
+    { role: 'Quicklook',   sizeInBytes: 14055,   width: 245,  height: 164,  href: 'https://example.com/quick.jpg',   type: 'Photo' },
+    { role: 'Mockup',      sizeInBytes: 19989,   width: 512,  height: 342,  href: 'https://example.com/mockup.jpg',  type: 'Photo' },
+    { role: 'Squared120',  sizeInBytes: 3696,    width: 120,  height: 120,  href: 'https://example.com/sq120.jpg',   type: 'Photo' },
   ],
 }];
 
@@ -21,11 +23,14 @@ const FIXTURE_BAG_NO_PREVIEW = [{
 }];
 
 describe('MEDIA_RENDITION_ROLE_MAP', () => {
+  it('maps Quicklook → quicklook', () => expect(MEDIA_RENDITION_ROLE_MAP['Quicklook']).toBe('quicklook'));
   it('maps Thumbnail → thumbnail', () => expect(MEDIA_RENDITION_ROLE_MAP['Thumbnail']).toBe('thumbnail'));
   it('maps Preview → preview', () => expect(MEDIA_RENDITION_ROLE_MAP['Preview']).toBe('preview'));
   it('maps Preview_B → preview', () => expect(MEDIA_RENDITION_ROLE_MAP['Preview_B']).toBe('preview'));
   it('maps Preview_W → preview', () => expect(MEDIA_RENDITION_ROLE_MAP['Preview_W']).toBe('preview'));
   it('maps HighDef → highdef', () => expect(MEDIA_RENDITION_ROLE_MAP['HighDef']).toBe('highdef'));
+  it('maps Mockup → mockup', () => expect(MEDIA_RENDITION_ROLE_MAP['Mockup']).toBe('mockup'));
+  it('maps Squared120 → squared120', () => expect(MEDIA_RENDITION_ROLE_MAP['Squared120']).toBe('squared120'));
 });
 
 describe('extractRenditions', () => {
@@ -37,11 +42,17 @@ describe('extractRenditions', () => {
     expect(extractRenditions([{}])).toEqual({});
   });
 
-  it('extracts thumbnail, preview, highdef from standard bagItem', () => {
+  it('extracts squared120, quicklook, thumbnail, mockup, preview, highdef from standard bagItem', () => {
     const r = extractRenditions(FIXTURE_BAG_ITEM);
+    expect(r.squared120?.href).toBe('https://example.com/sq120.jpg');
+    expect(r.squared120?.width).toBe(120);
+    expect(r.quicklook?.href).toBe('https://example.com/quick.jpg');
+    expect(r.quicklook?.width).toBe(245);
     expect(r.thumbnail?.href).toBe('https://example.com/thumb.jpg');
     expect(r.thumbnail?.width).toBe(320);
     expect(r.thumbnail?.sizeInBytes).toBe(33590);
+    expect(r.mockup?.href).toBe('https://example.com/mockup.jpg');
+    expect(r.mockup?.width).toBe(512);
     expect(r.preview?.href).toBe('https://example.com/prev.jpg');
     expect(r.preview?.width).toBe(1200);
     expect(r.highdef?.href).toBe('https://example.com/hd.jpg');
@@ -58,9 +69,15 @@ describe('extractRenditions', () => {
     expect(r.preview?.width).toBe(1800);
   });
 
-  it('ignores unknown roles (Quicklook)', () => {
-    const r = extractRenditions(FIXTURE_BAG_ITEM);
-    expect(Object.keys(r)).not.toContain('quicklook');
+  it('ignores genuinely unknown roles', () => {
+    const bagWithUnknownRole = [{
+      medias: [
+        ...FIXTURE_BAG_ITEM[0].medias,
+        { role: 'SomeFutureRole', href: 'https://example.com/future.jpg', width: 999, height: 999, type: 'Photo' },
+      ],
+    }];
+    const r = extractRenditions(bagWithUnknownRole);
+    expect(Object.keys(r)).not.toContain('somefuturerole');
   });
 
   it('uses first bagItem only (index 0)', () => {

package/src/__tests__/get-media.test.ts

@@ -25,11 +25,26 @@ describe('inferMimeType', () => {
 
 describe('selectRenditionForEmbed', () => {
   const renditions: MediaRenditions = {
+    quicklook: { href: 'https://example.com/quick.jpg', width: 245, height: 164, sizeInBytes: 14055 },
     thumbnail: { href: 'https://example.com/thumb.jpg', width: 320, height: 213, sizeInBytes: 33590 },
     preview:   { href: 'https://example.com/prev.jpg',  width: 1200, height: 800, sizeInBytes: 340621 },
     highdef:   { href: 'https://example.com/hd.jpg',    width: 3429, height: 2286, sizeInBytes: 5126566 },
   };
 
+  it('returns quicklook when explicitly requested and available', () => {
+    const r = selectRenditionForEmbed(renditions, 'quicklook');
+    expect(r?.href).toBe('https://example.com/quick.jpg');
+  });
+
+  it('downgrades to quicklook when thumbnail is absent and requested rendition exceeds 5MB', () => {
+    const noThumbnail: MediaRenditions = {
+      quicklook: { href: 'https://example.com/quick.jpg', width: 245, height: 164, sizeInBytes: 14055 },
+      highdef:   { href: 'https://example.com/hd.jpg',    width: 3429, height: 2286, sizeInBytes: 5126566 },
+    };
+    const r = selectRenditionForEmbed(noThumbnail, 'highdef');
+    expect(r?.href).toBe('https://example.com/quick.jpg');
+  });
+
   it('returns requested rendition when available and under size limit', () => {
     const r = selectRenditionForEmbed(renditions, 'preview');
     expect(r?.href).toBe('https://example.com/prev.jpg');
@@ -62,4 +77,22 @@ describe('selectRenditionForEmbed', () => {
     const r = selectRenditionForEmbed({}, 'preview');
     expect(r).toBeUndefined();
   });
+
+  it('returns mockup when explicitly requested and available', () => {
+    const withMockup: MediaRenditions = {
+      ...renditions,
+      mockup: { href: 'https://example.com/mockup.jpg', width: 512, height: 342, sizeInBytes: 19989 },
+    };
+    const r = selectRenditionForEmbed(withMockup, 'mockup');
+    expect(r?.href).toBe('https://example.com/mockup.jpg');
+  });
+
+  it('downgrades to squared120 as last resort when nothing lighter is available', () => {
+    const squaredOnly: MediaRenditions = {
+      squared120: { href: 'https://example.com/sq120.jpg', width: 120, height: 120, sizeInBytes: 3696 },
+      highdef:    { href: 'https://example.com/hd.jpg',    width: 3429, height: 2286, sizeInBytes: 5126566 },
+    };
+    const r = selectRenditionForEmbed(squaredOnly, 'highdef');
+    expect(r?.href).toBe('https://example.com/sq120.jpg');
+  });
 });

package/src/__tests__/search-media-handler.test.ts

@@ -0,0 +1,125 @@
+import { beforeEach, describe, expect, it, mock } from 'bun:test';
+import { afpSearchMediaTool, EMBED_MAX_DOCS } from '../tools/search-media.js';
+
+const ORIGINAL_FETCH = globalThis.fetch;
+
+function makeMediaDoc(uno: string, extraMedias: Record<string, unknown>[] = []) {
+  return {
+    uno,
+    title: `Photo ${uno}`,
+    caption: ['A caption'],
+    class: 'picture',
+    bagItem: [{
+      medias: [
+        { role: 'Quicklook', href: `https://example.com/${uno}-quick.jpg`, width: 245, height: 164, type: 'Photo' },
+        { role: 'Thumbnail', href: `https://example.com/${uno}-thumb.jpg`, width: 320, height: 213, type: 'Photo' },
+        ...extraMedias,
+      ],
+    }],
+  };
+}
+
+describe('afpSearchMediaTool.handler — embed', () => {
+  beforeEach(() => {
+    globalThis.fetch = ORIGINAL_FETCH;
+  });
+
+  it('rejects embed with a non-markdown format', async () => {
+    const apicore = { search: mock() };
+
+    const result = await afpSearchMediaTool.handler(apicore, { query: 'test', embed: true, format: 'json' });
+
+    expect('isError' in result && result.isError).toBe(true);
+    expect(apicore.search).not.toHaveBeenCalled();
+  });
+
+  it('caps the effective search size to EMBED_MAX_DOCS when embed is true', async () => {
+    const apicore = {
+      search: mock().mockResolvedValue({ documents: [], count: 0 }),
+    };
+
+    await afpSearchMediaTool.handler(apicore, { query: 'test', size: 50, embed: true });
+
+    const [request] = apicore.search.mock.calls[0]!;
+    expect(request.size).toBe(EMBED_MAX_DOCS);
+  });
+
+  it('does not cap size when embed is false', async () => {
+    const apicore = {
+      search: mock().mockResolvedValue({ documents: [], count: 0 }),
+    };
+
+    await afpSearchMediaTool.handler(apicore, { query: 'test', size: 50 });
+
+    const [request] = apicore.search.mock.calls[0]!;
+    expect(request.size).toBe(50);
+  });
+
+  it('embeds an image block per result, interleaved with its markdown text', async () => {
+    globalThis.fetch = mock().mockResolvedValue({
+      ok: true,
+      arrayBuffer: async () => new Uint8Array([1, 2, 3]).buffer,
+      headers: new Headers({ 'content-type': 'image/jpeg' }),
+    } as Response);
+
+    const apicore = {
+      search: mock().mockResolvedValue({
+        documents: [makeMediaDoc('MEDIA-1'), makeMediaDoc('MEDIA-2')],
+        count: 2,
+      }),
+    };
+
+    const result = await afpSearchMediaTool.handler(apicore, { query: 'test', embed: true });
+
+    // pagination + (text + image) per doc
+    expect(result.content).toHaveLength(1 + 2 * 2);
+    expect(result.content[1]).toEqual(expect.objectContaining({ type: 'text' }));
+    expect((result.content[1] as { text: string }).text).toContain('MEDIA-1');
+    expect(result.content[2]).toEqual(expect.objectContaining({ type: 'image', mimeType: 'image/jpeg' }));
+    expect((result.content[3] as { text: string }).text).toContain('MEDIA-2');
+    expect(result.content[4]).toEqual(expect.objectContaining({ type: 'image' }));
+  });
+
+  it('embeds the thumbnail (poster frame) for video results, not quicklook', async () => {
+    globalThis.fetch = mock().mockResolvedValue({
+      ok: true,
+      arrayBuffer: async () => new Uint8Array([1, 2, 3]).buffer,
+      headers: new Headers({ 'content-type': 'image/jpeg' }),
+    } as Response);
+
+    const videoDoc = {
+      uno: 'VIDEO-1',
+      title: 'A video',
+      class: 'video',
+      bagItem: [{
+        medias: [
+          { role: 'Quicklook', href: 'https://example.com/video-quick.jpg', width: 245, height: 164, type: 'Photo' },
+          { role: 'Thumbnail', href: 'https://example.com/video-thumb.jpg', width: 320, height: 213, type: 'Photo' },
+        ],
+      }],
+    };
+    const apicore = { search: mock().mockResolvedValue({ documents: [videoDoc], count: 1 }) };
+
+    await afpSearchMediaTool.handler(apicore, { query: 'test', class: 'video', embed: true });
+
+    const fetchMock = globalThis.fetch as unknown as ReturnType<typeof mock>;
+    expect(fetchMock.mock.calls[0]![0]).toBe('https://example.com/video-thumb.jpg');
+  });
+
+  it('skips embedding SVG graphics but still returns their metadata text', async () => {
+    const svgDoc = {
+      uno: 'GRAPHIC-1',
+      title: 'A graphic',
+      class: 'graphic',
+      bagItem: [{
+        medias: [{ role: 'Preview', href: 'https://example.com/graphic.svg', width: 1200, height: 800, type: 'Graphic' }],
+      }],
+    };
+    const apicore = { search: mock().mockResolvedValue({ documents: [svgDoc], count: 1 }) };
+
+    const result = await afpSearchMediaTool.handler(apicore, { query: 'test', class: 'graphic', embed: true });
+
+    expect(result.content.some((c: any) => c.type === 'image')).toBe(false);
+    expect(result.content.some((c: any) => c.type === 'text' && c.text.includes('GRAPHIC-1'))).toBe(true);
+  });
+});

package/src/__tests__/server.test.ts

@@ -355,6 +355,40 @@ describe('MCP integration', () => {
       expect(params).toMatchObject({ langs: ['fr'], class: ['text'], provider: ['afp'], dateFrom: 'now-1d' });
     });
 
+    it('forwards query and date window to the API', async () => {
+      await client.callTool({
+        name: 'afp_list_facets',
+        arguments: { facet: 'slug', query: 'elections', dateFrom: 'now-2d', dateTo: 'now-1d', lang: 'fr' },
+      });
+      const [facet, params] = apicore.list.mock.calls.at(-1)!;
+      expect(facet).toBe('slug');
+      expect(params).toMatchObject({
+        query: 'elections',
+        dateFrom: 'now-2d',
+        dateTo: 'now-1d',
+        langs: ['fr'],
+      });
+    });
+
+    it('forwards additional facet filters', async () => {
+      await client.callTool({
+        name: 'afp_list_facets',
+        arguments: { facet: 'genre', facets: { country: ['usa'] } },
+      });
+      const [, params] = apicore.list.mock.calls.at(-1)!;
+      expect(params).toMatchObject({ country: ['usa'] });
+    });
+
+    it('lets explicit dates override the trending preset window', async () => {
+      await client.callTool({
+        name: 'afp_list_facets',
+        arguments: { preset: 'trending-topics', dateFrom: 'now-7d', dateTo: 'now' },
+      });
+      const [facet, params] = apicore.list.mock.calls.at(-1)!;
+      expect(facet).toBe('slug');
+      expect(params).toMatchObject({ dateFrom: 'now-7d', dateTo: 'now' });
+    });
+
     it('returns isError on API failure', async () => {
       apicore.list.mockRejectedValueOnce(new Error('Service unavailable'));
       const result = await client.callTool({ name: 'afp_list_facets', arguments: { facet: 'slug' } });

package/src/tools/get-media.ts

@@ -2,47 +2,17 @@ import { z } from 'zod';
 import type { ApiCore } from 'afpnews-api';
 import { textContent, toolError } from '../utils/format.js';
 import { extractRenditions } from '../utils/format-media.js';
-import type { MediaRendition, MediaRenditions, ImageContent } from '../utils/types.js';
+import type { MediaRendition, MediaRenditions } from '../utils/types.js';
+import { inferMimeType, selectRenditionForEmbed, isSvgRendition, embedRendition } from '../utils/embed-media.js';
 import { renditionEnum, formatErrorMessage } from './shared.js';
 
-// Exported for testing
-export function inferMimeType(afpType: string | undefined, href: string): string {
-  if (afpType === 'Photo') return 'image/jpeg';
-  if (afpType === 'Graphic') return 'image/png';
-  const ext = href.split('?')[0].split('.').pop()?.toLowerCase();
-  if (ext === 'jpg' || ext === 'jpeg') return 'image/jpeg';
-  if (ext === 'png') return 'image/png';
-  if (ext === 'webp') return 'image/webp';
-  if (ext === 'gif') return 'image/gif';
-  if (ext === 'svg') return 'image/svg+xml';
-  return 'image/jpeg';
-}
-
-// Exported for testing
-export function selectRenditionForEmbed(
-  renditions: MediaRenditions,
-  requested: 'thumbnail' | 'preview' | 'highdef',
-): MediaRendition | undefined {
-  const SIZE_LIMIT = 5_000_000;
-
-  const get = (key: keyof MediaRenditions): MediaRendition | undefined => renditions[key];
-
-  // Try requested rendition, then fallback chain
-  const candidate = get(requested) ?? get('preview') ?? get('thumbnail');
-  if (!candidate) return undefined;
-
-  // Downgrade if over size limit (only once)
-  if ((candidate.sizeInBytes ?? 0) > SIZE_LIMIT) {
-    return get('thumbnail') ?? candidate; // proceed with candidate if no thumbnail
-  }
-
-  return candidate;
-}
+// Re-exported for testing (moved to utils/embed-media.ts for reuse by search-media.ts)
+export { inferMimeType, selectRenditionForEmbed };
 
 const inputSchema = z.object({
   uno: z.string().describe('AFP document UNO identifier (e.g. newsml.afp.com.20260316T202634Z.doc-a3jc2qq)'),
   embed: z.boolean().optional().describe('When true, fetches the image and returns it as base64 for Claude vision analysis. Default: false.'),
-  rendition: renditionEnum.optional().describe("Rendition size to embed: 'thumbnail' (320px), 'preview' (1200px, default), 'highdef' (~3400px)"),
+  rendition: renditionEnum.optional().describe("Rendition size to embed: 'squared120' (~120px, lightest, square crop), 'quicklook' (~245px, lightest full-frame), 'thumbnail' (320px), 'mockup' (~512px), 'preview' (1200px, default), 'highdef' (~3400px)"),
 });
 
 type GetMediaInput = z.infer<typeof inputSchema>;
@@ -65,10 +35,13 @@ function formatFullMediaText(doc: Record<string, unknown>, renditions: MediaRend
   if (doc.advisory) lines.push(`\n> ${doc.advisory}`);
 
   lines.push('\n**Renditions:**');
-  const { thumbnail, preview, highdef } = renditions;
-  if (thumbnail) lines.push(`- thumbnail: ${thumbnail.href} (${thumbnail.width}×${thumbnail.height})`);
-  if (preview)   lines.push(`- preview: ${preview.href} (${preview.width}×${preview.height})`);
-  if (highdef)   lines.push(`- highdef: ${highdef.href} (${highdef.width}×${highdef.height})`);
+  const { squared120, quicklook, thumbnail, mockup, preview, highdef } = renditions;
+  if (squared120) lines.push(`- squared120: ${squared120.href} (${squared120.width}×${squared120.height})`);
+  if (quicklook)  lines.push(`- quicklook: ${quicklook.href} (${quicklook.width}×${quicklook.height})`);
+  if (thumbnail)  lines.push(`- thumbnail: ${thumbnail.href} (${thumbnail.width}×${thumbnail.height})`);
+  if (mockup)     lines.push(`- mockup: ${mockup.href} (${mockup.width}×${mockup.height})`);
+  if (preview)    lines.push(`- preview: ${preview.href} (${preview.width}×${preview.height})`);
+  if (highdef)    lines.push(`- highdef: ${highdef.href} (${highdef.width}×${highdef.height})`);
 
   if (note) lines.push(`\n*${note}*`);
 
@@ -85,8 +58,8 @@ Media classes: picture (photo), video, graphic (infographic/SVG), videography (v
 Args:
   - uno: AFP document UNO (e.g. newsml.afp.com.20260316T202634Z.doc-a3jc2qq)
   - embed: When true, fetches the image and returns it as a base64 MCP image block that Claude can see and analyse visually. Default: false.
-  - rendition: Size to embed — 'thumbnail' (320px), 'preview' (1200px, default), 'highdef' (~3400px).
-               Files > 5 MB are automatically downgraded to thumbnail.
+  - rendition: Size to embed — 'squared120' (~120px, square crop, lightest), 'quicklook' (~245px, lightest full-frame), 'thumbnail' (320px), 'mockup' (~512px), 'preview' (1200px, default), 'highdef' (~3400px).
+               Files > 5 MB are automatically downgraded to a lighter rendition.
                Videos and videography always use thumbnail (poster frame). SVG graphics cannot be embedded.
 
 Returns:
@@ -112,9 +85,8 @@ Returns:
       }
 
       // Guard: SVG graphics (URL ends with .svg OR AFP type field is 'Graphic')
-      const isSvg = (r: MediaRendition) => r.href.split('?')[0].endsWith('.svg') || r.afpType === 'Graphic';
       const allRenditions = Object.values(renditions).filter(Boolean) as MediaRendition[];
-      if (doc.class === 'graphic' && allRenditions.some(isSvg)) {
+      if (doc.class === 'graphic' && allRenditions.some(isSvgRendition)) {
         return {
           content: [
             metadataText,
@@ -124,7 +96,7 @@ Returns:
       }
 
       // Guard: video → use thumbnail as poster frame
-      let renditionKey: 'thumbnail' | 'preview' | 'highdef' = requestedRendition;
+      let renditionKey: keyof MediaRenditions = requestedRendition;
       let note: string | undefined;
       if (doc.class === 'video') {
         renditionKey = 'thumbnail';
@@ -141,46 +113,21 @@ Returns:
         };
       }
 
-      let imageData: string;
-      let mimeType: string;
-
-      try {
-        const response = await fetch(chosen.href);
-        if (!response.ok) {
-          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-        }
-        const bytes = new Uint8Array(await response.arrayBuffer());
-        const chunks: string[] = [];
-        for (let i = 0; i < bytes.length; i += 8192) {
-          chunks.push(String.fromCharCode(...bytes.subarray(i, i + 8192)));
-        }
-        imageData = btoa(chunks.join(''));
-        // MIME priority: AFP type field → URL extension → HTTP Content-Type → fallback
-        mimeType = inferMimeType(chosen.afpType, chosen.href);
-        // Override with Content-Type from response if more specific
-        const ct = response.headers.get('content-type');
-        if (ct && ct.startsWith('image/')) mimeType = ct.split(';')[0].trim();
-      } catch (fetchErr) {
-        const msg = fetchErr instanceof Error ? fetchErr.message : 'Unknown fetch error';
+      const embedded = await embedRendition(chosen);
+      if (!embedded.ok) {
         return {
           content: [
             metadataText,
-            textContent(`Warning: image embed failed: ${msg}`),
+            textContent(`Warning: image embed failed: ${embedded.error}`),
           ],
         };
       }
 
-      const imageContent: ImageContent = {
-        type: 'image',
-        data: imageData,
-        mimeType,
-      };
-
       const metaWithNote = note
         ? textContent(formatFullMediaText(doc, renditions, note))
         : metadataText;
 
-      return { content: [metaWithNote, imageContent] };
+      return { content: [metaWithNote, embedded.image] };
     } catch (error) {
       return toolError(formatErrorMessage('retrieving AFP media document', error, 'Check the UNO identifier and try again.'));
     }

package/src/tools/list-facets.ts

@@ -3,6 +3,7 @@ import type { ApiCore, SearchQueryParams } from 'afpnews-api';
 import { escapeCsvValue, textContent, toolError, truncateToLimit, truncationHint } from '../utils/format.js';
 import {
   type FacetResult,
+  facetParamValueSchema,
   formatErrorMessage,
   langEnum,
   listPresetEnum,
@@ -13,8 +14,12 @@ const inputSchema = z.object({
   preset: listPresetEnum.optional().describe('Optional preset for list queries. Available preset: trending-topics.'),
   facet: z.string().optional().describe("Facet to list (e.g. 'slug', 'genre', 'country'). Required when no preset is used."),
   lang: langEnum.optional().describe("Language filter (e.g. 'en', 'fr')"),
+  query: z.string().optional().describe("Keywords to scope the facet counts (e.g. 'climate change'). When set, counts reflect only articles matching the query."),
+  dateFrom: z.string().optional().describe("Start of the time window (e.g. 'now-1d', '2026-01-01'). Combine with dateTo for a bounded window (e.g. to compare two periods)."),
+  dateTo: z.string().optional().describe("End of the time window (e.g. 'now', 'now-1d', '2026-01-31')."),
   size: z.number().optional().describe('Number of facet values to return'),
   format: outputFormatEnum.optional().describe('Output format: markdown (default), json, or csv.'),
+  facets: z.record(z.string(), facetParamValueSchema).optional().describe("Additional facet filters passed to the AFP query (e.g. { country: ['usa'], genre: 'Papier général', urgency: 1 })."),
 });
 
 type ListFacetsInput = z.infer<typeof inputSchema>;
@@ -22,14 +27,17 @@ type ListFacetsInput = z.infer<typeof inputSchema>;
 export const afpListFacetsTool = {
   name: 'afp_list_facets',
   title: 'List AFP Facet Values',
-  description: `List facet values and their article counts. Use this to discover available topics, genres, or countries, or to get trending topics.
+  description: `List facet values and their article counts. Use this to discover available topics, genres, or countries, get trending topics, or compare activity across time windows.
 
 Args:
   - preset: Optional preset (trending-topics) — overrides facet to 'slug' with last 24h news
   - facet: Facet to list (e.g. 'slug', 'genre', 'country'). Required when no preset is used.
   - lang: Language filter (e.g. 'en', 'fr')
+  - query: Keywords to scope the counts (e.g. 'climate change')
+  - dateFrom / dateTo: Time window for the counts (e.g. dateFrom 'now-1d'; dateFrom '2026-01-01', dateTo '2026-01-31')
   - size: Number of facet values to return
   - format: Output format — markdown (default), json, or csv.
+  - facets: Additional filters (country, genre, urgency, …)
 
 Returns:
   - markdown: Formatted list with labels and article counts
@@ -39,10 +47,12 @@ Returns:
 Examples:
   - Trending topics in French: { preset: "trending-topics" }
   - Trending topics in English: { preset: "trending-topics", lang: "en" }
-  - List available genres as CSV: { facet: "genre", format: "csv" }
+  - Top slugs over the last 24h: { facet: "slug", dateFrom: "now-1d", format: "json" }
+  - Top slugs over the previous 24h: { facet: "slug", dateFrom: "now-2d", dateTo: "now-1d", format: "json" }
+  - Genres about a topic: { facet: "genre", query: "elections", format: "csv" }
   - List countries as JSON: { facet: "country", size: 30, format: "json" }`,
   inputSchema,
-  handler: async (apicore: Pick<ApiCore, 'list'>, { preset, facet, lang, size, format = 'markdown' }: ListFacetsInput) => {
+  handler: async (apicore: Pick<ApiCore, 'list'>, { preset, facet, lang, query, dateFrom, dateTo, size, format = 'markdown', facets }: ListFacetsInput) => {
     try {
       const isTrendingTopics = preset === 'trending-topics';
       const resolvedFacet = isTrendingTopics ? 'slug' : facet;
@@ -52,9 +62,20 @@ Examples:
       }
 
       const resolvedSize = size ?? 10;
-      const params: SearchQueryParams = isTrendingTopics
-        ? { langs: [lang ?? 'fr'], class: ['text'], provider: ['afp'], dateFrom: 'now-1d', size: resolvedSize }
-        : { class: ['text'], provider: ['afp'], ...(lang ? { langs: [lang] } : {}), size: resolvedSize };
+      // Le preset trending impose slug + fenêtre 24h, mais dateFrom/dateTo/query
+      // explicites restent prioritaires pour affiner ou comparer des périodes.
+      const resolvedLang = lang ?? (isTrendingTopics ? 'fr' : undefined);
+      const resolvedDateFrom = dateFrom ?? (isTrendingTopics ? 'now-1d' : undefined);
+      const params: SearchQueryParams = {
+        class: ['text'],
+        provider: ['afp'],
+        size: resolvedSize,
+        ...(resolvedLang ? { langs: [resolvedLang] } : {}),
+        ...(query ? { query } : {}),
+        ...(resolvedDateFrom ? { dateFrom: resolvedDateFrom } : {}),
+        ...(dateTo ? { dateTo } : {}),
+        ...(facets ?? {}),
+      };
 
       const { keywords } = await apicore.list(resolvedFacet, params, 1);
       const results: FacetResult[] = keywords.map(k => ({ name: k.name ?? '', count: k.count }));

package/src/tools/search-media.ts

@@ -3,9 +3,12 @@ import type { ApiCore, SearchQueryParams } from 'afpnews-api';
 import { textContent, toolError, buildPaginationLine } from '../utils/format.js';
 import {
   formatMediaOutput,
+  formatMediaDocument,
   normalizeMediaDocument,
 } from '../utils/format-media.js';
 import { DEFAULT_SEARCH_SIZE } from '../utils/types.js';
+import type { AFPMediaDocument, AnyContent, MediaRendition } from '../utils/types.js';
+import { selectRenditionForEmbed, isSvgRendition, embedRendition } from '../utils/embed-media.js';
 import {
   mediaClassEnum,
   outputFormatEnum,
@@ -13,6 +16,33 @@ import {
   facetParamValueSchema,
 } from './shared.js';
 
+// Fetching + base64-encoding images is costly: cap how many results get embedded per call,
+// regardless of the requested `size` (see handler: `size` itself is clamped when embed is true).
+export const EMBED_MAX_DOCS = 5;
+
+async function embedMediaDocuments(docs: AFPMediaDocument[]): Promise<AnyContent[]> {
+  const content: AnyContent[] = [];
+
+  for (const doc of docs) {
+    content.push(formatMediaDocument(doc));
+
+    const allRenditions = Object.values(doc.renditions).filter(Boolean) as MediaRendition[];
+    if (doc.class === 'graphic' && allRenditions.some(isSvgRendition)) {
+      content.push(textContent('_Warning: SVG graphics cannot be embedded for vision._'));
+      continue;
+    }
+
+    const renditionKey = doc.class === 'video' || doc.class === 'videography' ? 'thumbnail' : 'quicklook';
+    const chosen = selectRenditionForEmbed(doc.renditions, renditionKey);
+    if (!chosen) continue;
+
+    const embedded = await embedRendition(chosen);
+    if (embedded.ok) content.push(embedded.image);
+  }
+
+  return content;
+}
+
 const reservedMediaFacetKeys = new Set(['class', 'format', 'query', 'size', 'sortOrder', 'offset', 'facets']);
 
 const MEDIA_API_FIELDS = [
@@ -31,6 +61,9 @@ const inputSchema = z.object({
   facets: z.record(z.string(), facetParamValueSchema).optional().describe(
     "Additional AFP facet filters (e.g. { langs: ['fr'], country: ['fra'], dateFrom: '2026-01-01' })"
   ),
+  embed: z.boolean().optional().describe(
+    `When true, fetches and embeds the lightest available image (quicklook, thumbnail poster frame for video) for each result as base64, for Claude vision analysis. Requires format: "markdown" (default). Size is capped to ${EMBED_MAX_DOCS} regardless of the requested value, since fetching/encoding images is costly. Default: false.`
+  ),
 }).strict().superRefine((value, ctx) => {
   for (const key of Object.keys(value.facets ?? {})) {
     if (reservedMediaFacetKeys.has(key)) {
@@ -67,6 +100,9 @@ Args:
   - format: markdown (default, with inline thumbnails), json (structured with rendition URLs), csv
   - facets: Additional AFP filters (e.g. { langs: ['fr'], country: ['fra'], dateFrom: '2026-01-01' }).
            Defaults: provider=afp. Override provider only when partner media is explicitly needed.
+  - embed: When true, fetches and embeds the lightest image for each result as base64 (Claude vision analysis) —
+           useful to visually compare or verify a handful of candidate photos before picking one.
+           Requires format: "markdown". Size is capped to ${EMBED_MAX_DOCS} regardless of the requested value.
 
 Pagination:
   Use \`offset\` to paginate (e.g. offset=10 to skip the first 10).
@@ -75,9 +111,10 @@ Pagination:
 Returns (json):
   { total, shown, offset, truncated, remaining, documents: [{ uno, title, caption, creditLine, creator,
     country, city, published, urgency, class, aspectRatios, advisory,
-    renditions: { thumbnail, preview, highdef } }] }
+    renditions: { quicklook, thumbnail, preview, highdef } }] }
 
 Rendition sizes:
+  - quicklook: ~245px wide (lightest, when available)
   - thumbnail: ~320px wide (gallery grid)
   - preview: ~1200px wide (display)
   - highdef: ~3400px wide (download / analysis)
@@ -90,13 +127,18 @@ Examples:
   inputSchema,
   handler: async (
     apicore: Pick<ApiCore, 'search'>,
-    { class: mediaClass, query, size = DEFAULT_SEARCH_SIZE, offset, sortOrder = 'desc', format = 'markdown', facets }: SearchMediaInput,
+    { class: mediaClass, query, size = DEFAULT_SEARCH_SIZE, offset, sortOrder = 'desc', format = 'markdown', facets, embed = false }: SearchMediaInput,
   ) => {
     try {
+      if (embed && format !== 'markdown') {
+        return toolError(`embed is only supported with format: "markdown" (got "${format}").`);
+      }
+
+      const effectiveSize = embed ? Math.min(size, EMBED_MAX_DOCS) : size;
       const classFilter = mediaClass ? [mediaClass] : ['picture', 'video', 'graphic', 'videography'];
       const request: SearchQueryParams = {
         query,
-        size,
+        size: effectiveSize,
         sortOrder,
         startAt: offset,
         class: classFilter,
@@ -112,6 +154,18 @@ Examples:
 
       const docs = rawDocs.map(normalizeMediaDocument);
       const currentOffset = offset ?? 0;
+
+      if (embed) {
+        const pagination = textContent(buildPaginationLine(docs.length, count, currentOffset));
+        const embeddedContent = await embedMediaDocuments(docs);
+        return {
+          content: [pagination, ...embeddedContent],
+          shown: docs.length,
+          truncated: false,
+          remaining: count - docs.length,
+        };
+      }
+
       return formatMediaOutput(docs, format, {
         jsonMeta: { total: count, offset: currentOffset },
         markdownPrefix: (shown) => [textContent(buildPaginationLine(shown, count, currentOffset))],

package/src/tools/shared.ts

@@ -28,7 +28,7 @@ const MEDIA_CLASS_VALUES = ['picture', 'video', 'graphic', 'videography'] as con
 export const mediaClassEnum = z.enum(MEDIA_CLASS_VALUES);
 export type MediaClass = z.infer<typeof mediaClassEnum>;
 
-const RENDITION_VALUES = ['thumbnail', 'preview', 'highdef'] as const;
+const RENDITION_VALUES = ['squared120', 'quicklook', 'thumbnail', 'mockup', 'preview', 'highdef'] as const;
 export const renditionEnum = z.enum(RENDITION_VALUES);
 export type RenditionKey = z.infer<typeof renditionEnum>;
 

package/src/utils/embed-media.ts

@@ -0,0 +1,65 @@
+import type { MediaRendition, MediaRenditions, ImageContent } from './types.js';
+
+// Exported for testing
+export function inferMimeType(afpType: string | undefined, href: string): string {
+  if (afpType === 'Photo') return 'image/jpeg';
+  if (afpType === 'Graphic') return 'image/png';
+  const ext = href.split('?')[0].split('.').pop()?.toLowerCase();
+  if (ext === 'jpg' || ext === 'jpeg') return 'image/jpeg';
+  if (ext === 'png') return 'image/png';
+  if (ext === 'webp') return 'image/webp';
+  if (ext === 'gif') return 'image/gif';
+  if (ext === 'svg') return 'image/svg+xml';
+  return 'image/jpeg';
+}
+
+// Exported for testing
+export function selectRenditionForEmbed(
+  renditions: MediaRenditions,
+  requested: keyof MediaRenditions,
+): MediaRendition | undefined {
+  const SIZE_LIMIT = 5_000_000;
+
+  const get = (key: keyof MediaRenditions): MediaRendition | undefined => renditions[key];
+
+  // Try requested rendition, then fallback chain (largest usable → lightest)
+  const candidate = get(requested) ?? get('preview') ?? get('thumbnail') ?? get('quicklook') ?? get('squared120');
+  if (!candidate) return undefined;
+
+  // Downgrade if over size limit (only once)
+  if ((candidate.sizeInBytes ?? 0) > SIZE_LIMIT) {
+    return get('thumbnail') ?? get('quicklook') ?? get('squared120') ?? candidate; // proceed with candidate if no lighter rendition
+  }
+
+  return candidate;
+}
+
+// SVG graphics (URL ends with .svg OR AFP type field is 'Graphic') cannot be embedded for vision.
+export function isSvgRendition(r: MediaRendition): boolean {
+  return r.href.split('?')[0].endsWith('.svg') || r.afpType === 'Graphic';
+}
+
+export async function embedRendition(
+  rendition: MediaRendition,
+): Promise<{ ok: true; image: ImageContent } | { ok: false; error: string }> {
+  try {
+    const response = await fetch(rendition.href);
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    const chunks: string[] = [];
+    for (let i = 0; i < bytes.length; i += 8192) {
+      chunks.push(String.fromCharCode(...bytes.subarray(i, i + 8192)));
+    }
+    const data = btoa(chunks.join(''));
+    // MIME priority: AFP type field → URL extension → HTTP Content-Type → fallback
+    let mimeType = inferMimeType(rendition.afpType, rendition.href);
+    const ct = response.headers.get('content-type');
+    if (ct && ct.startsWith('image/')) mimeType = ct.split(';')[0].trim();
+    return { ok: true, image: { type: 'image', data, mimeType } };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : 'Unknown fetch error';
+    return { ok: false, error: message };
+  }
+}

package/src/utils/format-media.ts

@@ -4,11 +4,14 @@ import { textContent, truncateToLimit, truncateContentItems, truncationHint } fr
 // Mapping role AFP → clé normalisée (utilise m.role, pas m.rendition)
 // Preview est prioritaire sur Preview_B/Preview_W (premier match gagne)
 export const MEDIA_RENDITION_ROLE_MAP: Record<string, keyof MediaRenditions> = {
-  'Thumbnail': 'thumbnail',
-  'Preview':   'preview',
-  'Preview_B': 'preview',
-  'Preview_W': 'preview',
-  'HighDef':   'highdef',
+  'Squared120': 'squared120',
+  'Quicklook':  'quicklook',
+  'Thumbnail':  'thumbnail',
+  'Mockup':     'mockup',
+  'Preview':    'preview',
+  'Preview_B':  'preview',
+  'Preview_W':  'preview',
+  'HighDef':    'highdef',
 };
 
 export function extractRenditions(bagItem: unknown): MediaRenditions {

package/src/utils/types.ts

@@ -32,7 +32,10 @@ export interface MediaRendition {
 }
 
 export interface MediaRenditions {
+  squared120?: MediaRendition;
+  quicklook?: MediaRendition;
   thumbnail?: MediaRendition;
+  mockup?: MediaRendition;
   preview?: MediaRendition;
   highdef?: MediaRendition;
 }