diffbot-mcp 0.2.0__py3-none-any.whl

diffbot_mcp/dql_builder.py

@@ -0,0 +1,223 @@
+"""Pure helpers for assembling DQL strings. No I/O, so the typed tools' queries are unit-testable."""
+
+import re
+import unicodedata
+from typing import Iterable, List, Optional, Tuple
+
+from fastmcp.exceptions import ToolError
+
+DATE_PATTERN = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+RADIUS_PATTERN = re.compile(r"^\d+(\.\d+)?\s?(mi|km)$")
+
+# Titles are free text and an abbreviation is not a substring of its expansion, so a
+# C-suite search that omits either form silently under-counts by ~5x. Board seats are
+# titled "Director" far more often than "Board Member" (904 vs 5 at Nvidia).
+TITLE_EXPANSIONS = {
+    "ceo": ["Chief Executive Officer", "CEO"],
+    "chief executive officer": ["Chief Executive Officer", "CEO"],
+    "cto": ["Chief Technology Officer", "CTO"],
+    "chief technology officer": ["Chief Technology Officer", "CTO"],
+    "cfo": ["Chief Financial Officer", "CFO"],
+    "chief financial officer": ["Chief Financial Officer", "CFO"],
+    "coo": ["Chief Operating Officer", "COO"],
+    "chief operating officer": ["Chief Operating Officer", "COO"],
+    "cio": ["Chief Information Officer", "CIO"],
+    "chief information officer": ["Chief Information Officer", "CIO"],
+    "cmo": ["Chief Marketing Officer", "CMO"],
+    "chief marketing officer": ["Chief Marketing Officer", "CMO"],
+    "board member": ["Board Member", "Board of Directors", "Director"],
+    "board of directors": ["Board Member", "Board of Directors", "Director"],
+    "board": ["Board Member", "Board of Directors", "Director"],
+}
+
+
+def quote(value: str) -> str:
+    escaped = str(value).replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'
+
+
+def clause(field: str, value: str, strict: bool = False) -> str:
+    return f"{'strict:' if strict else ''}{field}:{quote(value)}"
+
+
+def dedupe(values: Iterable[str]) -> List[str]:
+    seen = set()
+    out = []
+    for value in values:
+        value = str(value).strip()
+        if value and value not in seen:
+            seen.add(value)
+            out.append(value)
+    return out
+
+
+def or_clause(field: str, values: Iterable[str], strict: bool = False) -> str:
+    values = dedupe(values)
+    if not values:
+        return ""
+    if len(values) == 1:
+        return clause(field, values[0], strict)
+    return f"{'strict:' if strict else ''}{field}:or({','.join(quote(v) for v in values)})"
+
+
+def subquery(field: str, clauses: Iterable[str]) -> str:
+    """field.{a b c}: co-constrain several conditions on the same nested list object."""
+    inner = " ".join(c for c in clauses if c)
+    return f"{field}.{{{inner}}}" if inner else ""
+
+
+def number(value: float) -> str:
+    return str(int(value)) if float(value).is_integer() else str(value)
+
+
+def compare(field: str, operator: str, value) -> str:
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return f"{field}{operator}{number(value)}"
+    return f"{field}{operator}{quote(str(value))}"
+
+
+def validate_date(value: Optional[str], name: str) -> Optional[str]:
+    if value is None:
+        return None
+    value = value.strip()
+    if not DATE_PATTERN.match(value):
+        raise ToolError(f"{name} must be a full date in YYYY-MM-DD form, got '{value}'")
+    return value
+
+
+def date_range(field: str, since: Optional[str], until: Optional[str]) -> List[str]:
+    clauses = []
+    if since:
+        clauses.append(compare(field, ">=", validate_date(since, "since")))
+    if until:
+        clauses.append(compare(field, "<=", validate_date(until, "until")))
+    return clauses
+
+
+def sort_clause(field: str, descending: bool = True) -> str:
+    return f"{'revSortBy' if descending else 'sortBy'}:{field}"
+
+
+def near_clause(anchor: str, radius: Optional[str] = None) -> str:
+    if radius:
+        radius = radius.strip().replace(" ", "")
+        if not RADIUS_PATTERN.match(radius):
+            raise ToolError(f"radius must be a number followed by mi or km, e.g. '30mi', got '{radius}'")
+        return f"near(type:Place name:{quote(anchor)}, {radius})"
+    return f"near(type:Place name:{quote(anchor)})"
+
+
+def expand_titles(titles: Iterable[str]) -> List[str]:
+    expanded: List[str] = []
+    for title in titles:
+        expanded.extend(TITLE_EXPANSIONS.get(title.strip().lower(), [title]))
+    return dedupe(expanded)
+
+
+def ascii_variant(text: str) -> Optional[str]:
+    """The ASCII spelling of an accented name, or None when it is already ASCII. Diacritics are not normalized in the KG and coverage of each spelling is inconsistent."""
+    folded = unicodedata.normalize("NFKD", text).encode("ascii", "ignore").decode("ascii")
+    return folded if folded and folded != text else None
+
+
+def name_variants(text: str) -> List[str]:
+    variant = ascii_variant(text)
+    return [text, variant] if variant else [text]
+
+
+def looks_like_domain(text: str) -> bool:
+    text = text.strip()
+    return " " not in text and "." in text and not text.endswith(".")
+
+
+def build(clauses: Iterable[str]) -> str:
+    return " ".join(c for c in clauses if c)
+
+_UNITS = {"k": 1e3, "m": 1e6, "b": 1e9}
+_NUMBER = re.compile(r"^\$?([0-9][0-9,]*\.?[0-9]*)\s*([kmb])?$", re.IGNORECASE)
+
+
+def parse_amount(text: str, name: str) -> float:
+    """'10M' -> 10000000, '$1.5b' -> 1500000000, '50,000' -> 50000."""
+    match = _NUMBER.match(text.strip())
+    if not match:
+        raise ToolError(f"{name}: cannot read '{text}'; use a number with an optional K/M/B suffix, e.g. '10M'.")
+    value = float(match.group(1).replace(",", ""))
+    unit = (match.group(2) or "").lower()
+    return value * _UNITS.get(unit, 1)
+
+
+def parse_range(text: Optional[str], name: str, parse=parse_amount, integer: bool = False) -> Tuple[Optional[float], Optional[float]]:
+    """One range string -> inclusive (low, high). Forms: '10M-75M', '500+', '>=500', '>500', '<5000', '<=5000', '500' (exact).
+
+    Bounds are rendered as >= and <=, so with integer=True an exclusive '<20' becomes <=19 and '>20' becomes >=21.
+    """
+    if text is None:
+        return None, None
+    text = text.strip().replace(" ", "")
+    if not text:
+        return None, None
+    for op in (">=", "<=", ">", "<"):
+        if text.startswith(op):
+            value = parse(text[len(op):], name)
+            if integer:
+                value = int(value) + (1 if op == ">" else -1 if op == "<" else 0)
+            if op[0] == ">":
+                return value, None
+            return None, value
+    if integer:
+        parse_one = parse
+        parse = lambda t, n: int(parse_one(t, n))  # noqa: E731
+    if text.endswith("+"):
+        return parse(text[:-1], name), None
+    # split on a dash that is between two bounds, not a leading minus
+    parts = re.split(r"(?<=[0-9a-zA-Z])-(?=[\$0-9])", text, maxsplit=1)
+    if len(parts) == 2:
+        low, high = parse(parts[0], name), parse(parts[1], name)
+        if low > high:
+            raise ToolError(f"{name}: low bound {parts[0]} is above high bound {parts[1]}.")
+        return low, high
+    value = parse(text, name)
+    return value, value
+
+
+def parse_year_or_date(text: str, name: str) -> str:
+    """'2015' -> '2015' as-is for the caller to pad; full dates pass validate_date."""
+    text = text.strip()
+    if re.fullmatch(r"[0-9]{4}", text):
+        return text
+    return validate_date(text, name) or text
+
+
+def parse_date_range(text: Optional[str], name: str) -> Tuple[Optional[str], Optional[str]]:
+    """'2015-2020' -> ('2015-01-01', '2020-12-31'); '2019' -> that whole year; '>=2020-06-01' -> (that, None)."""
+    if text is None or not text.strip():
+        return None, None
+    text = text.strip().replace(" ", "")
+    def pad(value: Optional[str], end: bool) -> Optional[str]:
+        if value is None:
+            return None
+        return f"{value}-12-31" if end and len(value) == 4 else f"{value}-01-01" if len(value) == 4 else value
+    for op in (">=", "<=", ">", "<"):
+        if text.startswith(op):
+            value = parse_year_or_date(text[len(op):], name)
+            return (pad(value, False), None) if op[0] == ">" else (None, pad(value, True))
+    if text.endswith("+"):
+        return pad(parse_year_or_date(text[:-1], name), False), None
+    # year-year, or date-date (dates contain dashes, so split only on a dash followed by a 4-digit year)
+    parts = re.split(r"(?<=[0-9])-(?=[0-9]{4}(?:-|$))", text, maxsplit=1)
+    if len(parts) == 2 and parts[0] and parts[1]:
+        low, high = parse_year_or_date(parts[0], name), parse_year_or_date(parts[1], name)
+        return pad(low, False), pad(high, True)
+    value = parse_year_or_date(text, name)
+    return pad(value, False), pad(value, True)
+
+
+def split_near(text: Optional[str]) -> Tuple[Optional[str], Optional[str]]:
+    """'Austin 30mi' -> ('Austin', '30mi'); 'Austin' -> ('Austin', None)."""
+    if not text:
+        return None, None
+    match = re.match(r"^(.*?)[\s,]+([0-9]+(?:\.[0-9]+)?\s*(?:mi|miles|km|m))\.?$", text.strip(), re.IGNORECASE)
+    if match:
+        return match.group(1).strip(), match.group(2).replace(" ", "").replace("miles", "mi")
+    return text.strip(), None

