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
47 Commits 3 Branches 26 Tags
658dfda00b0d53808bff816a6c43888d24c73e5f
Commit Graph

8 Commits

Author SHA1 Message Date
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 f830f2947d feat: agent install telemetry (skill side, spec §8.1) (#31) 
## Summary

Skill-side half of the agent-install telemetry rollout (spec §8.1).
`check-update.sh` emits `TELEMETRY ...` lines on stdout, SKILL.md parses
them and dispatches via MCP. Adds 3-layer opt-out (file / env /
installer flag — file path checked here), 24h client-side dedup, and a
bats test harness.

- `skills/agentkey/scripts/check-update.sh` — `emit_telemetry()` +
`auto_upgrade_flag()` helpers, opt-out checks, 7 emit calls at 5 exit
points, 24h heartbeat dedup keyed by `LOCAL_VERSION`. Includes Linux
`stat` order fix (`-c %Y` first, `-f %m` second — `-f` on Linux means
filesystem mountpoint, not mtime)
- `skills/agentkey/SKILL.md` — Step 0 instructions for parsing
`TELEMETRY` lines and dispatching via
`execute_tool(\"agentkey_internal\", {path:\"telemetry/event\", ...})`;
upgrade-flow each branch dispatches `upgrade_decision` /
`upgrade_result` with mapped choice values
- `tests/check-update.bats` + `tests/helpers.bash` — 10 contract tests
with isolated `\$HOME` / `\$TMPDIR` / mocked curl
- `.github/workflows/scripts-test.yml` — bats CI on ubuntu + macos
- `README.md` + `docs/README_zh.md` — FAQ replacement for the old
\"nothing to collect\" sentence, new FAQ entry \"How do I opt out of
telemetry?\" / \"我如何关闭遥测？\"
- `scripts/uninstall.sh` — adds Step 7b to clean `~/.config/agentkey/`
(telemetry-disabled, update-disabled, snooze state)

## Blocked on

**AgentKey-Server PR** that registers the
`agentkey_internal/telemetry/event` MCP tool (must be filtered out of
`list_tools` / `find_tools` so the LLM doesn't accidentally call it).
SKILL.md falls back silently when the tool doesn't exist, so this PR is
safe to merge first — but the telemetry signal isn't recorded until the
server side lands.

Spec §11 mandates server-first merge order to keep the agent-side debug
log clean.

## Test plan

- [x] `bats tests/check-update.bats` — 10/10 passing locally
- [x] E2E smoke (skill-side plan Task 8 steps 1-3, 5):
  - Default emit on `up_to_date`
- `~/.config/agentkey/telemetry-disabled` early-return (no TELEMETRY
line)
  - `AGENTKEY_TELEMETRY=0` env override
  - 24h heartbeat dedup (2nd invocation within window does not re-emit)
  - `uninstall.sh` Step 7b cleans `~/.config/agentkey/`
- [ ] **Manual** — open Claude Code, ask an AgentKey-routed query.
Verify SKILL.md silently swallows the missing `agentkey_internal` tool
error (server not shipped yet) and the actual query still completes
- [ ] Verify bats CI runs green on ubuntu + macos matrix

## Pre-existing bug surfaced during testing (not in this PR)

`check-update.sh` line 130-ish cache fast-path uses the same wrong `stat
-f %m ... || stat -c %Y` order. Same Linux bug as the one fixed here in
`emit_telemetry`. Worth a separate one-line fix 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:41:35 +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