diffbot-mcp 0.2.0__py3-none-any.whl

diffbot_mcp/tools/dql.py

@@ -0,0 +1,28 @@
+from typing import Annotated, Literal, Optional
+
+from ..app import READ_ONLY, mcp
+from ..dql import run
+
+DESCRIPTION = (
+    "Runs a raw DQL query against the Diffbot Knowledge Graph. Prefer for entity types and query shapes the typed "
+    "search tools do not cover: products, patents, job posts, facet aggregations, cross-entity queries, or an id "
+    "filter from resolve_entities. Each typed tool returns the DQL it ran, which can be refined here. Conditions "
+    "on one nested list object go inside one {} block, e.g. employments.{employer.name:X isCurrent:true}. Confirm "
+    "field paths and taxonomy spellings with `dql_ontology`, since an unknown path is silently ignored. Do not add "
+    "a sort unless ordering is the question. Check hit counts with `dql_probe` before pulling rows. For a CSV "
+    "file, do not page rows: GET https://kg.diffbot.com/kg/v3/dql?token=..&format=csv&size=<hits>"
+    "&exportspec=<fields>&query=<DQL> for a download URL or save to disk."
+    " API docs: https://www.diffbot.com/docs/dql/"
+)
+
+
+@mcp.tool(name="dql", title="Run DQL Query", description=DESCRIPTION, annotations=READ_ONLY)
+async def dql(
+    query: Annotated[str, "DQL, starting with type:X"],
+    size: Annotated[int, "Max rows or buckets"] = 10,
+    offset: Annotated[int, "Rows to skip"] = 0,
+    fields: Annotated[Optional[str], "CSV columns as 'path,Label;path,Label'; default per entity type"] = None,
+    format: Annotated[Literal["csv", "json"], "'json' for full records; add get:a,b to query to limit"] = "csv",
+    hits_only: Annotated[bool, "Count only"] = False,
+) -> dict:
+    return await run(query, size=size, offset=offset, fields=fields, format=format, hits_only=hits_only)

diffbot_mcp/tools/dql_ontology.py

@@ -0,0 +1,50 @@
+import re
+from typing import Annotated, Literal, Optional
+
+from fastmcp.exceptions import ToolError
+
+from ..app import READ_ONLY, mcp
+from ..dql import enum_values, find_named, get_ontology, ontology_fields, ontology_names, rank_names, taxonomy_values
+
+DESCRIPTION = (
+    "Looks up the Knowledge Graph ontology: entity types, their fields, and taxonomy or enum values. Use before "
+    "raw dql to confirm a field path exists and to get the exact spelling of a value (a guessed path is silently "
+    "ignored, a guessed value returns zero). Results are ranked best match first."
+    " API docs: https://docs.diffbot.com/docs/ontology"
+)
+
+
+@mcp.tool(name="dql_ontology", title="Look Up DQL Ontology", description=DESCRIPTION, annotations=READ_ONLY)
+async def dql_ontology(
+    action: Annotated[Literal["types", "composites", "enums", "taxonomies", "fields", "taxonomy", "enum", "search"], "types and composites list entity types and nested object types; enums and taxonomies list value-set names; fields lists a type's or composite's fields (needs name); taxonomy or enum lists one value set (needs name); search matches names across everything (needs search)"],
+    name: Annotated[Optional[str], "Type or composite (fields), or taxonomy/enum name"] = None,
+    search: Annotated[Optional[str], "Case-insensitive regex filter"] = None,
+    limit: Annotated[int, "Max results; total is always reported"] = 25,
+) -> dict:
+    ontology = await get_ontology()
+    pattern = re.compile(search, re.IGNORECASE) if search else None
+
+    if action in ("fields", "taxonomy", "enum") and not name:
+        raise ToolError(f"name is required for action '{action}'")
+    if action == "search" and pattern is None:
+        raise ToolError("search is required for action 'search'")
+
+    if action in ("types", "composites", "enums", "taxonomies"):
+        results = ontology_names(ontology, action)
+    elif action == "fields":
+        results = ontology_fields(ontology, name, pattern)
+    elif action == "taxonomy":
+        results = taxonomy_values(ontology, name, pattern)
+        if pattern is not None:
+            results = rank_names(results, pattern)
+    elif action == "enum":
+        results = enum_values(ontology, name)
+    else:
+        results = find_named(ontology, pattern)
+
+    return {
+        "action": action,
+        "total": len(results),
+        "returned": min(len(results), limit),
+        "results": results[:limit],
+    }

