@alfe.ai/news-mcp 0.2.5 → 0.2.7

package/README.md

@@ -0,0 +1,25 @@
+# @alfe.ai/news-mcp
+
+Runtime-neutral stdio MCP server for metered APITube and NewsData search through
+Alfe. Provider credentials and billing remain in `services/news`; the MCP reads
+the agent's Alfe config and calls the typed Agent API client.
+
+## Tools
+
+- `news_search` searches recent articles with an explicit bounded query and
+  optional provider, source, date, language, category, and result limit.
+- `top_headlines` returns current headlines with optional provider filters.
+
+The default provider is APITube. NewsData accepts at most 50 results and
+`YYYY-MM-DD` date windows. Tool inputs mirror the service constraints, provider
+results are runtime-validated and size-bounded, and provider/billing/API errors
+surface as redacted MCP `isError` results.
+
+## Development
+
+```bash
+pnpm --filter @alfe.ai/news-mcp lint
+pnpm --filter @alfe.ai/news-mcp typecheck
+pnpm --filter @alfe.ai/news-mcp test
+pnpm --filter @alfe.ai/news-mcp build
+```

package/dist/server.cjs

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let node_fs = require("node:fs");
+let node_module = require("node:module");
+let node_url = require("node:url");
+let _modelcontextprotocol_sdk_server_mcp_js = require("@modelcontextprotocol/sdk/server/mcp.js");
+let _modelcontextprotocol_sdk_server_stdio_js = require("@modelcontextprotocol/sdk/server/stdio.js");
+let _alfe_ai_config = require("@alfe.ai/config");
+let _alfe_ai_agent_api_client = require("@alfe.ai/agent-api-client");
+let zod = require("zod");
+//#region src/boundary.ts
+const MAX_QUERY_CHARS = 400;
+const MAX_SOURCE_CHARS = 200;
+const MAX_DATE_CHARS = 40;
+const MAX_LANGUAGE_CHARS = 11;
+const MAX_CATEGORY_CHARS = 60;
+const MAX_TITLE_CHARS = 4096;
+const MAX_URL_CHARS = 16384;
+const MAX_RESULT_SOURCE_CHARS = 1024;
+const MAX_PUBLISHED_AT_CHARS = 128;
+const MAX_SNIPPET_CHARS = 16384;
+const MAX_SENTIMENT_LABEL_CHARS = 128;
+const MAX_ARTICLES = 100;
+const MAX_TOOL_RESULT_BYTES = 2 * 1024 * 1024;
+const newsProviderSchema = zod.z.enum(["apitube", "newsdata"]);
+function boundedInputString(max, label) {
+	return zod.z.string().min(1).max(max).refine((value) => !hasControlCharacters(value), `${label} cannot contain control characters`);
+}
+const baseSearchSchema = zod.z.object({
+	query: boundedInputString(MAX_QUERY_CHARS, "Search query"),
+	provider: newsProviderSchema.default("apitube"),
+	source: boundedInputString(MAX_SOURCE_CHARS, "News source").optional(),
+	from: boundedInputString(MAX_DATE_CHARS, "Start date").optional(),
+	to: boundedInputString(MAX_DATE_CHARS, "End date").optional(),
+	language: boundedInputString(MAX_LANGUAGE_CHARS, "Language").regex(/^[a-z]{2,3}(,[a-z]{2,3}){0,2}$/iu).optional(),
+	category: boundedInputString(MAX_CATEGORY_CHARS, "Category").optional(),
+	limit: zod.z.coerce.number().int().min(1).max(MAX_ARTICLES).optional()
+});
+const searchInputShape = baseSearchSchema.shape;
+const searchArgsSchema = baseSearchSchema.superRefine((value, context) => {
+	if (value.provider !== "newsdata") return;
+	if (value.limit !== void 0 && value.limit > 50) context.addIssue({
+		code: "custom",
+		path: ["limit"],
+		message: "NewsData supports at most 50 results"
+	});
+	for (const field of ["from", "to"]) {
+		const date = value[field];
+		if (date !== void 0 && !isNewsDataDate(date)) context.addIssue({
+			code: "custom",
+			path: [field],
+			message: "NewsData dates must use YYYY-MM-DD"
+		});
+	}
+	if (value.from !== void 0 && value.to !== void 0 && isNewsDataDate(value.from) && isNewsDataDate(value.to) && value.from > value.to) context.addIssue({
+		code: "custom",
+		path: ["to"],
+		message: "End date must not precede start date"
+	});
+});
+const baseHeadlinesSchema = zod.z.object({
+	provider: newsProviderSchema.default("apitube"),
+	category: boundedInputString(MAX_CATEGORY_CHARS, "Category").optional(),
+	source: boundedInputString(MAX_SOURCE_CHARS, "News source").optional(),
+	language: boundedInputString(MAX_LANGUAGE_CHARS, "Language").regex(/^[a-z]{2,3}(,[a-z]{2,3}){0,2}$/iu).optional(),
+	limit: zod.z.coerce.number().int().min(1).max(MAX_ARTICLES).optional()
+});
+const headlinesInputShape = baseHeadlinesSchema.shape;
+const headlinesArgsSchema = baseHeadlinesSchema.superRefine((value, context) => {
+	if (value.provider === "newsdata" && value.limit !== void 0 && value.limit > 50) context.addIssue({
+		code: "custom",
+		path: ["limit"],
+		message: "NewsData supports at most 50 results"
+	});
+});
+const resultString = (max) => zod.z.string().max(max).refine((value) => !hasControlCharacters(value));
+const articleUrlSchema = resultString(MAX_URL_CHARS).refine((value) => {
+	try {
+		const url = new URL(value);
+		return (url.protocol === "https:" || url.protocol === "http:") && !url.username && !url.password;
+	} catch {
+		return false;
+	}
+}, "Article URL must be a safe HTTP(S) URL");
+const sentimentSchema = zod.z.object({
+	score: zod.z.number().min(-1).max(1).optional(),
+	label: resultString(MAX_SENTIMENT_LABEL_CHARS).min(1).optional()
+}).refine((value) => value.score !== void 0 || value.label !== void 0, { message: "Sentiment must contain a score or label" });
+const newsResultSchema = zod.z.object({
+	provider: newsProviderSchema,
+	articles: zod.z.array(zod.z.object({
+		title: resultString(MAX_TITLE_CHARS).min(1),
+		url: articleUrlSchema,
+		source: resultString(MAX_RESULT_SOURCE_CHARS).min(1),
+		publishedAt: resultString(MAX_PUBLISHED_AT_CHARS).min(1).refine((value) => Number.isFinite(Date.parse(value)), "Invalid article timestamp"),
+		snippet: resultString(MAX_SNIPPET_CHARS),
+		sentiment: sentimentSchema.optional()
+	})).max(MAX_ARTICLES)
+});
+function normalizeNewsResult(value) {
+	const result = newsResultSchema.parse(value);
+	const encoded = JSON.stringify(result);
+	if (Buffer.byteLength(encoded, "utf8") > 2097152) throw new Error(`News result exceeds ${String(MAX_TOOL_RESULT_BYTES)} bytes`);
+	return result;
+}
+function encodeToolResult(value) {
+	const encoded = JSON.stringify(value);
+	if (Buffer.byteLength(encoded, "utf8") > 2097152) throw new Error(`News tool result exceeds ${String(MAX_TOOL_RESULT_BYTES)} bytes`);
+	return encoded;
+}
+function safeErrorMessage(error, secrets = []) {
+	let output = (error instanceof Error ? error.message : String(error)).slice(0, 4096).replace(/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/giu, "$1 [REDACTED]").replace(/\b(api[_-]?key|access[_-]?token|refresh[_-]?token|secret|password)\s*[=:]\s*[^\s,;]+/giu, "$1=[REDACTED]").replace(/https?:\/\/[^\s/@:]+:[^\s/@]+@/giu, "https://[REDACTED]@").replace(/\balfe_[A-Za-z0-9_-]{8,}/gu, "[REDACTED]");
+	for (const secret of secrets) if (secret.length >= 4) output = output.split(secret).join("[REDACTED]");
+	return flattenControls(output);
+}
+function isNewsDataDate(value) {
+	if (!/^\d{4}-\d{2}-\d{2}$/u.test(value)) return false;
+	const epoch = Date.parse(`${value}T00:00:00Z`);
+	return Number.isFinite(epoch) && new Date(epoch).toISOString().slice(0, 10) === value;
+}
+function hasControlCharacters(value) {
+	return Array.from(value).some((character) => {
+		const codePoint = character.codePointAt(0) ?? 0;
+		return codePoint < 32 || codePoint === 127;
+	});
+}
+function flattenControls(value) {
+	let output = "";
+	let previousWasControl = false;
+	for (const character of value) {
+		const codePoint = character.codePointAt(0) ?? 0;
+		const isControl = codePoint < 32 || codePoint === 127;
+		if (isControl) {
+			if (!previousWasControl) output += " ";
+		} else output += character;
+		previousWasControl = isControl;
+	}
+	return output;
+}
+//#endregion
+//#region src/tools.ts
+const providerSchema = newsProviderSchema.default("apitube").describe("News provider to query. APITube (default) covers 500K+ sources with sentiment.");
+function ok(data) {
+	return { content: [{
+		type: "text",
+		text: encodeToolResult(data)
+	}] };
+}
+function fail(err) {
+	return {
+		content: [{
+			type: "text",
+			text: encodeToolResult({ error: safeErrorMessage(err) })
+		}],
+		isError: true
+	};
+}
+function registerTools(server, client) {
+	const register = server.registerTool.bind(server);
+	register("news_search", {
+		description: "Search recent news across a broad provider (APITube / NewsData). Returns normalized articles with title, url, source, publishedAt, snippet, and (APITube) sentiment.",
+		inputSchema: {
+			query: searchInputShape.query.describe("Search query (keywords, entities, topics)."),
+			provider: providerSchema,
+			source: searchInputShape.source.describe("Restrict to a single source/domain (e.g. reuters.com)."),
+			from: searchInputShape.from.describe("Earliest publish date, ISO-8601 (e.g. 2026-07-01)."),
+			to: searchInputShape.to.describe("Latest publish date, ISO-8601."),
+			language: searchInputShape.language.describe("ISO-639-1 language code (e.g. en)."),
+			category: searchInputShape.category.describe("News category (e.g. business, technology)."),
+			limit: searchInputShape.limit.describe("Max articles to return.")
+		}
+	}, async (rawArgs) => {
+		try {
+			const args = searchArgsSchema.parse(rawArgs);
+			return ok(normalizeNewsResult(await client.newsSearch({
+				query: args.query,
+				provider: args.provider,
+				source: args.source,
+				from: args.from,
+				to: args.to,
+				language: args.language,
+				category: args.category,
+				limit: args.limit
+			})));
+		} catch (err) {
+			return fail(err);
+		}
+	});
+	register("top_headlines", {
+		description: "Fetch current top headlines for a provider, optionally filtered by category, source, or language.",
+		inputSchema: {
+			provider: providerSchema,
+			category: headlinesInputShape.category.describe("News category (e.g. business, technology)."),
+			source: headlinesInputShape.source.describe("Restrict to a single source/domain."),
+			language: headlinesInputShape.language.describe("ISO-639-1 language code (e.g. en)."),
+			limit: headlinesInputShape.limit.describe("Max headlines to return.")
+		}
+	}, async (rawArgs) => {
+		try {
+			const args = headlinesArgsSchema.parse(rawArgs);
+			return ok(normalizeNewsResult(await client.newsHeadlines({
+				provider: args.provider,
+				category: args.category,
+				source: args.source,
+				language: args.language,
+				limit: args.limit
+			})));
+		} catch (err) {
+			return fail(err);
+		}
+	});
+}
+const SERVER_VERSION = validatePackageVersion((0, node_module.createRequire)(require("url").pathToFileURL(__filename).href)("../package.json").version);
+function createServer(client) {
+	const server = new _modelcontextprotocol_sdk_server_mcp_js.McpServer({
+		name: "news-mcp-server",
+		version: SERVER_VERSION
+	});
+	registerTools(server, client);
+	return server;
+}
+async function startServer(client) {
+	const server = createServer(client ?? createConfiguredClient());
+	try {
+		await server.connect(new _modelcontextprotocol_sdk_server_stdio_js.StdioServerTransport());
+		log("News MCP server running (news_search, top_headlines)");
+		return server;
+	} catch (error) {
+		await server.close().catch(() => void 0);
+		throw error;
+	}
+}
+function isProcessEntrypoint(argvPath, metaUrl) {
+	try {
+		if (!argvPath) return false;
+		return (0, node_url.pathToFileURL)((0, node_fs.realpathSync)(argvPath)).href === (0, node_url.pathToFileURL)((0, node_fs.realpathSync)((0, node_url.fileURLToPath)(metaUrl))).href;
+	} catch {
+		return false;
+	}
+}
+function createConfiguredClient() {
+	const { apiKey, apiUrl } = (0, _alfe_ai_config.resolveConfig)();
+	return new _alfe_ai_agent_api_client.AgentApiClient({
+		apiKey,
+		apiUrl
+	});
+}
+function validatePackageVersion(value) {
+	if (typeof value !== "string" || !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/u.test(value)) throw new Error("news-mcp package version is invalid");
+	return value;
+}
+function log(message) {
+	process.stderr.write(`[news-mcp] ${message}\n`);
+}
+if (isProcessEntrypoint(process.argv[1], require("url").pathToFileURL(__filename).href)) startServer().then((server) => {
+	let shutdownPromise;
+	const shutdown = () => {
+		if (shutdownPromise) return;
+		shutdownPromise = server.close().catch((error) => {
+			log(`Failed to close cleanly: ${safeErrorMessage(error)}`);
+		}).then(() => process.exit(0));
+	};
+	process.once("SIGTERM", shutdown);
+	process.once("SIGINT", shutdown);
+}).catch((error) => {
+	log(`Fatal: ${safeErrorMessage(error)}`);
+	process.exitCode = 1;
+});
+//#endregion
+exports.SERVER_VERSION = SERVER_VERSION;
+exports.createServer = createServer;
+exports.isProcessEntrypoint = isProcessEntrypoint;
+exports.startServer = startServer;

