diff --git a/.github/workflows/version-check.yml b/.github/workflows/version-check.yml index 06f8d0c..6514888 100644 --- a/.github/workflows/version-check.yml +++ b/.github/workflows/version-check.yml @@ -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: diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 0000000..1d72987 --- /dev/null +++ b/.mcp.json @@ -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" + } + } +} diff --git a/.mcpbignore b/.mcpbignore index 875bed0..56e2584 100644 --- a/.mcpbignore +++ b/.mcpbignore @@ -18,3 +18,9 @@ __pycache__/ *.pyc *.egg-info/ .pytest_cache/ + +assets/ +plugin.json +mcp.json +.mcp.json +llms-install.md diff --git a/README.md b/README.md index 1cb5d8f..e87c045 100644 --- a/README.md +++ b/README.md @@ -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 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) @@ -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 . The server sends your tool inputs (URLs, search text, DQL queries) to Diffbot's APIs to produce results. diff --git a/RELEASING.md b/RELEASING.md index 3534ba7..3fee471 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -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 diff --git a/assets/diffbot-logo-400.png b/assets/diffbot-logo-400.png new file mode 100644 index 0000000..8959f5d Binary files /dev/null and b/assets/diffbot-logo-400.png differ diff --git a/assets/diffbot-logo-512.png b/assets/diffbot-logo-512.png new file mode 100644 index 0000000..f41f68a Binary files /dev/null and b/assets/diffbot-logo-512.png differ diff --git a/assets/diffbot-logomark.svg b/assets/diffbot-logomark.svg new file mode 100644 index 0000000..1f59888 --- /dev/null +++ b/assets/diffbot-logomark.svg @@ -0,0 +1,13 @@ + + + + + + + + + + + + + diff --git a/llms-install.md b/llms-install.md new file mode 100644 index 0000000..ba63b2a --- /dev/null +++ b/llms-install.md @@ -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 ` 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": "" } + } + } +} +``` + +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 diff --git a/mcp.json b/mcp.json new file mode 100644 index 0000000..1d72987 --- /dev/null +++ b/mcp.json @@ -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" + } + } +} diff --git a/plugin.json b/plugin.json new file mode 100644 index 0000000..d8948d2 --- /dev/null +++ b/plugin.json @@ -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"] +} diff --git a/scripts/sync_version.py b/scripts/sync_version.py index 22bcc56..cfb44b2 100755 --- a/scripts/sync_version.py +++ b/scripts/sync_version.py @@ -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 @@ -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. @@ -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") @@ -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) @@ -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