diffbot_mcp/schema.py

@@ -0,0 +1,34 @@
+"""Slims tool schemas on the way out of tools/list.
+
+Pydantic renders every Optional parameter as anyOf:[{type:X},{type:null}] with default:null, roughly
+55 bytes of structure per parameter that tells the model nothing it does not already know from the
+parameter being optional. Collapsing it is the largest single saving on the always-on schema cost.
+Validation of incoming arguments still runs against the function signature, so None stays accepted.
+"""
+
+from typing import Any, Sequence
+
+from fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext
+from fastmcp.tools import Tool
+
+
+def slim(node: Any) -> Any:
+    if isinstance(node, list):
+        return [slim(item) for item in node]
+    if not isinstance(node, dict):
+        return node
+    node = {key: slim(value) for key, value in node.items() if not (key == "default" and value is None)}
+    options = node.get("anyOf")
+    if isinstance(options, list):
+        non_null = [option for option in options if option != {"type": "null"}]
+        if len(non_null) == 1 and len(non_null) < len(options):
+            merged = dict(non_null[0])
+            merged.update({key: value for key, value in node.items() if key != "anyOf"})
+            return merged
+    return node
+
+
+class SlimSchemas(Middleware):
+    async def on_list_tools(self, context: MiddlewareContext, call_next: CallNext) -> Sequence[Tool]:
+        tools = await call_next(context)
+        return [tool.model_copy(update={"parameters": slim(tool.parameters)}) for tool in tools]

