Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions .github/workflows/version-check.yml
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
name: Version check

# Fails when server.json, gemini-extension.json, manifest.json or diffbot_mcp/__init__.py
# disagree with the version in pyproject.toml. Read-only, no secrets.
# Fails when server.json, gemini-extension.json, manifest.json, plugin.json or
# diffbot_mcp/__init__.py disagree with the version in pyproject.toml, or when .mcp.json
# stops matching mcp.json. Read-only, no secrets.
on:
pull_request:
push:
Expand Down
9 changes: 9 additions & 0 deletions .mcp.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers": {
"diffbot": {
"type": "streamable-http",
"url": "https://mcp.diffbot.com/mcp"
}
}
}
6 changes: 6 additions & 0 deletions .mcpbignore
Original file line number Diff line number Diff line change
Expand Up @@ -18,3 +18,9 @@ __pycache__/
*.pyc
*.egg-info/
.pytest_cache/

assets/
plugin.json
mcp.json
.mcp.json
llms-install.md
7 changes: 6 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@

Web knowledge fetching tools for your agent.

[![diffbot/diffbot-mcp MCP server](https://glama.ai/mcp/servers/diffbot/diffbot-mcp/badges/score.svg)](https://glama.ai/mcp/servers/diffbot/diffbot-mcp)

<!-- Install buttons are generated: run `python3 scripts/install_links.py` and paste its output here. -->
[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=diffbot-mcp&config=eyJ1cmwiOiJodHRwczovL21jcC5kaWZmYm90LmNvbS9tY3AifQ==)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Diffbot-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22diffbot-mcp%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.diffbot.com%2Fmcp%22%7D)
Expand Down Expand Up @@ -241,4 +243,7 @@ The code lives in `diffbot_mcp/`: `api.py` (token resolution and the shared requ
Releases are tag-driven: bump the version in `pyproject.toml`, run `python3 scripts/sync_version.py`, then push a `vX.Y.Z` tag — see [RELEASING.md](https://github.com/diffbot/diffbot-mcp/blob/main/RELEASING.md).

## 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) 😜.
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 [support@diffbot.com](mailto:support@diffbot.com).

## Privacy Policy
Diffbot's privacy policy is at <https://www.diffbot.com/company/privacy>. The server sends your tool inputs (URLs, search text, DQL queries) to Diffbot's APIs to produce results.
2 changes: 1 addition & 1 deletion RELEASING.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

`pyproject.toml` holds the only version number anyone edits. `scripts/sync_version.py` copies it
into `server.json` (the top-level `version` and every `packages[]` entry with `registryType: pypi`),
`gemini-extension.json`, `manifest.json` (the Claude Desktop extension), and `diffbot_mcp/__init__.py`. CI fails a pull request whose copies drift.
`gemini-extension.json`, `manifest.json` (the Claude Desktop extension), `plugin.json` (the Agent Plugins manifest cursor.directory reads), and `diffbot_mcp/__init__.py`. It also keeps `.mcp.json` a byte copy of `mcp.json`. CI fails a pull request whose copies drift.

Pushing a `vX.Y.Z` tag runs [`.github/workflows/release.yml`](.github/workflows/release.yml), which
publishes to PyPI, then to the MCP Registry, then cuts a GitHub release. Nothing publishes without a
Expand Down
Binary file added assets/diffbot-logo-400.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/diffbot-logo-512.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
13 changes: 13 additions & 0 deletions assets/diffbot-logomark.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
52 changes: 52 additions & 0 deletions llms-install.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# Installing Diffbot MCP (instructions for AI agents)

Diffbot MCP gives you web search, page extraction, site crawls, and Diffbot Knowledge Graph queries.
Pick one of the two options below. Never write a real token into a file that is committed to git.

## Option 1: hosted server (no token to paste)

Add a remote Streamable HTTP server. The user signs in with a Diffbot account (OAuth) the first time a tool runs.

```json
{
"mcpServers": {
"diffbot-mcp": {
"type": "streamable-http",
"url": "https://mcp.diffbot.com/mcp"
}
}
}
```

If your client cannot do OAuth, send the header `Authorization: Bearer <YOUR_DIFFBOT_TOKEN>` instead.

## Option 2: local server with `uvx`

Requires [uv](https://docs.astral.sh/uv/). The server reads its token from `DIFFBOT_TOKEN`,
`DIFFBOT_API_TOKEN`, or `~/.diffbot/credentials`.

```json
{
"mcpServers": {
"diffbot-mcp": {
"command": "uvx",
"args": ["diffbot-mcp"],
"env": { "DIFFBOT_TOKEN": "<YOUR_DIFFBOT_TOKEN>" }
}
}
}
```

A free token is available at https://app.diffbot.com/get-started. Ask the user for it; do not invent one.

## Check that it works

List the server's tools. You should see 12: `extract`, `search_web`, `crawl`, `resolve_entities`,
`search_news`, `search_organizations`, `search_people`, `search_places`, `search_deals`, `dql`,
`dql_probe`, and `dql_ontology`. Then try `search_web` with a short query.

## Links

- Docs: https://www.diffbot.com/docs/interfaces/mcp-server
- Source: https://github.com/diffbot/diffbot-mcp
- Support: support@diffbot.com
9 changes: 9 additions & 0 deletions mcp.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers": {
"diffbot": {
"type": "streamable-http",
"url": "https://mcp.diffbot.com/mcp"
}
}
}
15 changes: 15 additions & 0 deletions plugin.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "diffbot",
"version": "0.2.2",
"description": "Web knowledge fetching tools for your agent: search, extract, crawl, and query the Diffbot Knowledge Graph.",
"author": {
"name": "Diffbot",
"email": "support@diffbot.com",
"url": "https://www.diffbot.com"
},
"homepage": "https://www.diffbot.com/docs/interfaces/mcp-server",
"repository": "https://github.com/diffbot/diffbot-mcp",
"license": "MIT",
"keywords": ["web", "search", "extract", "crawl", "knowledge-graph", "research", "mcp"]
}
26 changes: 26 additions & 0 deletions scripts/sync_version.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
- server.json: the top-level "version" and every packages[] entry with registryType "pypi"
- gemini-extension.json: "version"
- manifest.json: the top-level "version" (Claude Desktop / MCPB)
- plugin.json: the top-level "version" (Agent Plugins manifest, read by cursor.directory)
- diffbot_mcp/__init__.py: __version__

The JSON files are edited in place, one "version" value at a time, so hand-written
Expand Down Expand Up @@ -38,6 +39,9 @@
SERVER_JSON = ROOT / "server.json"
GEMINI_JSON = ROOT / "gemini-extension.json"
MANIFEST_JSON = ROOT / "manifest.json"
PLUGIN_JSON = ROOT / "plugin.json"
MCP_JSON = ROOT / "mcp.json"
DOT_MCP_JSON = ROOT / ".mcp.json"
INIT_PY = ROOT / "diffbot_mcp" / "__init__.py"

# Matches one "version": "..." pair; group 2 is the value, which is what we rewrite.
Expand Down Expand Up @@ -99,6 +103,13 @@ def manifest_slots(data: dict) -> list[Slot]:
]


