skills/chainbase-labs__agentkey
1
0
Fork 0
mirror of https://github.com/chainbase-labs/Agentkey.git synced 2026-09-20 14:20:23 +08:00
Code Issues Packages Projects Releases Wiki Activity
52 Commits 3 Branches 26 Tags
83363014c47a029e972095ef1df16005dbf2620b
Commit Graph

9 Commits

Author SHA1 Message Date
不白 83363014c4 feat(installer): unify skill + MCP agent registration (16 agents) (#41) 
## Summary

- Drive both `npx skills add -a` and `@agentkey/mcp --auth-login --only`
from a single detected-agent list. MCP registration now follows the same
per-host auto-detection that skill install already does, expanding MCP
auto-registration from 3 clients to **16**.
- Fix the longstanding `claude-code` marker bug: it included Claude
Desktop's config dir, causing skills CLI to target a nonexistent Claude
Code on Desktop-only machines. `claude-desktop` is now its own id
(MCP-only) — passed to `--auth-login --only` but never to `skills add`.
- Detect Claude Desktop via `/Applications/Claude.app` /
`%LOCALAPPDATA%\AnthropicClaude` so "installed but never launched" still
registers (Linux still requires the config dir).
- New `scripts/dev-smoke.sh` — sandboxed 4-phase regression suite, 42
assertions, ~10s, never touches real `$HOME`. Run before any PR touching
install/uninstall scripts.

## Depends on


[chainbase-labs/AgentKey-Server#9](https://github.com/chainbase-labs/AgentKey-Server/pull/9)
— adds `--only <ids>` to `@agentkey/mcp --auth-login`. Older CLI
versions silently ignore the flag, so this PR is forward-compatible
either way.

## Uninstaller (the bigger gap before this)

The previous uninstaller only cleaned 3 config paths and only knew the
`mcpServers.<name>` JSON shape. With 13 new agents using 4 different
schema dialects, that left AgentKey configured everywhere after
uninstall.

- Expanded MCP cleanup to **14 JSON paths + codex TOML**, covering all
16 auto-registered agents
- Schema-agnostic JSON scrub: walks the tree and drops dict keys whose
name EXACTLY matches our server names. Handles `mcpServers.<name>` /
`mcp.<name>` / `amp.mcpServers.<name>` / `projects.X.mcpServers.<name>`
in one pass
- Codex TOML splice via awk / PowerShell (no parser dep) — drops
`[mcp_servers.agentkey]` + legacy quoted block, preserves sibling
sections
- `droid mcp remove` + `openclaw mcp unset` for CLI-registered agents
- **Exact-match** server names (not substring) so user keys like
`agentkey-helper` are preserved (regression test included in dev-smoke)

## Bugs fixed during review

| Where | Bug |
|---|---|
| install.sh:487 | Unbound `$TARGETS` variable (renamed during refactor)
— `set -u` would have made this fatal |
| install.ps1 | `$SkillTargets.Count` used where `$AllTargets.Count` was
meant — diverged from install.sh behavior |
| install.sh | `--only claude-desktop` ran `skills add -a` with no
filter, defeating the user's `--only` intent. Now correctly skips the
skill step |
| install.sh helpers | Leaked-scope loop vars (`_ids`, `_id`) — declared
`local -a` |

## Test plan

- [x] `scripts/dev-smoke.sh` — 42 passing / 0 failing (Phase 1 unit
tests + Phase 2 installer + Phase 3 writer schemas + Phase 4 uninstaller
w/ false-positive guard)
- [x] `bash -n` clean for install.sh + uninstall.sh
- [x] `--list-agents` correctly lists `claude-desktop` as a separate id
- [x] `--only claude-desktop --skip-mcp --yes` walks the new "MCP-only,
skip skill" branch
- [x] Auto-detect path tested via `bash -x` trace under `set -u` (no
unbound-variable explosion)
- [x] Uninstaller decoy fixtures: `agentkey-helper`, `other-svr`,
`[mcp_servers.other]`, `[unrelated_section]` all preserved after scrub
- [ ] Windows: `install.ps1` / `uninstall.ps1` syntax-checked but not
runtime-tested (no Windows box handy — happy to test if reviewer has
one)

---------

Co-authored-by: Bruce <bruce@checkabc.me>
 2026-05-20 10:07:11 +08:00
lxcong 26d220c582 fix(install): drop remote/local detection, always try browser (#52) 
## Summary

Installer was sniffing SSH env vars, `~/.openclaw`, and `\$DISPLAY` to
decide whether to pass `--no-browser` to `@agentkey/cli --auth-login`.
Inspecting the v1.0 CLI source confirms this was unnecessary:

```js
const { device_code, user_code, verification_uri, expires_in } = await res.json();
const authUrl = \`\${verification_uri}?code=\${user_code}\`;
console.log(\`  Open this URL to authorize:\`);   // ← always prints
console.log(\`  \${authUrl}\`);
// ...
if (!noBrowser) { /* best-effort open() */ }       // ← only this is gated
```

The CLI **always** prints the auth URL on stdout. `--no-browser` only
adds a terminal QR and skips the `open()`/`xdg-open()`/`start()`
attempt. The CLI's open-browser call is already best-effort — on a
headless host it silently no-ops.

So the installer-side heuristic was:
- **redundant** for the URL (CLI prints it either way)
- **harmful** when it mis-detected (local users on a headless tmux pane
or behind a mis-detected SSH session got the QR flow with no browser
attempt at all, even though their machine could have opened one)

This was the root cause of the reported "no browser pops up on \`curl …
| bash\`" symptom.

## Fix

Drop the heuristic. Always call \`npx -y @agentkey/cli --auth-login\`
(no \`--no-browser\`). The CLI tries \`open\` / \`xdg-open\` /
\`start\`; if that fails the user has the URL right there in the
terminal.

## Removed

- \`detect_remote()\` in \`scripts/install.sh\` / \`Test-RemoteInstall\`
in \`scripts/install.ps1\`
- \`--remote\` / \`--local\` / \`-Remote\` / \`-Local\` flags + their
mutually-exclusive guard + \`FORCE_REMOTE\` / \`FORCE_LOCAL\` state
- \`--no-browser\` passthrough to the CLI
- \"Installing over SSH, inside Docker, …\" details section in README.md
/ docs/README_zh.md — replaced with a one-line callout under the
advanced install options
- Synopsis / help / behavior copy mentioning the old detection logic

Net: **+24 / -174 lines**.

## Test plan

- [ ] On macOS / Linux desktop: \`curl -fsSL
https://agentkey.app/install.sh | bash\` — browser pops up; URL also
visible in terminal as a fallback
- [ ] In an SSH session: same one-liner — \`xdg-open\` no-ops on the
remote host (no harm), URL is right there in terminal; copy it to a
local browser to finish
- [ ] Windows PowerShell: \`irm https://agentkey.app/install.ps1 | iex\`
— \`start\` opens the default browser; URL also visible
- [ ] \`--skip-mcp\` still skips the auth step
- [ ] \`bash -n scripts/install.sh\` passes (verified)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: lxcong <lxcong@chainbase.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-15 18:03:58 +08:00
lxcong 658dfda00b fix(install): always run auth-login, drop stale already_authed check (#50) 
## Summary

The installer's "is AgentKey already configured?" heuristic went stale
after #47 / v1.7.0 switched `--auth-login` from a stdio MCP block to a
remote-HTTP one. The check still greps for `\"AGENTKEY_API_KEY\":
\"ak_...\"` (the old env-shaped field) — but the new config writes
`\"Authorization\": \"Bearer ak_...\"` inside `headers` instead.

**Observed symptom**: a user with a residual stdio config from an
earlier release sees

> ✓ AgentKey is already configured in an MCP client config — skipping
auth.

…the installer exits successfully, but calling any AgentKey MCP tool
errors out because the stdio runtime `@agentkey/mcp` is no longer used.

The mirror failure also exists: users who **have** successfully
re-authed into the new HTTP shape no longer match the regex and would
get re-prompted on every installer run.

## Fix

Delete the heuristic. `@agentkey/cli --auth-login` already knows whether
the local token can be reused or a fresh device-code round-trip is
needed — let the CLI decide instead of having the installer second-guess
from on-disk shape.

**Removed**

- \`already_authed()\` in \`scripts/install.sh\`
- \`Test-AlreadyAuthed\` in \`scripts/install.ps1\`
- \`--force-mcp\` / \`-ForceMcp\` flags (no longer meaningful — auth
always runs unless \`--skip-mcp\`)
- \`--force-mcp\` documentation in README.md / docs/README_zh.md

Net: **-57 / +10 lines** across the four files.

## Test plan

- [ ] On a machine with a stale stdio-shaped \`~/.claude.json\` from a
pre-1.7 install: \`curl -fsSL https://agentkey.app/install.sh | bash\`
now actually re-runs auth-login and the MCP block becomes a working HTTP
entry
- [ ] On a fresh machine: install still completes auth in one
device-code flow (no behavior change)
- [ ] On a machine already on the new HTTP shape: re-running the
installer still works and the CLI either reuses the token or prompts
(CLI's call, not the installer's)
- [ ] \`--skip-mcp\` continues to skip the auth step
- [ ] \`bash -n scripts/install.sh\` passes (verified)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: lxcong <lxcong@chainbase.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-15 17:19:24 +08:00
Bruce ab0dba7eb1 feat: rename @agentkey/mcp → @agentkey/cli in install scripts and docs (#47) 
## Summary

Companion change to
[chainbase-labs/AgentKey-Server#32](https://github.com/chainbase-labs/AgentKey-Server/pull/32).
The npm package has been renamed; this PR updates everything users
actually see.

**User-facing**
- \`scripts/install.{sh,ps1}\`: \`MCP_PACKAGE\` / \`$McpPackage\` →
\`CLI_PACKAGE\` / \`$CliPackage\`
- \`scripts/uninstall.{sh,ps1}\`: sweep BOTH \`@agentkey/cli\` and
\`@agentkey/mcp\` so users upgrading from v0.x get a clean uninstall
- \`skills/agentkey/SKILL.md\`: setup command + manual-config JSON
example
- \`README.md\` + \`docs/README_zh.md\`: every \`npx @agentkey/mcp\`
command + the manual-config JSON examples (switched from stale stdio
shape to the remote-HTTP shape that \`--auth-login\` actually writes in
v1.0)

**Internal / protocol docs**
- \`SECURITY.md\`: file/network audit tables
- \`protocol/skill-meta-v1.md\`, \`docs/SERVER-IMPLEMENTATION.md\`:
clarify the protocol partner is AgentKey-Server's hosted \`/v1/mcp\`
endpoint, not a standalone npm package — these references were already
misleading before the rename
- \`.claude/CLAUDE.md\`: keep Claude-session guidance in sync

\`CHANGELOG.md\` left untouched (release-please manages history).

## Sequencing

Merge this PR **after** \`@agentkey/cli\` is published to npm —
otherwise the install scripts here will reference a package that doesn't
exist yet. Recommended order:

1. Merge
[AgentKey-Server#32](https://github.com/chainbase-labs/AgentKey-Server/pull/32)
2. \`cd cli && npm publish\` (first \`@agentkey/cli\` release at
\`1.0.0\`)
3. Merge this PR

## Test plan

- [ ] Verify \`npx -y @agentkey/cli --auth-login\` works end-to-end
after npm publish
- [ ] Verify \`scripts/uninstall.sh\` on a machine with
\`@agentkey/mcp\` globally installed cleans it up
- [ ] Spot-check the rendered README on GitHub for any missed references
 2026-05-15 16:31:42 +08:00
lxcong 2069e0ca42 feat: agent install telemetry (installer side, spec §8.3) (#30) 
## Summary

Installer-side half of the agent-install telemetry rollout (spec §8.3).
Adds `--no-telemetry` opt-out, telemetry status banner, and 7-var env
passthrough to `npx -y @agentkey/mcp --auth-login` so the server can
capture `install_completed` with full install context.

- `scripts/install.sh`: `--no-telemetry` flag,
`compute_device_fingerprint()` helper, env exports immediately before
the `--auth-login` invocation
- `scripts/install.ps1`: PowerShell-mirror of the same — `-NoTelemetry`,
SHA-256 fingerprint, `$env:AGENTKEY_*` exports

## Blocked on

**AgentKey-Server PR** that consumes the 7 transparent env vars
(`AGENTKEY_TELEMETRY`, `AGENTKEY_INSTALL_SOURCE`,
`AGENTKEY_DETECTED_AGENTS`, `AGENTKEY_SELECTED_AGENTS`,
`AGENTKEY_INSTALLER_FLAGS`, `AGENTKEY_DEVICE_FINGERPRINT` — plus
implicit skill-version detection on the server side) and capture
`install_completed`. Until that lands, the env passthrough goes to a
process that does nothing with them — harmless, but the telemetry signal
is incomplete.

This PR can be merged independently — it does not break the existing
installer flow either way.

## Test plan

- [x] `bash -n scripts/install.sh` — syntactic check passes
- [x] `bash scripts/install.sh --help` — `--no-telemetry` documented in
Options
- [x] `bash scripts/install.sh --list-agents` — early-return path
unaffected
- [x] `bash scripts/install.sh --no-telemetry --skip-skill --skip-mcp
--yes` — creates `~/.config/agentkey/telemetry-disabled`, prints
"Telemetry: disabled (--no-telemetry)"
- [x] Pre-existing opt-out file recognized — prints "Telemetry: disabled
(~/.config/agentkey/telemetry-disabled exists)"
- [x] Default (no flag / no file) — prints "Telemetry: anonymous usage
stats enabled (re-run with --no-telemetry to opt out)"
- [x] `install.ps1` structural checks (line count, `\$NoTelemetry`
references, single `param(...)` block, brace balance)
- [ ] PowerShell parse on Windows runner (relies on existing
windows-latest CI for any install.ps1-touching PR)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: lxcong <lxcong@chainbase.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-14 16:09:36 +08:00
不白 65fb2f8181 feat: server-beacon skill-update path for non-Bash clients (#39) 
## Summary

Fixes the silent-update-failure mode where Claude Desktop (and any MCP
client without a Bash tool) gets stuck on whatever skill version shipped
at first install. On this developer's Desktop the skill had been frozen
at `0.1.2` since April — no upgrade ever fired.

Root cause is structural: SKILL.md Step 0's update check uses an inline
` ```bash ``` ` block. Claude Code executes it; Desktop reads it as
documentation. So the entire upgrade flow is dead code on Desktop. This
PR routes the version check through the MCP server instead (always-on,
available to every client), and tightens a couple of correctness bugs in
the existing install/uninstall path while we're here.

Companion PR: chainbase-labs/AgentKey-Server (server-side
`agentkey_skill_meta` tool).

## What's in here

1. **Protocol** (`protocol/skill-meta-v1.md` +
`skill-meta-v1.schema.json` + 4 fixtures) — versioned,
additive-evolution wire format for an MCP meta tool that returns
`{skill_version_latest, client_detected, update_command, update_doc_url,
…}`. Spec lives in this repo (single source of truth); server vendors a
copy and CI on both sides diffs them.
2. **SKILL.md** — Step 0 now has 0.A (beacon, cross-client) → 0.B
(inline bash, Code-only compat) → 0.C (MCP tool sanity check). Step B
branches every persistence option on whether Bash is available, with
explicit no-Bash fallback text that tells the user what didn't get saved
and the exact terminal command to persist it manually. Step C points the
non-shell fallback at GitHub Releases (we don't have a docs site).
3. **install/uninstall scripts** — `npx skills remove
chainbase-labs/agentkey` was the wrong invocation: the CLI takes the
skill name (`agentkey`), exits 0 on no-match, and made the uninstaller
falsely report success. Same class of silent-success bug in `install.sh`
when `git clone` fails mid-run. Both fixed; added post-install
filesystem verification.
4. **README / README_zh** — accurate per-client update story, including
a one-time bootstrap command for users currently stuck on a pre-1.4.0
skill on Desktop.
5. **CI** (`protocol-validate.yml`) — every fixture validates against
the schema, schema rejects 4 known-bad payloads (regression guard), spec
doc references every fixture (forces docs ↔ artifact sync).
6. **`docs/SERVER-IMPLEMENTATION.md`** — handoff doc for the server PR.

## How verified

- 4/4 fixtures pass schema; 4/4 bad payloads correctly rejected
- All cross-references in spec doc resolve
- `verify-version-sync` awk still extracts `1.3.0` from SKILL.md
frontmatter
- Companion server PR exercises the actual MCP handshake (initialize +
tools/list + tools/call); response is valid v1 JSON
- Real GitHub Releases fetch + ETag caching works on the server side

## Test plan

- [ ] CI green (`protocol-validate.yml` and `verify-version-sync.yml`
both pass)
- [ ] Companion server PR merged + new `@agentkey/mcp` published
- [ ] Release-please cuts `v1.4.0` from this branch
- [ ] On Claude Code: existing inline-bash Step 0 still fires for users
on `v1.3.x`; they get prompted to update normally
- [ ] On Claude Desktop with a pre-1.4.0 skill: user runs the README
bootstrap command once to land `v1.4.0`; from that point on, every
subsequent version is auto-discovered via the meta tool
- [ ] On Cursor / Codex: meta tool returns the `npx skills update -g
agentkey` recipe; user upgrades via shell

## Notes for the reviewer

- This is **additive**: Claude Code's existing inline-bash path is
unchanged, so no regression risk there. The protocol's
`protocol_version: 1` + immortal `update_doc_url` fallback make future
v2 servers safely degradable for v1 skills.
- Claude Desktop deliberately has no `update_command` recipe yet —
Desktop installs skills into a sandboxed `~/Library/Application
Support/Claude/local-agent-mode-sessions/skills-plugin/<UUID>/...` path
that no external CLI can reach, and we don't have a first-party
installer script. The skill rule's "no command → point at GitHub
Releases" fallback handles this until one exists. Adding a Desktop
recipe later is a non-breaking change (one row in the server's `RECIPES`
map).
 2026-05-12 17:46:55 +08:00
MOGU :\'-"/ f05e501e42 chore(install): remove fallback MCP snippet hint (#38) 
## Summary

- The post-install summary printed an `If your agent is NOT Claude Code
/ Claude Desktop / Cursor` block with a manual MCP JSON snippet. By the
time the user sees it, `@agentkey/mcp --auth-login` has already either
auto-written the supported configs or surfaced its own error — so this
block is ambiguous noise for the supported path, and the canonical
fallback for unsupported agents already lives in `SKILL.md`'s Fallback
section.
- Removed the same block from `install.ps1` to keep the Bash and
PowerShell installers in sync.

## Test plan

- [ ] `bash scripts/install.sh` ends with `Next steps` → `Docs` →
`Uninstall` (no fallback snippet block in between).
- [ ] `pwsh scripts/install.ps1` shows the same trimmed summary on
Windows.
- [ ] Confirm `skills/agentkey/SKILL.md` still documents the
manual-paste fallback for non-auto-targeted agents (no doc regression).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-12 15:26:43 +08:00
不白 29176d1aae feat(install): auto-detect agents, route MCP auth to QR mode for remote installs (#18) 
## Summary

Two end-to-end improvements to `install.sh` / `install.ps1`, mirrored
across both:

### 1. Agent auto-detection

Probe well-known config dirs and binaries for ~18 of
[vercel-labs/skills](https://github.com/vercel-labs/skills)' 45
supported agents (`claude-code`, `cursor`, `codex`, `gemini-cli`,
`opencode`, `openclaw`, `qwen-code`, `iflow-cli`, `windsurf`, `warp`,
`amp`, `crush`, `goose`, `droid`, `kode`, `kilo`, `kimi-cli`,
`kiro-cli`).

When detection finds anything, the `skills add` step gets `-a id1,id2,…`
instead of dumping the user into the multi-select. New flags:

- `--list-agents` — preview what we'd auto-select (and exit)
- `--all-agents` — skip our detection, let `skills` CLI scan everything
- `--only` — manual override (unchanged)

### 2. Local-vs-remote MCP auth routing

The current `--auth-login` always auto-opens a browser. On SSH sessions,
Docker containers, and OpenClaw remote channels (where the user is on a
phone), that silently launches a browser they can't see — leaving them
stuck on "Waiting for authorization…".

Detection (any signal fires ⇒ remote):

| Signal | Notes |
|---|---|
| `$HOME/.openclaw` exists | OpenClaw runtime — most reliable single
signal |
| `$SSH_CONNECTION` / `$SSH_TTY` | Generic SSH session |
| Linux without `$DISPLAY` / `$WAYLAND_DISPLAY` | Headless |

When remote, pass `--no-browser` to the MCP CLI, which prints URL + ANSI
QR for the user to scan with a phone.

New flags:

- `--remote` / `--local` — force either mode
- `--force-mcp` — re-auth even if AgentKey is already configured

Also adds an idempotency short-circuit: if any known MCP config already
has an `agentkey` block with a valid-looking API key, skip the auth step
entirely (`--force-mcp` to override).

### 3. Docs

`README.md` + `docs/README_zh.md` updated to document the new flags and
add a dedicated **"Installing over SSH / Docker / OpenClaw"** section.

## Companion PRs (server side)

The MCP-server changes that this installer routes to ship in a chain of
three PRs against `chainbase-labs/AgentKey-Server`:

| PR | Status | What it adds |
|---|---|---|
| [#2](https://github.com/chainbase-labs/AgentKey-Server/pull/2) |
merged | `--no-browser` / `--qr` / `--no-qr` flags + `qrcode-terminal`
dep (v0.3.5 source bump) |
| [#3](https://github.com/chainbase-labs/AgentKey-Server/pull/3) |
merged | Bump to 0.3.6 — npm `0.3.5` had been published from a pre-merge
commit and shipped stale `dist/` |
| [#4](https://github.com/chainbase-labs/AgentKey-Server/pull/4) | open
| Fix QR not rendering in `--no-browser` (CJS interop bug —
`qrcode-terminal`'s `generate` lives on `.default` under NodeNext); bump
to 0.3.7 |

**This installer needs `@agentkey/mcp@0.3.7`** to be on npm for the QR
flow to actually work. Sequence:

1. Merge #4 ✅
2. Maintainer runs `cd mcp-server && npm publish` (no npm-publish CI
workflow) ✅
3. Merge this PR — `npx -y @agentkey/mcp` will then pull 0.3.7+ and the
`--remote` path renders the QR

This installer change is **forward-compatible**: it can land anytime —
older `@agentkey/mcp` versions silently ignore the unknown
`--no-browser` flag, so worst case a remote user gets the old
browser-opens-on-the-wrong-host UX until the new mcp publishes.

## Test plan

Verified end-to-end on macOS against a local build of
`@agentkey/mcp@0.3.7` (server PR #4):

- [x] Bash syntax check passes (`bash -n install.sh`)
- [x] `install.sh --help` renders all 5 new flag rows
- [x] `install.sh --list-agents` correctly prints detected agents on
test host (10 agents incl. `openclaw`)
- [x] `install.sh --remote --local` exits with code 1 (mutex)
- [x] `install.sh --skip-skill` short-circuits with "AgentKey is already
configured…" when configs have agentkey
- [x] `install.sh --remote --skip-skill --force-mcp` end-to-end: prints
`Detected remote install context — printing QR + URL instead of opening
a browser here`, then `reason: $HOME/.openclaw exists (OpenClaw
runtime)`, launches mcp CLI, renders 16-row ANSI QR, polls — no `open`
process spawned
- [x] All 4 mcp 0.3.7 flag combinations behave correctly (`--no-browser`
/ `--no-browser --no-qr` / `--qr` / no-flags back-compat)
- [ ] `install.ps1` not lint-checked locally (no pwsh on test host);
logic is a strict mirror of bash — needs Windows smoke before merge
- [ ] Inside a real OpenClaw container — confirm `~/.openclaw` triggers
as expected

## Why now

Users running the installer via OpenClaw / Claude Code remote channels
(on a phone) currently see a black-hole UX: the browser opens on the
wrong machine and the install process appears to hang. The detection
here removes the manual `--remote` flag for the common case.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
 2026-04-27 21:55:57 +08:00
lxcong b3d806105b chore: initial public release 2026-04-23 13:52:31 +08:00