diffbot_mcp/server.py

@@ -0,0 +1,22 @@
+"""Composition root: importing the tool modules registers them."""
+
+from .app import mcp
+from .schema import SlimSchemas
+from .tools import (  # noqa: F401  (imported for their registration side effects)
+    extract,
+    search_web,
+    news,
+    organizations,
+    people,
+    places,
+    deals,
+    crawl,
+    resolve_entities,
+    dql,
+    dql_ontology,
+    dql_probe,
+)
+
+mcp.add_middleware(SlimSchemas())
+
+__all__ = ["mcp"]

diffbot_mcp/tools/__init__.py

@@ -0,0 +1 @@
+"""Tool modules. Importing a module registers its tool on the shared FastMCP instance."""

diffbot_mcp/tools/crawl.py

@@ -0,0 +1,140 @@
+import csv
+import io
+import time
+from typing import Annotated, Literal, Optional
+
+from fastmcp.exceptions import ToolError
+from mcp.types import ToolAnnotations
+
+from ..api import request, resolve_token
+from ..app import mcp
+from .extract import PageType, normalize_url
+
+CRAWL_ENDPOINT = "https://api.diffbot.com/v3/crawl"
+EXTRACT_BASE = "https://api.diffbot.com/v3"
+# jobStatus.status codes 0 and 7 mean the job is still in progress
+RUNNING_STATUS_CODES = (0, 7)
+
+DESCRIPTION = (
+    "Crawls a website from a seed URL and extracts every page it finds into markdown or typed JSON. Prefer when a "
+    "task needs to discover a catalog of pages from an entire site, or deep search a site for structured data "
+    "(e.g. all product inventory, all press releases, PDFs). Crawls run in the background. `start` returns a job "
+    "name, poll `status` until is_running is false, then read `results` or `urls`. `list` and `delete` manage jobs."
+    " API docs: https://www.diffbot.com/docs/crawl/"
+)
+
+
+def job_summary(job: dict) -> dict:
+    status = job.get("jobStatus") or {}
+    code = status.get("status")
+    return {
+        "job_name": job.get("name"),
+        "status": status.get("message"),
+        "status_code": code,
+        "is_running": code in RUNNING_STATUS_CODES,
+        "pages_crawled": job.get("pageCrawlSuccesses"),
+        "pages_processed": job.get("pageProcessSuccesses"),
+        "objects_found": job.get("objectsFound"),
+        "created": job.get("jobCreationTimeUTC"),
+    }
+
+
+@mcp.tool(name="crawl", title="Crawl Website", description=DESCRIPTION, annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=True, idempotentHint=False, openWorldHint=True))
+async def crawl(
+    action: Annotated[Literal["start", "status", "urls", "results", "list", "delete"], "start needs url; others need job_name"] = "start",
+    url: Annotated[Optional[str], "Seed URL (start)"] = None,
+    job_name: Annotated[Optional[str], "Job handle; generated on start if omitted"] = None,
+    hops: Annotated[int, "Link depth from seed"] = 2,
+    max_to_crawl: Annotated[int, "Max pages visited"] = 100,
+    max_to_process: Annotated[int, "Max pages extracted"] = 100,
+    restrict_domain: Annotated[bool, "Stay on the seed's domain"] = True,
+    url_crawl_pattern: Annotated[Optional[str], "Only visit URLs containing this"] = None,
+    url_process_pattern: Annotated[Optional[str], "Only extract URLs containing this, e.g. /blog/"] = None,
+    obey_robots: Annotated[bool, "Honor robots.txt"] = False,
+    use_proxies: Annotated[bool, "Crawl with Diffbot proxy; try when site blocks the crawler"] = False,
+    crawl_delay: Annotated[Optional[float], "Seconds between requests per domain"] = None,
+    custom_headers: Annotated[Optional[str], "Extra HTTP headers, newline separated"] = None,
+    page_type: Annotated[Optional[PageType], "Override auto-detection; rarely needed"] = None,
+    format: Annotated[Literal["markdown", "json"], "`markdown` for readable text; `json` for typed fields such as title, author, date, price, images"] = "markdown",
+    max_results: Annotated[int, "Max rows (urls, results)"] = 10,
+    offset: Annotated[int, "Rows to skip (urls, results)"] = 0,
+) -> dict:
+    token = resolve_token()
+
+    if action not in ("start", "list") and not job_name:
+        raise ToolError(f"job_name is required for action '{action}'")
+
+    if action == "start":
+        if not url:
+            raise ToolError("url is required to start a crawl")
+        url = normalize_url(url)
+        job_name = job_name or f"crawl-{int(time.time())}"
+
+        api_url = f"{EXTRACT_BASE}/{page_type or 'analyze'}"
+        if format == "markdown":
+            api_url = f"{api_url}?mode=llm"
+
+        params = {
+            "token": token,
+            "name": job_name,
+            "seeds": url,
+            "apiUrl": api_url,
+            "maxHops": hops,
+            "maxToCrawl": max_to_crawl,
+            "maxToProcess": max_to_process,
+            "restrictDomain": restrict_domain,
+            "obeyRobots": obey_robots,
+            "useProxies": use_proxies,
+            "urlCrawlPattern": url_crawl_pattern,
+            "urlProcessPattern": url_process_pattern,
+            "customHeaders": custom_headers,
+            "crawlDelay": crawl_delay if crawl_delay and crawl_delay > 0 else None,
+        }
+        response = await request(CRAWL_ENDPOINT, params=params)
+        return {"job_name": job_name, "response": response}
+
+    if action == "status":
+        response = await request(CRAWL_ENDPOINT, params={"token": token, "name": job_name})
+        jobs = response.get("jobs") or []
+        if not jobs:
+            raise ToolError(f"No crawl job named '{job_name}'")
+        return job_summary(jobs[0])
+
+    if action == "list":
+        response = await request(CRAWL_ENDPOINT, params={"token": token})
+        return {"jobs": [job_summary(job) for job in response.get("jobs") or []]}
+
+    if action == "delete":
+        response = await request(CRAWL_ENDPOINT, params={"token": token, "name": job_name, "delete": 1})
+        return {"job_name": job_name, "response": response}
+
+    if action == "urls":
+        text = await request(f"{CRAWL_ENDPOINT}/data", params={"token": token, "name": job_name, "type": "urls"}, as_text=True)
+        rows = []
+        for row in csv.DictReader(io.StringIO(text or "")):
+            page_url = (row.get("Url") or "").strip().strip('"')
+            if page_url:
+                rows.append({
+                    "url": page_url,
+                    "status": (row.get("Crawl Status") or "unknown").strip(),
+                    "crawled": (row.get("Crawled Time") or "").strip() or None,
+                })
+        return {
+            "job_name": job_name,
+            "total_urls": len(rows),
+            "offset": offset,
+            "urls": rows[offset:offset + max_results],
+        }
+
+    response = await request(f"{CRAWL_ENDPOINT}/data", params={"token": token, "name": job_name, "format": "json"})
+    if isinstance(response, dict):
+        if response.get("error"):
+            raise ToolError(f"{response['error']} (job '{job_name}')")
+        response = response.get("objects") or []
+
+    return {
+        "job_name": job_name,
+        "total_results": len(response),
+        "offset": offset,
+        "results": response[offset:offset + max_results],
+    }