def plugin_slots(data: dict) -> list[Slot]:
return [
Slot(f"plugin.json {path.lstrip('.')}", value, path == ".version")
for path, value in walk_version_keys(data)
]


def stamp_json(path: Path, slots: list[Slot], version: str, write: bool) -> list[str]:
"""Report slots that disagree with `version`; when `write`, rewrite just those values."""
text = path.read_text(encoding="utf-8")
Expand Down Expand Up @@ -134,6 +145,16 @@ def stamp_init(version: str, write: bool) -> list[str]:
return [f"diffbot_mcp/__init__.py __version__ is {match.group(1)!r}"]


def sync_mcp_copy(write: bool) -> list[str]:
""".mcp.json (the path cursor.directory scans) must be a byte copy of mcp.json (the Agent Plugins path)."""
source = MCP_JSON.read_bytes()
if DOT_MCP_JSON.exists() and DOT_MCP_JSON.read_bytes() == source:
return []
if write:
DOT_MCP_JSON.write_bytes(source)
return [".mcp.json differs from mcp.json"]


def sync(version: str, write: bool) -> list[str]:
server = json.loads(SERVER_JSON.read_text(encoding="utf-8"))
slots, problems = server_slots(server)
Expand All @@ -145,6 +166,11 @@ def sync(version: str, write: bool) -> list[str]:
manifest = json.loads(MANIFEST_JSON.read_text(encoding="utf-8"))
problems += stamp_json(MANIFEST_JSON, manifest_slots(manifest), version, write)

plugin = json.loads(PLUGIN_JSON.read_text(encoding="utf-8"))
problems += stamp_json(PLUGIN_JSON, plugin_slots(plugin), version, write)

problems += sync_mcp_copy(write)

problems += stamp_init(version, write)
return problems

Expand Down
Loading