feat(news-search): premium full-text article search across worker, SDKs, MCP

New /api/premium/news/search (Tier 1, 1 credit) plus matching SDK and
MCP support so AI agents can ask "what happened with X in March?" in
one paid call instead of paginating the free /news endpoint themselves.

Worker (worker/src/news-search.ts):
  - Tokenization strips stop words and tokens shorter than 2 chars
  - Relevance score blends title hits (weight 3), snippet hits (weight 1),
    and a recency boost in [0, 0.3] capped at score 1.0
  - Filters: q (free text), from / to (YYYY-MM-DD UTC), provider
    (substring match against source name and sourceDomain), category
    (substring match), limit (1-100, default 25)
  - Browse mode: omit q to get the latest filtered articles in
    publishedAt desc with relevance 1
  - Validation rejects malformed dates and from > to with 400

SDKs:
  Python 1.7.0  tf.news_search(q=, from_date=, to_date=, provider=, category=, limit=)
  TypeScript 1.6.0  tf.newsSearch({ q, from, to, provider, category, limit })
  TS exports NewsSearchResponse + NewsSearchResultItem

MCP (1.2.0):
  news_search tool with formatted text output (rank, title, source,
  url, date, relevance, matched terms, snippet)

Tests: 15 new vitest cases for tokenization, scoring, filters, browse
mode, validation, and empty corpus. Total worker tests: 95.

Also restored proper X_ACCESS_TOKEN / GITHUB_TOKEN field names in
worker/src/payments.test.ts (an over-aggressive rename had renamed
them in a prior commit; runtime tests passed but tsc was unhappy).

Updated /api/meta, public/llms.txt, /developers/agent-payments,
CLAUDE.md, and all three READMEs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: RipperMercs

CLAUDE.md

@@ -43,6 +43,8 @@ tensorfeed/
       watches.test.ts Vitest coverage for predicate edge transitions, SSRF guard, dispatch end-to-end
       agents-enriched.ts  Premium enriched agents directory: joins catalog with status, news, activity, pricing; trending score; sort/filter
       agents-enriched.test.ts  Vitest coverage for enrichment join logic, filters, sort, scoring
+      news-search.ts  Premium news search: tokenization, relevance scoring (title weight 3, snippet 1, recency boost), date/provider/category filters
+      news-search.test.ts  Vitest coverage for query mode, filters, browse mode, validation
       podcasts.ts     Podcast feed polling
       trending.ts     Trending GitHub repos
       twitter.ts      X/Twitter auto-posting
@@ -205,6 +207,7 @@ All mounted under `https://tensorfeed.ai/api/*` via the Worker.
 - `/api/premium/watches` (GET): List watches owned by the bearer token. Free.
 - `/api/premium/watches/{id}` (GET|DELETE): Read or remove an owned watch. Free.
 - `/api/premium/agents/directory?category=&status=&open_source=&capability=&sort=&limit=`: Tier 1, 1 credit. Enriched agents catalog joined with live status, recent news (count + top 3), agent traffic, flagship pricing, and a derived trending_score. Sort options: trending, alphabetical, status, price_low, price_high, news_count.
+- `/api/premium/news/search?q=&from=&to=&provider=&category=&limit=`: Tier 1, 1 credit. Full-text search over the article corpus with relevance scoring (term hits weighted 3 in title, 1 in snippet, plus recency boost) and date/provider/category filters. Default limit 25, max 100.
 
 **Admin (auth-gated via `?key=ENVIRONMENT`):**
 - `/api/admin/usage?date=YYYY-MM-DD`: Daily revenue + usage rollup

mcp-server/README.md

@@ -26,6 +26,7 @@ These tools require a `TENSORFEED_TOKEN` env var. Buy credits at [tensorfeed.ai/
 | `status_uptime` | 1 credit | Daily uptime % for one provider with incident-day list |
 | `history_compare` | 1 credit | Diff two daily snapshots: added, removed, changed entries |
 | `premium_agents_directory` | 1 credit | Enriched agents catalog with live status, news, traffic, trending_score |
+| `news_search` | 1 credit | Full-text news search with date/provider/category filters and relevance scoring |
 | `list_watches` | Free | List active webhook watches owned by the token |
 | `create_price_watch` | 1 credit | Register a webhook watch on a model price change |
 | `create_status_watch` | 1 credit | Register a webhook watch on a service status transition |

mcp-server/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tensorfeed/mcp-server",
-  "version": "1.1.0",
-  "description": "MCP server for TensorFeed.ai - AI news, status, model data, and premium endpoints (routing, history series, webhook watches, enriched directory) for AI agents",
+  "version": "1.2.0",
+  "description": "MCP server for TensorFeed.ai - AI news, status, model data, and premium endpoints (routing, history series, news search, webhook watches, enriched directory) for AI agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",

mcp-server/src/index.ts

@@ -5,7 +5,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod';
 
 const API_BASE = 'https://tensorfeed.ai/api';
-const SDK_VERSION = '1.1.0';
+const SDK_VERSION = '1.2.0';
 
 // ── API helpers ─────────────────────────────────────────────────────
 
@@ -550,6 +550,54 @@ server.tool(
   },
 );
 