package/dist/server.d.cts

@@ -0,0 +1,53 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+//#region ../agent-api-client/dist/index.d.ts
+
+/** One normalized article. `sentiment` is provider-shaped (APITube supplies it). */
+interface NewsArticle {
+  title: string;
+  url: string;
+  source: string;
+  publishedAt: string;
+  snippet: string;
+  sentiment?: unknown;
+}
+/** Provider-agnostic result — the server normalizes every adapter to this. */
+interface NewsResult {
+  articles: NewsArticle[];
+  provider: string;
+}
+//#endregion
+//#region src/tools.d.ts
+
+/**
+ * The subset of `AgentApiClient` this server needs. Declaring it as an
+ * interface (rather than importing the concrete class) keeps `registerTools`
+ * unit-testable with a stub and avoids constructing a real client in tests.
+ */
+interface NewsClient {
+  newsSearch(params: {
+    query: string;
+    provider?: "apitube" | "newsdata";
+    source?: string;
+    from?: string;
+    to?: string;
+    language?: string;
+    category?: string;
+    limit?: number;
+  }): Promise<NewsResult>;
+  newsHeadlines(params?: {
+    provider?: "apitube" | "newsdata";
+    category?: string;
+    source?: string;
+    language?: string;
+    limit?: number;
+  }): Promise<NewsResult>;
+}
+//#endregion
+//#region src/server.d.ts
+declare const SERVER_VERSION: string;
+declare function createServer(client: NewsClient): McpServer;
+declare function startServer(client?: NewsClient): Promise<McpServer>;
+declare function isProcessEntrypoint(argvPath: string | undefined, metaUrl: string): boolean;
+//#endregion
+export { SERVER_VERSION, createServer, isProcessEntrypoint, startServer };