diffbot_mcp/tools/dql_probe.py

@@ -0,0 +1,18 @@
+from typing import Annotated, List
+
+from ..app import READ_ONLY, mcp
+from ..dql import probe
+
+DESCRIPTION = (
+    "Hit counts for several DQL queries at once, to compare variants before pulling rows (co-constrained {} vs "
+    "loose, category vs descriptors). Zero hits means a wrong value (check dql_ontology); a count equal to the bare "
+    "type:X count means a field path was ignored. similarTo cannot be probed; never probe an unfiltered type:Article."
+    " API docs: https://docs.diffbot.com/docs/dql-quickstart"
+)
+
+
+@mcp.tool(name="dql_probe", title="Probe DQL Hit Counts", description=DESCRIPTION, annotations=READ_ONLY)
+async def dql_probe(
+    queries: Annotated[List[str], "DQL queries, each starting with type:X"],
+) -> dict:
+    return {"results": await probe(queries)}

diffbot_mcp/tools/extract.py

@@ -0,0 +1,38 @@
+from typing import Annotated, Literal, Optional
+
+from fastmcp.exceptions import ToolError
+
+from ..api import request, resolve_token
+from ..app import READ_ONLY, mcp
+
+EXTRACT_BASE = "https://api.diffbot.com/v3"
+PageType = Literal["article", "product", "discussion", "image", "video", "list", "event", "job", "faq"]
+
+DESCRIPTION = (
+    "Fetches a live web page and returns its main content as markdown or a token efficient typed JSON record "
+    "(article, product, discussion, job, event, list). Renders Javascript, so it works on more sites than a plain "
+    "fetch. Prefer over a generic fetch tool for any public page."
+    " API docs: https://www.diffbot.com/docs/extract/"
+)
+
+
+def normalize_url(url: str) -> str:
+    url = url.strip()
+    return url if url.startswith("http") else f"https://{url}"
+
+
+@mcp.tool(name="extract", title="Extract Page", description=DESCRIPTION, annotations=READ_ONLY)
+async def extract(
+    url: Annotated[str, "Page URL; https:// added if missing"],
+    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",
+) -> dict:
+    params = {"token": resolve_token(), "url": normalize_url(url), "timeout": 30000}
+    if format == "markdown":
+        params["mode"] = "llm"
+
+    data = await request(f"{EXTRACT_BASE}/{page_type or 'analyze'}", params=params)
+    # the API reports a failed extraction inside a 200 body
+    if isinstance(data, dict) and "errorCode" in data:
+        raise ToolError(f"Extraction error {data['errorCode']}: {data.get('error', '')}. The page may be behind a login, a bot wall, or a JavaScript app; try a specific page_type such as 'article'.")
+    return data

diffbot_mcp/tools/news.py