+// ── Tool: news_search (1 credit) ────────────────────────────────────
+
+server.tool(
+  'news_search',
+  'Full-text search over the TensorFeed news article corpus with optional date range, provider, and category filters. Relevance scoring with recency boost. Costs 1 credit.',
+  {
+    q: z.string().optional().describe('Free-text query, e.g. "claude opus pricing". Omit to browse latest filtered articles.'),
+    from: z.string().optional().describe('Start date YYYY-MM-DD UTC (inclusive)'),
+    to: z.string().optional().describe('End date YYYY-MM-DD UTC (inclusive end-of-day)'),
+    provider: z.string().optional().describe('Substring match against source name and domain (e.g. "anthropic", "openai", "techcrunch")'),
+    category: z.string().optional().describe('Substring match against article categories'),
+    limit: z.number().min(1).max(100).optional().describe('Max results (default 25, max 100)'),
+  },
+  async ({ q, from, to, provider, category, limit }) => {
+    const params = new URLSearchParams();
+    if (q) params.set('q', q);
+    if (from) params.set('from', from);
+    if (to) params.set('to', to);
+    if (provider) params.set('provider', provider);
+    if (category) params.set('category', category);
+    if (typeof limit === 'number') params.set('limit', String(limit));
+    const data = (await fetchJSON(`/premium/news/search?${params}`, { auth: true })) as {
+      query: string | null;
+      matched: number;
+      returned: number;
+      results: { title: string; url: string; source: string; published_at: string; relevance: number; matched_terms: string[]; snippet: string }[];
+      billing?: { credits_remaining?: number };
+    };
+    if (data.results.length === 0) {
+      return { content: [{ type: 'text' as const, text: `No articles matched. (matched: ${data.matched})` }] };
+    }
+    const list = data.results
+      .map(
+        (r, i) =>
+          `${i + 1}. ${r.title} (${r.source})\n   ${r.url}\n   ${r.published_at} | relevance ${r.relevance}${r.matched_terms.length ? ` | terms: ${r.matched_terms.join(', ')}` : ''}\n   ${r.snippet}`,
+      )
+      .join('\n\n');
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `${data.returned} of ${data.matched} matches${data.query ? ` for "${data.query}"` : ''}:\n\n${list}\n\nCredits remaining: ${data.billing?.credits_remaining ?? '?'}`,
+        },
+      ],
+    };
+  },
+);
+
 // ── Tool: list_watches ──────────────────────────────────────────────
 
 server.tool(

public/llms.txt

@@ -56,6 +56,7 @@ TensorFeed accepts USDC on Base as the sole payment method for premium endpoints
 - [Premium History Compare](https://tensorfeed.ai/api/premium/history/compare): Tier 1, 1 credit per call. Diff between two daily snapshots: added, removed, and changed entries with deltas. Params: `?from=YYYY-MM-DD&to=YYYY-MM-DD&type=pricing|benchmarks`.
 - [Premium Watches](https://tensorfeed.ai/api/premium/watches): Tier 1, 1 credit per registration. Webhook alerts for price changes (`{ type: "price", model, field: "inputPrice"|"outputPrice"|"blended", op: "lt"|"gt"|"changes", threshold? }`) or service status transitions (`{ type: "status", provider, op: "becomes"|"changes", value? }`). POST `{ spec, callback_url, secret? }` to register, GET to list, GET/DELETE on `/api/premium/watches/{id}` for individual control. Each watch lives 90 days, fires up to 100 times by default, delivers a signed POST to the callback URL with `X-TensorFeed-Signature: sha256=<hex>` and an `X-TensorFeed-Watch-Id` header. Listing and per-watch read/delete require the bearer token but cost no credits.
 - [Premium Agents Directory](https://tensorfeed.ai/api/premium/agents/directory): Tier 1, 1 credit per call. The agents catalog joined with live status, recent news count + top 3 articles, agent traffic stats, flagship pricing, and a derived `trending_score` (0-100). Server-side filter (`?category=&status=&open_source=&capability=`) and sort (`?sort=trending|alphabetical|status|price_low|price_high|news_count`). Default `limit=50`, max 100.
+- [Premium News Search](https://tensorfeed.ai/api/premium/news/search): Tier 1, 1 credit per call. Full-text search over the news corpus with relevance scoring (term hits in title weighted 3, snippet 1, plus recency boost). Filters: `?q=&from=YYYY-MM-DD&to=YYYY-MM-DD&provider=&category=&limit=`. Omit `q` to browse latest filtered articles in publishedAt desc. Stop words and short tokens are stripped. Each result includes title, url, source, snippet, published_at, relevance, and matched_terms. Default `limit=25`, max 100.
 
 **Recommended flow:** POST `/api/payment/buy-credits`, send USDC, POST `/api/payment/confirm`, then use the returned token for all premium calls. **Fallback (x402):** call any `/api/premium/*` endpoint without auth to receive a 402 response with payment instructions; send USDC and retry with `X-Payment-Tx: <txHash>` header.
 

sdk/javascript/README.md

@@ -199,6 +199,7 @@ try {
 | `tf.getWatch(id)` | Free | Read one watch including fire_count and last_fired_at |
 | `tf.deleteWatch(id)` | Free | Remove an owned watch |
 | `tf.premiumAgentsDirectory({ category?, status?, sort?, limit?, ... })` | 1 credit | Enriched directory: status, news, traffic, pricing, trending_score per agent |
+| `tf.newsSearch({ q?, from?, to?, provider?, category?, limit? })` | 1 credit | Full-text news search with date/provider filters, relevance scoring, recency boost |
 
 ## Wallet & Trust
 

sdk/javascript/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tensorfeed",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "JavaScript/TypeScript SDK for the TensorFeed.ai API: AI news, status, model pricing, benchmarks, premium history series, webhook watches, and agent-payable premium routing (USDC on Base)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

sdk/javascript/src/index.ts

@@ -10,7 +10,7 @@
  */
 
 const DEFAULT_BASE_URL = 'https://tensorfeed.ai/api';
-const DEFAULT_USER_AGENT = 'TensorFeed-SDK-JS/1.5';
+const DEFAULT_USER_AGENT = 'TensorFeed-SDK-JS/1.6';
 
 // ── Error types ─────────────────────────────────────────────────────
 
@@ -421,6 +421,29 @@ export type AgentsDirectorySort =
   | 'price_high'
   | 'news_count';
 
+export interface NewsSearchResultItem {
+  title: string;
+  url: string;
+  source: string;
+  source_domain: string;
+  snippet: string;
+  categories: string[];
+  published_at: string;
+  relevance: number;
+  matched_terms: string[];
+}
+
+export interface NewsSearchResponse {
+  ok: boolean;
+  query: string | null;
+  filters: { from?: string; to?: string; provider?: string; category?: string };
+  total_corpus: number;
+  matched: number;
+  returned: number;
+  results: NewsSearchResultItem[];
+  billing?: { credits_charged: number; credits_remaining?: number };
+}
+
 export interface PremiumAgentsDirectoryResponse {
   ok: boolean;
   source: 'tensorfeed.ai';
@@ -955,6 +978,40 @@ export class TensorFeed {
       requireToken: true,
     });
   }
+
+  // ── Paid: news search (1 credit per call) ──────────────────────
+
+  /**
+   * Full-text search over the TensorFeed news article corpus with date
+   * range, provider, and category filters. Relevance scoring blends term
+   * hits in title (weight 3) and snippet (weight 1) plus a recency boost.
+   * Costs 1 credit. Stop words and tokens shorter than 2 chars are
+   * stripped from the query.
+   *
+   * @throws Error if no token is set
+   * @throws PaymentRequired if the token has insufficient credits
+   */
+  async newsSearch(options?: {
+    q?: string;
+    from?: string;
+    to?: string;
+    provider?: string;
+    category?: string;
+    limit?: number;
+  }): Promise<NewsSearchResponse> {
+    this.requireToken('newsSearch');
+    return this.request<NewsSearchResponse>('GET', '/premium/news/search', {
+      params: {
+        q: options?.q,
+        from: options?.from,
+        to: options?.to,
+        provider: options?.provider,
+        category: options?.category,
+        limit: options?.limit,
+      },
+      requireToken: true,
+    });
+  }
 }
 
 export default TensorFeed;

sdk/python/README.md

@@ -221,6 +221,7 @@ except TensorFeedError as e:
 | `tf.get_watch(watch_id)` | Free | Read one watch including fire_count and last_fired_at |
 | `tf.delete_watch(watch_id)` | Free | Remove an owned watch |
 | `tf.premium_agents_directory(category=, status=, sort=, limit=, ...)` | 1 credit | Enriched directory: status, news, traffic, pricing, trending_score per agent |
+| `tf.news_search(q=, from_date=, to_date=, provider=, category=, limit=)` | 1 credit | Full-text news search with date/provider filters, relevance scoring, recency boost |
 
 ### Auto-send (requires `tensorfeed[web3]`)
 

sdk/python/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tensorfeed"
-version = "1.6.0"
+version = "1.7.0"
 description = "Python SDK for the TensorFeed.ai API: AI news, status, model pricing, premium routing + history series + webhook watches, agent payments via USDC on Base (optional web3 auto-send)"
 readme = "README.md"
 license = "MIT"