package/dist/server.d.ts

@@ -1 +1,53 @@
-export {};
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+//#region ../agent-api-client/dist/index.d.ts
+
+/** One normalized article. `sentiment` is provider-shaped (APITube supplies it). */
+interface NewsArticle {
+  title: string;
+  url: string;
+  source: string;
+  publishedAt: string;
+  snippet: string;
+  sentiment?: unknown;
+}
+/** Provider-agnostic result — the server normalizes every adapter to this. */
+interface NewsResult {
+  articles: NewsArticle[];
+  provider: string;
+}
+//#endregion
+//#region src/tools.d.ts
+
+/**
+ * The subset of `AgentApiClient` this server needs. Declaring it as an
+ * interface (rather than importing the concrete class) keeps `registerTools`
+ * unit-testable with a stub and avoids constructing a real client in tests.
+ */
+interface NewsClient {
+  newsSearch(params: {
+    query: string;
+    provider?: "apitube" | "newsdata";
+    source?: string;
+    from?: string;
+    to?: string;
+    language?: string;
+    category?: string;
+    limit?: number;
+  }): Promise<NewsResult>;
+  newsHeadlines(params?: {
+    provider?: "apitube" | "newsdata";
+    category?: string;
+    source?: string;
+    language?: string;
+    limit?: number;
+  }): Promise<NewsResult>;
+}
+//#endregion
+//#region src/server.d.ts
+declare const SERVER_VERSION: string;
+declare function createServer(client: NewsClient): McpServer;
+declare function startServer(client?: NewsClient): Promise<McpServer>;
+declare function isProcessEntrypoint(argvPath: string | undefined, metaUrl: string): boolean;
+//#endregion
+export { SERVER_VERSION, createServer, isProcessEntrypoint, startServer };