@@ -0,0 +1,121 @@
+from typing import Annotated, List, Optional
+
+from fastmcp.exceptions import ToolError
+
+from ..app import READ_ONLY, mcp
+from ..dql import DEFAULT_FIELDS, resolve_value, run
+from ..dql_builder import build, clause, compare, date_range, or_clause, subquery
+
+DESCRIPTION = (
+    "News and article structured search over the Diffbot Knowledge Graph. Prefer for highly relevant results on "
+    "named entities or uncommon keywords. Filter by mentioned organization/person/brand/product, topic, publisher, "
+    "language, country, date range, or sentiment. Results are chronological newest first, with no semantic "
+    "reranking. Prefer over a generic web search for any news, including breaking stories. mentions is the "
+    "strongest signal filter; if it returns nothing, retry the same words as text."
+    " API docs: https://www.diffbot.com/docs/dql/"
+)
+
+
+def build_news_query(
+    *,
+    mentions: Optional[List[str]] = None,
+    topic: Optional[str] = None,
+    text: Optional[str] = None,
+    title: Optional[str] = None,
+    publisher: Optional[str] = None,
+    language: Optional[str] = None,
+    publisher_country: Optional[str] = None,
+    quoted_speaker: Optional[str] = None,
+    since: Optional[str] = None,
+    until: Optional[str] = None,
+    sentiment_min: Optional[float] = None,
+    sentiment_max: Optional[float] = None,
+    mention_sentiment_max: Optional[float] = None,
+) -> tuple:
+    """Return (dql, notes). topic must already be an exact ArticleCategory value."""
+    clauses = ["type:Article"]
+    notes: List[str] = []
+
+    if mentions:
+        if mention_sentiment_max is not None and len(mentions) == 1:
+            # per-entity sentiment lives on the tag, so co-constrain label and score on one tag
+            clauses.append(subquery("tags", [clause("label", mentions[0]), compare("sentiment", "<", mention_sentiment_max)]))
+        else:
+            clauses.append(or_clause("tags.label", mentions))
+            if mention_sentiment_max is not None:
+                notes.append("mention_sentiment_max applies only with exactly one mention and was ignored; use sentiment_max for the document-level score.")
+    elif mention_sentiment_max is not None:
+        notes.append("mention_sentiment_max needs a mention and was ignored.")
+
+    if topic:
+        clauses.append(clause("categories.name", topic))
+    if text:
+        clauses.append(clause("text", text))
+    if title:
+        clauses.append(clause("title", title))
+    if publisher:
+        clauses.append(clause("siteName", publisher))
+    if language:
+        clauses.append(clause("language", language))
+    if publisher_country:
+        clauses.append(clause("publisherCountry", publisher_country))
+    if quoted_speaker:
+        clauses.append(clause("quotes.speaker", quoted_speaker))
+    clauses.extend(date_range("date", since, until))
+    if sentiment_min is not None:
+        clauses.append(compare("sentiment", ">=", sentiment_min))
+    if sentiment_max is not None:
+        clauses.append(compare("sentiment", "<=", sentiment_max))
+
+    if len(clauses) == 1:
+        raise ToolError("search_news needs at least one narrowing parameter (mentions, topic, text, title, publisher, quoted_speaker, or a date range); an unfiltered article query times out.")
+
+    clauses.append("sortBy:date")
+    return build(clauses), notes
+
+
+@mcp.tool(name="search_news", title="Search News", description=DESCRIPTION, annotations=READ_ONLY)
+async def search_news(
+    mentions: Annotated[Optional[List[str]], "Organizations, people, brand, product or entities the article must mention (OR)"] = None,
+    topic: Annotated[Optional[str], "Topic category; free text ok"] = None,
+    text: Annotated[Optional[str], "Phrase in article body. Use for uncommon phrases or as a fallback to mentions"] = None,
+    title: Annotated[Optional[str], "Phrase in the headline"] = None,
+    publisher: Annotated[Optional[str], "Publisher site, e.g. Reuters"] = None,
+    language: Annotated[Optional[str], "ISO code, e.g. en"] = None,
+    publisher_country: Annotated[Optional[str], "Publisher's country, e.g. United States"] = None,
+    quoted_speaker: Annotated[Optional[str], "Person quoted in the article"] = None,
+    since: Annotated[Optional[str], "Earliest date, YYYY-MM-DD"] = None,
+    until: Annotated[Optional[str], "Latest date, YYYY-MM-DD"] = None,
+    sentiment_min: Annotated[Optional[float], "Document sentiment floor, -1..1"] = None,
+    sentiment_max: Annotated[Optional[float], "Document sentiment ceiling, -1..1"] = None,
+    mention_sentiment_max: Annotated[Optional[float], "Sentiment ceiling toward the one mention"] = None,
+    size: Annotated[int, "Max rows"] = 10,
+    offset: Annotated[int, "Rows to skip"] = 0,
+) -> dict:
+    notes: List[str] = []
+    if topic:
+        resolved = await resolve_value("ArticleCategory", topic)
+        if resolved.value is None:
+            if resolved.candidates:
+                return {"dql": None, "candidates": {"topic": resolved.candidates}, "notes": [resolved.note]}
+            notes.append(f"{resolved.note}; searched the article text for '{topic}' instead.")
+            text = f"{text} {topic}".strip() if text else topic
+            topic = None
+        else:
+            topic = resolved.value
+            if resolved.note:
+                notes.append(resolved.note)
+
+    query, build_notes = build_news_query(
+        mentions=mentions, topic=topic, text=text, title=title, publisher=publisher, language=language,
+        publisher_country=publisher_country, quoted_speaker=quoted_speaker, since=since, until=until,
+        sentiment_min=sentiment_min, sentiment_max=sentiment_max, mention_sentiment_max=mention_sentiment_max,
+    )
+    notes.extend(build_notes)
+
+    result = await run(query, size=size, offset=offset, fields=DEFAULT_FIELDS["Article"])
+    if result.get("hits") == 0 and mentions and not text:
+        notes.append("No article carries that tag. Tag values are entity names that may not match; retry with the same words in text.")
+    if notes:
+        result["notes"] = result.get("notes", []) + notes
+    return result

