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
2 changes: 1 addition & 1 deletion .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
"name": "nutrient",
"source": "./plugins/nutrient",
"description": "Extract data from PDFs, Office files, images and scans, with page citations and warnings for values to check. Also convert documents to Markdown and classify them. Uses your Nutrient account.",
"version": "1.0.2",
"version": "1.0.3",
"author": { "name": "Nutrient", "url": "https://www.nutrient.io" },
"homepage": "https://www.nutrient.io/api/",
"license": "MIT"
Expand Down
14 changes: 9 additions & 5 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
# Nutrient MCP plugins: agent guidance

This repository publishes one plugin, `plugins/nutrient`, to Claude and to OpenAI (ChatGPT and Codex). Claude reads
`.claude-plugin/plugin.json`, OpenAI reads `.codex-plugin/plugin.json`, and both share `.mcp.json`, `skills/` and the
README and license. `.claude-plugin/marketplace.json` and `.agents/plugins/marketplace.json` list it for each host.
`.claude-plugin/plugin.json` and `.mcp.json`, OpenAI reads `.codex-plugin/plugin.json` and `.codex-plugin/mcp.json`,
and both share `skills/` and the README and license. `.claude-plugin/marketplace.json` and
`.agents/plugins/marketplace.json` list it for each host.
Anthropic's directory tracks this repository's default branch, so every merge to `main` is a release candidate there;
OpenAI's directory takes a ZIP of `plugins/nutrient`, uploaded for each release.

Expand All @@ -22,9 +23,12 @@ OpenAI's directory takes a ZIP of `plugins/nutrient`, uploaded for each release.

Never change `name` in `plugin.json`: it is the plugin's permanent identity.

Keep `scopes` in `.mcp.json`. Without it, Codex asks for every scope the authorization server lists instead of the
service's own, and the service can't exchange that grant, so every tool call fails. Claude Code asks for the same pair,
taken from the service's sign-in challenge, and ChatGPT for the scopes the service advertises. `ci/check.py` checks it.
Keep `scopes` in `.codex-plugin/mcp.json`, at the top of the server entry. Without it, Codex asks for every scope the
authorization server lists instead of the service's own, and the service can't exchange that grant, so every tool call
fails. Codex doesn't read `oauth.scopes`. Keep it out of `.mcp.json`: Anthropic's directory refuses fields outside its
list from organizations it hasn't Verified, and a remote server there may have only `type`, `url`, `headers`,
`timeout`, `alwaysLoad`, `oauth` and text fields. Claude Code asks for the same pair, taken from the service's sign-in
challenge, and ChatGPT for the scopes the service advertises. `ci/check.py` checks both files.

## Refreshing the tool snapshot

Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,8 @@ On Team and Enterprise plans, an Owner can roll the plugin out to the whole orga
## Contents