package/dist/server.js

@@ -1,39 +1,155 @@
 #!/usr/bin/env node
+import { createRequire } from "node:module";
+import { realpathSync } from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { resolveConfig } from "@alfe.ai/config";
 import { AgentApiClient } from "@alfe.ai/agent-api-client";
 import { z } from "zod";
+//#region src/boundary.ts
+const MAX_QUERY_CHARS = 400;
+const MAX_SOURCE_CHARS = 200;
+const MAX_DATE_CHARS = 40;
+const MAX_LANGUAGE_CHARS = 11;
+const MAX_CATEGORY_CHARS = 60;
+const MAX_TITLE_CHARS = 4096;
+const MAX_URL_CHARS = 16384;
+const MAX_RESULT_SOURCE_CHARS = 1024;
+const MAX_PUBLISHED_AT_CHARS = 128;
+const MAX_SNIPPET_CHARS = 16384;
+const MAX_SENTIMENT_LABEL_CHARS = 128;
+const MAX_ARTICLES = 100;
+const MAX_TOOL_RESULT_BYTES = 2 * 1024 * 1024;
+const newsProviderSchema = z.enum(["apitube", "newsdata"]);
+function boundedInputString(max, label) {
+	return z.string().min(1).max(max).refine((value) => !hasControlCharacters(value), `${label} cannot contain control characters`);
+}
+const baseSearchSchema = z.object({
+	query: boundedInputString(MAX_QUERY_CHARS, "Search query"),
+	provider: newsProviderSchema.default("apitube"),
+	source: boundedInputString(MAX_SOURCE_CHARS, "News source").optional(),
+	from: boundedInputString(MAX_DATE_CHARS, "Start date").optional(),
+	to: boundedInputString(MAX_DATE_CHARS, "End date").optional(),
+	language: boundedInputString(MAX_LANGUAGE_CHARS, "Language").regex(/^[a-z]{2,3}(,[a-z]{2,3}){0,2}$/iu).optional(),
+	category: boundedInputString(MAX_CATEGORY_CHARS, "Category").optional(),
+	limit: z.coerce.number().int().min(1).max(MAX_ARTICLES).optional()
+});
+const searchInputShape = baseSearchSchema.shape;
+const searchArgsSchema = baseSearchSchema.superRefine((value, context) => {
+	if (value.provider !== "newsdata") return;
+	if (value.limit !== void 0 && value.limit > 50) context.addIssue({
+		code: "custom",
+		path: ["limit"],
+		message: "NewsData supports at most 50 results"
+	});
+	for (const field of ["from", "to"]) {
+		const date = value[field];
+		if (date !== void 0 && !isNewsDataDate(date)) context.addIssue({
+			code: "custom",
+			path: [field],
+			message: "NewsData dates must use YYYY-MM-DD"
+		});
+	}
+	if (value.from !== void 0 && value.to !== void 0 && isNewsDataDate(value.from) && isNewsDataDate(value.to) && value.from > value.to) context.addIssue({
+		code: "custom",
+		path: ["to"],
+		message: "End date must not precede start date"
+	});
+});
+const baseHeadlinesSchema = z.object({
+	provider: newsProviderSchema.default("apitube"),
+	category: boundedInputString(MAX_CATEGORY_CHARS, "Category").optional(),
+	source: boundedInputString(MAX_SOURCE_CHARS, "News source").optional(),
+	language: boundedInputString(MAX_LANGUAGE_CHARS, "Language").regex(/^[a-z]{2,3}(,[a-z]{2,3}){0,2}$/iu).optional(),
+	limit: z.coerce.number().int().min(1).max(MAX_ARTICLES).optional()
+});
+const headlinesInputShape = baseHeadlinesSchema.shape;
+const headlinesArgsSchema = baseHeadlinesSchema.superRefine((value, context) => {
+	if (value.provider === "newsdata" && value.limit !== void 0 && value.limit > 50) context.addIssue({
+		code: "custom",
+		path: ["limit"],
+		message: "NewsData supports at most 50 results"
+	});
+});
+const resultString = (max) => z.string().max(max).refine((value) => !hasControlCharacters(value));
+const articleUrlSchema = resultString(MAX_URL_CHARS).refine((value) => {
+	try {
+		const url = new URL(value);
+		return (url.protocol === "https:" || url.protocol === "http:") && !url.username && !url.password;
+	} catch {
+		return false;
+	}
+}, "Article URL must be a safe HTTP(S) URL");
+const sentimentSchema = z.object({
+	score: z.number().min(-1).max(1).optional(),
+	label: resultString(MAX_SENTIMENT_LABEL_CHARS).min(1).optional()
+}).refine((value) => value.score !== void 0 || value.label !== void 0, { message: "Sentiment must contain a score or label" });
+const newsResultSchema = z.object({
+	provider: newsProviderSchema,
+	articles: z.array(z.object({
+		title: resultString(MAX_TITLE_CHARS).min(1),
+		url: articleUrlSchema,
+		source: resultString(MAX_RESULT_SOURCE_CHARS).min(1),
+		publishedAt: resultString(MAX_PUBLISHED_AT_CHARS).min(1).refine((value) => Number.isFinite(Date.parse(value)), "Invalid article timestamp"),
+		snippet: resultString(MAX_SNIPPET_CHARS),
+		sentiment: sentimentSchema.optional()
+	})).max(MAX_ARTICLES)
+});
+function normalizeNewsResult(value) {
+	const result = newsResultSchema.parse(value);
+	const encoded = JSON.stringify(result);
+	if (Buffer.byteLength(encoded, "utf8") > 2097152) throw new Error(`News result exceeds ${String(MAX_TOOL_RESULT_BYTES)} bytes`);
+	return result;
+}
+function encodeToolResult(value) {
+	const encoded = JSON.stringify(value);
+	if (Buffer.byteLength(encoded, "utf8") > 2097152) throw new Error(`News tool result exceeds ${String(MAX_TOOL_RESULT_BYTES)} bytes`);
+	return encoded;
+}
+function safeErrorMessage(error, secrets = []) {
+	let output = (error instanceof Error ? error.message : String(error)).slice(0, 4096).replace(/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/giu, "$1 [REDACTED]").replace(/\b(api[_-]?key|access[_-]?token|refresh[_-]?token|secret|password)\s*[=:]\s*[^\s,;]+/giu, "$1=[REDACTED]").replace(/https?:\/\/[^\s/@:]+:[^\s/@]+@/giu, "https://[REDACTED]@").replace(/\balfe_[A-Za-z0-9_-]{8,}/gu, "[REDACTED]");
+	for (const secret of secrets) if (secret.length >= 4) output = output.split(secret).join("[REDACTED]");
+	return flattenControls(output);
+}
+function isNewsDataDate(value) {
+	if (!/^\d{4}-\d{2}-\d{2}$/u.test(value)) return false;
+	const epoch = Date.parse(`${value}T00:00:00Z`);
+	return Number.isFinite(epoch) && new Date(epoch).toISOString().slice(0, 10) === value;
+}
+function hasControlCharacters(value) {
+	return Array.from(value).some((character) => {
+		const codePoint = character.codePointAt(0) ?? 0;
+		return codePoint < 32 || codePoint === 127;
+	});
+}
+function flattenControls(value) {
+	let output = "";
+	let previousWasControl = false;
+	for (const character of value) {
+		const codePoint = character.codePointAt(0) ?? 0;
+		const isControl = codePoint < 32 || codePoint === 127;
+		if (isControl) {
+			if (!previousWasControl) output += " ";
+		} else output += character;
+		previousWasControl = isControl;
+	}
+	return output;
+}
+//#endregion
 //#region src/tools.ts
