@agentutility/mcp-compose 0.1.0

package/README.md

@@ -0,0 +1,129 @@
+# @agentutility/mcp-compose
+
+> One call, several of our endpoints, one settlement.
+
+Composite endpoints that run two to five of our own capabilities in parallel and return one merged result. A company dossier is enrichment plus whois plus TLS plus tech stack in a single paid call. You skip the orchestration, the retries, and four extra settlements.
+
+**Pricing:** pay-per-call in USDC on Base. No subscriptions, no API keys. See per-tool prices below.
+
+## Install — Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "agentutility-compose": {
+      "command": "npx",
+      "args": ["-y", "@agentutility/mcp-compose"],
+      "env": { "X402_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY_HEX" }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. 56 tools appear in the tool palette.
+
+## Install — Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "agentutility-compose": {
+      "command": "npx",
+      "args": ["-y", "@agentutility/mcp-compose"],
+      "env": { "X402_PRIVATE_KEY": "0x..." }
+    }
+  }
+}
+```
+
+## Funding
+
+Send any amount of **USDC on Base mainnet** to the address derived from your `X402_PRIVATE_KEY`. The MCP server uses it to pay for tool calls automatically.
+
+USDC on Base contract: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
+
+## Tools (56)
+
+| Tool | Description |
+|---|---|
+| `address-intel-pack` | (0.03 USDC/call) Address intelligence API / address parse + geocode + timezone + permits in one call / location enrichment / property context for real-estate and logistics agents. Composite: one call runs address-parse + address-geocode in parallel, then timezone-lookup on the geocoded coordinates and building-permits when the address resolves to a supported open-data city (NYC, SF, Chicago, LA, Seattle, Austin). Merged output {parsed, location, timezone, permits}. Open-data sources only (OSM Nominatim, TimeAPI, city Socrata portals). |
+| `article-brief` | (0.04 USDC/call) Article brief / URL to summary + entities + sentiment / news article analyzer / one-call article intelligence. Give it an article URL and get back scraped text stats, a bullet summary, named entities (people, organizations, locations, dates), and overall sentiment with score — the standard agent reading pipeline collapsed into a single request. Ideal for news monitoring, research agents, content triage, brand tracking. Composite: one call runs scrape first, then summarize-text + extract-entities + sentiment in parallel over the text. |
+| `audio-brief` | (0.07 USDC/call) Audio brief / podcast summary / call recording digest / transcribe summarize sentiment in one call / speech-to-text plus TLDR plus emotion. Composite: one call runs audio-transcribe + summarize-text + sentiment. Whisper large v3 transcription of any audio URL, then summary and sentiment analysis run in parallel over the transcript. Returns transcript, detected language, duration, summary, sentiment scores, and per-component telemetry. |
+| `brand-presence-report` | (0.10 USDC/call) Brand presence report API / brand name check / startup name screening / domain + handle + clearance + lookalike bundle for naming and launch agents. Composite: one call runs domain-availability + social-handle-check + brand-clearance + homoglyph-check in parallel and merges them into {domains, social_handle, clearance, lookalike_risk}. Domain availability is checked per requested TLD (default com, ai, io, dev; max 6), the X handle is probed read-only, brand-clearance aggregates USPTO/domain/Wikipedia/HN signals, and homoglyph-check scores Unicode lookalike risk. Screening data only — not legal, trademark, or brand advice. |
+| `caption-translate-pack` | (0.07 USDC/call) Caption translate pack / translated subtitles / SRT generator plus translation / localized video captions / subtitle localization in one call. Composite: one call runs video-to-subtitles + translate. Generates SRT subtitles from any video URL (Whisper v3), then translates the subtitle text into the target language (100+ languages, structure preserved). Returns original subtitles, translated subtitles, and per-component telemetry. |
+| `clean-text-pack` | (0.03 USDC/call) Clean text pack / text sanitizer / Unicode normalize + homoglyph audit + PII detect + PII redact in one call / GDPR-safe ingest pipeline / input scrubber. Give it raw text and get back the NFC-normalized string, a script/homoglyph/hidden-character audit (Cyrillic lookalikes, zero-width chars, RTL overrides), every PII match with risk level, and a fully redacted copy with [EMAIL]/[PHONE]/[SSN]-style masks. One paid call replaces four sanitization steps: ideal for log scrubbing, dataset prep, LLM input hygiene, phishing triage. Composite: one call runs text-normalize + unicode-normalize + detect-pii + pii-redact in parallel over the same text. |
+| `company-dossier` | (0.05 USDC/call) Company dossier API / company research / firmographic profile / domain intelligence / company background lookup / account research for sales and B2B agents. Composite: one call runs company-enrich + domain-enrich + whois + ssl-cert-info + tech-stack-detect in parallel and merges them into {profile, domain, registration, security, tech_stack}. Accepts a domain or a bare company name (name inputs are resolved via a best-guess domain probe; unresolvable names return the profile only with the rest marked skipped). Public-data only; no private enrichment databases. |
+| `company-verify-pack` | (0.04 USDC/call) Company verification data API / company existence check / vendor data consistency / domain-backed company signals for procurement and marketplace agents. Composite: one call runs company-enrich + registrar-lookup + domain-age-check + ssl-cert-info in parallel and merges them into {profile, registrar, age, tls}. Public-data existence and consistency signals only — this is data verification from open sources, NOT compliance, KYB, KYC, or identity verification. |
+| `competitor-snapshot` | (0.06 USDC/call) Competitor snapshot API / company news monitor / competitive intelligence data / company profile + recent news + sentiment in one call for market-research agents. Composite: one call runs company-enrich + web-search + brand-sentiment-analysis; the profile and a week-recency '<company> news' search run in parallel, then sentiment is scored over the top result snippets when the search returns hits. Merged output {profile, news, sentiment}. Data snapshot only — no analysis, recommendations, or investment advice. |
+| `contact-normalize-pack` | (0.03 USDC/call) Contact normalization API / contact dedupe bundle / match key generator / record linkage pack / CRM hygiene for email, name, phone, and address in one call. Composite: one call runs match-key-email + match-key-name + match-key-phone + match-key-address + address-parse in parallel — only the constituents whose input field is present are invoked (at least one of email/name/phone/address required). Returns normalized values and stable match keys per field plus parsed US address components. Pure compute, no upstream calls, no data retention. |
+| `content-quality-pack` | (0.04 USDC/call) Content quality pack / pre-publish content check / AI-detection + PII scan + moderation + sentiment in one call / UGC safety gate. Give it text and get back an AI-generated probability with verdict, every PII match with risk level, an allow/review/block moderation verdict, and overall sentiment — the standard pre-publish gauntlet collapsed into a single request. Ideal for UGC pipelines, comment gating, guest-post screening, agent output review. Composite: one call runs ai-content-detector + detect-pii + moderate-content + sentiment in parallel over the same text. |
+| `contract-trust-pack` | (0.04 USDC/call) Contract trust pack / smart-contract verification bundle / source verification + honeypot simulation + LP lock check in one call / EVM contract due-diligence data. Composite: one call runs contract-source-verified + token-honeypot + lp-lock-check in parallel and merges Etherscan-verified source status (name, compiler, ABI, proxy flag), buy/sell tax simulation results, and liquidity-locker holdings into one structured report with per-component telemetry. Long Solidity sources are truncated in the merged payload. Data-only aggregation; no advice. |
+| `cron-pack` | (0.02 USDC/call) Cron pack / cron expression one-stop / parse + explain + next fire times in a single call / crontab validator + plain-English schedule + forecast / when does this cron run. Composite: one call runs cron-parse + cron-explain + cron-next in parallel over the same 5/6/7-field cron expression or @daily/@hourly/@weekly/@monthly/@yearly macro. Returns validation + frequency bucket, a plain-English explanation, and the next N firing times as ISO 8601 + epoch seconds + human-readable strings in your timezone, with regular-cadence detection. Includes composed_of + per-component telemetry; partial failure degrades instead of failing. |
+| `defi-protocol-dossier` | (0.04 USDC/call) DeFi protocol dossier / protocol TVL + yield pools in one call / DeFiLlama protocol profile bundle / Aave Lido Uniswap TVL and APY data pack. Composite: one call runs defi-llama-protocol + defi-yield-pools in parallel, merging the protocol's canonical profile (name, category, audits, current TVL, per-chain TVL breakdown, 24h/7d/30d change) with its yield-bearing pools filtered to the same project slug (APY, TVL, exposure, IL-risk classification). Pool list is optional and degrades without failing the call. Data-only aggregation; no advice. |
+| `doc-brief` | (0.05 USDC/call) Document brief / PDF summary + entities in one call / PDF intelligence / report digest API / contract skim. Give it a public PDF URL and get back layout-aware markdown (headings, tables, lists preserved), an executive summary, and the named entities (people, organizations, dates, monetary amounts) inside — the read-a-document agent pipeline collapsed into one request. Handles digital and scanned PDFs up to 30 pages. Ideal for report triage, contract review prep, research ingestion, due-diligence agents. Composite: one call runs pdf-to-markdown first, then summarize-text + extract-entities in parallel over the markdown. |
+| `domain-dossier` | (0.04 USDC/call) Domain dossier API / full domain report / domain intelligence / WHOIS + DNS + TLS + DMARC in one call / phishing triage bundle / brand-protection domain workup. Composite: one call runs whois + dns-lookup + ssl-cert-info + domain-age-check + domain-risk-check + dmarc-check in parallel and merges them into {registration, dns, tls, age, risk, email_auth}. One request replaces six separate lookups for security, fraud, and due-diligence agents. |
+| `email-trust-report` | (0.03 USDC/call) Email trust report API / email verification bundle / email risk data / deliverability + disposable + DMARC + dedupe key in one call for signup vetting and CRM hygiene agents. Composite: one call runs email-deliverability-check + disposable-email-check + dmarc-check + match-key-email in parallel and merges them into {deliverability, disposable, email_auth, match_key}. dmarc-check audits the email's domain; match-key-email supplies a normalized record-linkage key. DNS + public blocklist data only — no mailbox probing. |
+| `flight-brief` | (0.03 USDC/call) Flight brief / live flight status plus FAA airport delays plus airport info in one call / flight tracker bundle / callsign lookup with delay context. Composite: one call runs flight-status + airport-delays + iata-airport-info. Live aircraft state for a flight callsign (OpenSky Network) plus FAA ground stops, GDPs, and delay programs. Pass optional origin/destination IATA-3 codes to get per-airport delay events and airport metadata (name, coordinates, links); omit them and the national FAA delay picture is attached instead. Live data from OpenSky Network and FAA NAS Status. |
+| `image-caption-localize` | (0.04 USDC/call) Image caption localize / translated image caption / multilingual alt text / caption an image in any language / vision caption plus translation. Composite: one call runs describe-image + translate. Captions an image with a vision LLM (single-sentence caption mode), then translates the caption into the target language (100+ languages). Returns the source caption, translated caption, and per-component telemetry. |
+| `image-intel-pack` | (0.04 USDC/call) Image intel pack / image analysis bundle / describe image plus brand logo detection plus content moderation / vision intelligence in one call. Composite: one call runs describe-image + logo-detect + moderate-content. Vision LLM description and brand logo detection run in parallel, then the description text is moderated for safety (harassment, hate, violence, sexual content, spam, phishing). Returns description, detected brands, moderation verdict, and per-component telemetry. |
+| `json-dev-pack` | (0.03 USDC/call) JSON dev pack / JSON to TypeScript + YAML + schema validation in one call / API response toolkit / quicktype-style type generation with format conversion / structured-output verifier bundle. Composite: one call runs type-inference-from-json + json-yaml in parallel, plus json-schema-validate when you supply a schema. Returns a generated TypeScript interface (with date-time/uuid/uri/email format detection), the YAML rendering of the same document, and — when a JSON Schema (draft-07 or 2020-12) is provided — a validation report with per-error instance_path + keyword + message. Input capped at 200k chars. Includes composed_of + per-component telemetry; partial failure degrades instead of failing. |
+| `lead-qualify` | (0.06 USDC/call) Lead qualification data API / lead verification / email + company enrichment bundle / signup vetting / CRM intake check for sales and growth agents. Composite: one call runs lead-enrich + email-deliverability-check + disposable-email-check + company-enrich in parallel and merges them into a qualification object {email_valid, disposable, person, company} plus a deterministic fit_signals array (e.g. corporate_email_domain, domain_accepts_mail, disposable_email_domain). Data and derived signals only — no lead scoring, ranking, or buying advice. Company context is derived from the email domain when no company name is supplied. |
+| `localize-pack` | (0.05 USDC/call) Localize pack / detect + translate + tone rewrite in one call / localization pipeline API / multilingual content adapter. Give it text and a target language and get back the detected source language (ISO code + confidence), a fluent translation, and — when a tone is supplied — the translated text rewritten in that tone (formal, casual, friendly, persuasive, and 8 more). One paid call replaces the detect → translate → restyle chain: ideal for support reply localization, multilingual publishing, agent-to-human messaging. Composite: one call runs detect-language + translate in parallel, then rewrite-tone over the translation when a tone is provided. |
+| `market-rates-pack` | (0.04 USDC/call) Market rates pack / FX + perp funding + Hyperliquid mark price in one call / cross-market rates bundle / ECB exchange rates + Binance funding + perps data merge. Composite: one call runs exchange-rates + funding-rates + hyperliquid-market in parallel, merging ECB fiat FX rates for a chosen base currency, Binance USD-M perpetual funding (current rate, mark/index price, next funding time, 24h history), and Hyperliquid perp market data (mark price, max leverage, size decimals) for a chosen crypto symbol. Data-only market data merge; no advice. |
+| `meeting-brief` | (0.08 USDC/call) Meeting brief / meeting summary from recording / who-said-what digest / diarized meeting notes / speaker-labeled transcript plus summary. Composite: one call runs speaker-diarize + summarize-text. Diarizes a meeting or call recording (Whisper v3 + speaker labels), then summarizes the speaker-labeled transcript. Returns utterances by speaker, speaker count, labeled transcript, summary, and per-component telemetry. |
+| `naming-pack` | (0.06 USDC/call) Naming pack / startup name workflow in one call / business name generator + domain availability + brand score + social handle check / company naming bundle / brandable domain finder. Composite: one call runs business-name-generator first, then fans out domain-availability, brand-name-score, and social-handle-check over the top candidates (bounded to 9 component calls total). Returns brainstormed brandable candidates ranked by available TLDs + brandability, then an enriched shortlist: brand-quality score with risks and recommendations, X/Twitter handle availability, and RDAP .com registration status with registrar and expiry. Enrichment checks are optional — failures degrade the response instead of failing it. Includes composed_of + per-component telemetry. |
+| `news-digest` | (0.05 USDC/call) News digest / topic news summary / current events briefing / news search + summarize + entities in one call / agent news monitor. Give it a topic and a recency window (day/week/month) and get back ranked news results plus a bullet digest of the coverage and the named entities (people, companies, places) driving the story. One paid call replaces a search-then-summarize agent loop: ideal for daily briefings, brand monitoring, market awareness, research agents. Composite: one call runs web-search first, then summarize-text + extract-entities in parallel over the result snippets. |
+| `npm-trust-pack` | (0.04 USDC/call) npm trust pack / npm install pre-flight bundle / supply-chain risk score + registry stats in one call / typosquat check + downloads + maintainers / Socket.dev-adjacent vetting bundle. Composite: one call runs package-risk-npm + npm-package-stats in parallel for any npm package (scoped names supported). Returns the 0-10 risk score with risk_level bucket, contributing factors, typosquat candidates, and plain-English summary, plus the raw registry metrics: latest version, version count, age, days since last release, maintainer list, and last day/week/month/year downloads. Includes composed_of + per-component telemetry; partial failure degrades instead of failing. |
+| `onchain-identity-pack` | (0.03 USDC/call) Onchain identity pack / ENS + Basename + wallet label in one call / name-to-address and address-to-name resolver bundle / vitalik.eth lookup / .base.eth lookup / EVM address identity data. Composite: one call runs ens-resolve + basename-resolve + wallet-label in parallel. Pass a 0x address for reverse ENS, reverse Basename, and known-address labelling, or pass a name ('vitalik.eth', 'jesse.base.eth', bare 'alice') for forward resolution on both name services with text records. All components are optional individually; at least one must resolve or the call returns 424. Data-only aggregation; no advice. |
+| `outreach-pack` | (0.05 USDC/call) Outreach pack / cold email draft + deliverability check in one call / write the email and verify the address / sales outreach pre-flight / inbox-readiness bundle. Composite: one call runs email-draft + email-deliverability-check in parallel. Returns a ready-to-send email (subject, body, salutation, sign-off — tone controllable) plus a deliverability report on the recipient address: syntax, MX records, disposable-domain and role-account detection, SPF/DMARC/DKIM posture, and a 0-100 deliverability score. Privacy-safe DNS only, no mailbox probing. Includes composed_of + per-component telemetry; partial failure degrades instead of failing. |
+| `paper-brief` | (0.04 USDC/call) Paper brief / arXiv paper digest / research paper summary plus BibTeX citation in one call / find and summarize a paper / arXiv search summarize cite bundle. Composite: one call runs arxiv-search + arxiv-summarize + arxiv-bibtex. Pass a topic query (resolves to the top relevance hit) or an arXiv ID (search stage skipped); the structured LLM summary (TLDR, key findings, methods, limitations) and a ready-to-paste BibTeX entry are generated in parallel. Public arXiv API. |
+| `person-dossier` | (0.05 USDC/call) Person dossier API / contact research / email intelligence / lead profile lookup / person background from email for CRM and sales agents. Composite: one call runs person-enrich + email-deliverability-check + disposable-email-check + social-handle-check in parallel and merges them into {person, deliverability, disposable, social_handle}. The email local-part is probed as a candidate X handle (optional, degrades gracefully). Public-data enrichment only — no private people databases, no social-network scraping. |
+| `pr-pack` | (0.05 USDC/call) PR pack / git diff to commit message + PR description in one call / pull request bundle / conventional commit + PR body generator / ship-a-branch helper. Composite: one call runs commit-message-from-diff + pr-description-from-diff in parallel over the same unified diff. Returns a Conventional Commits message (type, scope, subject, full_message) plus a review-ready PR description (title, summary bullets, Markdown test-plan checklist, breaking_change flag, paste-ready body). Diff capped at 30,000 chars. Response includes composed_of + per-component telemetry; partial upstream failure degrades instead of failing. |
+| `prediction-market-snapshot` | (0.04 USDC/call) Prediction market snapshot / cross-venue market search / Polymarket + Kalshi in one call / event odds listing bundle / two-venue prediction market data. Composite: one call runs polymarket-markets + kalshi-markets in parallel with the same free-text query and returns merged {polymarket: [], kalshi: []} lists of open markets — questions, tickers, implied outcome prices (0-1), volume, liquidity, and end dates from both venues. Data-only listing of public market data; no probability advice, no order entry, no trading. |
+| `product-listing-pack` | (0.06 USDC/call) Product listing pack / ecommerce listing bundle / product description + SEO keywords + name score in one call / marketplace listing generator / Shopify Amazon Etsy listing prep. Composite: one call runs product-description + keyword-suggest + product-name-score in parallel. Returns marketing-ready copy (description, selling points, key features, listing titles built from your supplied facts), a de-duplicated ranked SEO keyword list from Wikipedia + DuckDuckGo autocomplete, and a name-quality score with grade, risks, and recommendations. name-score is optional: its failure degrades the response instead of failing it. Includes composed_of + per-component telemetry. |
+| `pubmed-brief` | (0.04 USDC/call) PubMed brief / biomedical literature search + bullet summary in one call / NIH paper digest / research literature synthesis / MeSH query with abstract roll-up. Composite: one call runs pubmed-search first, then summarize-text over the retrieved titles + abstracts. Returns the matching papers (PMID, title, authors, journal, date, abstract, DOI) plus a bullet-point synthesis of what the abstracts say. Literature synthesis only — this is NOT medical advice; output describes published research and always carries a consult-a-clinician disclaimer. Summary stage is optional: its failure degrades the response instead of failing it. Federal public-domain data via NCBI E-utilities. Includes composed_of + per-component telemetry. |
+| `pypi-trust-pack` | (0.04 USDC/call) PyPI trust pack / pip install pre-flight bundle / Python supply-chain risk score + package stats in one call / typosquat check + downloads + release history / requirements.txt + pyproject.toml vetting bundle. Composite: one call runs pypi-package-risk + pypi-package-stats in parallel for any Python package. Returns the 0-10 risk score with risk_level bucket, contributing factors, typosquat candidates, and plain-English summary, plus the raw PyPI metrics: latest version, version count, age, days since last release, author/maintainer, classifiers, and pypistats day/week/month downloads. Includes composed_of + per-component telemetry; partial failure degrades instead of failing. |
+| `regex-pack` | (0.03 USDC/call) Regex pack / natural language to regex + live test in one call / NL pattern builder with verification / generate-and-verify regex workflow / regex playground bundle. Composite: one call runs regex-from-prompt first, then feeds the generated pattern into regex-test over your test_strings (optional stage, runs only when test_strings are provided). Returns the JavaScript pattern + flags + explanation + examples, plus per-input matched/not-matched verdicts with capture groups so you know the pattern actually matches what you asked for. Prompt capped at 2,000 chars; up to 100 test strings of 5,000 chars each. Includes composed_of + per-component telemetry. |
+| `repo-health-brief` | (0.05 USDC/call) GitHub repo brief / open-source dependency vetting bundle / repo health + README + star history in one call / should-I-depend-on-this-repo check. Composite: one call runs github-repo-health + github-readme + github-stars-history in parallel for any public GitHub repo. Returns the 0-100 maintainability score with grade (abandoned/stale/okay/healthy/thriving) and LLM verdict, the raw README markdown (truncated at 20k chars), and a sampled cumulative-stars-vs-date growth series. stars-history is optional: if it fails the response degrades instead of failing. Includes composed_of + per-component telemetry. |
+| `resume-review-pack` | (0.06 USDC/call) Resume review pack / ATS score + PII scan + summary polish in one call / job application pre-flight / resume vs job description fit bundle / CV review workflow. Composite: one call runs resume-scorer + detect-pii + rewrite-tone in parallel. Returns the 0-100 ATS fit score with calibrated subscores (keyword match, experience, skills, formatting, impact) and ranked improvement suggestions, a PII exposure report (emails, phones, addresses, SSNs) with risk level, and a confident-tone rewrite of the resume's summary/objective section. The rewrite stage is optional and bounded — its failure degrades the response instead of failing it. Includes composed_of + per-component telemetry. |
+| `seo-snapshot` | (0.04 USDC/call) SEO snapshot / on-page SEO audit / page metadata + link profile + keyword ideas in one call / SEO research API for agents. Give it a URL and get back head metadata (title, description, canonical, OG/Twitter cards), the internal/external link breakdown, and ranked keyword suggestions seeded from your seed_keyword or the page's own title. One paid call replaces three: ideal for content-gap analysis, SEO audits, competitor page reviews, programmatic SEO pipelines. Composite: one call runs url-metadata-extract + link-extract in parallel, then keyword-suggest seeded from the page title. |
+| `site-snapshot-pack` | (0.05 USDC/call) Site snapshot pack / website screenshot + metadata + SSL certificate in one call / visual + technical site profile / landing-page verifier. Give it a URL and get back a rendered PNG screenshot (hosted image URL), head metadata (title, description, OG/Twitter cards, favicon), and the TLS certificate summary (issuer, days until expiry) for the host. One paid call replaces three: ideal for link-preview generation, phishing triage, uptime/appearance audits, portfolio monitoring, sales prospect research. Composite: one call runs website-screenshot + url-metadata-extract + ssl-cert-info in parallel. |
+| `social-profile-pack` | (0.04 USDC/call) Social profile pack API / X profile + recent tweets + sentiment in one call / Twitter account snapshot / audience research data for social and brand agents. Composite: one call runs twitter-user-lookup + user-tweets + twitter-sentiment in parallel for a username and merges them into {profile, tweets, sentiment}; sentiment is scored over the account's recent public posts and degrades gracefully when unavailable. Read-only X API v2 — no posting, replying, liking, following, or account mutation. |
+| `solana-token-report` | (0.04 USDC/call) Solana token report / SPL token data pack / mint + freeze authority check + flagged-list membership in one call / Solana memecoin screening data / GoPlus + DEX Screener composite. Composite: one call runs solana-token-safety + solana-flagged-tokens in parallel, returning the 0-100 GoPlus safety score, authority flags, holder concentration, and whether the mint appears on the recently-flagged DEX Screener risk list (membership check computed server-side). The flagged-list component is optional and degrades without failing the call. Data-only aggregation; no advice. |
+| `stablecoin-health-report` | (0.04 USDC/call) Stablecoin health report / peg deviation + stablecoin pool TVL in one call / USDC USDT DAI depeg monitor bundle / stablecoin market data pack. Composite: one call runs stablecoin-peg + defi-yield-pools (stablecoin-only) in parallel, merging live price and basis-point deviation from $1 (USDT, USDC, DAI, FRAX, PYUSD, FDUSD, USDE, RLUSD, with configurable depeg-alert threshold) with the largest stablecoin yield pools tracked by DeFiLlama (TVL, APY, chain, project). Optional symbol filter narrows both components to one stablecoin. Pool data is optional and degrades without failing the call. Data-only aggregation; no advice. |
+| `text-intel-pack` | (0.03 USDC/call) Text intel pack / full text analysis in one call / language + sentiment + entities + token count + zero-shot classification / NLP toolbelt API. Give it text (plus optional labels) and get back the detected language with confidence, overall sentiment and score, named entities, an estimated token count, and — when 2-25 labels are supplied — a zero-shot classification verdict. One paid call replaces five NLP requests: ideal for inbound message routing, CRM enrichment, content pipelines, agent preprocessing. Composite: one call runs detect-language + sentiment + extract-entities + token-count (and text-classify when labels are given) in parallel. |
+| `token-dossier` | (0.05 USDC/call) Token dossier / EVM token data pack / token due-diligence bundle / ERC-20 metadata + risk score + honeypot simulation + LP lock + burn stats in one call. Composite: one call runs erc20-metadata + token-risk-score + token-honeypot + lp-lock-check + token-burn-stats in parallel and merges the results into a single structured report with per-component telemetry. Covers name/symbol/decimals/supply, composite 0-100 security score, buy/sell tax simulation, liquidity-locker holdings, and burn-address transfer history for tokens on Base, Ethereum, and other EVM chains. Data-only aggregation; no advice. |
+| `trip-conditions-pack` | (0.03 USDC/call) Trip conditions pack / travel conditions bundle / weather plus AQI plus sunrise sunset plus timezone for any coordinates / destination briefing in one call. Composite: one call runs weather-forecast + sunrise-sunset + air-quality + timezone-lookup in parallel. Everything an agent needs to brief a trip stop for a lat/lon: current conditions and 1-7 day forecast, sun and twilight times, US/European AQI with pollutant readings, and IANA timezone with local time. Partial failures degrade instead of erroring. |
+| `tx-dossier` | (0.04 USDC/call) Transaction dossier / EVM tx data pack / decoded receipt + plain-English explanation in one call / tx debug bundle / Basescan + Etherscan tx reader. Composite: one call runs tx-receipt-decode + crypto-tx-explainer in parallel and merges decoded event logs (ERC-20/ERC-721 transfers, approvals, verified-ABI events) with an LLM-written plain-English summary of what the transaction did. Includes status, gas, from/to/value, and per-component telemetry. The explainer is optional and degrades on timeout without failing the call. Data-only aggregation; no advice. |
+| `url-dossier` | (0.05 USDC/call) URL dossier / full page intelligence / website profile in one call / page metadata + content + summary + links + tech stack. Give it a URL and get back head metadata (title, description, OG/Twitter cards, canonical, favicon), scraped body text with an LLM summary, the outbound link list, and a tech-stack fingerprint (CMS, framework, CDN, hosting, analytics). One paid call replaces five: ideal for agent research, lead qualification, content cataloging, competitive analysis, RAG ingestion. Composite: one call runs url-metadata-extract + scrape + link-extract + tech-stack-detect in parallel, then summarize-text over the scraped text. |
+| `video-brief` | (0.08 USDC/call) Video brief / video summary from URL / transcribe and summarize video / video TLDR / video digest / Whisper transcription plus LLM summary. Composite: one call runs video-to-text + summarize-text. Transcribes any video URL (Whisper v3, auto-detects 90+ languages), then summarizes the transcript. Returns full transcript, duration, summary, and per-component telemetry. If transcription times out, responds 424 with partial telemetry. |
+| `wallet-dossier` | (0.05 USDC/call) Wallet dossier / EVM address data pack / wallet profile bundle / address label + ENS reverse lookup + ERC-20 balance + FIFO token P&L in one call. Composite: one call runs wallet-label + ens-resolve + wallet-current-balance + wallet-pnl in parallel and merges the results into one structured report with per-component telemetry. Returns known-address label and category, EOA-vs-contract status, primary ENS name, current ERC-20 balance (USDC on Base by default, any token via token_address), and FIFO cost-basis P&L for that token. wallet-pnl is optional and degrades on timeout. Data-only aggregation; no advice. |
+| `webpage-change-report` | (0.04 USDC/call) Webpage change report / website change monitor with plain-language summary / page-watch + diff digest / TOS-policy change explainer / price-page monitor with narrative. Give it a URL (plus optional previous_hash or previous_text baseline and CSS selector scope) and get back the changed flag, content hash, added/removed line diff, and an LLM summary of what actually changed — ready to drop into an alert or agent decision. Ideal for competitor monitoring, policy-change tracking, status-page watching, changelog digests. Composite: one call runs webpage-diff first, then summarize-text over the diff. |
+| `website-trust-report` | (0.04 USDC/call) Website trust report API / URL safety data / site legitimacy signals / phishing triage bundle / link inspection for security and moderation agents. Composite: one call runs ssl-cert-info + domain-risk-check + homoglyph-check + url-metadata-extract + tech-stack-detect in parallel over a URL (the hostname is derived for the domain-shaped checks) and merges them into {tls, domain_risk, lookalike, metadata, tech_stack}. Data signals only — no verdicts or safety guarantees. |
+| `wiki-brief` | (0.03 USDC/call) Wiki brief / Wikipedia topic briefing / encyclopedia lookup + summary + entities in one call / RAG context builder / topic primer API. Give it a topic and get back the canonical Wikipedia article (title, URL, Wikidata Q-id, intro), a bullet brief distilled from the article body, and the named entities (people, organizations, locations, dates) it mentions. One paid call replaces the lookup-then-digest agent loop: ideal for topic primers, RAG context assembly, research agents, quiz/content generation. Composite: one call runs wikipedia-lookup first, then summarize-text + extract-entities in parallel over the article text. |
+| `youtube-brief` | (0.05 USDC/call) YouTube brief / YouTube video summary / YouTube transcript plus TLDR plus named entities / video digest from YouTube URL or ID / closed-caption summarizer. Composite: one call runs youtube-transcript + summarize-text + extract-entities. Pulls the YouTube transcript, then summary and named entity extraction (people, orgs, locations, dates) run in parallel. Returns transcript excerpt, summary, entities, and per-component telemetry. |
+
+## How it works
+
+1. Agent calls a tool (e.g. `address-intel-pack`).
+2. MCP server POSTs to `https://x402.agentutility.ai/address-intel-pack`.
+3. The endpoint responds **HTTP 402** with payment instructions.
+4. The MCP server signs an EIP-3009 USDC transfer authorization with `X402_PRIVATE_KEY` and retries.
+5. CDP facilitator settles on Base.
+6. The endpoint returns the actual response.
+
+The agent never sees the payment flow — it just gets the result.
+
+## Links
+
+- Cluster overview: https://agentutility.ai/compose/
+- All MCP packages: https://mcp.agentutility.ai/
+- Source: https://github.com/rooz21/x402/tree/main/packages/mcp-compose
+
+---
+
+**Version:** 0.1.0 · **License:** MIT

