a5ef8963c7
Renamed @keisei/mcp-server → @keisei84/mcp-server (scope must match
github org KeiSei84 for GitHub Packages publish). Replaced private:true
with publishConfig pinned to npm.pkg.github.com so an accidental
`npm publish` cannot leak to npm.org. CI npm-publish job rewired to
GitHub Packages auth (GITHUB_TOKEN with packages:write permission).
Why GitHub Packages, not npm.org:
- Authentication piggybacks on existing github org / PAT — no separate
account or NPM_TOKEN required for the core kit
- Scope @keisei84 maps 1:1 to org KeiSei84 (npm rule for github)
- Doesn't require public DNS for our private Forgejo (Tailscale-only
100.91.246.53 cannot be the publish target — IP-leak in public ref)
- Published artefacts live under github.com/orgs/KeiSei84/packages,
same access surface as the source repo
Why not @keisei (un-scoped or different scope):
- npm scope @keisei IS reachable on npm.org but we don't own it there
(would require email-verified npm account claim + ongoing maintenance)
- @keisei84 requires zero new accounts; works the moment KeiSei84 org
has packages enabled (github default)
Files changed (11):
- _ts_packages/packages/mcp-server/package.json — rename + publishConfig
+ repository field (required by GitHub Packages); removed private:true
- _ts_packages/package-lock.json — regenerated via `npm install`
(workspace recognises @keisei84/mcp-server symlink)
- README.md (2 hunks) — maturity row says "alpha" not
"alpha (unpublished)"; install section documents `~/.npmrc` setup
for `@keisei84:registry=https://npm.pkg.github.com/`
- PLUGIN.md (3 hunks) — same `~/.npmrc` setup; .mcp.json references
@keisei84/mcp-server; "not yet on npm" replaced with "lives on
GitHub Packages, not npm.org"
- .claude-plugin/mcp-template.json — args use @keisei84 scope
- _ts_packages/README.md (4 hunks) — package layout + npx examples
- docs/INSTALL.md, install/lib-rust.sh — comment refs
- docs/encyclopedia/substrate-overview.md (2 hunks) — package table +
publishing notes (was "published to keigit.com npm" — wrong; keigit
is a separate community-publish path for user-contributed packages,
not the destination for core @keisei84 packages)
- .github/workflows/release.yml — npm-publish job rebuilt:
· permissions: packages:write
· Two-scope .npmrc temp-write: @keisei84 → npm.pkg.github.com (always),
@keisei → npm.org (only if NPM_TOKEN secret set, else skipped per pkg)
· NODE_AUTH_TOKEN sourced from GITHUB_TOKEN
· .npmrc cleaned up via `if: always()` step
- .gitignore — _ts_packages/.npmrc + .npmrc excluded (RULE 0.8: auth
tokens never in git; CI temp-creates per-job)
Verification:
- `npm install` clean against new scope: node_modules/@keisei84/mcp-server
symlinks to packages/mcp-server, other adapters untouched in
node_modules/@keisei/* [REAL: install ran 2026-05-03 in this session]
- `npm run build --workspace=@keisei84/mcp-server` produces dist/index.js
[REAL: tsc -b exit 0]
- Server starts cleanly: `node dist/index.js` runs >1s, emits expected
"[adapters] not installed" warnings for un-built sibling adapters,
doesn't throw
- 17 references to old @keisei/mcp-server scope migrated; 0 left
[REAL: grep -rn "@keisei/mcp-server" returns 0 lines]
Bad-commit-hygiene note:
- Two earlier local commits (cb8dc2a + revert 474fe1c) attempted a
keigit.com-pinned variant; soft-reset past them so this commit lands
on top of public 368df5b. Bad commits never reached remote.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
86 lines
5.4 KiB
Markdown
86 lines
5.4 KiB
Markdown
# KeiSeiKit — Anthropic Claude Code plugin format
|
|
|
|
This document describes the plugin-format install path (v0.16+) and how it relates to the classic `./install.sh` path. Both paths are supported; use whichever fits.
|
|
|
|
## TL;DR
|
|
|
|
```bash
|
|
# One-time
|
|
/plugin marketplace add KeiSei84/KeiSeiKit
|
|
# Install
|
|
/plugin install keisei@keisei-marketplace
|
|
```
|
|
|
|
The plugin auto-registers: agents, skills, hooks, and the MCP server. No manual `~/.claude/settings.json` edits. No `install.sh` needed for the core (non-primitive) experience.
|
|
|
|
## Layout
|
|
|
|
The repo follows the [Anthropic Claude Code plugin spec](https://code.claude.com/docs/en/plugins):
|
|
|
|
```
|
|
.claude-plugin/
|
|
plugin.json # plugin manifest (name, version, author, license, keywords)
|
|
marketplace.json # marketplace manifest — lets this repo serve as a marketplace source
|
|
mcp-template.json # template for .mcp.json (copy to repo root; see "MCP prerequisite" below)
|
|
agents/ # auto-discovered by Claude Code at plugin-install time
|
|
skills/<name>/SKILL.md # auto-discovered
|
|
hooks/hooks.json # PreToolUse / PostToolUse / Stop hooks with ${CLAUDE_PLUGIN_ROOT} paths
|
|
.mcp.json # MCP server registration (see prerequisite note)
|
|
```
|
|
|
|
Paths inside `hooks/hooks.json` use `${CLAUDE_PLUGIN_ROOT}` (expanded by Claude Code at runtime to the plugin install directory) rather than absolute `$HOME/.claude/hooks/...` paths. This lets the same hooks ship unchanged whether the plugin is installed from GitHub, npm, or a local path.
|
|
|
|
## Plugin install vs classic install — what differs
|
|
|
|
| Feature | Plugin install | Classic `./install.sh` |
|
|
|---|---|---|
|
|
| Agents registered | yes, automatic | yes, copied to `~/.claude/agents/` |
|
|
| Skills registered | yes, automatic | yes, copied to `~/.claude/skills/` |
|
|
| Hooks wired | yes, via `hooks/hooks.json` | requires `--activate-hooks` (jq-merge of `settings-snippet.json`) |
|
|
| MCP server | yes, via `.mcp.json` (uses `@keisei84/mcp-server` from GitHub Packages — requires `~/.npmrc` setup, see below) | same |
|
|
| 47 Rust primitives | **no** — plugin ships manifest sources only; no cargo build | yes, `--profile=<name>` builds the selected set |
|
|
| 13 shell primitives | **no** | yes, copied to `~/.claude/agents/_primitives/` |
|
|
| Disk footprint | ~2 MB (plugin cache) | ~2 MB minimal up to ~200 MB full |
|
|
| Update path | `/plugin update keisei` | `git pull && ./install.sh` |
|
|
| Update visibility | Claude Code shows version change | silent |
|
|
|
|
**Bottom line:** plugin install is the right default for the agent-kit experience (agents + skills + hooks). For the Rust primitives (`tomd`, `kei-ledger`, `provision-hetzner`, `kei-migrate`, etc.), fall back to the classic installer or run it alongside the plugin — the two don't collide because the plugin namespaces into its own install dir and the classic installer writes to `~/.claude/`.
|
|
|
|
## Prerequisites
|
|
|
|
**For plugin install:**
|
|
- Claude Code 2.1+ (check with `claude --version`)
|
|
- Network access to `github.com/KeiSei84/KeiSeiKit` on `/plugin marketplace add`
|
|
|
|
**For the MCP server subset:**
|
|
- `@keisei84/mcp-server` available from **GitHub Packages**
|
|
(`https://npm.pkg.github.com/`). One-time `~/.npmrc` setup:
|
|
```
|
|
@keisei84:registry=https://npm.pkg.github.com/
|
|
//npm.pkg.github.com/:_authToken=<github PAT with read:packages>
|
|
```
|
|
Without the `~/.npmrc` rows, `npx` cannot resolve the scoped
|
|
package and the `keisei` MCP server simply won't appear in your
|
|
tool list — the agents, skills, and hooks all work without it.
|
|
- Node.js 18+ (for `npx` to fetch the server on demand)
|
|
|
|
**For the Rust primitives (classic install only):**
|
|
- Rust stable, `jq`, plus the soft-deps listed in the main README per-profile table.
|
|
|
|
## Known limitations
|
|
|
|
1. **Rust primitives not auto-installed.** The plugin format doesn't currently express "also run `cargo build` at install time". We ship the manifest sources in-repo so that users who want the primitives can run `./install.sh --profile=full` alongside the plugin. A future version may add pre-built release binaries for common platforms (macOS arm64/x86_64, Linux x86_64) into `bin/` so the plugin can ship primitives without a cargo step.
|
|
2. **`@keisei84/mcp-server` lives on GitHub Packages, not npm.org.** The `.mcp.json` entry uses `npx -y @keisei84/mcp-server` which resolves through the `~/.npmrc` `@keisei84:registry` line above. Without that line, `npx` will hit npm.org by default and 404. See `_ts_packages/packages/mcp-server/README.md` for the publish pipeline.
|
|
3. **Hooks use `${CLAUDE_PLUGIN_ROOT}`.** This is the official Claude Code plugin variable. Older Claude Code versions (<2.1) that predate plugin support will not expand this variable — stick with classic install on those versions.
|
|
4. **No version-pinning yet.** `/plugin install keisei@keisei-marketplace` installs the default branch HEAD. For reproducible team installs, add the `--ref=<tag>` flag once it lands in Claude Code (currently in the spec per the extension schema `ref` field).
|
|
|
|
## Feedback & bugs
|
|
|
|
Open an issue at [github.com/KeiSei84/KeiSeiKit/issues](https://github.com/KeiSei84/KeiSeiKit/issues). A well-formed problem description is already half the solution.
|
|
|
|
## References
|
|
|
|
- [Anthropic Claude Code plugins docs](https://code.claude.com/docs/en/plugins)
|
|
- `README.md` — main install guide (plugin section is the new default)
|
|
- `settings-snippet.json` — retained for classic install; the plugin path does not use it
|
|
- `install.sh --help` — classic installer options, now with a plugin-first banner
|