-/**
-* MCP tool registration for the News MCP server.
-*
-* Tools:
-*   news_search    → client.newsSearch(...)    (POST /agent/news/search)
-*   top_headlines  → client.newsHeadlines(...)  (POST /agent/news/headlines)
-*
-* Both take a strict zod input schema. `provider` is an ENUM
-* (`apitube | newsdata`) defaulting to `apitube` — never free-text, because a
-* typo'd provider server-side is an unpriceable product. All provider keys and
-* billing live server-side in `services/news`; this server only forwards a
-* typed body via `@alfe.ai/agent-api-client` and normalizes errors.
-*
-* Provider / billing / HTTP errors are surfaced as an `isError` MCP result
-* carrying the error text — never a fake success.
-*/
-const providerSchema = z.enum(["apitube", "newsdata"]).default("apitube").describe("News provider to query. APITube (default) covers 500K+ sources with sentiment.");
+const providerSchema = newsProviderSchema.default("apitube").describe("News provider to query. APITube (default) covers 500K+ sources with sentiment.");
 function ok(data) {
 	return { content: [{
 		type: "text",
-		text: JSON.stringify(data)
+		text: encodeToolResult(data)
 	}] };
 }
 function fail(err) {
-	const message = err instanceof Error ? err.message : String(err);
 	return {
 		content: [{
 			type: "text",
-			text: JSON.stringify({ error: message })
+			text: encodeToolResult({ error: safeErrorMessage(err) })
 		}],
 		isError: true
 	};
@@ -43,18 +159,19 @@ function registerTools(server, client) {
 	register("news_search", {
 		description: "Search recent news across a broad provider (APITube / NewsData). Returns normalized articles with title, url, source, publishedAt, snippet, and (APITube) sentiment.",
 		inputSchema: {
-			query: z.string().min(1).describe("Search query (keywords, entities, topics)."),
+			query: searchInputShape.query.describe("Search query (keywords, entities, topics)."),
 			provider: providerSchema,
-			source: z.string().optional().describe("Restrict to a single source/domain (e.g. reuters.com)."),
-			from: z.string().optional().describe("Earliest publish date, ISO-8601 (e.g. 2026-07-01)."),
-			to: z.string().optional().describe("Latest publish date, ISO-8601."),
-			language: z.string().optional().describe("ISO-639-1 language code (e.g. en)."),
-			category: z.string().optional().describe("News category (e.g. business, technology)."),
-			limit: z.coerce.number().int().positive().max(100).optional().describe("Max articles to return.")
+			source: searchInputShape.source.describe("Restrict to a single source/domain (e.g. reuters.com)."),
+			from: searchInputShape.from.describe("Earliest publish date, ISO-8601 (e.g. 2026-07-01)."),
+			to: searchInputShape.to.describe("Latest publish date, ISO-8601."),
+			language: searchInputShape.language.describe("ISO-639-1 language code (e.g. en)."),
+			category: searchInputShape.category.describe("News category (e.g. business, technology)."),
+			limit: searchInputShape.limit.describe("Max articles to return.")
 		}
-	}, async (args) => {
+	}, async (rawArgs) => {
 		try {
-			return ok(await client.newsSearch({
+			const args = searchArgsSchema.parse(rawArgs);
+			return ok(normalizeNewsResult(await client.newsSearch({
 				query: args.query,
 				provider: args.provider,
 				source: args.source,
@@ -63,7 +180,7 @@ function registerTools(server, client) {
 				language: args.language,
 				category: args.category,
 				limit: args.limit
-			}));
+			})));
 		} catch (err) {
 			return fail(err);
 		}
@@ -72,68 +189,81 @@ function registerTools(server, client) {
 		description: "Fetch current top headlines for a provider, optionally filtered by category, source, or language.",
 		inputSchema: {
 			provider: providerSchema,
-			category: z.string().optional().describe("News category (e.g. business, technology)."),
-			source: z.string().optional().describe("Restrict to a single source/domain."),
-			language: z.string().optional().describe("ISO-639-1 language code (e.g. en)."),
-			limit: z.coerce.number().int().positive().max(100).optional().describe("Max headlines to return.")
+			category: headlinesInputShape.category.describe("News category (e.g. business, technology)."),
+			source: headlinesInputShape.source.describe("Restrict to a single source/domain."),
+			language: headlinesInputShape.language.describe("ISO-639-1 language code (e.g. en)."),
+			limit: headlinesInputShape.limit.describe("Max headlines to return.")
 		}
-	}, async (args) => {
+	}, async (rawArgs) => {
 		try {
-			return ok(await client.newsHeadlines({
+			const args = headlinesArgsSchema.parse(rawArgs);
+			return ok(normalizeNewsResult(await client.newsHeadlines({
 				provider: args.provider,
 				category: args.category,
 				source: args.source,
 				language: args.language,
 				limit: args.limit
-			}));
+			})));
 		} catch (err) {
 			return fail(err);
 		}
 	});
 }
-//#endregion
-//#region src/server.ts
-/**
-* News MCP Server
-*
-* Standalone stdio MCP server for broad news search (APITube / NewsData behind
-* a `provider` arg). Runtime-agnostic — spawned via `npx -y @alfe.ai/news-mcp`
-* from an integration manifest, speaks MCP over stdio, so it runs under any
-* runtime that can spawn `npx`.
-*
-* Architecture:
-*   Agent runtime ←(stdio/MCP)→ this server ←(HTTPS)→ services/news (metered)
-*
-* No provider credentials live on the box. At startup we self-fetch the agent's
-* `{ apiKey, apiUrl }` via `resolveConfig()` and call the metered `services/news`
-* Lambda through `AgentApiClient`. Provider keys + billing are server-side; the
-* Lambda is the metering chokepoint.
-*/
-function log(msg) {
-	process.stderr.write(`[news-mcp] ${msg}\n`);
-}
-async function main() {
-	const { apiKey, apiUrl } = resolveConfig();
-	const client = new AgentApiClient({
-		apiKey,
-		apiUrl
-	});
+const SERVER_VERSION = validatePackageVersion(createRequire(import.meta.url)("../package.json").version);
+function createServer(client) {
 	const server = new McpServer({
 		name: "news-mcp-server",
-		version: "0.1.0"
+		version: SERVER_VERSION
 	});
 	registerTools(server, client);
+	return server;
+}
+async function startServer(client) {
+	const server = createServer(client ?? createConfiguredClient());
+	try {
+		await server.connect(new StdioServerTransport());
+		log("News MCP server running (news_search, top_headlines)");
+		return server;
+	} catch (error) {
+		await server.close().catch(() => void 0);
+		throw error;
+	}
+}
+function isProcessEntrypoint(argvPath, metaUrl) {
+	try {
+		if (!argvPath) return false;
+		return pathToFileURL(realpathSync(argvPath)).href === pathToFileURL(realpathSync(fileURLToPath(metaUrl))).href;
+	} catch {
+		return false;
+	}
+}
+function createConfiguredClient() {
+	const { apiKey, apiUrl } = resolveConfig();
+	return new AgentApiClient({
+		apiKey,
+		apiUrl
+	});
+}
+function validatePackageVersion(value) {
+	if (typeof value !== "string" || !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/u.test(value)) throw new Error("news-mcp package version is invalid");
+	return value;
+}
+function log(message) {
+	process.stderr.write(`[news-mcp] ${message}\n`);
+}
+if (isProcessEntrypoint(process.argv[1], import.meta.url)) startServer().then((server) => {
+	let shutdownPromise;
 	const shutdown = () => {
-		process.exit(0);
+		if (shutdownPromise) return;
+		shutdownPromise = server.close().catch((error) => {
+			log(`Failed to close cleanly: ${safeErrorMessage(error)}`);
+		}).then(() => process.exit(0));
 	};
-	for (const signal of ["SIGTERM", "SIGINT"]) process.on(signal, shutdown);
-	const transport = new StdioServerTransport();
-	await server.connect(transport);
-	log("News MCP server running (news_search, top_headlines)");
-}
-main().catch((err) => {
-	log(`Fatal: ${err instanceof Error ? err.message : String(err)}`);
-	process.exit(1);
+	process.once("SIGTERM", shutdown);
+	process.once("SIGINT", shutdown);
+}).catch((error) => {
+	log(`Fatal: ${safeErrorMessage(error)}`);
+	process.exitCode = 1;
 });
 //#endregion
-export {};
+export { SERVER_VERSION, createServer, isProcessEntrypoint, startServer };

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@alfe.ai/news-mcp",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "News MCP server — broad news search (APITube / NewsData) with sentiment, metered server-side via Alfe",
   "type": "module",
   "main": "./dist/server.js",
+  "types": "./dist/server.d.ts",
   "bin": {
     "news-mcp-server": "./dist/server.js"
   },
   "exports": {
     ".": {
       "types": "./dist/server.d.ts",
+      "require": "./dist/server.cjs",
       "import": "./dist/server.js"
     }
   },
@@ -19,8 +21,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.0.5",
-    "@alfe.ai/agent-api-client": "0.14.0",
-    "@alfe.ai/config": "0.4.0"
+    "@alfe.ai/agent-api-client": "0.16.0",
+    "@alfe.ai/config": "0.4.1"
   },
   "license": "UNLICENSED",
   "homepage": "https://alfe.ai",