webdata-tools-mcp 0.1.0 → 0.2.0

package/README.md

@@ -1,5 +1,11 @@
 # webdata-tools-mcp
 
+[![npm](https://img.shields.io/npm/v/webdata-tools-mcp)](https://www.npmjs.com/package/webdata-tools-mcp)
+[![CI](https://github.com/tacps126/webdata-tools-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/tacps126/webdata-tools-mcp/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[Smithery](https://smithery.ai/servers/tacps126/webdata-tools-mcp)
+[![webdata-tools-mcp MCP server](https://glama.ai/mcp/servers/tacps126/webdata-tools-mcp/badges/score.svg)](https://glama.ai/mcp/servers/tacps126/webdata-tools-mcp)
+
 An [MCP](https://modelcontextprotocol.io) server that gives AI agents ten web-data tools: job
 postings, hiring signals, Google News, Trustpilot and app-store reviews, Reddit mentions, website
 contacts, German property listings and Shopify products.
@@ -24,6 +30,10 @@ anywhere except Apify.
 | `get_shopify_products` | Prices, discounts, stock, variants from Shopify stores | $1 / 1,000 products | [shopify-products](https://apify.com/tacps126/shopify-products) |
 
 Every tool also takes an optional `extra_input` object for any other field the Actor documents.
+Every result comes back as text and as structured content (`tool`, `count`, `shown`, `truncated`,
+`items`), and every tool is marked read-only, so clients can run it without asking.
+
+More about the tools: <https://tacps126.github.io/mcp.html>
 
 ## Setup
 
@@ -60,6 +70,14 @@ Requires Node.js 18 or newer.
 - "Find news from the last 7 days about open-source LLM licensing, with the real publisher links."
 - "Get contact emails for these 20 agency websites." (use only for lawful business outreach)
 
+## Settings
+
+| Environment variable | Default | Meaning |
+|---|---|---|
+| `APIFY_TOKEN` | required | Your Apify API token |
+| `WEBDATA_MAX_CHARGE_USD` | `0.5` | Spend cap per tool call; Apify stops the run when it is reached |
+| `WEBDATA_TIMEOUT_SECS` | `150` | How long one call may run (30 to 300) |
+
 ## Cost safety
 
 - Every call is capped at **$0.50** of Apify spend (`WEBDATA_MAX_CHARGE_USD` changes it). Apify stops

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webdata-tools-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "mcpName": "io.github.tacps126/webdata-tools-mcp",
   "description": "MCP server for AI agents: job postings, hiring signals, Google News, Trustpilot and app reviews, Reddit mentions, website contacts, German real estate and Shopify products. Runs ready-made Apify Actors with your own Apify token.",
   "type": "module",
@@ -10,6 +10,7 @@
   "main": "src/index.js",
   "files": [
     "src",
+    "icon.png",
     "README.md",
     "LICENSE"
   ],

package/src/server.js

@@ -1,10 +1,15 @@
 // MCP server definition: one typed tool per Apify Actor.
 
+import { readFileSync } from 'node:fs';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
 import { ApifyError, runActorSync } from './apify.js';
 import { extraInput, TOOLS } from './tools.js';
 
+const { version: VERSION } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+
 const DEFAULT_MAX_CHARGE_USD = 0.5;
+const DEFAULT_TIMEOUT_SECS = 150;
 const MAX_TEXT_CHARS = 60_000; // keep one tool result inside a sane context budget
 const MAX_FIELD_CHARS = 600;
 
@@ -20,8 +25,26 @@ export function shrink(value) {
   return value;
 }
 
-/** Format dataset items as the text an agent reads, dropping rows if the result is too big. */
-export function formatResult(tool, items) {
+/** Shape of every successful tool result (also advertised as the tool's output schema). */
+export const outputShape = {
+  tool: z.string().describe('Name of the tool that produced the result.'),
+  count: z.number().int().describe('Number of records the Actor returned.'),
+  shown: z.number().int().describe('Number of records included in `items` (can be lower than count when the result is long).'),
+  truncated: z.boolean().describe('True when records were left out to keep the result short; ask for fewer items.'),
+  items: z.array(z.record(z.string(), z.unknown())).describe('The records. Long text fields are shortened to 600 characters.'),
+};
+
+/** MCP annotations: every tool only reads public web data, so it is read-only and repeatable. */
+export const annotationsOf = (tool) => ({
+  title: tool.title,
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: true,
+});
+
+/** Turn dataset items into the text an agent reads plus the structured result, dropping rows if too big. */
+export function buildResult(tool, items) {
   const rows = items.map(shrink);
   let kept = rows.length;
   let body = JSON.stringify(rows, null, 1);
@@ -29,16 +52,23 @@ export function formatResult(tool, items) {
     kept = Math.max(1, Math.floor(kept * 0.7));
     body = JSON.stringify(rows.slice(0, kept), null, 1);
   }
-  const note =
-    kept < rows.length
-      ? ` Showing the first ${kept} of ${rows.length} (output size limit); ask for fewer items.`
-      : '';
-  return `${tool.title}: ${rows.length} result(s).${note}\n${body}`;
+  const truncated = kept < rows.length;
+  const note = truncated
+    ? ` Showing the first ${kept} of ${rows.length} (output size limit); ask for fewer items.`
+    : '';
+  return {
+    text: `${tool.title}: ${rows.length} result(s).${note}\n${body}`,
+    structured: { tool: tool.name, count: rows.length, shown: kept, truncated, items: rows.slice(0, kept) },
+  };
 }
 
+/** Same as buildResult but only the text (kept for callers that do not use structured output). */
+export const formatResult = (tool, items) => buildResult(tool, items).text;
+
 export function buildServer({ env = process.env, fetchImpl = fetch } = {}) {
-  const server = new McpServer({ name: 'webdata-tools-mcp', version: '0.1.0' });
+  const server = new McpServer({ name: 'webdata-tools-mcp', version: VERSION });
   const maxCharge = Number(env.WEBDATA_MAX_CHARGE_USD) || DEFAULT_MAX_CHARGE_USD;
+  const timeoutSecs = Math.min(300, Math.max(30, Number(env.WEBDATA_TIMEOUT_SECS) || DEFAULT_TIMEOUT_SECS));
 
   for (const tool of TOOLS) {
     server.registerTool(
@@ -47,7 +77,8 @@ export function buildServer({ env = process.env, fetchImpl = fetch } = {}) {
         title: tool.title,
         description: `${tool.description} Runs the Apify Actor ${tool.actor} on your Apify account (${tool.price}; spend per call is capped at $${maxCharge}).`,
         inputSchema: { ...tool.shape, extra_input: extraInput },
-        annotations: { readOnlyHint: true, openWorldHint: true },
+        outputSchema: outputShape,
+        annotations: annotationsOf(tool),
       },
       async (args) => {
         const problem = tool.check?.(args);
@@ -59,9 +90,11 @@ export function buildServer({ env = process.env, fetchImpl = fetch } = {}) {
             limit: tool.limit(args),
             token: env.APIFY_TOKEN,
             maxChargeUsd: maxCharge,
+            timeoutSecs,
             fetchImpl,
           });
-          return { content: [{ type: 'text', text: formatResult(tool, items) }] };
+          const { text, structured } = buildResult(tool, items);
+          return { content: [{ type: 'text', text }], structuredContent: structured };
         } catch (err) {
           const text = err instanceof ApifyError ? err.message : `Unexpected error: ${err.message}`;
           return { isError: true, content: [{ type: 'text', text }] };

package/src/tools.js

@@ -131,7 +131,7 @@ export const TOOLS = [
       location: z.string().optional().describe('City, state, postcode or "Remote". Empty = whole country.'),
       country: z.enum(['us', 'uk', 'ca', 'au', 'ie', 'de', 'fr', 'nl', 'sg']).default('us').describe('Indeed country site.'),
       date_posted_days: z.enum(['1', '3', '7', '14']).optional().describe('Only jobs posted in the last N days.'),
-      job_type: z.enum(['fulltime', 'parttime', 'contract', 'temporary', 'internship']).optional(),
+      job_type: z.enum(['fulltime', 'parttime', 'contract', 'temporary', 'internship']).optional().describe('Only this employment type.'),
       max_items: maxItems(30),
     },
     map: (a) =>
@@ -155,9 +155,9 @@ export const TOOLS = [
     shape: {
       companies: strings('Company domains or Trustpilot URLs, e.g. "apify.com".'),
       star_ratings: z.array(z.enum(['1', '2', '3', '4', '5'])).optional().describe('Only these ratings, e.g. ["1","2"] for complaints.'),
-      sort: z.enum(['recency', 'relevance']).default('recency'),
+      sort: z.enum(['recency', 'relevance']).default('recency').describe('Newest reviews first (recency) or most relevant first.'),
       search: z.string().optional().describe('Only reviews containing this text.'),
-      date_period: z.enum(['last30days', 'last3months', 'last6months']).optional(),
+      date_period: z.enum(['last30days', 'last3months', 'last6months']).optional().describe('Only reviews from this period.'),
       max_reviews: maxItems(50),
     },
     map: (a) =>
@@ -204,9 +204,9 @@ export const TOOLS = [
     shape: {
       keywords: z.array(z.string()).optional().describe('Search all of Reddit; "exact phrase" works.'),
       subreddits: z.array(z.string()).optional().describe('Subreddit names, e.g. ["webscraping"].'),
-      sort: z.enum(['new', 'hot', 'top', 'relevance']).default('new'),
-      time: z.enum(['hour', 'day', 'week', 'month', 'year', 'all']).default('week'),
-      include_comments: z.boolean().default(false),
+      sort: z.enum(['new', 'hot', 'top', 'relevance']).default('new').describe('Result order.'),
+      time: z.enum(['hour', 'day', 'week', 'month', 'year', 'all']).default('week').describe('Time window for keyword searches.'),
+      include_comments: z.boolean().default(false).describe('Also return comments of the matched posts (more results, higher cost).'),
       max_items: maxItems(50),
     },
     check: (a) =>
@@ -233,7 +233,7 @@ export const TOOLS = [
       'Finds business emails, phone numbers, addresses and social profiles (LinkedIn, X, Facebook, Instagram, YouTube) on any list of websites; it visits the contact and about pages itself. Use only for lawful business outreach (GDPR / CAN-SPAM).',
     shape: {
       websites: strings('Website addresses or domains, e.g. "apify.com".'),
-      max_pages_per_site: z.number().int().min(1).max(20).default(5),
+      max_pages_per_site: z.number().int().min(1).max(20).default(5).describe('Pages read per website; contact, imprint and about pages are picked first.'),
       require_email: z.boolean().default(false).describe('Drop sites where no email was found.'),
       max_items: maxItems(50, 1000),
     },
@@ -255,12 +255,12 @@ export const TOOLS = [
       'Apartments and houses for rent or sale in Germany: price, rent, area, rooms, address with coordinates, energy class, features, agent, photos and dates. Germany only.',
     shape: {
       locations: strings('Cities, districts or regions in plain words, e.g. ["Berlin","München Schwabing"].'),
-      offer_type: z.enum(['rent', 'buy']).default('rent'),
-      property_type: z.enum(['apartment', 'house']).default('apartment'),
-      min_price: z.number().optional(),
-      max_price: z.number().optional(),
+      offer_type: z.enum(['rent', 'buy']).default('rent').describe('Rent or buy listings.'),
+      property_type: z.enum(['apartment', 'house']).default('apartment').describe('Apartments or houses.'),
+      min_price: z.number().optional().describe('Minimum price in EUR (monthly rent or purchase price).'),
+      max_price: z.number().optional().describe('Maximum price in EUR (monthly rent or purchase price).'),
       min_area: z.number().optional().describe('Minimum area in m2.'),
-      min_rooms: z.number().optional(),
+      min_rooms: z.number().optional().describe('Minimum number of rooms.'),
       max_items: maxItems(50),
     },
     map: (a) =>
@@ -286,8 +286,8 @@ export const TOOLS = [
     shape: {
       stores: strings('Store domains, collection links or product links, e.g. "allbirds.com".'),
       keywords: z.array(z.string()).optional().describe('Only products matching any of these words.'),
-      only_on_sale: z.boolean().default(false),
-      only_available: z.boolean().default(false),
+      only_on_sale: z.boolean().default(false).describe('Only products with a sale price.'),
+      only_available: z.boolean().default(false).describe('Only products that are in stock.'),
       max_items: maxItems(100, 1000),
     },
     map: (a) =>