afpnews-mcp-server 1.2.0 → 1.3.1

package/README.md

@@ -1,6 +1,8 @@
 # afpnews-mcp
 
-MCP (Model Context Protocol) server that exposes [AFP](https://www.afp.com/) news content as tools for AI assistants. Works with any MCP-compatible client: Claude Code, Claude Desktop, Continue, Cursor, etc.
+MCP (Model Context Protocol) server that exposes [AFP](https://www.afp.com/) news content as tools for AI assistants. Works with any MCP-compatible client.
+
+The package can also be used as a library without MCP server glue via `afpnews-mcp-server/definitions`.
 
 ## Prerequisites
 
@@ -11,8 +13,8 @@ MCP (Model Context Protocol) server that exposes [AFP](https://www.afp.com/) new
 ## Setup
 
 ```bash
-git clone https://github.com/julesbonnard/afpnews-mcp.git
-cd afpnews-mcp
+git clone https://github.com/julesbonnard/afpnews-mcp-server.git
+cd afpnews-mcp-server
 pnpm install
 pnpm run build
 ```
@@ -25,39 +27,19 @@ APICORE_USERNAME=your-username
 APICORE_PASSWORD=your-password
 ```
 
-Or for stdio only, provide a serialized auth token instead:
-
-```
-APICORE_AUTH_TOKEN={"accessToken":"...","refreshToken":"...","tokenExpires":1735689600000,"authType":"credentials"}
-```
-
 ## Usage
 
 ### Stdio transport (default)
 
 For local MCP clients like Claude Code or Claude Desktop:
 
-```bash
-pnpm run start
-```
-
-Direct CLI call (same stdio behavior):
-
-```bash
-APICORE_AUTH_TOKEN='{"accessToken":"...","refreshToken":"...","tokenExpires":1735689600000,"authType":"credentials"}' node build/index.js
-```
-
-#### Claude Code
-
-Add to your Claude Code MCP settings:
-
 ```json
 {
   "mcpServers": {
     "afpnews": {
       "command": "node",
       "args": ["build/index.js"],
-      "cwd": "/path/to/afpnews-mcp",
+      "cwd": "/absolute/path/to/afpnews-mcp-server",
       "env": {
         "APICORE_API_KEY": "your-api-key",
         "APICORE_USERNAME": "your-username",
@@ -76,6 +58,10 @@ For remote or multi-user deployments. Each session authenticates independently v
 MCP_TRANSPORT=http PORT=3000 pnpm run start
 ```
 
+Notes:
+- Keep `APICORE_API_KEY` set in the server environment (`.env` or runtime env).
+- If you expose the server remotely, use HTTPS.
+
 ### Docker
 
 ```bash
@@ -84,18 +70,43 @@ docker build -t afpnews-mcp .
 docker run -e APICORE_API_KEY=your-api-key -p 3000:3000 afpnews-mcp
 ```
 
+### As a library (without MCP server dependency)
+
+You can import pure definitions (tools, prompts, resources) and wire them into your own runtime:
+
+```ts
+import { AFP_DEFINITIONS } from 'afpnews-mcp-server/definitions';
+
+const { tools, prompts, resources } = AFP_DEFINITIONS;
+```
+
+Or import each collection directly:
+
+```ts
+import {
+  TOOL_DEFINITIONS,
+  PROMPT_DEFINITIONS,
+  RESOURCE_DEFINITIONS,
+} from 'afpnews-mcp-server/definitions';
+```
+
+Each definition is framework-agnostic:
+- `tools`: `name`, `title`, `description`, `inputSchema`, `handler(apicore, args)`
+- `prompts`: `name`, `title`, `description`, `argsSchema`, `handler(args)`
+- `resources`: `name`, `uri`, `description`, `mimeType`, `handler()`
+
 ## Tools
 
 | Tool | Description |
 |------|-------------|
-| `search` | Search AFP articles with filters, presets, and full-text mode |
-| `get` | Get a full article by its UNO identifier |
-| `mlt` | Find similar articles (More Like This) from a UNO |
-| `list` | List facet values (topics, genres, countries) with frequency counts |
+| `afp_search_articles` | Search AFP articles with filters, presets, and full-text mode |
+| `afp_get_article` | Get a full article by its UNO identifier |
+| `afp_find_similar` | Find similar articles (More Like This) from a UNO |
+| `afp_list_facets` | List facet values (topics, genres, countries) with frequency counts |
 
 ### Search presets
 
-The `search` tool supports presets that apply predefined filters:
+The `afp_search_articles` tool supports presets that apply predefined filters:
 
 - **`a-la-une`** — Top story (French, last 24h)
 - **`agenda`** — Upcoming events
@@ -108,7 +119,7 @@ The `search` tool supports presets that apply predefined filters:
 
 ### Full text
 
-By default, `search` returns excerpts (first 4 paragraphs). Set `fullText: true` to get the complete article body. Presets default to full text.
+By default, `afp_search_articles` returns excerpts (first 4 paragraphs). Set `fullText: true` to get the complete article body. Presets default to full text.
 
 ## Prompts
 
@@ -133,6 +144,16 @@ pnpm run build
 pnpm test
 ```
 
+## Internal Architecture
+
+- `src/tools/*.ts`, `src/prompts/*.ts`, `src/resources/*.ts` contain pure definitions.
+- `src/tools/index.ts`, `src/prompts/index.ts`, `src/resources/index.ts` contain MCP registration glue.
+- `src/definitions.ts` exports aggregated, server-agnostic definitions:
+  - `AFP_DEFINITIONS`
+  - `TOOL_DEFINITIONS`
+  - `PROMPT_DEFINITIONS`
+  - `RESOURCE_DEFINITIONS`
+
 ## License
 
 ISC

package/build/definitions.js

@@ -0,0 +1,9 @@
+import { TOOL_DEFINITIONS } from './tools/index.js';
+import { PROMPT_DEFINITIONS } from './prompts/index.js';
+import { RESOURCE_DEFINITIONS } from './resources/index.js';
+export const AFP_DEFINITIONS = {
+    tools: TOOL_DEFINITIONS,
+    prompts: PROMPT_DEFINITIONS,
+    resources: RESOURCE_DEFINITIONS,
+};
+export { TOOL_DEFINITIONS, PROMPT_DEFINITIONS, RESOURCE_DEFINITIONS };

package/build/index.js

@@ -15,38 +15,14 @@ function decodeBasicAuth(header) {
         password: decoded.substring(colon + 1)
     };
 }
-function parseAuthToken(tokenValue) {
-    let parsed;
-    try {
-        parsed = JSON.parse(tokenValue);
-    }
-    catch {
-        throw new Error('APICORE_AUTH_TOKEN must be a valid JSON object');
-    }
-    if (!parsed || typeof parsed !== 'object') {
-        throw new Error('APICORE_AUTH_TOKEN must be a JSON object');
-    }
-    const token = parsed;
-    if (typeof token.accessToken !== 'string' ||
-        typeof token.refreshToken !== 'string' ||
-        typeof token.tokenExpires !== 'number' ||
-        (token.authType !== 'anonymous' && token.authType !== 'credentials')) {
-        throw new Error('APICORE_AUTH_TOKEN must include accessToken, refreshToken, tokenExpires and authType');
-    }
-    return token;
-}
 export function resolveStdioAuthConfig(env = process.env) {
-    const rawToken = env.APICORE_AUTH_TOKEN?.trim();
-    if (rawToken) {
-        return { mode: 'token', token: parseAuthToken(rawToken) };
-    }
     const apiKey = env.APICORE_API_KEY?.trim();
     const username = env.APICORE_USERNAME?.trim();
     const password = env.APICORE_PASSWORD?.trim();
     if (!apiKey || !username || !password) {
-        throw new Error('Missing stdio auth configuration: set APICORE_AUTH_TOKEN or APICORE_API_KEY + APICORE_USERNAME + APICORE_PASSWORD.');
+        throw new Error('Missing stdio auth configuration: set APICORE_API_KEY + APICORE_USERNAME + APICORE_PASSWORD.');
     }
-    return { mode: 'credentials', apiKey, username, password };
+    return { apiKey, username, password };
 }
 async function startHttpServer() {
     const { default: express } = await import('express');
@@ -104,9 +80,7 @@ async function startHttpServer() {
 }
 async function startStdioServer() {
     const authConfig = resolveStdioAuthConfig();
-    const server = authConfig.mode === 'token'
-        ? await createServer(authConfig.token)
-        : await createServer(authConfig.apiKey, authConfig.username, authConfig.password);
+    const server = await createServer(authConfig.apiKey, authConfig.username, authConfig.password);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error('MCP stdio server started');

package/build/prompts/comprehensive-analysis.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+export const comprehensiveAnalysisPrompt = {
+    name: 'comprehensive-analysis',
+    title: 'Comprehensive analysis',
+    description: 'Perform an in-depth analysis on a specific topic',
+    argsSchema: {
+        query: z.string().describe("The topic or query to analyze (e.g. 'climate change', 'French elections')"),
+    },
+    handler: async ({ query }) => {
+        return {
+            messages: [{
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: `Perform an in-depth analysis on "${query}":
+1. Use afp_search_articles to find recent articles about "${query}" (size: 10).
+2. Use afp_find_similar on the most relevant article to find related coverage.
+3. Use afp_get_article to retrieve the full text of the most important articles.
+4. Synthesize the information from these articles to write a comprehensive analysis covering: key facts, timeline, different angles, and outlook.`,
+                    },
+                }],
+        };
+    },
+};

package/build/prompts/country-news.js

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+export const countryNewsPrompt = {
+    name: 'country-news',
+    title: 'Country News',
+    description: 'News summary for a specific country',
+    argsSchema: {
+        country: z.string().describe("Country code (e.g. 'fra', 'usa', 'gbr')"),
+        lang: z.string().optional().describe("Language (e.g. 'en', 'fr'). Default: 'fr'"),
+    },
+    handler: async ({ country, lang = 'fr' }) => {
+        return {
+            messages: [{
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: `Use afp_search_articles to find recent news for country "${country}" (lang: ["${lang}"], country: ["${country}"], size: 15). Write a news summary for this country covering the main stories of the day.`,
+                    },
+                }],
+        };
+    },
+};

package/build/prompts/daily-briefing.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+export const dailyBriefingPrompt = {
+    name: 'daily-briefing',
+    title: 'Daily Briefing',
+    description: 'Generate a news briefing for today',
+    argsSchema: {
+        lang: z.string().optional().describe("Language (e.g. 'en', 'fr'). Default: 'fr'"),
+    },
+    handler: async ({ lang }) => {
+        const l = lang || 'fr';
+        const today = new Date().toISOString().split('T')[0];
+        return {
+            messages: [{
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: `Use the afp_search_articles tool to find today's most important news (dateFrom: "${today}", lang: ["${l}"], size: 15, sortOrder: "desc"). Then write a concise daily briefing summarizing the key stories, grouped by theme.`,
+                    },
+                }],
+        };
+    },
+};

package/build/prompts/factcheck.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+export const factcheckPrompt = {
+    name: 'factcheck',
+    title: 'Fact Check',
+    description: 'Verify facts about a specific topic',
+    argsSchema: {
+        query: z.string().describe("The topic or query to verify (e.g. 'climate change', 'French elections')"),
+    },
+    handler: async ({ query }) => {
+        return {
+            messages: [{
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: `Factcheck the following query: "${query}":
+1. Use afp_search_articles to find recent factchecks related to "${query}" (genreid:"afpattribute:FactcheckInvestigation") (size: 10).
+2. For each relevant factcheck, use afp_get_article to retrieve the full text.
+3. Summarize the findings, including: what is being claimed, what the factcheck verdict is, and the evidence provided.`,
+                    },
+                }],
+        };
+    },
+};

package/build/prompts/index.js

@@ -1,81 +1,19 @@
-import { z } from 'zod';
+import { dailyBriefingPrompt } from './daily-briefing.js';
+import { comprehensiveAnalysisPrompt } from './comprehensive-analysis.js';
+import { factcheckPrompt } from './factcheck.js';
+import { countryNewsPrompt } from './country-news.js';
+export const PROMPT_DEFINITIONS = [
+    dailyBriefingPrompt,
+    comprehensiveAnalysisPrompt,
+    factcheckPrompt,
+    countryNewsPrompt,
+];
 export function registerPrompts({ server }) {
-    server.registerPrompt("daily-briefing", {
-        title: "Daily Briefing",
-        description: "Generate a news briefing for today",
-        argsSchema: {
-            lang: z.string().optional().describe("Language (e.g. 'en', 'fr'). Default: 'fr'")
-        }
-    }, async ({ lang }) => {
-        const l = lang || 'fr';
-        const today = new Date().toISOString().split('T')[0];
-        return {
-            messages: [{
-                    role: 'user',
-                    content: {
-                        type: 'text',
-                        text: `Use the afp_search_articles tool to find today's most important news (dateFrom: "${today}", lang: ["${l}"], size: 15, sortOrder: "desc"). Then write a concise daily briefing summarizing the key stories, grouped by theme.`
-                    }
-                }]
-        };
-    });
-    server.registerPrompt("comprehensive-analysis", {
-        title: "Comprehensive analysis",
-        description: "Perform an in-depth analysis on a specific topic",
-        argsSchema: {
-            query: z.string().describe("The topic or query to analyze (e.g. 'climate change', 'French elections')")
-        }
-    }, async ({ query }) => {
-        return {
-            messages: [{
-                    role: 'user',
-                    content: {
-                        type: 'text',
-                        text: `Perform an in-depth analysis on "${query}":
-1. Use afp_search_articles to find recent articles about "${query}" (size: 10).
-2. Use afp_find_similar on the most relevant article to find related coverage.
-3. Use afp_get_article to retrieve the full text of the most important articles.
-4. Synthesize the information from these articles to write a comprehensive analysis covering: key facts, timeline, different angles, and outlook.`
-                    }
-                }]
-        };
-    });
-    server.registerPrompt("factcheck", {
-        title: "Fact Check",
-        description: "Verify facts about a specific topic",
-        argsSchema: {
-            query: z.string().describe("The topic or query to verify (e.g. 'climate change', 'French elections')")
-        }
-    }, async ({ query }) => {
-        return {
-            messages: [{
-                    role: 'user',
-                    content: {
-                        type: 'text',
-                        text: `Factcheck the following query: "${query}":
-1. Use afp_search_articles to find recent factchecks related to "${query}" (genreid:"afpattribute:FactcheckInvestigation") (size: 10).
-2. For each relevant factcheck, use afp_get_article to retrieve the full text.
-3. Summarize the findings, including: what is being claimed, what the factcheck verdict is, and the evidence provided.`
-                    }
-                }]
-        };
-    });
-    server.registerPrompt("country-news", {
-        title: "Country News",
-        description: "News summary for a specific country",
-        argsSchema: {
-            country: z.string().describe("Country code (e.g. 'fra', 'usa', 'gbr')"),
-            lang: z.string().optional().describe("Language (e.g. 'en', 'fr'). Default: 'fr'")
-        }
-    }, async ({ country, lang = 'fr' }) => {
-        return {
-            messages: [{
-                    role: 'user',
-                    content: {
-                        type: 'text',
-                        text: `Use afp_search_articles to find recent news for country "${country}" (lang: ["${lang}"], country: ["${country}"], size: 15). Write a news summary for this country covering the main stories of the day.`
-                    }
-                }]
-        };
-    });
+    for (const prompt of PROMPT_DEFINITIONS) {
+        server.registerPrompt(prompt.name, {
+            title: prompt.title,
+            description: prompt.description,
+            argsSchema: prompt.argsSchema,
+        }, prompt.handler);
+    }
 }

package/build/resources/index.js

@@ -1,14 +1,10 @@
-import { TOPICS } from '../utils/topics.js';
+import { topicsResource } from './topics.js';
+export const RESOURCE_DEFINITIONS = [topicsResource];
 export function registerResources({ server }) {
-    server.registerResource("topics", "afp://topics", {
-        description: "AFP Stories topic catalog — available sections by language (fr, en, de, pt, es, ar) with their identifiers",
-        mimeType: "application/json"
-    }, async () => {
-        return {
-            contents: [{
-                    uri: "afp://topics",
-                    text: JSON.stringify(TOPICS, null, 2)
-                }]
-        };
-    });
+    for (const resource of RESOURCE_DEFINITIONS) {
+        server.registerResource(resource.name, resource.uri, {
+            description: resource.description,
+            mimeType: resource.mimeType,
+        }, resource.handler);
+    }
 }

package/build/resources/topics.js

@@ -0,0 +1,15 @@
+import { TOPICS } from '../utils/topics.js';
+export const topicsResource = {
+    name: 'topics',
+    uri: 'afp://topics',
+    description: 'AFP Stories topic catalog — available sections by language (fr, en, de, pt, es, ar) with their identifiers',
+    mimeType: 'application/json',
+    handler: async () => {
+        return {
+            contents: [{
+                    uri: 'afp://topics',
+                    text: JSON.stringify(TOPICS, null, 2),
+                }],
+        };
+    },
+};

package/build/server.js

@@ -3,29 +3,12 @@ import { ApiCore } from "afpnews-api";
 import { registerTools } from "./tools/index.js";
 import { registerResources } from "./resources/index.js";
 import { registerPrompts } from "./prompts/index.js";
-function isAuthToken(value) {
-    if (!value || typeof value !== "object") {
-        return false;
-    }
-    const token = value;
-    return (typeof token.accessToken === "string" &&
-        typeof token.refreshToken === "string" &&
-        typeof token.tokenExpires === "number" &&
-        (token.authType === "anonymous" || token.authType === "credentials"));
-}
-export async function createServer(apiKeyOrToken, username, password) {
-    let apicore;
-    if (isAuthToken(apiKeyOrToken)) {
-        apicore = new ApiCore();
-        apicore.token = apiKeyOrToken;
-    }
-    else {
-        if (!apiKeyOrToken || !username || !password) {
-            throw new Error("Missing authentication configuration. Provide either an AuthToken or APICORE_API_KEY, APICORE_USERNAME and APICORE_PASSWORD.");
-        }
-        apicore = new ApiCore({ apiKey: apiKeyOrToken });
-        await apicore.authenticate({ username, password });
+export async function createServer(apiKey, username, password) {
+    if (!apiKey || !username || !password) {
+        throw new Error("Missing authentication configuration. Provide APICORE_API_KEY, APICORE_USERNAME and APICORE_PASSWORD.");
     }
+    const apicore = new ApiCore({ apiKey });
+    await apicore.authenticate({ username, password });
     const server = new McpServer({
         name: "afpnews",
         version: "1.2.0",

package/build/tools/find-similar.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import { textContent, toolError, truncateIfNeeded } from '../utils/format.js';
+import { formatDocuments, formatErrorMessage, langEnum, } from './shared.js';
+export const afpFindSimilarTool = {
+    name: 'afp_find_similar',
+    title: 'Find Similar AFP Articles',
+    description: `Find AFP news articles similar to a given article (More Like This). Useful for exploring related coverage or finding follow-up stories.
+
+Args:
+  - uno: The UNO of the reference article to find similar content for
+  - lang: Language for results (e.g. 'en', 'fr')
+  - size: Number of similar articles to return (default 10)
+
+Returns:
+  Pagination summary, followed by markdown-formatted article excerpts:
+  - ## Headline
+  - *UNO | Published date | Lang | Genre*
+  - Article excerpt (first paragraphs)
+
+Examples:
+  - Find similar articles in French: { uno: "NEWS-FR-123456-ABC", lang: "fr" }
+  - Get 5 similar English articles: { uno: "NEWS-EN-789", lang: "en", size: 5 }`,
+    inputSchema: {
+        uno: z.string().describe('The UNO of the reference article'),
+        lang: langEnum.describe("Language for results (e.g. 'en', 'fr')"),
+        size: z.number().optional().describe('Number of similar articles to return (default 10)'),
+    },
+    handler: async (apicore, { uno, lang, size }) => {
+        try {
+            const { documents, count } = await apicore.mlt(uno, lang, size);
+            if (count === 0) {
+                return { content: [textContent('No similar articles found.')] };
+            }
+            const content = [
+                textContent(`*Found ${count} similar articles.*`),
+                ...formatDocuments(documents, false),
+            ];
+            return { content: truncateIfNeeded(content) };
+        }
+        catch (error) {
+            return toolError(formatErrorMessage(`finding similar articles for "${uno}"`, error, 'Verify the UNO identifier is correct.'));
+        }
+    },
+};

package/build/tools/get-article.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { formatDocument, toolError } from '../utils/format.js';
+import { formatErrorMessage } from './shared.js';
+export const afpGetArticleTool = {
+    name: 'afp_get_article',
+    title: 'Get AFP Article',
+    description: `Get a full AFP news article by its UNO identifier. Use this after searching to retrieve the complete text of a specific article.
+
+Args:
+  - uno: The unique identifier (UNO) of the article (e.g. 'NEWS-FR-123456-ABC')
+
+Returns:
+  Markdown-formatted full article:
+  - ## Headline
+  - *UNO | Published date | Lang | Genre*
+  - Complete article body
+
+Examples:
+  - Get a specific article: { uno: "NEWS-FR-123456-ABC" }`,
+    inputSchema: {
+        uno: z.string().describe('The unique identifier (UNO) of the article'),
+    },
+    handler: async (apicore, { uno }) => {
+        try {
+            const doc = await apicore.get(uno);
+            return { content: [formatDocument(doc, true)] };
+        }
+        catch (error) {
+            return toolError(formatErrorMessage(`fetching article "${uno}"`, error, 'Verify the UNO identifier is correct.'));
+        }
+    },
+};

package/build/tools/index.js

@@ -1,237 +1,21 @@
-import { z } from 'zod';
-import { formatDocument, DEFAULT_FIELDS, GENRE_EXCLUSIONS, textContent, toolError, truncateIfNeeded, buildPaginationLine } from '../utils/format.js';
-import { getTopicLabel } from '../utils/topics.js';
-import { DEFAULT_SEARCH_SIZE, DEFAULT_FACET_SIZE } from '../utils/types.js';
-const SEARCH_PRESET_VALUES = ['a-la-une', 'agenda', 'previsions', 'major-stories'];
-const searchPresetEnum = z.enum(SEARCH_PRESET_VALUES);
-const LIST_PRESET_VALUES = ['trending-topics'];
-const listPresetEnum = z.enum(LIST_PRESET_VALUES);
-const langEnum = z.enum(['en', 'fr', 'de', 'pt', 'es', 'ar']);
-const READ_ONLY_ANNOTATIONS = {
-    readOnlyHint: true,
-    destructiveHint: false,
-    idempotentHint: true,
-    openWorldHint: true,
-};
-const SEARCH_PRESETS = {
-    'a-la-une': {
-        product: ['news'],
-        lang: ['fr'],
-        slug: ['afp', 'actualites'],
-        dateFrom: 'now-1d',
-        size: 1,
-        genreid: GENRE_EXCLUSIONS,
-    },
-    'agenda': {
-        product: ['news'],
-        size: 5,
-        genreid: ['afpattribute:Agenda'],
-    },
-    'previsions': {
-        product: ['news'],
-        size: 5,
-        genreid: ['afpattribute:Program', 'afpedtype:TextProgram'],
-    },
-    'major-stories': {
-        product: ['news'],
-        genreid: ['afpattribute:Article'],
-    },
-};
-function formatErrorMessage(context, error, hint) {
-    const message = error instanceof Error ? error.message : String(error);
-    return `Error ${context}: ${message}. ${hint}`;
-}
-function formatDocuments(documents, fullText) {
-    return documents.map((doc) => formatDocument(doc, fullText));
-}
-export function registerTools({ server, apicore }) {
-    server.registerTool("afp_search_articles", {
-        title: "Search AFP News Articles",
-        description: `Search AFP news articles with filters and presets. This is the primary query tool for all AFP news search use cases.
-
-Args:
-  - preset: Optional predefined filter set (a-la-une, agenda, previsions, major-stories)
-  - fullText: Return full article body (true) or excerpt only (false, default). Presets override to true.
-  - query: Search keywords in the language specified by 'lang' (e.g. 'climate change')
-  - lang: Article language filter (e.g. ['en', 'fr']). Use ['en'] for photos.
-  - dateFrom/dateTo: Date range in ISO format (e.g. '2025-01-01') or relative ('now-1d')
-  - size: Number of results (default 10, max 1000)
-  - sortOrder: 'asc' or 'desc' by date (default 'desc')
-  - offset: Pagination offset (number of results to skip)
-  - country: Country code filter (e.g. ['fra', 'usa'])
-  - slug: Topic/slug filter (e.g. ['economy', 'sports'])
-  - product: Content type filter (default ['news', 'factcheck'])
-
-Returns:
-  Pagination summary line, followed by markdown-formatted articles:
-  - ## Headline
-  - *UNO | Published date | Lang | Genre*
-  - Article body (excerpt or full text)
-
-Examples:
-  - Latest Ukraine news: { query: "Ukraine", lang: ["en"], size: 5 }
-  - French front page: { preset: "a-la-une" }
-  - Recent photos: { product: ["photo"], lang: ["en"], size: 5 }
-  - Page 2 of results: { query: "economy", size: 10, offset: 10 }`,
-        inputSchema: {
-            preset: searchPresetEnum.optional().describe("Optional preset that applies predefined AFP filters. Available presets: a-la-une, agenda, previsions, major-stories."),
-            fullText: z.boolean().optional().describe("When true, returns the full article body. Default is false. If omitted and a preset is used, fullText defaults to true."),
-            query: z.string().optional().describe("List of keywords to search for in the news articles (e.g. 'climate change'), in the language specified by the 'lang' parameter. If not specified, the search will be performed in all languages. Do not use keywords in multiple languages."),
-            lang: langEnum.array().optional().describe("Language of the news articles (e.g. 'en', 'fr'). Always use 'en' if you look for photos."),
-            dateFrom: z.string().optional().describe("Start date for the search in ISO format (e.g. '2023-01-01') or relative (e.g. 'now-1d')"),
-            dateTo: z.string().optional().describe("End date for the search in ISO format (e.g. '2023-12-31')"),
-            size: z.number().optional().describe("Number of results to return (default 10, max 1000)"),
-            sortOrder: z.enum(['asc', 'desc']).optional().describe("Sort order by date (default 'desc')"),
-            offset: z.number().optional().describe("Offset for pagination (number of results to skip)"),
-            country: z.string().array().optional().describe("Country filter (e.g. 'fra', 'usa')"),
-            slug: z.string().array().optional().describe("Topic/slug filter (e.g. 'economy', 'sports')"),
-            product: z.enum(['news', 'factcheck', 'photo', 'video', 'multimedia', 'graphic', 'videographic']).array().optional().describe("Content type filter (default ['news', 'factcheck'])")
-        },
-        annotations: READ_ONLY_ANNOTATIONS,
-    }, async ({ preset, fullText = false, query, lang, dateFrom, dateTo, size = DEFAULT_SEARCH_SIZE, sortOrder = 'desc', offset, country, slug, product = ['news', 'factcheck'] }) => {
-        try {
-            let request = {
-                query, lang, product, dateFrom, dateTo, size, sortOrder,
-                startAt: offset, country, slug, genreid: GENRE_EXCLUSIONS,
-            };
-            if (preset) {
-                request = { ...request, ...SEARCH_PRESETS[preset] };
-                fullText = true;
-            }
-            const { documents, count } = await apicore.search(request, [...DEFAULT_FIELDS]);
-            if (count === 0) {
-                return { content: [textContent('No results found.')] };
-            }
-            const currentOffset = offset ?? 0;
-            const content = [
-                textContent(buildPaginationLine(documents.length, count, currentOffset)),
-                ...formatDocuments(documents, fullText),
-            ];
-            return { content: truncateIfNeeded(content) };
-        }
-        catch (error) {
-            return toolError(formatErrorMessage('searching AFP articles', error, 'Check your query parameters and try again.'));
-        }
-    });
-    server.registerTool("afp_get_article", {
-        title: "Get AFP Article",
-        description: `Get a full AFP news article by its UNO identifier. Use this after searching to retrieve the complete text of a specific article.
-
-Args:
-  - uno: The unique identifier (UNO) of the article (e.g. 'NEWS-FR-123456-ABC')
-
-Returns:
-  Markdown-formatted full article:
-  - ## Headline
-  - *UNO | Published date | Lang | Genre*
-  - Complete article body
-
-Examples:
-  - Get a specific article: { uno: "NEWS-FR-123456-ABC" }`,
-        inputSchema: {
-            uno: z.string().describe("The unique identifier (UNO) of the article"),
-        },
-        annotations: READ_ONLY_ANNOTATIONS,
-    }, async ({ uno }) => {
-        try {
-            const doc = await apicore.get(uno);
-            return { content: [formatDocument(doc, true)] };
-        }
-        catch (error) {
-            return toolError(formatErrorMessage(`fetching article "${uno}"`, error, 'Verify the UNO identifier is correct.'));
-        }
-    });
-    server.registerTool("afp_find_similar", {
-        title: "Find Similar AFP Articles",
-        description: `Find AFP news articles similar to a given article (More Like This). Useful for exploring related coverage or finding follow-up stories.
-
-Args:
-  - uno: The UNO of the reference article to find similar content for
-  - lang: Language for results (e.g. 'en', 'fr')
-  - size: Number of similar articles to return (default 10)
-
-Returns:
-  Pagination summary, followed by markdown-formatted article excerpts:
-  - ## Headline
-  - *UNO | Published date | Lang | Genre*
-  - Article excerpt (first paragraphs)
-
-Examples:
-  - Find similar articles in French: { uno: "NEWS-FR-123456-ABC", lang: "fr" }
-  - Get 5 similar English articles: { uno: "NEWS-EN-789", lang: "en", size: 5 }`,
-        inputSchema: {
-            uno: z.string().describe("The UNO of the reference article"),
-            lang: langEnum.describe("Language for results (e.g. 'en', 'fr')"),
-            size: z.number().optional().describe("Number of similar articles to return (default 10)"),
-        },
-        annotations: READ_ONLY_ANNOTATIONS,
-    }, async ({ uno, lang, size }) => {
-        try {
-            const { documents, count } = await apicore.mlt(uno, lang, size);
-            if (count === 0) {
-                return { content: [textContent('No similar articles found.')] };
-            }
-            const content = [
-                textContent(`*Found ${count} similar articles.*`),
-                ...formatDocuments(documents, false),
-            ];
-            return { content: truncateIfNeeded(content) };
-        }
-        catch (error) {
-            return toolError(formatErrorMessage(`finding similar articles for "${uno}"`, error, 'Verify the UNO identifier is correct.'));
-        }
-    });
-    server.registerTool("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.
-
-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')
-  - size: Number of facet values to return
-
-Returns:
-  Markdown-formatted list of facet values with article counts:
-  - **Label or key** — N articles
-
-Examples:
-  - Trending topics in French: { preset: "trending-topics" }
-  - Trending topics in English: { preset: "trending-topics", lang: "en" }
-  - List available genres: { facet: "genre" }
-  - List countries: { facet: "country", size: 30 }`,
-        inputSchema: {
-            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')"),
-            size: z.number().optional().describe("Number of facet values to return"),
-        },
-        annotations: READ_ONLY_ANNOTATIONS,
-    }, async ({ preset, facet, lang, size }) => {
-        try {
-            const isTrendingTopics = preset === 'trending-topics';
-            const resolvedFacet = isTrendingTopics ? 'slug' : facet;
-            if (!resolvedFacet) {
-                return toolError("Missing required parameter: facet (e.g. 'slug', 'genre', 'country'). Alternatively, use preset: 'trending-topics'.");
-            }
-            const params = isTrendingTopics
-                ? { langs: [lang ?? 'fr'], product: ['news'], dateFrom: 'now-1d' }
-                : (lang ? { langs: [lang] } : {});
-            const resolvedSize = isTrendingTopics ? (size ?? DEFAULT_FACET_SIZE) : size;
-            const rawResult = await apicore.list(resolvedFacet, params, resolvedSize);
-            const results = rawResult?.keywords ?? rawResult ?? [];
-            if (results.length === 0) {
-                return { content: [textContent(`No facet values found for "${resolvedFacet}".`)] };
-            }
-            const heading = isTrendingTopics ? 'Trending Topics' : `Facet: ${resolvedFacet}`;
-            const lines = results.map((item) => {
-                const label = isTrendingTopics ? (getTopicLabel(item.key) ?? item.key) : item.key;
-                return `- **${label}** — ${item.count} articles`;
-            });
-            return { content: [textContent(`## ${heading}\n\n${lines.join('\n')}`)] };
-        }
-        catch (error) {
-            return toolError(formatErrorMessage('listing facet values', error, "Check that the facet name is valid (e.g. 'slug', 'genre', 'country')."));
-        }
-    });
+import { afpSearchArticlesTool } from './search-articles.js';
+import { afpGetArticleTool } from './get-article.js';
+import { afpFindSimilarTool } from './find-similar.js';
+import { afpListFacetsTool } from './list-facets.js';
+import { READ_ONLY_ANNOTATIONS } from './shared.js';
+export const TOOL_DEFINITIONS = [
+    afpSearchArticlesTool,
+    afpGetArticleTool,
+    afpFindSimilarTool,
+    afpListFacetsTool,
+];
+export function registerTools(ctx) {
+    for (const tool of TOOL_DEFINITIONS) {
+        ctx.server.registerTool(tool.name, {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            annotations: READ_ONLY_ANNOTATIONS,
+        }, async (args) => tool.handler(ctx.apicore, args));
+    }
 }

package/build/tools/list-facets.js

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import { textContent, toolError } from '../utils/format.js';
+import { getTopicLabel } from '../utils/topics.js';
+import { DEFAULT_FACET_SIZE } from '../utils/types.js';
+import { formatErrorMessage, langEnum, listPresetEnum, } from './shared.js';
+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.
+
+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')
+  - size: Number of facet values to return
+
+Returns:
+  Markdown-formatted list of facet values with article counts:
+  - **Label or key** — N articles
+
+Examples:
+  - Trending topics in French: { preset: "trending-topics" }
+  - Trending topics in English: { preset: "trending-topics", lang: "en" }
+  - List available genres: { facet: "genre" }
+  - List countries: { facet: "country", size: 30 }`,
+    inputSchema: {
+        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')"),
+        size: z.number().optional().describe('Number of facet values to return'),
+    },
+    handler: async (apicore, { preset, facet, lang, size }) => {
+        try {
+            const isTrendingTopics = preset === 'trending-topics';
+            const resolvedFacet = isTrendingTopics ? 'slug' : facet;
+            if (!resolvedFacet) {
+                return toolError("Missing required parameter: facet (e.g. 'slug', 'genre', 'country'). Alternatively, use preset: 'trending-topics'.");
+            }
+            const params = isTrendingTopics
+                ? { langs: [lang ?? 'fr'], product: ['news'], dateFrom: 'now-1d' }
+                : (lang ? { langs: [lang] } : {});
+            const resolvedSize = isTrendingTopics ? (size ?? DEFAULT_FACET_SIZE) : size;
+            const rawResult = await apicore.list(resolvedFacet, params, resolvedSize);
+            const results = rawResult?.keywords ?? rawResult ?? [];
+            if (results.length === 0) {
+                return { content: [textContent(`No facet values found for "${resolvedFacet}".`)] };
+            }
+            const heading = isTrendingTopics ? 'Trending Topics' : `Facet: ${resolvedFacet}`;
+            const lines = results.map((item) => {
+                const label = isTrendingTopics ? (getTopicLabel(item.key) ?? item.key) : item.key;
+                return `- **${label}** — ${item.count} articles`;
+            });
+            return { content: [textContent(`## ${heading}\n\n${lines.join('\n')}`)] };
+        }
+        catch (error) {
+            return toolError(formatErrorMessage('listing facet values', error, "Check that the facet name is valid (e.g. 'slug', 'genre', 'country')."));
+        }
+    },
+};

package/build/tools/search-articles.js

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+import { DEFAULT_FIELDS, GENRE_EXCLUSIONS, textContent, toolError, truncateIfNeeded, buildPaginationLine, } from '../utils/format.js';
+import { DEFAULT_SEARCH_SIZE } from '../utils/types.js';
+import { SEARCH_PRESETS, formatErrorMessage, formatDocuments, langEnum, searchPresetEnum, } from './shared.js';
+export const afpSearchArticlesTool = {
+    name: 'afp_search_articles',
+    title: 'Search AFP News Articles',
+    description: `Search AFP news articles with filters and presets. This is the primary query tool for all AFP news search use cases.
+
+Args:
+  - preset: Optional predefined filter set (a-la-une, agenda, previsions, major-stories)
+  - fullText: Return full article body (true) or excerpt only (false, default). Presets override to true.
+  - query: Search keywords in the language specified by 'lang' (e.g. 'climate change')
+  - lang: Article language filter (e.g. ['en', 'fr']). Use ['en'] for photos.
+  - dateFrom/dateTo: Date range in ISO format (e.g. '2025-01-01') or relative ('now-1d')
+  - size: Number of results (default 10, max 1000)
+  - sortOrder: 'asc' or 'desc' by date (default 'desc')
+  - offset: Pagination offset (number of results to skip)
+  - country: Country code filter (e.g. ['fra', 'usa'])
+  - slug: Topic/slug filter (e.g. ['economy', 'sports'])
+  - product: Content type filter (default ['news', 'factcheck'])
+
+Returns:
+  Pagination summary line, followed by markdown-formatted articles:
+  - ## Headline
+  - *UNO | Published date | Lang | Genre*
+  - Article body (excerpt or full text)
+
+Examples:
+  - Latest Ukraine news: { query: "Ukraine", lang: ["en"], size: 5 }
+  - French front page: { preset: "a-la-une" }
+  - Recent photos: { product: ["photo"], lang: ["en"], size: 5 }
+  - Page 2 of results: { query: "economy", size: 10, offset: 10 }`,
+    inputSchema: {
+        preset: searchPresetEnum.optional().describe('Optional preset that applies predefined AFP filters. Available presets: a-la-une, agenda, previsions, major-stories.'),
+        fullText: z.boolean().optional().describe('When true, returns the full article body. Default is false. If omitted and a preset is used, fullText defaults to true.'),
+        query: z.string().optional().describe("List of keywords to search for in the news articles (e.g. 'climate change'), in the language specified by the 'lang' parameter. If not specified, the search will be performed in all languages. Do not use keywords in multiple languages."),
+        lang: langEnum.array().optional().describe("Language of the news articles (e.g. 'en', 'fr'). Always use 'en' if you look for photos."),
+        dateFrom: z.string().optional().describe("Start date for the search in ISO format (e.g. '2023-01-01') or relative (e.g. 'now-1d')"),
+        dateTo: z.string().optional().describe("End date for the search in ISO format (e.g. '2023-12-31')"),
+        size: z.number().optional().describe('Number of results to return (default 10, max 1000)'),
+        sortOrder: z.enum(['asc', 'desc']).optional().describe("Sort order by date (default 'desc')"),
+        offset: z.number().optional().describe('Offset for pagination (number of results to skip)'),
+        country: z.string().array().optional().describe("Country filter (e.g. 'fra', 'usa')"),
+        slug: z.string().array().optional().describe("Topic/slug filter (e.g. 'economy', 'sports')"),
+        product: z.enum(['news', 'factcheck', 'photo', 'video', 'multimedia', 'graphic', 'videographic']).array().optional().describe("Content type filter (default ['news', 'factcheck'])"),
+    },
+    handler: async (apicore, { preset, fullText = false, query, lang, dateFrom, dateTo, size = DEFAULT_SEARCH_SIZE, sortOrder = 'desc', offset, country, slug, product = ['news', 'factcheck'] }) => {
+        try {
+            let request = {
+                query,
+                lang,
+                product,
+                dateFrom,
+                dateTo,
+                size,
+                sortOrder,
+                startAt: offset,
+                country,
+                slug,
+                genreid: GENRE_EXCLUSIONS,
+            };
+            if (preset) {
+                request = { ...request, ...SEARCH_PRESETS[preset] };
+                fullText = true;
+            }
+            const { documents, count } = await apicore.search(request, [...DEFAULT_FIELDS]);
+            if (count === 0) {
+                return { content: [textContent('No results found.')] };
+            }
+            const currentOffset = offset ?? 0;
+            const content = [
+                textContent(buildPaginationLine(documents.length, count, currentOffset)),
+                ...formatDocuments(documents, fullText),
+            ];
+            return { content: truncateIfNeeded(content) };
+        }
+        catch (error) {
+            return toolError(formatErrorMessage('searching AFP articles', error, 'Check your query parameters and try again.'));
+        }
+    },
+};

package/build/tools/shared.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import { formatDocument, GENRE_EXCLUSIONS, } from '../utils/format.js';
+const SEARCH_PRESET_VALUES = ['a-la-une', 'agenda', 'previsions', 'major-stories'];
+export const searchPresetEnum = z.enum(SEARCH_PRESET_VALUES);
+const LIST_PRESET_VALUES = ['trending-topics'];
+export const listPresetEnum = z.enum(LIST_PRESET_VALUES);
+export const langEnum = z.enum(['en', 'fr', 'de', 'pt', 'es', 'ar']);
+export const READ_ONLY_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+export const SEARCH_PRESETS = {
+    'a-la-une': {
+        product: ['news'],
+        lang: ['fr'],
+        slug: ['afp', 'actualites'],
+        dateFrom: 'now-1d',
+        size: 1,
+        genreid: GENRE_EXCLUSIONS,
+    },
+    'agenda': {
+        product: ['news'],
+        size: 5,
+        genreid: ['afpattribute:Agenda'],
+    },
+    'previsions': {
+        product: ['news'],
+        size: 5,
+        genreid: ['afpattribute:Program', 'afpedtype:TextProgram'],
+    },
+    'major-stories': {
+        product: ['news'],
+        genreid: ['afpattribute:Article'],
+    },
+};
+export function formatErrorMessage(context, error, hint) {
+    const message = error instanceof Error ? error.message : String(error);
+    return `Error ${context}: ${message}. ${hint}`;
+}
+export function formatDocuments(documents, fullText) {
+    return documents.map((doc) => formatDocument(doc, fullText));
+}

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "afpnews-mcp-server",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "",
   "main": "build/index.js",
   "type": "module",
+  "exports": {
+    ".": "./build/index.js",
+    "./definitions": "./build/definitions.js"
+  },
   "scripts": {
     "build": "tsc && chmod 755 build/index.js",
     "start": "node build/index.js",
@@ -32,4 +36,4 @@
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   }
-}
+}