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
4 changes: 4 additions & 0 deletions DEVELOPING.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,10 @@ make release-plan # which plugins a merge to main would release (fetches tag
- Each zip holds one top-level `<name>/` directory: everything tracked under
`plugins/<name>/` except `tests/`. The exclusion list is `EXCLUDED` in
`scripts/release.py`.
- The zip's `mcp.json` gains `"$schema"` (`MCP_SCHEMA` in `scripts/release.py`); the
committed one must not have it. OpenAI finds no MCP server in an `mcp.json` without
it and refuses the plugin's `test_cases`. The Anthropic Directory scans the repo and
refuses the field from organizations it has not verified.
- `make package` fails on what OpenAI would reject: files beside the plugin directory,
a missing `plugin.json` or referenced asset, a file under `skills/` that is not a
skill directory with a `SKILL.md`, symlinks, more than 5,000 entries or more than
Expand Down
2 changes: 1 addition & 1 deletion plugins/helical-platform/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "helical-platform",
"displayName": "Helical",
"version": "1.0.6",
"version": "1.0.7",
"description": "Compute embeddings with Helical foundation models, hosted on Helical's GPUs or locally on your own GPU with the open-source package.",
"author": {
"name": "Helical",
Expand Down
2 changes: 1 addition & 1 deletion plugins/helical-platform/plugin.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "helical-platform",
"version": "1.0.6",
"version": "1.0.7",
"description": "Compute embeddings with Helical foundation models, hosted on Helical's GPUs or locally on your own GPU with the open-source package.",
"author": {
"name": "Helical",
Expand Down
34 changes: 33 additions & 1 deletion scripts/release.py
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,12 @@
MAX_ZIP_BYTES = 100 * 1024 * 1024
MAX_ZIP_ENTRIES = 5000

# OpenAI reads mcp.json as an agent-plugins file only when it names this schema;
# without it, it finds no server and refuses plugin-level test_cases. The Anthropic
# Directory refuses the same field from organizations it has not verified, so the
# repo's mcp.json leaves it out and build_zip adds it to the OpenAI zip only.
MCP_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json"

# The version becomes part of a git tag, so it has to be a plain semantic version.
SEMVER = re.compile(r"\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?")

Expand Down Expand Up @@ -98,13 +104,37 @@ def build_zip(repo: Path, plugin: Plugin, dist: Path, ref: str = "HEAD") -> Path
same bytes."""
out = dist / plugin.zip_name
committed = git(repo, "log", "-1", "--format=%cI", ref, "--", plugin.path).strip()
pathspecs = [f":!{excluded}" for excluded in EXCLUDED]
virtual = []
mcp_json = openai_mcp_json(repo, plugin, ref)
if mcp_json is not None:
# OpenAI needs $schema in mcp.json and the Anthropic Directory refuses it in the
# repo (see MCP_SCHEMA). So the committed mcp.json is excluded, and a virtual
# file takes its place: git writes it into the zip from the given text, with
# no copy on disk or in git. --prefix does not apply to it, so its path
# includes the plugin root.
pathspecs.append(":!mcp.json")
virtual.append(f"--add-virtual-file={plugin.name}/mcp.json:{mcp_json}")
git(
repo, "archive", "--format=zip", f"--prefix={plugin.name}/", f"--mtime={committed}",
"-o", str(out), f"{ref}:{plugin.path}", *(f":!{excluded}" for excluded in EXCLUDED),
*virtual, "-o", str(out), f"{ref}:{plugin.path}", *pathspecs,
)
return out


def openai_mcp_json(repo: Path, plugin: Plugin, ref: str = "HEAD") -> str | None:
"""The plugin's committed mcp.json with MCP_SCHEMA added, for the zip to carry in
place of the committed file. None when there is no mcp.json or it already names a
schema: then the committed file is packaged as it is."""
try:
config = json.loads(git(repo, "show", f"{ref}:{plugin.path}/mcp.json"))
except GitError:
return None
if "$schema" in config:
return None
return json.dumps({"$schema": MCP_SCHEMA, **config}, indent=2) + "\n"


def asset_refs(value: object) -> set[str]:
"""Every "./assets/..." string anywhere in a manifest."""
if isinstance(value, str):
Expand Down Expand Up @@ -138,6 +168,8 @@ def check_zip(path: Path, name: str) -> list[str]:
for ref in sorted(asset_refs(manifest)):
if root + ref.removeprefix("./") not in names:
problems.append(f"plugin.json references {ref}, which is not in the zip")
if f"{root}mcp.json" in names and "$schema" not in json.loads(zf.read(f"{root}mcp.json")):
problems.append(f"{root}mcp.json has no $schema, so OpenAI finds no MCP server in it")
for excluded in EXCLUDED:
if any(n.startswith(f"{root}{excluded}/") for n in names):
problems.append(f"{root}{excluded}/ should not be packaged")
Expand Down
6 changes: 6 additions & 0 deletions tests/helical-platform/test_plugin_manifest.py
Original file line number Diff line number Diff line change
Expand Up @@ -175,6 +175,12 @@ def test_the_claude_manifest_points_at_the_shared_mcp_config(self):
self.assertNotIn("skills", CLAUDE_MANIFEST)
self.assertFalse((PLUGIN / ".mcp.json").exists(), "a second MCP config would drift")

def test_the_shared_mcp_config_names_no_schema(self):
"""The Anthropic Directory scans this file and refuses fields Claude Code does
not read, `$schema` included, from organizations it has not verified. OpenAI
needs `$schema`, so scripts/release.py adds it to the OpenAI zip only."""
self.assertNotIn("$schema", MCP_JSON)

def test_the_auth_skill_names_the_server_as_claude_code_registers_it(self):
"""A plugin-provided server is registered as `plugin:<plugin>:<server>`, and
`claude mcp login <server>` answers "No MCP server named ..." for it. Renaming
Expand Down
29 changes: 29 additions & 0 deletions tests/test_release.py
Original file line number Diff line number Diff line change
Expand Up @@ -175,6 +175,31 @@ def test_the_zip_built_on_develop_matches_the_one_built_after_merging_to_main(se
[on_main] = release.package(self.repo, self.dist)
self.assertEqual(on_main.read_bytes(), uploaded)

def test_the_zip_mcp_json_names_its_schema_but_the_repo_one_does_not(self):
"""OpenAI finds no MCP server in an mcp.json without `$schema`; the Anthropic
Directory refuses the field in the repo. So only the zip carries it."""
(self.repo / "plugins/demo/mcp.json").write_text(
json.dumps({"mcpServers": {"x": {"type": "http", "url": "https://x"}}})
)
commit(self.repo)
[path] = release.package(self.repo, self.dist)
with zipfile.ZipFile(path) as zf:
packaged = json.loads(zf.read("demo/mcp.json"))
years = {info.date_time[0] for info in zf.infolist()}
attrs = {zf.getinfo(n).external_attr for n in ("demo/mcp.json", "demo/plugin.json")}
self.assertEqual(packaged["$schema"], release.MCP_SCHEMA)
self.assertEqual(packaged["mcpServers"], {"x": {"type": "http", "url": "https://x"}})
self.assertEqual(years, {2001}, "the generated mcp.json must carry the commit time")
self.assertEqual(len(attrs), 1, "the generated mcp.json must get the same mode as the rest")
self.assertNotIn("$schema", json.loads((self.repo / "plugins/demo/mcp.json").read_text()))

def test_a_schema_already_in_mcp_json_is_kept(self):
(self.repo / "plugins/demo/mcp.json").write_text(json.dumps({"$schema": "custom"}))
commit(self.repo)
[path] = release.package(self.repo, self.dist)
with zipfile.ZipFile(path) as zf:
self.assertEqual(json.loads(zf.read("demo/mcp.json"))["$schema"], "custom")

def test_writes_only_the_zips(self):
"""GitHub computes and shows a SHA-256 for every release asset, so no checksum
file is published alongside the zips."""
Expand Down Expand Up @@ -262,6 +287,10 @@ def test_rejects_a_file_directly_under_skills_and_a_skill_without_skill_md(self)
self.assertTrue(any("demo/skills/notes.md" in p for p in problems), problems)
self.assertTrue(any("demo/skills/empty" in p for p in problems), problems)

def test_rejects_an_mcp_json_without_its_schema(self):
problems = self.check({**VALID_ENTRIES, "demo/mcp.json": "{}"})
self.assertTrue(any("mcp.json" in p and "$schema" in p for p in problems), problems)

def test_rejects_symlinks(self):
problems = self.check(VALID_ENTRIES, symlinks=("demo/skills/hello/link",))
self.assertTrue(any("symlink" in p and "demo/skills/hello/link" in p for p in problems), problems)
Expand Down
Loading