diffbot-mcp 0.2.0__py3-none-any.whl

diffbot_mcp-0.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,28 @@
+diffbot_mcp_server.py,sha256=2ifp4YD8GAbVmSRj4_pWzzrQi4AlHOtHIOZaK7xEvIw,157
+diffbot_mcp/__init__.py,sha256=iAynpkMUc8EXa6axc9ajjIZGMQAN4S5XYe18F8-AsWE,129
+diffbot_mcp/api.py,sha256=f1WIzGY0kvOlm5Ap1a0mbj8kmsdt9CmQ4x-pq4Gv3E4,4590
+diffbot_mcp/app.py,sha256=DnBJzd1ZzlRaSP3R_s3V-eBMbzkmsVQCRAmLpiBVeaU,441
+diffbot_mcp/auth.py,sha256=97HMNlliZ4SiZpQXVcmZu2i0f-Nxp5hx9VWEXIQu3_4,3324
+diffbot_mcp/dql.py,sha256=_O09jpY9ltFqB492MPJ6EGNaLXg3P3w0ALY2zYfFGuI,15074
+diffbot_mcp/dql_builder.py,sha256=fq3DOuek_J_HmM2aYl-xKEuh9jPiIdiW0geQdFGFYpk,8996
+diffbot_mcp/schema.py,sha256=cIlAZcicDIv9zDkHsou1Fws9J0uyUAEDAeNPW19Vbxw,1519
+diffbot_mcp/server.py,sha256=N1lft5k0rdC0rYzarLULHVvC-XwZaT8DUSLsXrSKhaQ,428
+diffbot_mcp/tools/__init__.py,sha256=By8NGbkLgEiATUvSSfGjrFDNYY0M63UyDS_PkeX77G8,90
+diffbot_mcp/tools/crawl.py,sha256=yb8EWoO0w_hD1MgeVXJW_84mbgW4fP04XrfOWArIozY,6328
+diffbot_mcp/tools/deals.py,sha256=lxKBajNGU1dNl29aMo1DPc4G9uV1ypAsD5UFixU7EHI,11480
+diffbot_mcp/tools/dql.py,sha256=qORZyCguZZx0ghX99QejdPXYPuDArkE1-NcasU59XR4,1702
+diffbot_mcp/tools/dql_ontology.py,sha256=zk26ubEJYJ_V0kKIKVqDNBl9e8-reUMGhCODsViQMgQ,2438
+diffbot_mcp/tools/dql_probe.py,sha256=ySc_FjG9OCf6Bv9AyM1Pti8T9iO_JEfy2WNVnR71jSg,786
+diffbot_mcp/tools/extract.py,sha256=waAfiwrwF14HpSXtqr1mqGXc1oR1PH0p2IfFMRCdW5k,1818
+diffbot_mcp/tools/news.py,sha256=nt0EdobOOgPrpq_UfEObDkdAnv-dE1cf75qjyU4impA,6079
+diffbot_mcp/tools/organizations.py,sha256=Lj9uf746JI2mD1JmlWZ5Ye2XbMGnjGHoo-WduqxHjC4,10246
+diffbot_mcp/tools/people.py,sha256=sgvYueM2W7jaPT48vUDNUknFGFJuLmJNBcfbVj0u1K8,12520
+diffbot_mcp/tools/places.py,sha256=9MHeDfkveNvBGXbBvwErfkiQErkHUr1Lc29z6tR8WZk,5096
+diffbot_mcp/tools/resolve_entities.py,sha256=mNyDwx4q9PoxLV_3pGry9iSK_aHhGaqmuRS4dm4LCfQ,2211
+diffbot_mcp/tools/search_web.py,sha256=4cWGUIMejNmSxqqXZf2GHI97PWqRF9jNfUzZQ1uGBxU,2486
+diffbot_mcp-0.2.0.dist-info/licenses/LICENSE,sha256=uH9YNmGPoWRPUoOFDp2mX8OXiANYAnElEOetEKzrghU,1064
+diffbot_mcp-0.2.0.dist-info/METADATA,sha256=46EXsGMAaImbfHkmTVLX3okJKSTrmqFFUFAOFg7et60,10788
+diffbot_mcp-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+diffbot_mcp-0.2.0.dist-info/entry_points.txt,sha256=lYIjYAOQVjCNDGLV0eK0VlJj7JF7tSjzqIRYi4VMfaI,56
+diffbot_mcp-0.2.0.dist-info/top_level.txt,sha256=XubNd66_A5cBXfhRBnAvv6EStdn1pNowo2QsJz1zDn4,31
+diffbot_mcp-0.2.0.dist-info/RECORD,,

diffbot_mcp-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

diffbot_mcp-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+diffbot-mcp = diffbot_mcp_server:main

diffbot_mcp-0.2.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+diffbot_mcp
+diffbot_mcp_server

diffbot_mcp_server.py

@@ -0,0 +1,11 @@
+import os
+
+from diffbot_mcp.server import mcp
+
+
+def main() -> None:
+    mcp.run(os.getenv("MCP_TRANSPORT", "stdio"))
+
+
+if __name__ == "__main__":
+    main()