diffbot_mcp/tools/organizations.py

@@ -0,0 +1,191 @@
+from typing import Annotated, List, Literal, Optional, Union
+
+from fastmcp.exceptions import ToolError
+
+from ..app import READ_ONLY, mcp
+from ..dql import DEFAULT_FIELDS, resolve_value, run
+from ..dql_builder import build, clause, compare, looks_like_domain, near_clause, or_clause, sort_clause, validate_date, subquery, parse_date_range, parse_range, split_near
+
+DESCRIPTION = (
+    "Company and organization structured search over the Diffbot Knowledge Graph. Prefer for prospect lists, "
+    "market maps, competitor sets, and firmographic facts on a market or named company(ies). Filter by industry, "
+    "location, headcount, revenue, founding date, public status, founder, investor, acquirer, parent company. "
+    "Prefer over a generic web search when answer involves structured company data. For investment data use "
+    "search_deals; for people use search_people."
+    " API docs: https://www.diffbot.com/docs/dql/"
+)
+
+Sort = Literal["employees", "revenue", "founded", "importance"]
+SORT_FIELDS = {"employees": "nbEmployees", "revenue": "revenue.value", "founded": "foundingDate", "importance": "importance"}
+
+
+def build_organizations_query(
+    *,
+    name: Optional[Union[str, List[str]]] = None,
+    name_match: Literal["strict", "contains"] = "strict",
+    homepage: Optional[str] = None,
+    industry: Optional[List[str]] = None,
+    primary_industry: bool = True,
+    descriptors: Optional[str] = None,
+    city: Optional[Union[str, List[str]]] = None,
+    region: Optional[str] = None,
+    country: Optional[str] = None,
+    any_office: bool = False,
+    near: Optional[str] = None,
+    radius: Optional[str] = None,
+    min_employees: Optional[int] = None,
+    max_employees: Optional[int] = None,
+    min_revenue: Optional[float] = None,
+    max_revenue: Optional[float] = None,
+    is_public: Optional[bool] = None,
+    founded_after: Optional[str] = None,
+    founded_before: Optional[str] = None,
+    founder: Optional[str] = None,
+    investor: Optional[str] = None,
+    series: Optional[str] = None,
+    acquired_by: Optional[str] = None,
+    subsidiary: Optional[str] = None,
+    part_of: Optional[str] = None,
+    similar_to: Optional[str] = None,
+    sort: Optional[Sort] = None,
+    facet: Optional[str] = None,
+) -> str:
+    """industry values must already be exact OrganizationCategory names."""
+    clauses = ["type:Organization"]
+
+    if similar_to:
+        anchor = clause("homepageUri", similar_to) if looks_like_domain(similar_to) else clause("name", similar_to)
+        clauses.append(f"similarTo({anchor})")
+    if name:
+        names = [name] if isinstance(name, str) else list(name)
+        clauses.append(or_clause("name", names, strict=name_match == "strict"))
+    if homepage:
+        clauses.append(clause("homepageUri", homepage))
+    if industry:
+        if primary_industry:
+            # categories.{...} co-constrains name and isPrimary on the same category entry;
+            # the loose categories.name form also matches secondary tags (hospitals tagged software).
+            clauses.append(subquery("categories", [or_clause("name", industry), "isPrimary:true"]))
+        else:
+            clauses.append(or_clause("categories.name", industry))
+    if descriptors:
+        clauses.append(clause("descriptors", descriptors))
+
+    # singular location is the headquarters; plural locations is any office
+    prefix = "locations" if any_office else "location"
+    for level, value in (("city", city), ("region", region), ("country", country)):
+        if value:
+            values = [value] if isinstance(value, str) else list(value)
+            clauses.append(or_clause(f"{prefix}.{level}.name", values))
+    if near:
+        clauses.append(near_clause(near, radius))
+
+    if min_employees is not None:
+        clauses.append(compare("nbEmployees", ">=", min_employees))
+    if max_employees is not None:
+        clauses.append(compare("nbEmployees", "<=", max_employees))
+    if min_revenue is not None:
+        clauses.append(compare("revenue.value", ">=", min_revenue))
+    if max_revenue is not None:
+        clauses.append(compare("revenue.value", "<=", max_revenue))
+    if is_public is not None:
+        clauses.append(f"isPublic:{'true' if is_public else 'false'}")
+    if founded_after:
+        clauses.append(compare("foundingDate", ">=", validate_date(founded_after, "founded_after")))
+    if founded_before:
+        clauses.append(compare("foundingDate", "<=", validate_date(founded_before, "founded_before")))
+    if founder:
+        clauses.append(clause("founders.name", founder))
+    if investor:
+        clauses.append(clause("investments.investors.name", investor))
+    if series:
+        clauses.append(clause("investments.series", series))
+    if acquired_by:
+        clauses.append("isAcquired:true")
+        clauses.append(clause("acquiredBy.name", acquired_by))
+    if subsidiary:
+        clauses.append(clause("subsidiaries.name", subsidiary))
+    if part_of:
+        clauses.append(clause("partOf.name", part_of))
+
+    if len(clauses) == 1:
+        raise ToolError("search_organizations needs at least one filter.")
+
+    if facet:
+        clauses.append(f"facet:{facet}")
+    elif sort:
+        clauses.append(sort_clause(SORT_FIELDS[sort], descending=True))
+    return build(clauses)
+
+
+@mcp.tool(name="search_organizations", title="Search Organizations", description=DESCRIPTION, annotations=READ_ONLY)
+async def search_organizations(
+    name: Annotated[Optional[Union[str, List[str]]], "Company name(s) or homepage domain"] = None,
+    industry: Annotated[Optional[List[str]], "Industries (OR); free text ok"] = None,
+    primary_industry: Annotated[bool, "False: also match secondary tags"] = True,
+    descriptors: Annotated[Optional[str], "Free-text niche, e.g. 'plant-based'"] = None,
+    city: Annotated[Optional[Union[str, List[str]]], "HQ city or cities"] = None,
+    region: Annotated[Optional[str], "HQ state/region"] = None,
+    country: Annotated[Optional[str], "HQ country"] = None,
+    near: Annotated[Optional[str], "Place and radius, e.g. 'Austin 30mi'"] = None,
+    revenue: Annotated[Optional[str], "Range, e.g. '10M-75M', '1B+'"] = None,
+    employees: Annotated[Optional[str], "Range, e.g. '50-500', '<=20', '500+'"] = None,
+    founded: Annotated[Optional[str], "Year or range, e.g. '2015-2020'"] = None,
+    is_public: Annotated[Optional[bool], "Publicly traded"] = None,
+    founder: Annotated[Optional[str], "Founder name: companies they founded"] = None,
+    investor: Annotated[Optional[str], "Investor: its portfolio"] = None,
+    series: Annotated[Optional[str], "Funding round raised, e.g. 'Series B'"] = None,
+    acquired_by: Annotated[Optional[str], "Acquirer: its acquisitions"] = None,
+    subsidiary: Annotated[Optional[str], "Subsidiary name: its parent"] = None,
+    part_of: Annotated[Optional[str], "Index or group, e.g. 'S&P 500'"] = None,
+    similar_to: Annotated[Optional[str], "Anchor company for lookalikes"] = None,
+    sort: Annotated[Optional[Sort], "Only if ordering is the question"] = None,
+    facet: Annotated[Optional[str], "Bucket by field, e.g. categories.name"] = None,
+    size: Annotated[int, "Max rows"] = 10,
+    offset: Annotated[int, "Rows to skip"] = 0,
+) -> dict:
+    min_revenue, max_revenue = parse_range(revenue, "revenue")
+    min_employees, max_employees = parse_range(employees, "employees", integer=True)
+    founded_after, founded_before = parse_date_range(founded, "founded")
+    near, radius = split_near(near)
+    any_office = False  # headquarters only; raw dql with locations.* matches any office
+    homepage = name if isinstance(name, str) and looks_like_domain(name) else None
+    name = None if homepage else name
+
+    notes: List[str] = []
+    resolved_industry: List[str] = []
+    for value in industry or []:
+        resolved = await resolve_value("OrganizationCategory", value)
+        if resolved.value is None:
+            if resolved.candidates:
+                return {"dql": None, "candidates": {"industry": resolved.candidates}, "notes": [resolved.note]}
+            notes.append(f"{resolved.note}; matched descriptors on '{value}' instead.")
+            descriptors = descriptors or value
+        else:
+            resolved_industry.append(resolved.value)
+            if resolved.note:
+                notes.append(resolved.note)
+
+    query = build_organizations_query(
+        name=name, name_match="strict", homepage=homepage, industry=resolved_industry, primary_industry=primary_industry, descriptors=descriptors,
+        city=city, region=region, country=country, any_office=any_office, near=near, radius=radius,
+        min_employees=min_employees, max_employees=max_employees, min_revenue=min_revenue, max_revenue=max_revenue,
+        is_public=is_public,
+        founded_after=founded_after, founded_before=founded_before, founder=founder, investor=investor, series=series, acquired_by=acquired_by,
+        subsidiary=subsidiary, part_of=part_of, similar_to=similar_to, sort=sort, facet=facet,
+    )
+    result = await run(query, size=size, offset=offset, fields=DEFAULT_FIELDS["Organization"], bare_type_check=True)
+    if name and not similar_to and not facet and result.get("hits") == 0:
+        # exact name missed: retry with contains-matching, which over-matches but beats an empty answer
+        query = build_organizations_query(
+            name=name, name_match="contains", industry=resolved_industry, descriptors=descriptors,
+            city=city, region=region, country=country, any_office=any_office, near=near, radius=radius,
+            min_employees=min_employees, max_employees=max_employees, min_revenue=min_revenue, max_revenue=max_revenue,
+            is_public=is_public, founded_after=founded_after, founded_before=founded_before, founder=founder, investor=investor, series=series,
+            acquired_by=acquired_by, subsidiary=subsidiary, part_of=part_of, primary_industry=primary_industry, sort=sort,
+        )
+        result = await run(query, size=size, offset=offset, fields=DEFAULT_FIELDS["Organization"], bare_type_check=True)
+        notes.append(f"No exact match for '{name}'; showing contains-matches, which may include unrelated companies.")
+    if notes:
+        result["notes"] = result.get("notes", []) + notes
+    return result