feat(plugin): add Codex plugin support (#73)

## Summary Ships this repo as a **Codex plugin**, alongside the existing Claude Code plugin and Skills-CLI paths. - **`.codex-plugin/plugin.json`** — Codex plugin manifest: bundles `skills/`, points `mcpServers` at `.codex-plugin/mcp.json`, and carries `interface` metadata for the install UI (fields calibrated against the official Notion/Figma plugins in `openai/plugins`). - **`.codex-plugin/mcp.json`** — remote-HTTP MCP entry for `https://api.agentkey.app/v1/mcp`, authenticated via **MCP OAuth (RFC 9728 discovery)**. Codex plugins have no `userConfig`/header-interpolation mechanism, so the Claude-style `${user_config.AGENTKEY_API_KEY}` injection can't be reused. - **`.agents/plugins/marketplace.json`** — the repo is its own Codex marketplace: `codex plugin marketplace add chainbase-labs/agentkey`, then install AgentKey from `/plugins`. - **`release-please-config.json`** — bumps the Codex manifest version in lockstep with the Claude one. - **`AGENTS.md`** — accurate agent-facing repo guidance mirroring `.claude/CLAUDE.md` (replaces a stale draft that predated `@agentkey/cli`). - **Description/keywords refresh** — both plugin manifests and the Claude marketplace entry now use the Product Hunt positioning ("one-stop live data marketplace for your agent") and cover the full category list (finance, e-commerce, business data, weather/maps, travel). - **README / README_zh** — document the Codex plugin install path. ## Why no `oauth_resource` The first local test failed at the Clerk authorize endpoint with `invalid_request: The request includes the parameter 'resource' more than once`. Root cause: the rmcp SDK already appends `resource=<server url>` to the authorization request automatically (RFC 8707), and Codex appends a configured `oauth_resource` as a *second* `resource` param without deduplication (`codex-rs/rmcp-client/src/perform_oauth_login.rs`). Clerk enforces RFC 6749's no-repeated-params rule. Since our server fully advertises RFC 9728 resource metadata, `type` + `url` alone is sufficient — discovery does the rest. Guardrails documented in `.claude/CLAUDE.md` / `AGENTS.md` checklists. ## Test plan - [x] All JSON manifests validate - [x] `codex plugin marketplace add <local path>` + install succeeds (Codex desktop) - [ ] OAuth sign-in completes end-to-end after `oauth_resource` removal (re-test pending) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-09-20 14:20:23 +08:00 · 2026-07-17 13:38:16 +08:00
parent a2309d9db6
commit 71331667a3
11 changed files with 226 additions and 10 deletions
@@ -0,0 +1,20 @@
+{
+  "name": "agentkey",
+  "interface": {
+    "displayName": "AgentKey"
+  },
+  "plugins": [
+    {
+      "name": "agentkey",
+      "source": {
+        "source": "local",
+        "path": "./"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Data & Analytics"
+    }
+  ]
+}
@@ -1,6 +1,6 @@
 {
  "name": "agentkey",
-  "description": "Unified API for real-time external data: web search, social media, crypto/blockchain data, and web scraping",
+  "description": "One-stop live data marketplace for your agent: web search, web scraping, social media, finance, crypto, e-commerce, business data, weather/maps, and travel",
  "owner": {
    "name": "Chainbase Labs",
    "url": "https://agentkey.app"
@@ -8,11 +8,11 @@
  "plugins": [
    {
      "name": "agentkey",
-      "description": "AgentKey — unified API for real-time external data: web search, social media (Twitter, Reddit, 小红书, Instagram, 知乎, TikTok, 抖音, B站, 微博, Threads, YouTube, LinkedIn), crypto/blockchain data, and web scraping",
+      "description": "AgentKey — one-stop live data marketplace for your agent: web search, web scraping, social media, finance, crypto, e-commerce, business data, weather/maps, and travel through a single MCP server. No API keys to manage, auto failover across providers, free to start.",
      "source": "./",
      "category": "data",
      "homepage": "https://github.com/chainbase-labs/agentkey",
-      "tags": ["agentkey", "web-search", "social-media", "crypto", "blockchain", "real-time-data", "scraping"]
+      "tags": ["agentkey", "web-search", "scraping", "social-media", "finance", "crypto", "blockchain", "e-commerce", "business-data", "weather", "maps", "travel", "real-time-data"]
    }
  ]
 }
@@ -1,7 +1,7 @@
 {
  "name": "agentkey",
  "version": "1.11.0",
-  "description": "AgentKey — unified API for real-time external data: web search, social media (Twitter, Reddit, 小红书, Instagram, 知乎, TikTok, 抖音, B站, 微博, Threads, YouTube, LinkedIn), crypto/blockchain data, and web scraping",
+  "description": "AgentKey — one-stop live data marketplace for your agent: web search, web scraping, social media, finance, crypto, e-commerce, business data, weather/maps, and travel through a single MCP server. No API keys to manage, auto failover across providers, free to start.",
  "author": {
    "name": "Chainbase Labs",
    "url": "https://agentkey.app"
@@ -11,11 +11,17 @@
  "keywords": [
    "agentkey",
    "web-search",
+    "scraping",
    "social-media",
+    "finance",
    "crypto",
    "blockchain",
-    "real-time-data",
-    "scraping"
+    "e-commerce",
+    "business-data",
+    "weather",
+    "maps",
+    "travel",
+    "real-time-data"
  ],
  "skills": "./skills/",
  "mcpServers": "./.mcp.json",
@@ -15,12 +15,18 @@ The skill is useless without the MCP server; the MCP server works without the sk

 The same repo also works as a Claude Code plugin (via `.claude-plugin/plugin.json` + `.mcp.json`) for users on the plugin marketplace path; in that mode the plugin's `userConfig` + `.mcp.json` substitute for step 2.

+It additionally works as a **Codex plugin** (via `.codex-plugin/plugin.json` + `.codex-plugin/mcp.json`, distributed through `.agents/plugins/marketplace.json` — the repo is its own marketplace, added with `codex plugin marketplace add chainbase-labs/agentkey`). Codex plugins have no `userConfig`/header-interpolation mechanism, so auth uses MCP OAuth instead: the server's `/v1/mcp` endpoint advertises `WWW-Authenticate: Bearer resource_metadata=…` (RFC 9728) and supports dynamic client registration, so `.codex-plugin/mcp.json` needs only `type` + `url` — discovery does the rest. In that mode the OAuth sign-in substitutes for step 2.
+
 ## Directory Structure

 ```
 agentkey/
 ├── .claude-plugin/plugin.json   # Claude Code plugin manifest
-├── .mcp.json                    # Auto-registers AgentKey MCP when installed as a plugin
+├── .codex-plugin/
+│   ├── plugin.json              # Codex plugin manifest (skills + mcpServers + interface metadata)
+│   └── mcp.json                 # Codex MCP entry — http + oauth_resource (NOT the root .mcp.json)
+├── .agents/plugins/marketplace.json  # Codex marketplace listing this repo as a local-source plugin
+├── .mcp.json                    # Auto-registers AgentKey MCP when installed as a Claude Code plugin
 ├── skills/agentkey/
 │   ├── SKILL.md                 # Decision tree + routing rules (end-user facing)
 │   ├── scripts/                 # check-update helper
@@ -52,7 +58,7 @@ Releases are driven by [release-please](https://github.com/googleapis/release-pl

 ## Version & Release Rules

- `skills/agentkey/version.txt`, `.claude-plugin/plugin.json` version, and `CHANGELOG.md` are managed by release-please based on Conventional Commits — never edit manually except via PR that intentionally amends them.
+- `skills/agentkey/version.txt`, `.claude-plugin/plugin.json` version, `.codex-plugin/plugin.json` version, and `CHANGELOG.md` are managed by release-please based on Conventional Commits — never edit manually except via PR that intentionally amends them.
 - `version.txt` lives inside `skills/agentkey/` (not at repo root) so it travels with the skill when the Skills CLI copies the subdirectory. `release-please-config.json` points at this path via `version-file`.
 - Tag format: `v` prefix (e.g. `v0.4.5`)
 - Plugin updates trigger on **GitHub Release** publication, not on plain commits
@@ -67,6 +73,11 @@ Releases are driven by [release-please](https://github.com/googleapis/release-pl
 - The MCP server is `type: http` (remote endpoint, no subprocess), so inject the API key by interpolating the userConfig value as `${user_config.AGENTKEY_API_KEY}` in the `Authorization` header — the key name MUST match the `plugin.json` `userConfig` key. Do NOT use `${CLAUDE_PLUGIN_OPTION_<KEY>}`: those env vars are only exported to stdio/subprocess servers and hook/monitor commands, and are not interpolated into an http server's headers.
 - Only matters for the Claude Code plugin path; the Skills-CLI path writes MCP config through `npx @agentkey/cli --auth-login`

+**Changes to `.codex-plugin/mcp.json`:**
+- Codex plugin MCP config does NOT support `${user_config.*}` interpolation — a literal `${…}` would be sent as the Authorization header. Auth is MCP OAuth via RFC 9728 discovery: the server's 401 advertises `resource_metadata`, and the rmcp client automatically appends `resource=<server url>` to the authorization request.
+- Do NOT set `oauth_resource`: rmcp already sends `resource` on its own, and Codex appends `oauth_resource` as a *second* `resource` query param without deduplication (`codex-rs/rmcp-client/src/perform_oauth_login.rs`). Clerk enforces RFC 6749 (no repeated params) and rejects the request with `invalid_request: The request includes the parameter 'resource' more than once`. The official Notion/Figma plugins get away with it only because their authorization servers tolerate duplicates.
+- Keep the endpoint URL in sync with the root `.mcp.json` — both must point at the same `/v1/mcp` endpoint.
+
 **Changes to install/uninstall docs:**
 - Update both `README.md` and `docs/README_zh.md` together — they mirror each other
 - The canonical install is always the two-command sequence (`npx skills add …` + `npx -y @agentkey/cli --auth-login`). Don't imply either command does both.
@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "agentkey": {
+      "type": "http",
+      "url": "https://api.agentkey.app/v1/mcp"
+    }
+  }
+}
@@ -0,0 +1,42 @@
+{
+  "name": "agentkey",
+  "version": "1.11.0",
+  "description": "AgentKey — one-stop live data marketplace for your agent: web search, web scraping, social media, finance, crypto, e-commerce, business data, weather/maps, and travel through a single MCP server. No API keys to manage, auto failover across providers, free to start.",
+  "author": {
+    "name": "Chainbase Labs",
+    "url": "https://agentkey.app"
+  },
+  "repository": "https://github.com/chainbase-labs/agentkey",
+  "license": "MIT",
+  "keywords": [
+    "agentkey",
+    "web-search",
+    "scraping",
+    "social-media",
+    "finance",
+    "crypto",
+    "blockchain",
+    "e-commerce",
+    "business-data",
+    "weather",
+    "maps",
+    "travel",
+    "real-time-data"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.codex-plugin/mcp.json",
+  "interface": {
+    "displayName": "AgentKey",
+    "shortDescription": "One-stop live data marketplace for your agent",
+    "longDescription": "AgentKey connects your agent to live external data through a single MCP server — web search, web scraping, social media, finance, crypto, e-commerce, business data, weather/maps, and travel — with no per-provider API integrations or key management. Providers are vetted and health-monitored, every call carries provenance, and auto failover keeps workflows running. Free to start.",
+    "developerName": "Chainbase Labs",
+    "category": "Data & Analytics",
+    "capabilities": ["Read"],
+    "websiteURL": "https://agentkey.app",
+    "defaultPrompt": [
+      "Search the web and social media for the latest news about a topic",
+      "Get the current price and on-chain activity for a crypto token",
+      "Scrape a URL and summarize its content"
+    ]
+  }
+}
@@ -19,3 +19,4 @@ cli/.vitest/
 # Claude Code workflow artifacts (internal, not shipped publicly)
 docs/superpowers/
 RELEASE_NOTES.md
+.claude/worktrees/
@@ -0,0 +1,93 @@
+# AGENTS.md
+
+This file provides guidance to coding agents (Codex, and any AGENTS.md-aware tool) when working with code in this repository. It mirrors `.claude/CLAUDE.md` — keep the two in sync.
+
+## What This Repo Is
+
+AgentKey Skill ships the agent-side half of AgentKey: a single skill that teaches agents how to call the AgentKey MCP tools correctly.
+
+AgentKey has **two pieces** and a full end-user install is two commands:
+
+1. `npx skills add chainbase-labs/agentkey` — installs **this** skill. It does NOT register the MCP server.
+2. `npx -y @agentkey/cli --auth-login` — runs the AgentKey CLI (`@agentkey/cli` from `../AgentKey-Server/cli`). It mints an API key via device-code login and writes a remote-HTTP MCP block (pointing at `https://api.agentkey.app/v1/mcp`) into agent configs (Claude Code, Codex, Cursor, and 13 more). The hosted MCP server itself lives at `/v1/mcp` on AgentKey-Server.
+
+The skill is useless without the MCP server; the MCP server works without the skill but the agent won't know to prefer it over built-in web search. Keep this mental model when editing docs — do not let either command drift into claiming it does both.
+
+The same repo also works as:
+
+- a **Claude Code plugin** (`.claude-plugin/plugin.json` + root `.mcp.json`) — the plugin's `userConfig` injects the API key via `${user_config.AGENTKEY_API_KEY}`, substituting for step 2.
+- a **Codex plugin** (`.codex-plugin/plugin.json` + `.codex-plugin/mcp.json`, distributed through `.agents/plugins/marketplace.json`; the repo is its own marketplace: `codex plugin marketplace add chainbase-labs/agentkey`). Codex plugins have no `userConfig`/header-interpolation mechanism, so auth uses MCP OAuth via the server's RFC 9728 metadata discovery (`type` + `url` only in mcp.json), substituting for step 2.
+
+## Directory Structure
+
+```
+agentkey/
+├── .claude-plugin/plugin.json   # Claude Code plugin manifest
+├── .codex-plugin/
+│   ├── plugin.json              # Codex plugin manifest (skills + mcpServers + interface metadata)
+│   └── mcp.json                 # Codex MCP entry — http + oauth_resource (NOT the root .mcp.json)
+├── .agents/plugins/marketplace.json  # Codex marketplace listing this repo as a local-source plugin
+├── .mcp.json                    # Auto-registers AgentKey MCP when installed as a Claude Code plugin
+├── skills/agentkey/
+│   ├── SKILL.md                 # Decision tree + routing rules (end-user facing)
+│   ├── scripts/                 # check-update helper
+│   └── version.txt              # Managed by release-please only — must live inside the skill so it survives `npx skills add`
+└── scripts/
+    └── uninstall.sh             # End-user cleanup helper
+```
+
+## Key Commands
+
+```bash
+# Test a local edit against every detected agent
+npx skills add .
+
+# Daily commit (does NOT trigger user updates)
+git add -A && git commit -m "..." && git push origin main
+
+# Publish a new release
+# Releases are cut automatically by release-please on merge to main.
+# To manually trigger: merge a conventional-commit PR; release-please will open
+# a Release PR; merge that to tag and create the GitHub Release.
+
+# Undo a bad release
+git tag -d vX.Y.Z && git push origin :refs/tags/vX.Y.Z
+gh release delete vX.Y.Z --repo chainbase-labs/agentkey --yes
+```
+
+Releases are driven by [release-please](https://github.com/googleapis/release-please): merged PRs with Conventional Commit messages (`feat:`, `fix:`, `feat!:`, etc.) update an open Release PR that bumps `skills/agentkey/version.txt`, both plugin manifest versions, and `CHANGELOG.md`. Merging the Release PR tags the release and creates the GitHub Release, which in turn triggers plugin updates for users.
+
+## Version & Release Rules
+
+- `skills/agentkey/version.txt`, `.claude-plugin/plugin.json` version, `.codex-plugin/plugin.json` version, and `CHANGELOG.md` are managed by release-please based on Conventional Commits — never edit manually except via PR that intentionally amends them.
+- `version.txt` lives inside `skills/agentkey/` (not at repo root) so it travels with the skill when the Skills CLI copies the subdirectory. `release-please-config.json` points at this path via `version-file`.
+- Tag format: `v` prefix (e.g. `v0.4.5`)
+- Plugin updates trigger on **GitHub Release** publication, not on plain commits
+- `npx skills update` pulls from the default branch, so main must always be shippable
+
+## Change Checklists
+
+**Changes to either `plugin.json`:**
+- release-please automatically bumps both manifest versions + `CHANGELOG.md` from merged conventional-commit PRs; maintainers review + merge the generated Release PR rather than editing these files directly
+
+**Changes to the root `.mcp.json` (Claude Code plugin path):**
+- The MCP server is `type: http` (remote endpoint, no subprocess), so inject the API key by interpolating the userConfig value as `${user_config.AGENTKEY_API_KEY}` in the `Authorization` header — the key name MUST match the `.claude-plugin/plugin.json` `userConfig` key. Do NOT use `${CLAUDE_PLUGIN_OPTION_<KEY>}`: those env vars are only exported to stdio/subprocess servers and hook/monitor commands, and are not interpolated into an http server's headers.
+- Only matters for the Claude Code plugin path; the Skills-CLI path writes MCP config through `npx @agentkey/cli --auth-login`
+
+**Changes to `.codex-plugin/mcp.json` (Codex plugin path):**
+- Codex plugin MCP config does NOT support `${user_config.*}` interpolation — a literal `${…}` would be sent as the Authorization header. Auth is MCP OAuth via RFC 9728 discovery: the server's 401 advertises `resource_metadata`, and the rmcp client automatically appends `resource=<server url>` to the authorization request.
+- Do NOT set `oauth_resource`: rmcp already sends `resource` on its own, and Codex appends `oauth_resource` as a *second* `resource` query param without deduplication (`codex-rs/rmcp-client/src/perform_oauth_login.rs`). Clerk enforces RFC 6749 (no repeated params) and rejects the request with `invalid_request: The request includes the parameter 'resource' more than once`. The official Notion/Figma plugins get away with it only because their authorization servers tolerate duplicates.
+- Keep the endpoint URL in sync with the root `.mcp.json` — both must point at the same `/v1/mcp` endpoint.
+
+**Changes to install/uninstall docs:**
+- Update both `README.md` and `docs/README_zh.md` together — they mirror each other
+- The canonical install is always the two-command sequence (`npx skills add …` + `npx -y @agentkey/cli --auth-login`). Don't imply either command does both.
+- Do **not** re-add OpenClaw / per-agent installers without a new design — historical context is in git history (removed in chore/remove-archive-directory)
+
+## Architecture Constraints
+
+- Setup mode in SKILL.md runs `! npx -y @agentkey/cli --auth-login` to authenticate via browser — same command as step 2 of the public install
+- `@agentkey/cli --auth-login` auto-writes MCP configs for 16 agents (canonical list lives in `AGENT_REGISTRY` in `../AgentKey-Server/cli/src/lib/mcp-clients.ts`): Claude Code, Claude Desktop, Cursor, Codex, Gemini CLI, OpenCode, Qwen Code, iFlow CLI, Kimi CLI, Kiro CLI, Windsurf, Warp, Amp, Crush, droid, openclaw. The `--only <ids>` flag (used by install.sh's `MCP_TARGETS` and install.ps1's `$McpTargets`) filters this list — its id values MUST match `npx skills add -a` ids, with `claude-desktop` as the one documented MCP-only exception. Goose / kode / kilo still need a manual JSON paste (see SKILL.md's "Fallback" section); when adding more agents server-side, keep `MCP_AUTO_AGENTS` in both install scripts and the cleanup list in both uninstall scripts in sync.
+- Root `.mcp.json` registers the remote-HTTP MCP endpoint (`https://api.agentkey.app/v1/mcp`) in Claude Code plugin mode; the API key flows from plugin userConfig into the `Authorization: Bearer ${user_config.AGENTKEY_API_KEY}` header (no stdio binary is launched)
+- `.codex-plugin/mcp.json` registers the same endpoint in Codex plugin mode, authenticated via MCP OAuth (RFC 9728 discovery; no `oauth_resource` — see checklist above)
+- `README.md` / `docs/README_zh.md` are the public-facing docs; keep them in sync with any structural changes
@@ -353,12 +353,27 @@ claude plugin install agentkey@agentkey

 On enable, Claude Code prompts for `AGENTKEY_API_KEY` (stored in your OS keychain) and injects it into the plugin's `.mcp.json` via `${user_config.AGENTKEY_API_KEY}`. Reload a local checkout with `claude plugin update agentkey` after edits. Day-to-day skill iteration is still fastest via the skills-CLI path; the plugin path is the one-step option for Claude Code users.

+**Codex plugin mode** — install from the marketplace bundled in this repo. Auth is OAuth (browser sign-in on install), so there's **no API key to paste and no second `@agentkey/cli` step**:
+
+```bash
+# Public install
+codex plugin marketplace add chainbase-labs/agentkey
+# then run /plugins inside Codex and install AgentKey,
+# or: codex plugin install agentkey@agentkey
+```
+
+The plugin manifest lives in `.codex-plugin/plugin.json`; it bundles the same skill plus a remote-HTTP MCP entry (`.codex-plugin/mcp.json`) that authenticates against `https://api.agentkey.app/v1/mcp` via MCP OAuth (RFC 9728 discovery). Sign in with your AgentKey account when Codex prompts you.
+
 **Repo layout:**

 ```
 agentkey/
 ├── .claude-plugin/plugin.json   # Claude Code plugin manifest
-├── .mcp.json                    # Used when installed as a plugin
+├── .codex-plugin/
+│   ├── plugin.json              # Codex plugin manifest
+│   └── mcp.json                 # Codex MCP entry (OAuth, no user_config)
+├── .agents/plugins/marketplace.json  # Codex marketplace (this repo is its own marketplace)
+├── .mcp.json                    # Used when installed as a Claude Code plugin
 ├── skills/agentkey/
 │   ├── SKILL.md                 # Decision tree + routing rules
 │   ├── scripts/                 # check-update helper
@@ -353,12 +353,27 @@ claude plugin install agentkey@agentkey

 启用时 Claude Code 会提示填 `AGENTKEY_API_KEY`（存进系统钥匙串），并通过 `${user_config.AGENTKEY_API_KEY}` 注入插件的 `.mcp.json`。改了本地 checkout 后用 `claude plugin update agentkey` 重新加载。日常 Skill 迭代仍是 skills CLI 最快；插件路径是给 Claude Code 用户的一步到位选项。

+**Codex 插件模式** —— 从本仓库自带的 marketplace 安装。认证走 OAuth（安装时浏览器登录），**不用粘贴 API Key，也不需要再单独跑 `@agentkey/cli`**：
+
+```bash
+# 公开安装
+codex plugin marketplace add chainbase-labs/agentkey
+# 然后在 Codex 里运行 /plugins 安装 AgentKey，
+# 或者：codex plugin install agentkey@agentkey
+```
+
+插件清单在 `.codex-plugin/plugin.json`；它捆绑了同一个 Skill，外加一条远程 HTTP MCP 配置（`.codex-plugin/mcp.json`），通过 MCP OAuth（RFC 9728 自动发现）对 `https://api.agentkey.app/v1/mcp` 做认证。Codex 提示时用你的 AgentKey 账号登录即可。
+
 **仓库结构：**

 ```
 agentkey/
 ├── .claude-plugin/plugin.json   # Claude Code 插件清单
-├── .mcp.json                    # 作为插件安装时使用
+├── .codex-plugin/
+│   ├── plugin.json              # Codex 插件清单
+│   └── mcp.json                 # Codex MCP 配置（OAuth，无 user_config）
+├── .agents/plugins/marketplace.json  # Codex marketplace（本仓库即自己的 marketplace）
+├── .mcp.json                    # 作为 Claude Code 插件安装时使用
 ├── skills/agentkey/
 │   ├── SKILL.md                 # 决策树 & 路由规则
 │   ├── scripts/                 # check-update 辅助脚本
@@ -15,6 +15,11 @@
          "path": ".claude-plugin/plugin.json",
          "jsonpath": "$.version"
        },
+        {
+          "type": "json",
+          "path": ".codex-plugin/plugin.json",
+          "jsonpath": "$.version"
+        },
        {
          "type": "generic",
          "path": "skills/agentkey/scripts/check-update.sh"