keisei/KeiSeiKit-1.0
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
KeiSeiKit-1.0/PLUGIN.md
Parfii-bot 94a7d682c4 feat(mcp-server): production publish path via keigit.com (Forgejo npm) 
Wire @keisei/mcp-server publish to the author-operated keigit.com
Forgejo npm registry. Verified live: keigit.com → 45.77.41.204 (Vultr,
public DNS), Caddy → Forgejo 9.0.3, TLS valid, /api/v1/version=200.

Why keigit, not GitHub Packages or npm.org:
- keigit IS the canonical npm registry for the @keisei scope (operator
  runs it; no separate vendor account needed)
- npm scope @keisei stays @keisei (no rename to match a github org)
- Public DNS resolves from any client; auth via per-user PAT
- One auth surface for both the git remote and the npm registry

Files changed (7):
- _ts_packages/packages/mcp-server/package.json
  · removed `private: true` (was blocking ALL publish, including ours)
  · added publishConfig.registry = https://keigit.com/api/packages/keisei/npm/
    so accidental `npm publish` cannot route to npm.org
  · added repository field (provenance link to KeiSeiKit-1.0)
  · added license: Apache-2.0
- README.md (2 hunks): maturity row + install section say
  "published to keigit.com", show ~/.npmrc setup
- PLUGIN.md (3 hunks): same updates referencing keigit
- .claude-plugin/mcp-template.json: _comment updated
- docs/encyclopedia/substrate-overview.md (1 hunk): MCP row says
  "alpha" not "stable" + clarifies registry+scope
- .github/workflows/release.yml: npm-publish job rewired:
  · KEIGIT_TOKEN secret instead of NPM_TOKEN as gate
  · Two-row .npmrc temp-write: @keisei → keigit.com (always when
    KEIGIT_TOKEN set), npm.org auth as optional fallback
  · .npmrc cleanup via `if: always()` step
- .gitignore: _ts_packages/.npmrc + .npmrc excluded (RULE 0.8)

Verification:
- node -e 'require("./.../package.json")' parses clean,
  publishConfig pinned to keigit, private:false [REAL: ran in session]
- `npm run build --workspace=@keisei/mcp-server` → tsc -b exit 0,
  dist/index.js produced [REAL: built in session]
- Server starts: `node dist/index.js` lives >1s, doesn't throw,
  reports expected `[adapters] not installed` for un-built siblings
- keigit.com reachable from this machine: HTTP 200 root + Forgejo
  9.0.3 version endpoint [REAL: curl ran in session]

Required user-side setup before first publish:
1. Create user/org `keisei` on keigit.com (web UI; currently /keisei → 404)
2. Generate a keigit PAT with write:package scope
3. Add as github repo secret KEIGIT_TOKEN
4. Push tag v0.14.1+ → release workflow's npm-publish job picks it up

History note:
- Earlier in this session a github-packages-scope-rename variant
  (commit a6f1c72) was pushed; reverted by 542a0a8 because keigit
  is the right registry. Current commit lands the keigit wiring on
  top of the revert.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-03 18:11:24 +08:00

86 lines
5.4 KiB
Markdown
Raw Blame History

# 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 `@keisei/mcp-server` from keigit.com — 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:**
- `@keisei/mcp-server` available from **keigit.com**
(`https://keigit.com/api/packages/keisei/npm/`). One-time `~/.npmrc` setup:
```
@keisei:registry=https://keigit.com/api/packages/keisei/npm/
//keigit.com/:_authToken=<keigit PAT with read:package>
```
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. **`@keisei/mcp-server` lives on keigit.com, not npm.org.** The `.mcp.json` entry uses `npx -y @keisei/mcp-server` which resolves through the `~/.npmrc` `@keisei: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
Reference in a new issue View git blame Copy permalink