afpnews-mcp-server 1.3.6 → 1.3.9

package/build/index.js

@@ -19,10 +19,11 @@ export function resolveStdioAuthConfig(env = process.env) {
     const apiKey = env.APICORE_API_KEY?.trim();
     const username = env.APICORE_USERNAME?.trim();
     const password = env.APICORE_PASSWORD?.trim();
+    const baseUrl = env.APICORE_BASE_URL?.trim();
     if (!apiKey || !username || !password) {
         throw new Error('Missing stdio auth configuration: set APICORE_API_KEY + APICORE_USERNAME + APICORE_PASSWORD.');
     }
-    return { apiKey, username, password };
+    return { apiKey, username, password, baseUrl };
 }
 async function startHttpServer() {
     const { default: express } = await import('express');
@@ -30,6 +31,7 @@ async function startHttpServer() {
     if (!apiKey) {
         throw new Error('APICORE_API_KEY environment variable is required');
     }
+    const baseUrl = process.env.APICORE_BASE_URL?.trim();
     const app = express();
     const sessions = new Map();
     app.all('/mcp', async (req, res) => {
@@ -57,7 +59,7 @@ async function startHttpServer() {
         const transport = new StreamableHTTPServerTransport({
             sessionIdGenerator: () => crypto.randomUUID(),
         });
-        const server = await createServer(apiKey, credentials.username, credentials.password);
+        const server = await createServer({ apiKey, username: credentials.username, password: credentials.password, baseUrl });
         await server.connect(transport);
         transport.onclose = () => {
             const sid = transport.sessionId;
@@ -80,7 +82,7 @@ async function startHttpServer() {
 }
 async function startStdioServer() {
     const authConfig = resolveStdioAuthConfig();
-    const server = await createServer(authConfig.apiKey, authConfig.username, authConfig.password);
+    const server = await createServer(authConfig);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error('MCP stdio server started');

package/build/server.js

@@ -3,15 +3,15 @@ import { ApiCore } from "afpnews-api";
 import { registerTools } from "./tools/index.js";
 import { registerResources } from "./resources/index.js";
 import { registerPrompts } from "./prompts/index.js";
-export async function createServer(apiKey, username, password) {
+export async function createServer({ apiKey, username, password, baseUrl, }) {
     if (!apiKey || !username || !password) {
         throw new Error("Missing authentication configuration. Provide APICORE_API_KEY, APICORE_USERNAME and APICORE_PASSWORD.");
     }
-    const apicore = new ApiCore({ apiKey });
+    const apicore = new ApiCore({ ...(baseUrl ? { baseUrl } : {}), apiKey });
     await apicore.authenticate({ username, password });
     const server = new McpServer({
         name: "afpnews",
-        version: "1.2.0",
+        version: "1.3.8",
     });
     const ctx = { server, apicore };
     registerTools(ctx);

package/build/tools/find-similar.js

@@ -1,36 +1,49 @@
 import { z } from 'zod';
-import { textContent, toolError, truncateIfNeeded } from '../utils/format.js';
-import { formatDocuments, formatErrorMessage, langEnum, } from './shared.js';
+import { formatDocumentsAsJson, formatDocumentsAsCsv, textContent, toolError, truncateIfNeeded, } from '../utils/format.js';
+import { formatDocuments, formatErrorMessage, langEnum, outputFormatEnum, docFieldEnum, DEFAULT_OUTPUT_FIELDS, UNO_FORMAT_NOTE, } 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.
 
+${UNO_FORMAT_NOTE}
+
 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)
+  - format: Output format — markdown (default), json, or csv. json/csv omit article body text.
+  - fields: Fields to include in json/csv output (default: uno, headline, lang, genre).
+            Available: uno, headline, lang, genre, afpshortid, published, status, signal, advisory, country, city, slug, product, revision, created.
 
 Returns:
-  Pagination summary, followed by markdown-formatted article excerpts:
-  - ## Headline
-  - *UNO | Published date | Lang | Genre*
-  - Article excerpt (first paragraphs)
+  - markdown: Summary line + formatted article excerpts
+  - json: { total, documents: [...] } with selected fields
+  - csv: Header row + data rows with selected fields
 
 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 }`,
+  - Find similar articles in French: { uno: "newsml.afp.com.20260222T090659Z.doc-98hu39e", lang: "fr" }
+  - Export similar as CSV: { uno: "newsml.afp.com.20260222T090659Z.doc-98hu39e", lang: "en", format: "csv", fields: ["uno", "headline"] }`,
     inputSchema: z.object({
         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)'),
+        format: outputFormatEnum.optional().describe('Output format: markdown (default, with article excerpt), json (structured, no body), csv (tabular, no body).'),
+        fields: docFieldEnum.array().optional().describe('Fields to include in json/csv output. Default: afpshortid, uno, headline, published, lang, genre.'),
     }),
-    handler: async (apicore, { uno, lang, size }) => {
+    handler: async (apicore, { uno, lang, size, format = 'markdown', fields }) => {
         try {
             const { documents, count } = await apicore.mlt(uno, lang, size);
             if (count === 0) {
                 return { content: [textContent('No similar articles found.')] };
             }
+            const outputFields = fields ?? DEFAULT_OUTPUT_FIELDS;
+            if (format === 'json') {
+                return { content: [formatDocumentsAsJson(documents, outputFields, { total: count })] };
+            }
+            if (format === 'csv') {
+                return { content: [formatDocumentsAsCsv(documents, outputFields)] };
+            }
             const content = [
                 textContent(`*Found ${count} similar articles.*`),
                 ...formatDocuments(documents, false),

package/build/tools/get-article.js

@@ -1,29 +1,42 @@
 import { z } from 'zod';
-import { formatDocument, toolError } from '../utils/format.js';
-import { formatErrorMessage } from './shared.js';
+import { formatFullArticle, toolError } from '../utils/format.js';
+import { formatErrorMessage, UNO_FORMAT_NOTE } 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.
+    description: `Retrieve the complete text of a specific AFP article by its UNO identifier.
+
+Use this tool when you have a UNO (from afp_search_articles or afp_find_similar results) and need:
+  - The full, untruncated article body
+  - All available metadata (country, city, slug, revision, status, signal, advisory)
+  - A definitive version of the article before quoting or summarising
+
+Do NOT use this to discover articles — use afp_search_articles for that.
+
+${UNO_FORMAT_NOTE}
 
 Args:
-  - uno: The unique identifier (UNO) of the article (e.g. 'NEWS-FR-123456-ABC')
+  - uno: The unique article identifier (e.g. newsml.afp.com.20260222T090659Z.doc-98hu39e)
 
 Returns:
-  Markdown-formatted full article:
+  Markdown-formatted article:
   - ## Headline
-  - *UNO | Published date | Lang | Genre*
-  - Complete article body
+  - **UNO:** ...
+  - **Lang:** · **Genre:** · **Product:** · **Revision:**
+  - **Country:** · **City:** · **Slug:** (when available)
+  - **Status:** · **Signal:** · **Advisory:** (when present)
+  - ---
+  - Full article body (all paragraphs, no truncation)
 
-Examples:
-  - Get a specific article: { uno: "NEWS-FR-123456-ABC" }`,
+Example:
+  { uno: "newsml.afp.com.20260222T090659Z.doc-98hu39e" }`,
     inputSchema: z.object({
-        uno: z.string().describe('The unique identifier (UNO) of the article'),
+        uno: z.string().describe('The unique UNO identifier of the article (e.g. AFP-FR-2025-12-31-0001)'),
     }),
     handler: async (apicore, { uno }) => {
         try {
             const doc = await apicore.get(uno);
-            return { content: [formatDocument(doc, true)] };
+            return { content: [formatFullArticle(doc)] };
         }
         catch (error) {
             return toolError(formatErrorMessage(`fetching article "${uno}"`, error, 'Verify the UNO identifier is correct.'));

package/build/tools/list-facets.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { textContent, toolError } from '../utils/format.js';
-import { formatErrorMessage, langEnum, listPresetEnum, } from './shared.js';
+import { formatErrorMessage, langEnum, listPresetEnum, outputFormatEnum, } from './shared.js';
 export const afpListFacetsTool = {
     name: 'afp_list_facets',
     title: 'List AFP Facet Values',
@@ -11,23 +11,26 @@ Args:
   - 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
+  - format: Output format — markdown (default), json, or csv.
 
 Returns:
-  Markdown-formatted list of facet values with article counts:
-  - **Label or key** — N articles
+  - markdown: Formatted list with labels and article counts
+  - json: Array of { name, count } objects
+  - csv: name,count rows
 
 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 }`,
+  - List available genres as CSV: { facet: "genre", format: "csv" }
+  - List countries as JSON: { facet: "country", size: 30, format: "json" }`,
     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')"),
         size: z.number().optional().describe('Number of facet values to return'),
+        format: outputFormatEnum.optional().describe('Output format: markdown (default), json, or csv.'),
     }),
-    handler: async (apicore, { preset, facet, lang, size }) => {
+    handler: async (apicore, { preset, facet, lang, size, format = 'markdown' }) => {
         try {
             const isTrendingTopics = preset === 'trending-topics';
             const resolvedFacet = isTrendingTopics ? 'slug' : facet;
@@ -42,10 +45,18 @@ Examples:
             if (results.length === 0) {
                 return { content: [textContent(`No facet values found for "${resolvedFacet}".`)] };
             }
+            if (format === 'json') {
+                return { content: [textContent(JSON.stringify(results, null, 2))] };
+            }
+            if (format === 'csv') {
+                const rows = results.map(r => {
+                    const name = /[",\n\r]/.test(r.name) ? `"${r.name.replaceAll('"', '""')}"` : r.name;
+                    return `${name},${r.count}`;
+                });
+                return { content: [textContent(['name,count', ...rows].join('\n'))] };
+            }
             const heading = isTrendingTopics ? 'Trending Topics' : `Facet: ${resolvedFacet}`;
-            const lines = results.map((item) => {
-                return `- **${item.name}** — ${item.count} articles`;
-            });
+            const lines = results.map((item) => `- **${item.name}** — ${item.count} articles`);
             return { content: [textContent(`## ${heading}\n\n${lines.join('\n')}`)] };
         }
         catch (error) {

package/build/tools/search-articles.js

@@ -1,15 +1,20 @@
 import { z } from 'zod';
-import { DEFAULT_FIELDS, GENRE_EXCLUSIONS, textContent, toolError, truncateIfNeeded, buildPaginationLine, } from '../utils/format.js';
+import { DEFAULT_FIELDS, GENRE_EXCLUSIONS, formatDocumentsAsJson, formatDocumentsAsCsv, 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';
+import { SEARCH_PRESETS, formatErrorMessage, formatDocuments, langEnum, searchPresetEnum, outputFormatEnum, docFieldEnum, DEFAULT_OUTPUT_FIELDS, UNO_FORMAT_NOTE, } 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.
 
+${UNO_FORMAT_NOTE}
+
 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.
+  - format: Output format — markdown (default), json, or csv. json/csv omit article body text.
+  - fields: Fields to include in json/csv output (default: uno, headline, lang, genre).
+            Available: uno, headline, lang, genre, afpshortid, published, status, signal, advisory, country, city, slug, product, revision, created.
+  - fullText: Return full article body (true) or excerpt only (false, default). Only applies to markdown. 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')
@@ -21,19 +26,19 @@ Args:
   - 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)
+  - markdown: Pagination summary line + formatted articles with headline, metadata, body
+  - json: { total, shown, offset, documents: [...] } with selected fields
+  - csv: Header row + data rows with selected fields
 
 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 }`,
+  - Export metadata as CSV: { query: "economy", format: "csv", fields: ["uno", "headline", "country"] }`,
     inputSchema: z.object({
         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.'),
+        format: outputFormatEnum.optional().describe('Output format: markdown (default, with article body), json (structured, no body), csv (tabular, no body).'),
+        fields: docFieldEnum.array().optional().describe('Fields to include in json/csv output. Default: afpshortid, uno, headline, published, lang, genre.'),
+        fullText: z.boolean().optional().describe('When true, returns the full article body (markdown only). Default is false. Presets override 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')"),
@@ -45,7 +50,7 @@ Examples:
         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'] }) => {
+    handler: async (apicore, { preset, format = 'markdown', fields, fullText = false, query, lang, dateFrom, dateTo, size = DEFAULT_SEARCH_SIZE, sortOrder = 'desc', offset, country, slug, product = ['news', 'factcheck'] }) => {
         try {
             let request = {
                 query,
@@ -64,11 +69,21 @@ Examples:
                 request = { ...request, ...SEARCH_PRESETS[preset] };
                 fullText = true;
             }
-            const { documents, count } = await apicore.search(request, [...DEFAULT_FIELDS]);
+            const outputFields = fields ?? DEFAULT_OUTPUT_FIELDS;
+            const apiFields = format === 'markdown'
+                ? [...DEFAULT_FIELDS]
+                : [...new Set(['afpshortid', 'uno', ...outputFields])];
+            const { documents, count } = await apicore.search(request, apiFields);
             if (count === 0) {
                 return { content: [textContent('No results found.')] };
             }
             const currentOffset = offset ?? 0;
+            if (format === 'json') {
+                return { content: [formatDocumentsAsJson(documents, outputFields, { total: count, shown: documents.length, offset: currentOffset })] };
+            }
+            if (format === 'csv') {
+                return { content: [formatDocumentsAsCsv(documents, outputFields)] };
+            }
             const content = [
                 textContent(buildPaginationLine(documents.length, count, currentOffset)),
                 ...formatDocuments(documents, fullText),

package/build/tools/shared.js

@@ -1,5 +1,17 @@
 import { z } from 'zod';
 import { formatDocument, GENRE_EXCLUSIONS, } from '../utils/format.js';
+import { ALL_DOC_FIELDS, DEFAULT_OUTPUT_FIELDS } from '../utils/types.js';
+export { ALL_DOC_FIELDS, DEFAULT_OUTPUT_FIELDS };
+// UNO format: newsml.afp.com.20260222T090659Z.doc-98hu39e
+//   - timestamp: 20260222T090659Z → 2026-02-22 09:06:59 UTC
+//   - afpshortid: the segment after "doc-" (e.g. 98hu39e)
+// Published date and afpshortid are encoded in the UNO — no need to fetch them as separate fields.
+export const UNO_FORMAT_NOTE = `Note on the UNO identifier (e.g. newsml.afp.com.20260222T090659Z.doc-98hu39e):
+  - Publication date: the timestamp segment, e.g. 20260222T090659Z → 2026-02-22 09:06:59 UTC
+  - Short ID (afpshortid): the segment after "doc-", e.g. 98hu39e
+  Both are embedded in the UNO — request afpshortid or published as explicit fields only if needed.`;
+export const outputFormatEnum = z.enum(['markdown', 'json', 'csv']);
+export const docFieldEnum = z.enum(ALL_DOC_FIELDS);
 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'];

package/build/utils/format.js

@@ -1,4 +1,22 @@
 import { EXCERPT_PARAGRAPH_COUNT, CHARACTER_LIMIT } from './types.js';
+function escapeCsvValue(value) {
+    const str = Array.isArray(value) ? value.join('|') : String(value ?? '');
+    if (/[",\n\r]/.test(str))
+        return `"${str.replaceAll('"', '""')}"`;
+    return str;
+}
+export function pickDocFields(doc, fields) {
+    const d = doc;
+    return Object.fromEntries(fields.map(f => [f, d[f] ?? null]));
+}
+export function formatDocumentsAsJson(docs, fields, meta = {}) {
+    const documents = docs.map(doc => pickDocFields(doc, fields));
+    return textContent(JSON.stringify({ ...meta, documents }, null, 2));
+}
+export function formatDocumentsAsCsv(docs, fields) {
+    const rows = docs.map(doc => fields.map(f => escapeCsvValue(doc[f])).join(','));
+    return textContent([fields.join(','), ...rows].join('\n'));
+}
 export const GENRE_EXCLUSIONS = {
     exclude: [
         'afpgenre:Agenda',
@@ -11,12 +29,11 @@ export const GENRE_EXCLUSIONS = {
         'afpattribute:PictureProgram'
     ]
 };
-export const DEFAULT_FIELDS = ['uno', 'status', 'signal', 'advisory', 'published', 'headline', 'news', 'lang', 'genre'];
+export const DEFAULT_FIELDS = ['uno', 'status', 'signal', 'advisory', 'headline', 'news', 'lang', 'genre'];
 export function formatDocument(doc, fullText = false) {
     const d = doc;
     const meta = [
         `UNO: ${d.uno}`,
-        `Published: ${typeof d.published === 'string' ? d.published : new Date(d.published).toISOString()}`,
         `Lang: ${d.lang}`,
         `Genre: ${d.genre}`,
     ];
@@ -33,6 +50,25 @@ export function formatDocument(doc, fullText = false) {
     const text = `## ${d.headline}\n*${meta.join(' | ')}*\n\n${body}`;
     return { type: 'text', text };
 }
+export function formatFullArticle(doc) {
+    const d = doc;
+    const row = (...pairs) => pairs
+        .filter(([, v]) => v != null && v !== '')
+        .map(([k, v]) => `**${k}:** ${Array.isArray(v) ? v.join(', ') : v}`)
+        .join(' · ');
+    const lines = [];
+    lines.push(row(['UNO', d.uno]));
+    lines.push(row(['Lang', d.lang], ['Genre', d.genre], ['Product', d.product], ['Revision', d.revision]));
+    const extras = row(['Country', d.country], ['City', d.city], ['Slug', d.slug]);
+    if (extras)
+        lines.push(extras);
+    const flags = row(['Status', d.status], ['Signal', d.signal], ['Advisory', d.advisory]);
+    if (flags)
+        lines.push(flags);
+    const meta = lines.join('\n');
+    const body = (Array.isArray(d.news) ? d.news : []).join('\n\n');
+    return { type: 'text', text: `## ${d.headline}\n\n${meta}\n\n---\n\n${body}` };
+}
 export function textContent(text) {
     return { type: 'text', text };
 }

package/build/utils/types.js

@@ -2,3 +2,8 @@ export const EXCERPT_PARAGRAPH_COUNT = 4;
 export const CHARACTER_LIMIT = 25_000;
 export const DEFAULT_SEARCH_SIZE = 10;
 export const DEFAULT_FACET_SIZE = 20;
+export const ALL_DOC_FIELDS = [
+    'afpshortid', 'uno', 'headline', 'published', 'lang', 'genre',
+    'status', 'signal', 'advisory', 'country', 'city', 'slug', 'product', 'revision', 'created',
+];
+export const DEFAULT_OUTPUT_FIELDS = ['uno', 'headline', 'lang', 'genre'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "afpnews-mcp-server",
-  "version": "1.3.6",
+  "version": "1.3.9",
   "description": "",
   "main": "build/index.js",
   "type": "module",