diffbot-mcp 0.2.0__tar.gz

diffbot_mcp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Diffbot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

diffbot_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: diffbot-mcp
+Version: 0.2.0
+Summary: A Diffbot MCP server with a variety of helpful web knowledge fetching tools for your agent or LLM pipeline.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/diffbot/diffbot-mcp
+Project-URL: Repository, https://github.com/diffbot/diffbot-mcp
+Project-URL: Issues, https://github.com/diffbot/diffbot-mcp/issues
+Project-URL: Documentation, https://www.diffbot.com/docs/
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp~=4.1.0
+Requires-Dist: aiohttp~=3.14.5
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# Diffbot MCP Server
+A Diffbot MCP server with a variety of helpful web knowledge fetching tools for your agent or LLM pipeline.
+
+**What is Diffbot?**
+Diffbot is an applied AI lab building models that structure all of human knowledge. Our commercial product suite make it possible to fetch and structure knowledge at the scale of the entire public web.
+
+This is the MCP counterpart to [diffbot-skills](https://github.com/diffbot/diffbot-skills) without requiring bash access.
+
+## Tools
+
+### Web
+
+#### 🧬 extract
+**Web fetch tool alternative.** Conventional fetch tools return either 500k+ tokens of HTML or a markdown approximation of the page's content. Extract classifies the page it is fetching and extracts content into a meaningful and consistent JSON schema. Responses are optimized for minimal token usage while maintaining data fidelity. [Learn more.](https://www.diffbot.com/docs/extract/).
+
+#### 🔎 search_web
+**Web search tool that ranks accuracy, not popularity.** Built on Diffbot's independent web index. Ranking model heavily favors primary sources over secondary sources (e.g. press release > news piece on said press release). Returns markdown formatted content chunks for source citation, with `num_results` and `max_tokens` controls. [Learn more.](https://www.diffbot.com/docs/web-search/)
+
+Also includes a **page cache reader**. Query `url:<URL>` and it returns Diffbot's already-parsed copy of that page from the index in a fraction of the time for live fetch. Use it for full content from reference prose (docs, articles, papers) and reach for `extract` when the page's current state matters.
+
+#### 🕷️ crawl
+**Find all links on a web page (the seed) and extract them all.** A classic web crawl without the need for scraping rules. Crawls run as background jobs and can be polled for status. Crawl automatically classifies and structures pages in a standard ontology for easy querying. Use crawl to archive documentation, take snapshots of web projects, or site mapping. [Learn More.](https://www.diffbot.com/docs/crawl/)
+
+#### 🧠 resolve_entities
+**Recognize and resolve entities in text.** Uses Diffbot NLP to recognize organizations, people, places, addresses, and other proper nouns in text. Entities are resolved to entity IDs in the Diffbot Knowledge Graph, and the response includes a ready-made `dql_filter` (`id:or(...)`) to fetch their full records with `dql`. Use to keep AI hallucinations in check and explore deep research opportunities. [Learn more.](https://www.diffbot.com/docs/natural-language/)
+
+### Knowledge Graph
+
+The Diffbot Knowledge Graph contains over 10 billion entities: Organizations, people, news, places, and more, all linked together by their relationship to each other. It is a representation of things, facts, and connections mentioned by the trillions of websites that make up the public web. 
+
+#### 📰 search_news
+News and articles by mentioned entity, topic, publisher, language, date range, or sentiment. Newest first by default, relevance-ranked inside a date window. 
+
+#### 🏢 search_organizations
+Companies by industry, headquarters, headcount, revenue, funding, ownership, or leadership, plus `similar_to` lookalike lists for competitor mapping.
+
+#### 👤 search_people
+People by title, employer, employer industry, skills, education, location, or nationality. Covers people with a public online professional presence only.
+
+#### 🗺️ search_places
+Cities, counties, states, countries, and points of interest by name, population, prominence, containing place, or proximity.
+
+#### 💸 search_deals
+Funding rounds, investments, and acquisitions by date, size, series, investor, acquirer, or industry.
+
+#### 🎯 dql
+**Raw querying of the Diffbot Knowledge Graph.** The general-purpose layer under the five tools above, for any entity type or query shape they do not cover: products, patents, brands, job posts, cross-entity queries, and facet aggregations. Returns compact csv rows with per-type default columns, or full json records on request.
+
+#### 🔬 dql_probe
+**Parallel hit counts for several candidate queries.** The way to check that a query is neither too broad nor too narrow before pulling rows, and to compare the `{}` co-constrained form of a query against the loose one.
+
+#### 🧭 dql_ontology
+**Helper utility for accurate dql ontology navigation.** Holds the keys to Diffbot's entire ontology and taxonomy reference: entity types, fields, taxonomies, and enums. A guessed field name is silently ignored by the graph, so this is how the exact spelling gets confirmed. Humans don't need to touch this, but feel free to satisfy your curiosity.
+
+## Example Prompts
+
+```
+# extract
+→ Install Diffbot agent skills following these instructions https://www.diffbot.com/docs/interfaces/agent-skills
+
+# crawl
+→ Crawl Philips' websites for product data sheet PDFs
+
+# search_organizations
+→ AI companies based in San Francisco started by previous YC founders
+
+# search_deals
+→ recent M&As in pharma
+```
+
+## Authentication
+A free Diffbot token is required for tool use. [Get one here.](https://app.diffbot.com/get-started)
+
+MCP clients that support OAuth (Claude, Cursor, VS Code) can connect to `https://mcp.diffbot.com/mcp` without a token and sign in with a Diffbot account instead.
+
+Otherwise the server looks for a token in this order:
+
+1. `Authorization: Bearer <token>` header or `?token=<token>` query parameter (HTTP transport)
+2. `DIFFBOT_TOKEN` or `DIFFBOT_API_TOKEN` environment variable
+3. A `DIFFBOT_API_TOKEN=<token>` line in `~/.diffbot/credentials`, the same file the [`db` CLI](https://github.com/diffbot/diffbot-python) and diffbot-skills read, so one credential serves all three
+
+To enable OAuth on a self-hosted HTTP server, set:
+
+| Variable | Example |
+| --- | --- |
+| `DIFFBOT_OAUTH_ISSUER` | `https://app.diffbot.com` |
+| `MCP_BASE_URL` | Public URL of this server, e.g. `https://mcp.diffbot.com` |
+| `DIFFBOT_OAUTH_CLIENT_ID` / `DIFFBOT_OAUTH_CLIENT_SECRET` | Confidential client allowed to call the dashboard's introspection endpoint |
+
+OAuth is off when `DIFFBOT_OAUTH_ISSUER` is unset. With `docker compose`, `MCP_BASE_URL` and `DIFFBOT_OAUTH_CLIENT_ID` are set in `docker-compose.yml`; `DIFFBOT_OAUTH_ISSUER` and `DIFFBOT_OAUTH_CLIENT_SECRET` go in a `.env` next to it, which the production deploy writes from the `DIFFBOT_OAUTH_CLIENT_SECRET` GitHub Actions secret. The server runs without it.
+
+## Get Started
+
+Two ways to connect. The remote server is hosted by Diffbot and deploys from this repo. The local server runs on your machine from PyPI with [uv](https://docs.astral.sh/uv/getting-started/installation/).
+
+### Remote server
+
+```
+https://mcp.diffbot.com/mcp?token=<YOUR_DIFFBOT_TOKEN>
+```
+
+### Local server
+
+```bash
+uvx diffbot-mcp
+```
+
+`uvx` installs the package into its own environment and runs it. The process reads a token from `DIFFBOT_TOKEN`, `DIFFBOT_API_TOKEN`, or `~/.diffbot/credentials`.
+
+### Setup with MCP Clients
+
+For a local process, this config works with Claude Desktop and most other MCP clients. Follow the [official installation guide](https://modelcontextprotocol.io/docs/develop/connect-local-servers) for where the file lives.
+
+```json
+{
+    "mcpServers": {
+        "diffbot-mcp": {
+            "command": "uvx",
+            "args": ["diffbot-mcp"],
+            "env": {
+                "DIFFBOT_TOKEN": "<YOUR_DIFFBOT_TOKEN>"
+            }
+        }
+    }
+}
+```
+
+To use the remote server instead, point the client at `https://mcp.diffbot.com/mcp?token=<YOUR_DIFFBOT_TOKEN>`.
+
+For a Docker install, build the image with `docker build -t diffbot-mcp .` and use this configuration.
+
+```json
+{
+    "mcpServers": {
+        "diffbot-mcp": {
+            "command": "docker",
+            "args": [
+                "run",
+                "--rm",
+                "-i",
+                "-e", "DIFFBOT_TOKEN=<YOUR_DIFFBOT_TOKEN>",
+                "diffbot-mcp"
+            ]
+        }
+    }
+}
+```
+
+<details>
+<summary>Gemini CLI</summary>
+
+Requires [uv](https://docs.astral.sh/uv/getting-started/installation/) on `PATH`. The extension starts the server with `uvx`.
+
+```bash
+gemini extensions install https://github.com/diffbot/diffbot-mcp
+```
+
+Gemini CLI asks for a Diffbot API token on install. Leave it blank to use `~/.diffbot/credentials`.
+</details>
+
+<details>
+<summary>Visual Studio Code / Copilot</summary>
+
+For remote setup, simply enter the remote server URL and include "http" as the transport type.
+
+```json
+{
+  "servers": {
+    "diffbot-mcp": {
+      "type": "http",
+      "url": "https://mcp.diffbot.com/mcp/?token=<YOUR_DIFFBOT_TOKEN>"
+    }
+  }
+}
+```
+
+For a local server, this config prompts for the token instead of storing it in the file.
+
+```json
+{
+	"servers": {
+        "diffbot-mcp": {
+            "command": "uvx",
+            "args": ["diffbot-mcp"],
+            "env": {
+                "DIFFBOT_TOKEN": "${input:diffbot-api-key}"
+            }
+        }
+	},
+	"inputs": [
+		{
+			"password": true,
+			"id": "diffbot-api-key",
+			"type": "promptString",
+			"description": "Diffbot API Key"
+		}
+	]
+}
+```
+</details>
+
+## Development
+
+```bash
+python3 -m venv env && env/bin/pip install -e '.[dev]'
+env/bin/python -m pytest tests/test_builder.py     # generated-DQL assertions, no network
+env/bin/python tests/smoke.py                      # one live call per tool, needs a token
+env/bin/python tests/eval_routing.py               # real questions through `claude -p`, asserts tool routing; costs model tokens
+MCP_TRANSPORT=http env/bin/python diffbot_mcp_server.py & ./test.sh   # HTTP transport smoke
+```
+
+The code lives in `diffbot_mcp/`: `api.py` (token resolution and the shared request helper), `dql.py` (query execution, default columns, the cached ontology), `dql_builder.py` (pure DQL assembly), and one module per tool under `tools/`. `diffbot_mcp_server.py` is the entry point.
+
+## Help & Support
+This project is built and maintained by [@jeromechoo](https://github.com/jeromechoo). For support, file an issue and he'll get back to you as soon as he can. For faster answers, write to [sales@diffbot.com](mailto:sales@diffbot.com) 😜.

diffbot_mcp-0.2.0/README.md

@@ -0,0 +1,215 @@
+# Diffbot MCP Server
+A Diffbot MCP server with a variety of helpful web knowledge fetching tools for your agent or LLM pipeline.
+
+**What is Diffbot?**
+Diffbot is an applied AI lab building models that structure all of human knowledge. Our commercial product suite make it possible to fetch and structure knowledge at the scale of the entire public web.
+
+This is the MCP counterpart to [diffbot-skills](https://github.com/diffbot/diffbot-skills) without requiring bash access.
+
+## Tools
+
+### Web
+
+#### 🧬 extract
+**Web fetch tool alternative.** Conventional fetch tools return either 500k+ tokens of HTML or a markdown approximation of the page's content. Extract classifies the page it is fetching and extracts content into a meaningful and consistent JSON schema. Responses are optimized for minimal token usage while maintaining data fidelity. [Learn more.](https://www.diffbot.com/docs/extract/).
+
+#### 🔎 search_web
+**Web search tool that ranks accuracy, not popularity.** Built on Diffbot's independent web index. Ranking model heavily favors primary sources over secondary sources (e.g. press release > news piece on said press release). Returns markdown formatted content chunks for source citation, with `num_results` and `max_tokens` controls. [Learn more.](https://www.diffbot.com/docs/web-search/)
+
+Also includes a **page cache reader**. Query `url:<URL>` and it returns Diffbot's already-parsed copy of that page from the index in a fraction of the time for live fetch. Use it for full content from reference prose (docs, articles, papers) and reach for `extract` when the page's current state matters.
+
+#### 🕷️ crawl
+**Find all links on a web page (the seed) and extract them all.** A classic web crawl without the need for scraping rules. Crawls run as background jobs and can be polled for status. Crawl automatically classifies and structures pages in a standard ontology for easy querying. Use crawl to archive documentation, take snapshots of web projects, or site mapping. [Learn More.](https://www.diffbot.com/docs/crawl/)
+
+#### 🧠 resolve_entities
+**Recognize and resolve entities in text.** Uses Diffbot NLP to recognize organizations, people, places, addresses, and other proper nouns in text. Entities are resolved to entity IDs in the Diffbot Knowledge Graph, and the response includes a ready-made `dql_filter` (`id:or(...)`) to fetch their full records with `dql`. Use to keep AI hallucinations in check and explore deep research opportunities. [Learn more.](https://www.diffbot.com/docs/natural-language/)
+
+### Knowledge Graph
+
+The Diffbot Knowledge Graph contains over 10 billion entities: Organizations, people, news, places, and more, all linked together by their relationship to each other. It is a representation of things, facts, and connections mentioned by the trillions of websites that make up the public web. 
+
+#### 📰 search_news
+News and articles by mentioned entity, topic, publisher, language, date range, or sentiment. Newest first by default, relevance-ranked inside a date window. 
+
+#### 🏢 search_organizations
+Companies by industry, headquarters, headcount, revenue, funding, ownership, or leadership, plus `similar_to` lookalike lists for competitor mapping.
+
+#### 👤 search_people
+People by title, employer, employer industry, skills, education, location, or nationality. Covers people with a public online professional presence only.
+
+#### 🗺️ search_places
+Cities, counties, states, countries, and points of interest by name, population, prominence, containing place, or proximity.
+
+#### 💸 search_deals
+Funding rounds, investments, and acquisitions by date, size, series, investor, acquirer, or industry.
+
+#### 🎯 dql
+**Raw querying of the Diffbot Knowledge Graph.** The general-purpose layer under the five tools above, for any entity type or query shape they do not cover: products, patents, brands, job posts, cross-entity queries, and facet aggregations. Returns compact csv rows with per-type default columns, or full json records on request.
+
+#### 🔬 dql_probe
+**Parallel hit counts for several candidate queries.** The way to check that a query is neither too broad nor too narrow before pulling rows, and to compare the `{}` co-constrained form of a query against the loose one.
+
+#### 🧭 dql_ontology
+**Helper utility for accurate dql ontology navigation.** Holds the keys to Diffbot's entire ontology and taxonomy reference: entity types, fields, taxonomies, and enums. A guessed field name is silently ignored by the graph, so this is how the exact spelling gets confirmed. Humans don't need to touch this, but feel free to satisfy your curiosity.
+
+## Example Prompts
+
+```
+# extract
+→ Install Diffbot agent skills following these instructions https://www.diffbot.com/docs/interfaces/agent-skills
+
+# crawl
+→ Crawl Philips' websites for product data sheet PDFs
+
+# search_organizations
+→ AI companies based in San Francisco started by previous YC founders
+
+# search_deals
+→ recent M&As in pharma
+```
+
+## Authentication
+A free Diffbot token is required for tool use. [Get one here.](https://app.diffbot.com/get-started)
+
+MCP clients that support OAuth (Claude, Cursor, VS Code) can connect to `https://mcp.diffbot.com/mcp` without a token and sign in with a Diffbot account instead.
+
+Otherwise the server looks for a token in this order:
+
+1. `Authorization: Bearer <token>` header or `?token=<token>` query parameter (HTTP transport)
+2. `DIFFBOT_TOKEN` or `DIFFBOT_API_TOKEN` environment variable
+3. A `DIFFBOT_API_TOKEN=<token>` line in `~/.diffbot/credentials`, the same file the [`db` CLI](https://github.com/diffbot/diffbot-python) and diffbot-skills read, so one credential serves all three
+
+To enable OAuth on a self-hosted HTTP server, set:
+
+| Variable | Example |
+| --- | --- |
+| `DIFFBOT_OAUTH_ISSUER` | `https://app.diffbot.com` |
+| `MCP_BASE_URL` | Public URL of this server, e.g. `https://mcp.diffbot.com` |
+| `DIFFBOT_OAUTH_CLIENT_ID` / `DIFFBOT_OAUTH_CLIENT_SECRET` | Confidential client allowed to call the dashboard's introspection endpoint |
+
+OAuth is off when `DIFFBOT_OAUTH_ISSUER` is unset. With `docker compose`, `MCP_BASE_URL` and `DIFFBOT_OAUTH_CLIENT_ID` are set in `docker-compose.yml`; `DIFFBOT_OAUTH_ISSUER` and `DIFFBOT_OAUTH_CLIENT_SECRET` go in a `.env` next to it, which the production deploy writes from the `DIFFBOT_OAUTH_CLIENT_SECRET` GitHub Actions secret. The server runs without it.
+
+## Get Started
+
+Two ways to connect. The remote server is hosted by Diffbot and deploys from this repo. The local server runs on your machine from PyPI with [uv](https://docs.astral.sh/uv/getting-started/installation/).
+
+### Remote server
+
+```
+https://mcp.diffbot.com/mcp?token=<YOUR_DIFFBOT_TOKEN>
+```
+
+### Local server
+
+```bash
+uvx diffbot-mcp
+```
+
+`uvx` installs the package into its own environment and runs it. The process reads a token from `DIFFBOT_TOKEN`, `DIFFBOT_API_TOKEN`, or `~/.diffbot/credentials`.
+
+### Setup with MCP Clients
+
+For a local process, this config works with Claude Desktop and most other MCP clients. Follow the [official installation guide](https://modelcontextprotocol.io/docs/develop/connect-local-servers) for where the file lives.
+
+```json
+{
+    "mcpServers": {
+        "diffbot-mcp": {
+            "command": "uvx",
+            "args": ["diffbot-mcp"],
+            "env": {
+                "DIFFBOT_TOKEN": "<YOUR_DIFFBOT_TOKEN>"
+            }
+        }
+    }
+}
+```
+
+To use the remote server instead, point the client at `https://mcp.diffbot.com/mcp?token=<YOUR_DIFFBOT_TOKEN>`.
+
+For a Docker install, build the image with `docker build -t diffbot-mcp .` and use this configuration.
+
+```json
+{
+    "mcpServers": {
+        "diffbot-mcp": {
+            "command": "docker",
+            "args": [
+                "run",
+                "--rm",
+                "-i",
+                "-e", "DIFFBOT_TOKEN=<YOUR_DIFFBOT_TOKEN>",
+                "diffbot-mcp"
+            ]
+        }
+    }
+}
+```
+
+<details>
+<summary>Gemini CLI</summary>
+
+Requires [uv](https://docs.astral.sh/uv/getting-started/installation/) on `PATH`. The extension starts the server with `uvx`.
+
+```bash
+gemini extensions install https://github.com/diffbot/diffbot-mcp
+```
+
+Gemini CLI asks for a Diffbot API token on install. Leave it blank to use `~/.diffbot/credentials`.
+</details>
+
+<details>
+<summary>Visual Studio Code / Copilot</summary>
+
+For remote setup, simply enter the remote server URL and include "http" as the transport type.
+
+```json
+{
+  "servers": {
+    "diffbot-mcp": {
+      "type": "http",
+      "url": "https://mcp.diffbot.com/mcp/?token=<YOUR_DIFFBOT_TOKEN>"
+    }
+  }
+}
+```
+
+For a local server, this config prompts for the token instead of storing it in the file.
+
+```json
+{
+	"servers": {
+        "diffbot-mcp": {
+            "command": "uvx",
+            "args": ["diffbot-mcp"],
+            "env": {
+                "DIFFBOT_TOKEN": "${input:diffbot-api-key}"
+            }
+        }
+	},
+	"inputs": [
+		{
+			"password": true,
+			"id": "diffbot-api-key",
+			"type": "promptString",
+			"description": "Diffbot API Key"
+		}
+	]
+}
+```
+</details>
+
+## Development
+
+```bash
+python3 -m venv env && env/bin/pip install -e '.[dev]'
+env/bin/python -m pytest tests/test_builder.py     # generated-DQL assertions, no network
+env/bin/python tests/smoke.py                      # one live call per tool, needs a token
+env/bin/python tests/eval_routing.py               # real questions through `claude -p`, asserts tool routing; costs model tokens
+MCP_TRANSPORT=http env/bin/python diffbot_mcp_server.py & ./test.sh   # HTTP transport smoke
+```
+
+The code lives in `diffbot_mcp/`: `api.py` (token resolution and the shared request helper), `dql.py` (query execution, default columns, the cached ontology), `dql_builder.py` (pure DQL assembly), and one module per tool under `tools/`. `diffbot_mcp_server.py` is the entry point.
+
+## Help & Support
+This project is built and maintained by [@jeromechoo](https://github.com/jeromechoo). For support, file an issue and he'll get back to you as soon as he can. For faster answers, write to [sales@diffbot.com](mailto:sales@diffbot.com) 😜.

diffbot_mcp-0.2.0/diffbot_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Diffbot MCP server: web extraction, search, crawling, entity resolution, and Knowledge Graph tools."""
+
+__version__ = "0.2.0"

diffbot_mcp-0.2.0/diffbot_mcp/api.py

@@ -0,0 +1,128 @@
+"""Token resolution and the shared HTTP helper behind every Diffbot API call."""
+
+import asyncio
+import json
+import os
+import pathlib
+from typing import Any, Optional
+
+import aiohttp
+from fastmcp.exceptions import ToolError
+from fastmcp.server.dependencies import get_access_token, get_http_request
+
+# DIFFBOT_TOKEN is this server's historical name; DIFFBOT_API_TOKEN and the credentials
+# file are what the db CLI and diffbot-skills read, so one credential serves both.
+TOKEN_ENV_VARS = ("DIFFBOT_TOKEN", "DIFFBOT_API_TOKEN")
+CREDENTIALS_PATH = pathlib.Path.home() / ".diffbot" / "credentials"
+CREDENTIALS_KEY = "DIFFBOT_API_TOKEN"
+
+REQUEST_TIMEOUT_SECONDS = 120
+
+MISSING_TOKEN = (
+    "No Diffbot token found. On the HTTP transport pass it as 'Authorization: Bearer <token>' "
+    "or '?token=<token>'; otherwise set DIFFBOT_TOKEN or DIFFBOT_API_TOKEN in the environment, "
+    f"or write '{CREDENTIALS_KEY}=<token>' to {CREDENTIALS_PATH}. "
+    "Get a free token at https://app.diffbot.com/get-started"
+)
+
+
+def _credentials_file_token() -> str:
+    try:
+        lines = CREDENTIALS_PATH.read_text().splitlines()
+    except OSError:
+        return ""
+    for line in lines:
+        line = line.strip()
+        if line.startswith(f"{CREDENTIALS_KEY}="):
+            return line.split("=", 1)[1].strip().strip("'\"")
+    return ""
+
+
+def resolve_token() -> str:
+    """Per-request credentials first, then the environment, then the credentials file."""
+    try:
+        request = get_http_request()
+    except RuntimeError:
+        request = None  # stdio transport: no request in flight
+
+    if request is not None:
+        # Set when OAuth is on: the verified token resolves to the user's Diffbot API token
+        access_token = get_access_token()
+        if access_token is not None and access_token.claims.get("diffbot_token"):
+            return access_token.claims["diffbot_token"]
+        auth_header = request.headers.get("Authorization", "")
+        if auth_header.lower().startswith("bearer "):
+            return auth_header[7:].strip()
+        token = request.query_params.get("token")
+        if token:
+            return token
+
+    for var in TOKEN_ENV_VARS:
+        token = os.getenv(var, "").strip()
+        if token:
+            return token
+
+    token = _credentials_file_token()
+    if token:
+        return token
+
+    raise ToolError(MISSING_TOKEN)
+
+
+async def _error_message(response: aiohttp.ClientResponse) -> str:
+    body = await response.text()
+    message: Optional[str] = None
+    try:
+        data = json.loads(body)
+        if isinstance(data, dict):
+            message = data.get("message") or data.get("error")
+    except ValueError:
+        pass
+
+    if response.status in (401, 403):
+        return "Invalid or unauthorized Diffbot token" + (f": {message}" if message else "")
+    if response.status == 429:
+        retry_after = response.headers.get("Retry-After")
+        return "Diffbot rate limit exceeded" + (f", retry after {retry_after}s" if retry_after else "")
+    if not message:
+        message = body[:200] + ("..." if len(body) > 200 else "")
+    return f"Diffbot API error {response.status}: {message}"
+
+
+def clean_params(params: dict) -> dict:
+    """Drop None values and render booleans as the 1/0 the Diffbot APIs expect."""
+    cleaned = {}
+    for key, value in params.items():
+        if value is None:
+            continue
+        if isinstance(value, bool):
+            value = 1 if value else 0
+        cleaned[key] = value
+    return cleaned
+
+
+async def request(
+    url: str,
+    *,
+    params: Optional[dict] = None,
+    json_body: Any = None,
+    headers: Optional[dict] = None,
+    as_text: bool = False,
+    method: str = "GET",
+) -> Any:
+    """One Diffbot API call. Non-2xx responses become a ToolError carrying the API's own message."""
+    timeout = aiohttp.ClientTimeout(total=REQUEST_TIMEOUT_SECONDS)
+    try:
+        async with aiohttp.ClientSession(timeout=timeout) as session:
+            async with session.request(
+                method, url, params=clean_params(params or {}), json=json_body, headers=headers
+            ) as response:
+                if response.status >= 400:
+                    raise ToolError(await _error_message(response))
+                if as_text:
+                    return await response.text()
+                return await response.json(content_type=None)
+    except asyncio.TimeoutError:
+        raise ToolError(f"Diffbot request timed out after {REQUEST_TIMEOUT_SECONDS}s: {url}")
+    except aiohttp.ClientError as error:
+        raise ToolError(f"Diffbot request failed: {error}")

diffbot_mcp-0.2.0/diffbot_mcp/app.py

@@ -0,0 +1,11 @@
+"""The FastMCP instance. Kept in its own module so tool modules can import it without a cycle."""
+
+from fastmcp import FastMCP
+from mcp.types import ToolAnnotations
+
+from .auth import build_auth
+
+mcp = FastMCP(name="Diffbot MCP Server", auth=build_auth())
+
+# Every tool except crawl only reads from Diffbot's APIs or the open web
+READ_ONLY = ToolAnnotations(readOnlyHint=True, destructiveHint=False, idempotentHint=True, openWorldHint=True)