diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json new file mode 100644 index 0000000..1df8138 --- /dev/null +++ b/.agents/plugins/marketplace.json @@ -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" + } + ] +} diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 8d9bd46..2d85d04 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -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"] } ] } diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 03d8af2..d2d3670 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -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", diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 1c3d507..3382ad4 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -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_}`: 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=` 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. diff --git a/.codex-plugin/mcp.json b/.codex-plugin/mcp.json new file mode 100644 index 0000000..2a958b8 --- /dev/null +++ b/.codex-plugin/mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "agentkey": { + "type": "http", + "url": "https://api.agentkey.app/v1/mcp" + } + } +} diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json new file mode 100644 index 0000000..9ad3db9 --- /dev/null +++ b/.codex-plugin/plugin.json @@ -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" + ] + } +} diff --git a/.gitignore b/.gitignore index f70f715..954f9a9 100644 --- a/.gitignore +++ b/.gitignore @@ -19,3 +19,4 @@ cli/.vitest/ # Claude Code workflow artifacts (internal, not shipped publicly) docs/superpowers/ RELEASE_NOTES.md +.claude/worktrees/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..afa423b --- /dev/null +++ b/AGENTS.md @@ -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_}`: 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=` 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 ` 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 diff --git a/README.md b/README.md index d00cb35..56bf439 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/README_zh.md b/docs/README_zh.md index 86050a1..686c3e8 100644 --- a/docs/README_zh.md +++ b/docs/README_zh.md @@ -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 辅助脚本 diff --git a/release-please-config.json b/release-please-config.json index 5e79345..541ef5d 100644 --- a/release-please-config.json +++ b/release-please-config.json @@ -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"