- [`plugins/nutrient`](plugins/nutrient): the plugin, with its [README](plugins/nutrient/README.md), which says what it
sends to Nutrient. Claude reads `.claude-plugin/plugin.json` and OpenAI reads `.codex-plugin/plugin.json`; both use
the same connector (`.mcp.json`) and skill.
sends to Nutrient. Claude reads `.claude-plugin/plugin.json` and `.mcp.json`, and OpenAI reads
`.codex-plugin/plugin.json` and `.codex-plugin/mcp.json`; both connect to the same service and use the same skill.
- [`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json) and
[`.agents/plugins/marketplace.json`](.agents/plugins/marketplace.json): list the plugin, so this repository works as a
marketplace for Claude and for Codex
Expand Down
27 changes: 19 additions & 8 deletions ci/check.py
Original file line number Diff line number Diff line change
Expand Up @@ -78,12 +78,13 @@ def collect(node, names):
check(readme.exists() and words(readme.read_text()) >= 40, f"{readme.relative_to(ROOT)} has at least 40 words of prose")
check((folder / "LICENSE").exists(), f"{(folder / 'LICENSE').relative_to(ROOT)} exists")

# OpenAI (ChatGPT and Codex): .codex-plugin/plugin.json shares .mcp.json and skills/ with Claude's manifest.
# OpenAI (ChatGPT and Codex): .codex-plugin/plugin.json shares skills/ with Claude's manifest, and has its own MCP file,
# because Codex needs a field that Anthropic's directory refuses in .mcp.json (see the connector checks below).
codex = load(PLUGIN / ".codex-plugin" / "plugin.json")
check(codex.get("name") == manifest.get("name") and codex.get("version") == manifest.get("version"),
".codex-plugin/plugin.json has the same name and version as .claude-plugin/plugin.json")
check(codex.get("mcpServers") == "./.mcp.json" and codex.get("skills") == "./skills/",
".codex-plugin/plugin.json uses the shared .mcp.json and skills/")
check(codex.get("mcpServers") == "./.codex-plugin/mcp.json" and codex.get("skills") == "./skills/",
".codex-plugin/plugin.json uses its own .codex-plugin/mcp.json and the shared skills/")
interface = codex.get("interface", {})
# OpenAI's submission limits (developers.openai.com/plugins/deploy/submission).
limit(codex.get("name"), 64, ".codex-plugin/plugin.json name")
Expand Down Expand Up @@ -130,12 +131,22 @@ def collect(node, names):
check(len(openai_entries) == 1 and openai_entries[0].get("policy", {}).get("installation") in ("AVAILABLE", "INSTALLED_BY_DEFAULT", "NOT_AVAILABLE"),
".agents/plugins/marketplace.json gives the plugin a valid installation policy")

servers = load(PLUGIN / ".mcp.json").get("mcpServers", {})
check(list(servers) == ["nutrient"] and servers["nutrient"].get("type") == "http" and servers["nutrient"].get("url") == SERVICE,
f".mcp.json declares one server, nutrient, at {SERVICE} over HTTP (OpenAI connects one server per plugin)")
for mcp_file in (".mcp.json", ".codex-plugin/mcp.json"):
servers = load(PLUGIN / mcp_file).get("mcpServers", {})
check(list(servers) == ["nutrient"] and servers["nutrient"].get("type") == "http" and servers["nutrient"].get("url") == SERVICE,
f"{mcp_file} declares one server, nutrient, at {SERVICE} over HTTP (OpenAI connects one server per plugin)")
# Anthropic's directory refuses any other field on a remote server in Claude's .mcp.json from an organization it hasn't
# Verified, and the refusal blocks the release. These are the fields its policy check lists.
claude_server = load(PLUGIN / ".mcp.json").get("mcpServers", {}).get("nutrient", {})
oauth = claude_server.get("oauth", {})
check(isinstance(oauth, dict), ".mcp.json oauth is an object")
extra = set(claude_server) - {"type", "url", "headers", "timeout", "alwaysLoad", "oauth", "name", "title", "displayName", "description"}
extra |= {f"oauth.{key}" for key in (oauth if isinstance(oauth, dict) else {})} - {"oauth.clientId", "oauth.callbackPort", "oauth.authServerMetadataUrl", "oauth.scopes"}
check(not extra, f".mcp.json has only fields Anthropic's directory accepts; remove: {', '.join(sorted(extra))}")
# Without scopes, Codex asks for every scope the authorization server lists, and the service can't use that grant.
check(servers.get("nutrient", {}).get("scopes") == ["mcp:invoke", "offline_access"],
".mcp.json requests the service's own scopes, mcp:invoke and offline_access")
# Codex reads them only at the top of the server entry, not under oauth.
check(load(PLUGIN / ".codex-plugin" / "mcp.json").get("mcpServers", {}).get("nutrient", {}).get("scopes") == ["mcp:invoke", "offline_access"],
".codex-plugin/mcp.json requests the service's own scopes, mcp:invoke and offline_access")

skills = sorted((PLUGIN / "skills").glob("*/SKILL.md"))
check(len(skills) > 0, "the plugin has at least one skill")
Expand Down
2 changes: 1 addition & 1 deletion ci/package_openai.py
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@
and not EXCLUDED_DIRECTORIES & set(path.relative_to(PLUGIN).parts[:-1])
)
names = [path.relative_to(PLUGIN).as_posix() for path in files]
for required in (".codex-plugin/plugin.json", ".mcp.json"):
for required in (".codex-plugin/plugin.json", ".codex-plugin/mcp.json"):
if required not in names:
sys.exit(f"FAIL the package has no {required}")

Expand Down
3 changes: 2 additions & 1 deletion plugins/nutrient/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
{
"name": "nutrient",
"displayName": "Nutrient",
"version": "1.0.2",
"version": "1.0.3",
"description": "Extract data from PDFs, Office files, images and scans, with page citations and warnings for values to check. Also convert documents to Markdown and classify them. Uses your Nutrient account.",
"author": { "name": "Nutrient", "url": "https://www.nutrient.io" },
"homepage": "https://www.nutrient.io/api/",
"privacyPolicyUrl": "https://www.nutrient.io/legal/privacy/",
"license": "MIT"
}
12 changes: 12 additions & 0 deletions plugins/nutrient/.codex-plugin/mcp.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
{
"mcpServers": {
"nutrient": {
"type": "http",
"url": "https://mcp.nutrient.io/mcp",
"scopes": [
"mcp:invoke",
"offline_access"
]
}
}
}
4 changes: 2 additions & 2 deletions plugins/nutrient/.codex-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "nutrient",
"version": "1.0.2",
"version": "1.0.3",
"description": "Extract data from PDFs, Office files, images and scans, with page citations and warnings for values to check. Also convert documents to Markdown and classify them. Uses your Nutrient account.",
"author": {
"name": "Nutrient",
Expand All @@ -18,7 +18,7 @@
"classification"
],
"skills": "./skills/",
"mcpServers": "./.mcp.json",
"mcpServers": "./.codex-plugin/mcp.json",
"interface": {
"displayName": "Nutrient",
"shortDescription": "Extract data from documents",
Expand Down
6 changes: 1 addition & 5 deletions plugins/nutrient/.mcp.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,7 @@
"mcpServers": {
"nutrient": {
"type": "http",
"url": "https://mcp.nutrient.io/mcp",
"scopes": [
"mcp:invoke",
"offline_access"
]
"url": "https://mcp.nutrient.io/mcp"
}
}
}
Loading