diffbot_mcp/tools/deals.py

@@ -0,0 +1,234 @@
+from typing import Annotated, List, Literal, Optional
+
+from fastmcp.exceptions import ToolError
+
+from ..app import READ_ONLY, mcp
+from ..dql import DEFAULT_FIELDS, clean_value, resolve_value, run
+from ..dql_builder import build, clause, compare, date_range, sort_clause, subquery, parse_range
+
+DESCRIPTION = (
+    "Funding rounds, investments, and acquisitions in the Diffbot Knowledge Graph by company, investor, acquirer, "
+    "round series, amount, date, or the company's industry. Prefer for deal flow, a company's funding history, an "
+    "investor's portfolio activity, M&A lists, and the largest deals in a period. For related company data use "
+    "search_organizations."
+    " API docs: https://www.diffbot.com/docs/dql/"
+)
+
+Kind = Literal["funding", "acquisitions", "any"]
+Sort = Literal["newest", "largest"]
+Facet = Literal["series", "investors", "amount"]
+
+ACQUISITION_FIELDS = (
+    "name,Target;acquiredBy.name,Acquirer;acquiredBy.amount.value,Amount;acquiredBy.amount.currency,Currency;"
+    "acquiredBy.date.str,Date;categories.name,Industry;id,Id"
+)
+INDUSTRY_GET = "get:id,name,investments,categories"
+
+
+def build_deals_query(
+    *,
+    kind: Kind = "funding",
+    company: Optional[str] = None,
+    investor: Optional[str] = None,
+    acquirer: Optional[str] = None,
+    series: Optional[str] = None,
+    min_amount: Optional[float] = None,
+    max_amount: Optional[float] = None,
+    currency: Optional[str] = "USD",
+    since: Optional[str] = None,
+    until: Optional[str] = None,
+    industry: Optional[str] = None,
+    sort: Optional[Sort] = None,
+    facet: Optional[Facet] = None,
+) -> tuple:
+    """Return (dql, fields, mode) where mode is 'rows' or 'industry' (company-side json read). industry must already be an exact OrganizationCategory value."""
+    sort = sort or "newest"
+    if kind == "acquisitions":
+        clauses = ["type:Organization", "isAcquired:true"]
+        if company:
+            clauses.append(clause("name", company, strict=True))
+        if acquirer:
+            clauses.append(clause("acquiredBy.name", acquirer))
+        if investor:
+            raise ToolError("investor does not apply to acquisitions; use acquirer.")
+        if series:
+            raise ToolError("series does not apply to acquisitions.")
+        if industry:
+            clauses.append(clause("categories.name", industry))
+        if min_amount is not None:
+            clauses.append(compare("acquiredBy.amount.value", ">=", min_amount))
+        if max_amount is not None:
+            clauses.append(compare("acquiredBy.amount.value", "<=", max_amount))
+        if (min_amount is not None or max_amount is not None) and currency:
+            clauses.append(clause("acquiredBy.amount.currency", currency))
+        clauses.extend(date_range("acquiredBy.date", since, until))
+        if facet:
+            facet_field = {"investors": "acquiredBy.name", "amount": "acquiredBy.amount.value"}.get(facet)
+            if not facet_field:
+                raise ToolError("facet 'series' does not apply to acquisitions.")
+            clauses.append(f"facet:{facet_field}")
+        elif sort:
+            clauses.append(sort_clause("acquiredBy.date" if sort == "newest" else "acquiredBy.amount.value"))
+        return build(clauses), ACQUISITION_FIELDS, "rows"
+
+    if kind == "funding" and industry:
+        # investee is a bare LinkedEntity with no categories, so the industry lives on the
+        # company; the round's conditions are co-constrained on one investment with {}
+        round_conditions = []
+        if series:
+            round_conditions.append(clause("series", series))
+        if investor:
+            round_conditions.append(clause("investors.name", investor))
+        if min_amount is not None:
+            round_conditions.append(compare("amount.value", ">=", min_amount))
+        if max_amount is not None:
+            round_conditions.append(compare("amount.value", "<=", max_amount))
+        if (min_amount is not None or max_amount is not None) and currency:
+            round_conditions.append(clause("amount.currency", currency))
+        round_conditions.extend(date_range("date", since, until))
+        clauses = ["type:Organization", clause("categories.name", industry)]
+        if company:
+            clauses.append(clause("name", company, strict=True))
+        clauses.append(subquery("investments", round_conditions) if round_conditions else "has:investments")
+        if facet:
+            raise ToolError("facet does not combine with industry; drop industry or facet.")
+        if sort:
+            clauses.append(sort_clause("investments.date" if sort == "newest" else "investments.amount.value"))
+        return build(clauses), None, "industry"
+
+    if kind == "funding":
+        clauses = ["type:Investment"]
+        company_field, investor_field, amount_field, date_field = "investee.name", "investment.investors.name", "investment.amount", "investment.date"
+    else:
+        clauses = ["type:Transaction"]
+        company_field, investor_field, amount_field, date_field = "payee.name", "payers.name", "amount", "date"
+        if series:
+            raise ToolError("series applies to kind 'funding' only.")
+        if industry:
+            raise ToolError("industry applies to kind 'funding' or 'acquisitions'.")
+
+    if company:
+        clauses.append(clause(company_field, company))
+    if investor or acquirer:
+        clauses.append(clause(investor_field, investor or acquirer))
+    if series:
+        clauses.append(clause("investment.series", series))
+    if min_amount is not None:
+        clauses.append(compare(f"{amount_field}.value", ">=", min_amount))
+    if max_amount is not None:
+        clauses.append(compare(f"{amount_field}.value", "<=", max_amount))
+    if (min_amount is not None or max_amount is not None) and currency:
+        clauses.append(clause(f"{amount_field}.currency", currency))
+    clauses.extend(date_range(date_field, since, until))
+
+    if len(clauses) == 1:
+        raise ToolError("search_deals needs at least one filter.")
+
+    if facet:
+        facet_field = {"series": "investment.series", "investors": investor_field, "amount": f"{amount_field}.value"}[facet]
+        if kind == "any" and facet == "series":
+            raise ToolError("facet 'series' applies to kind 'funding' only.")
+        clauses.append(f"facet:{facet_field}")
+    elif sort:
+        clauses.append(sort_clause(date_field if sort == "newest" else f"{amount_field}.value"))
+    fields = DEFAULT_FIELDS["Investment" if kind == "funding" else "Transaction"]
+    return build(clauses), fields, "rows"
+
+
+def plain_number(value):
+    """json amounts arrive as floats; render integral ones as ints so rows match the csv form."""
+    if isinstance(value, float) and value.is_integer():
+        return int(value)
+    return value
+
+
+def investment_matches(investment: dict, *, series, investor, min_amount, max_amount, currency, since, until) -> bool:
+    amount = investment.get("amount") or {}
+    value = amount.get("value")
+    if min_amount is not None and (value is None or value < min_amount):
+        return False
+    if max_amount is not None and (value is None or value > max_amount):
+        return False
+    if (min_amount is not None or max_amount is not None) and currency and amount.get("currency") and amount["currency"] != currency:
+        return False
+    if series and series.lower() not in (investment.get("series") or "").lower():
+        return False
+    if investor and not any(investor.lower() in (i.get("name") or "").lower() for i in investment.get("investors") or []):
+        return False
+    date = clean_value((investment.get("date") or {}).get("str") or "")[:10]
+    if since and (not date or date < since):
+        return False
+    if until and (not date or date > until):
+        return False
+    return True
+
+
+def render_company_rounds(entity: dict, **conditions) -> List[dict]:
+    rows = []
+    for investment in entity.get("investments") or []:
+        if not investment_matches(investment, **conditions):
+            continue
+        amount = investment.get("amount") or {}
+        row = {
+            "Company": entity.get("name"),
+            "Round": investment.get("series"),
+            "Amount": plain_number(amount.get("value")),
+            "Currency": amount.get("currency"),
+            "Date": clean_value((investment.get("date") or {}).get("str") or "")[:10] or None,
+            "Investors": ", ".join(i.get("name") for i in investment.get("investors") or [] if i.get("name")) or None,
+            "Company Id": entity.get("id"),
+        }
+        rows.append({key: value for key, value in row.items() if value is not None and value != ""})
+    return rows
+
+
+@mcp.tool(name="search_deals", title="Search Deals", description=DESCRIPTION, annotations=READ_ONLY)
+async def search_deals(
+    kind: Annotated[Kind, "funding | acquisitions | any"] = "funding",
+    company: Annotated[Optional[str], "Company raising or acquired"] = None,
+    investor: Annotated[Optional[str], "Investor name"] = None,
+    acquirer: Annotated[Optional[str], "Acquirer name"] = None,
+    series: Annotated[Optional[str], "Round, e.g. 'Series A'"] = None,
+    amount: Annotated[Optional[str], "Deal size range, e.g. '50M+', '1M-10M'"] = None,
+    currency: Annotated[Optional[str], "Currency of amount"] = "USD",
+    since: Annotated[Optional[str], "Earliest date, YYYY-MM-DD"] = None,
+    until: Annotated[Optional[str], "Latest date, YYYY-MM-DD"] = None,
+    industry: Annotated[Optional[str], "Company's industry; free text ok"] = None,
+    sort: Annotated[Optional[Sort], "Default newest; `largest` for biggest deals first"] = None,
+    facet: Annotated[Optional[Facet], "Bucket by series, investors, or amount"] = None,
+    size: Annotated[int, "Max rows or buckets"] = 10,
+    offset: Annotated[int, "Rows to skip"] = 0,
+) -> dict:
+    min_amount, max_amount = parse_range(amount, "amount")
+    notes: List[str] = []
+    if industry:
+        resolved = await resolve_value("OrganizationCategory", industry)
+        if resolved.value is None:
+            if resolved.candidates:
+                return {"dql": None, "candidates": {"industry": resolved.candidates}, "notes": [resolved.note]}
+            raise ToolError(resolved.note)
+        industry = resolved.value
+        if resolved.note:
+            notes.append(resolved.note)
+
+    query, fields, mode = build_deals_query(
+        kind=kind, company=company, investor=investor, acquirer=acquirer, series=series, min_amount=min_amount,
+        max_amount=max_amount, currency=currency, since=since, until=until, industry=industry, sort=sort, facet=facet,
+    )
+
+    if mode == "industry":
+        result = await run(f"{query} {INDUSTRY_GET}", size=size, offset=offset, format="json", bare_type_check=True)
+        conditions = dict(series=series, investor=investor, min_amount=min_amount, max_amount=max_amount, currency=currency, since=since, until=until)
+        rows = []
+        for entity in result.get("results") or []:
+            rows.extend(render_company_rounds(entity, **conditions))
+        result["dql"] = query
+        result["results"] = rows
+        result["returned"] = len(rows)
+        notes.append("hits counts companies in the industry with a matching round; results list each matching round per company.")
+    else:
+        result = await run(query, size=size, offset=offset, fields=fields, bare_type_check=True)
+
+    if notes:
+        result["notes"] = result.get("notes", []) + notes
+    return result