package/dist/index.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * @agentutility/mcp-<cluster> — stdio MCP server exposing the cluster's
+ * x402-paid endpoints as MCP tools. Forwards every CallToolRequest to
+ * x402.agentutility.ai, where @x402/fetch handles 402 → payment → retry
+ * using the agent's own wallet (X402_PRIVATE_KEY env var).
+ *
+ * Boilerplate is single-sourced at packages/_template/src/index.ts and
+ * copied verbatim into each packages/mcp-<cluster>/src/index.ts by
+ * scripts/generate-mcp-clusters.mjs. The codegen also writes a matching
+ * tools.generated.ts so this file imports CLUSTER_SLUG + VERSION + TOOLS
+ * rather than hard-coding.
+ *
+ * Required env: X402_PRIVATE_KEY (hex EVM key, USDC on Base).
+ * Optional env: X402_BASE_URL (default https://x402.agentutility.ai)
+ *               X402_RPC_URL  (default https://mainnet.base.org)
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
+import { ExactEvmScheme, toClientEvmSigner } from "@x402/evm";
+import { privateKeyToAccount } from "viem/accounts";
+import { createPublicClient, http } from "viem";
+import { base } from "viem/chains";
+import { TOOLS, CLUSTER_SLUG, VERSION } from "./tools.generated.js";
+const BASE_URL = (process.env.X402_BASE_URL || "https://x402.agentutility.ai").replace(/\/$/, "");
+const RPC_URL = process.env.X402_RPC_URL || "https://mainnet.base.org";
+const PK = process.env.X402_PRIVATE_KEY;
+if (!PK) {
+    console.error(`[@agentutility/mcp-${CLUSTER_SLUG}] FATAL: X402_PRIVATE_KEY env var is required.`);
+    console.error("Set it to a hex-encoded EVM private key with USDC balance on Base (chain 8453).");
+    console.error("USDC on Base: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913");
+    process.exit(1);
+}
+const account = privateKeyToAccount((PK.startsWith("0x") ? PK : `0x${PK}`));
+const publicClient = createPublicClient({
+    chain: base,
+    transport: http(RPC_URL),
+});
+const signer = toClientEvmSigner(account, publicClient);
+const client = new x402Client().register("eip155:8453", new ExactEvmScheme(signer));
+const paidFetch = wrapFetchWithPayment(fetch, client);
+async function trackedFetch(url, init) {
+    const headers = new Headers(init?.headers);
+    headers.set("X-Agent-Channel", `mcp-stdio-${CLUSTER_SLUG}`);
+    headers.set("X-Agent-Id", "47167");
+    if (!headers.has("User-Agent")) {
+        headers.set("User-Agent", `agentutility-mcp/${CLUSTER_SLUG}/${VERSION}`);
+    }
+    return paidFetch(url, { ...init, headers });
+}
+const server = new Server({ name: `agentutility-${CLUSTER_SLUG}`, version: VERSION }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.input_schema,
+    })),
+}));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const name = req.params.name;
+    const tool = TOOLS.find((t) => t.name === name);
+    if (!tool) {
+        return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
+    }
+    try {
+        const res = await trackedFetch(`${BASE_URL}/${tool.http_name}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(req.params.arguments ?? {}),
+        });
+        const body = await res.text();
+        if (!res.ok) {
+            return { content: [{ type: "text", text: `HTTP ${res.status}: ${body}` }], isError: true };
+        }
+        return { content: [{ type: "text", text: body }] };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `tool call failed: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+        };
+    }
+});
+await server.connect(new StdioServerTransport());