webdata-tools-mcp 0.1.0 → 0.4.0

package/README.md

@@ -1,8 +1,14 @@
 # webdata-tools-mcp
 
-An [MCP](https://modelcontextprotocol.io) server that gives AI agents ten web-data tools: job
+[![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 eleven web-data tools: job
 postings, hiring signals, Google News, Trustpilot and app-store reviews, Reddit mentions, website
-contacts, German property listings and Shopify products.
+contacts, German and Austrian property listings, Shopify products and trade-show exhibitor lists.
 
 Each tool runs a ready-made [Apify](https://apify.com/tacps126) Actor and returns clean JSON. You
 pay Apify per result (about $1–3 per 1,000 results); there is no subscription and nothing is sent
@@ -20,10 +26,15 @@ anywhere except Apify.
 | `get_app_reviews` | App Store and Google Play reviews | $0.20 / 1,000 reviews | [app-reviews](https://apify.com/tacps126/app-reviews) |
 | `search_reddit` | Reddit posts and comments by keyword or subreddit | $1 / 1,000 items | [reddit-monitor](https://apify.com/tacps126/reddit-monitor) |
 | `find_website_contacts` | Emails, phones, socials from websites | $2 / 1,000 sites with contacts | [contact-details](https://apify.com/tacps126/contact-details) |
-| `search_german_property_listings` | Rent/buy listings in Germany (ImmoScout24) | $1 / 1,000 listings | [immobilienscout24-scraper](https://apify.com/tacps126/immobilienscout24-scraper) |
+| `search_german_property_listings` | Rent/buy listings in Germany and Austria (ImmoScout24) | $1 / 1,000 listings | [immobilienscout24-scraper](https://apify.com/tacps126/immobilienscout24-scraper) |
 | `get_shopify_products` | Prices, discounts, stock, variants from Shopify stores | $1 / 1,000 products | [shopify-products](https://apify.com/tacps126/shopify-products) |
+| `get_trade_show_exhibitors` | Trade-show exhibitors: booth, email, phone, website, address (76 shows or any supported exhibitor-list link) | $2 / 1,000 exhibitors | [exhibition-scraper](https://apify.com/tacps126/exhibition-scraper) |
 
 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 +71,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,8 +1,8 @@
 {
   "name": "webdata-tools-mcp",
-  "version": "0.1.0",
+  "version": "0.4.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.",
+  "description": "MCP server for AI agents: job postings, hiring signals, Google News, Trustpilot and app reviews, Reddit mentions, website contacts, German real estate, Shopify products and trade-show exhibitor lists. Runs ready-made Apify Actors with your own Apify token.",
   "type": "module",
   "bin": {
     "webdata-tools-mcp": "src/index.js"
@@ -10,6 +10,7 @@
   "main": "src/index.js",
   "files": [
     "src",
+    "icon.png",
     "README.md",
     "LICENSE"
   ],
@@ -27,7 +28,9 @@
     "google-news",
     "trustpilot",
     "reviews",
-    "lead-generation"
+    "lead-generation",
+    "trade-shows",
+    "exhibitors"
   ],
   "license": "MIT",
   "engines": {

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),
     },
@@ -249,22 +249,24 @@ export const TOOLS = [
   {
     name: 'search_german_property_listings',
     actor: 'tacps126/immobilienscout24-scraper',
-    title: 'Search German property listings (ImmoScout24)',
+    title: 'Search German and Austrian property listings (ImmoScout24)',
     price: 'about $0.001 per listing',
     description:
-      '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.',
+      'Apartments and houses for rent or sale in Germany or Austria: price, rent, area, rooms, address with coordinates, energy class, features, agent, photos and dates. Not Switzerland.',
     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(),
+      country: z.enum(['de', 'at']).default('de').describe('de = Germany (immobilienscout24.de), at = Austria (immobilienscout24.at).'),
+      locations: strings('Cities, districts or regions in plain words, e.g. ["Berlin","München Schwabing"]; in Austria a city or federal state, e.g. ["Wien","Tirol"].'),
+      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) =>
       clean({
+        country: a.country,
         locations: a.locations,
         offerType: a.offer_type,
         propertyType: a.property_type,
@@ -286,8 +288,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) =>
@@ -300,6 +302,29 @@ export const TOOLS = [
       }),
     limit: (a) => a.max_items,
   },
+  {
+    name: 'get_trade_show_exhibitors',
+    actor: 'tacps126/exhibition-scraper',
+    title: 'Get trade show exhibitor lists (booths and contacts)',
+    price: 'about $0.002 per exhibitor',
+    description:
+      "Exhibitor lists of trade shows as B2B leads: company, booth and hall, email, phone, website, address, socials and categories. 76 built-in shows (e.g. medica, sema-show, nab-show, fabtech, ish, automechanika, wtm-london, world-health-expo) or any exhibitor-list link on Messe Frankfurt, Messe Düsseldorf, RX, Map Your Show, a2z / A2Z Connect, Swapcard or Corussoft; the link's own show and year are used. Contact coverage depends on what the organiser publishes.",
+    shape: {
+      shows: z.array(z.string().min(1)).optional().describe('Built-in show ids, e.g. ["medica","sema-show"]. The Actor README lists all ids.'),
+      urls: z.array(z.string().url()).optional().describe("Links to any show's exhibitor list or exhibitor search page (or its homepage)."),
+      include_contacts: z.boolean().default(true).describe('Open each exhibitor profile for email, phone, website, address and socials. Off = names and booths only (faster).'),
+      max_items: maxItems(50, 2000),
+    },
+    map: (a) =>
+      clean({
+        exhibitionList: a.shows,
+        startUrls: (a.urls ?? []).map((url) => ({ url })),
+        includeDetails: a.include_contacts,
+        maxResults: a.max_items,
+      }),
+    // max_items applies per show.
+    limit: (a) => a.max_items * Math.max(1, (a.shows?.length ?? 0) + (a.urls?.length ?? 0)),
+  },
 ];
 
 export const ACTORS = [...new Set(TOOLS.map((t) => t.actor))];