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>
111 lines
3.5 KiB
Markdown
111 lines
3.5 KiB
Markdown
# KeiSeiKit TypeScript Packages
|
|
|
|
> v0.14.0 part B: MCP server layer + external-API adapters.
|
|
|
|
## RULE 0.2 exception
|
|
|
|
TypeScript is chosen here under **RULE 0.2 exception #4 (Browser/DOM adjacent)** because:
|
|
|
|
1. The official Model Context Protocol SDK is TypeScript-native; Rust MCP
|
|
libraries are immature (as of 2026-04).
|
|
2. The API adapters rely on JS-native SDKs with no Rust equivalents:
|
|
- `grammy` (type-safe Telegram bot)
|
|
- `googleapis` (official Google API SDK for Gmail + YouTube)
|
|
- `youtube-transcript` (Tier-1 free transcript extractor)
|
|
3. Async, JSON-heavy glue code is TypeScript's sweet spot.
|
|
|
|
**Core primitives (signing, ledger, graph, memory, refactor, etc.) remain
|
|
Rust** in `../_primitives/_rust/`. This TS layer is a THIN wrapper: it
|
|
spawns the Rust CLIs as subprocesses and exposes them as MCP tools, plus
|
|
the six adapters above that have no Rust equivalent.
|
|
|
|
## Layout
|
|
|
|
```
|
|
_ts_packages/
|
|
├── package.json npm workspace root
|
|
├── tsconfig.base.json strict TS 5.x
|
|
└── packages/
|
|
├── mcp-server/ @keisei84/mcp-server
|
|
├── telegram-adapter/ @keisei/telegram-adapter
|
|
├── recall-adapter/ @keisei/recall-adapter (Zoom via Recall.ai)
|
|
├── grok-adapter/ @keisei/grok-adapter (xAI)
|
|
├── gmail-adapter/ @keisei/gmail-adapter
|
|
└── youtube-adapter/ @keisei/youtube-adapter
|
|
```
|
|
|
|
## Install (for end users)
|
|
|
|
### 1. Install workspace deps
|
|
|
|
```bash
|
|
cd _ts_packages
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
### 2. Link each package as a global CLI (optional)
|
|
|
|
```bash
|
|
npm i -g ./packages/mcp-server
|
|
npm i -g ./packages/telegram-adapter
|
|
# ... etc
|
|
```
|
|
|
|
Or install into a Claude agent directory:
|
|
|
|
```bash
|
|
npm i --prefix ~/.claude/agents/_ts_packages/packages/mcp-server \
|
|
./_ts_packages/packages/mcp-server
|
|
```
|
|
|
|
## Environment variables (RULE 0.8 — secrets in `~/.claude/secrets/.env`)
|
|
|
|
| Var | Package | Purpose |
|
|
|---|---|---|
|
|
| `TELEGRAM_BOT_TOKEN` | telegram-adapter | Bot API token |
|
|
| `RECALL_API_KEY` | recall-adapter | Recall.ai API key (Zoom meetings) |
|
|
| `XAI_API_KEY` | grok-adapter | xAI Grok API key |
|
|
| `GMAIL_CLIENT_ID` | gmail-adapter | Google OAuth2 client id |
|
|
| `GMAIL_CLIENT_SECRET` | gmail-adapter | Google OAuth2 client secret |
|
|
| `GMAIL_REFRESH_TOKEN` | gmail-adapter | Long-lived OAuth2 refresh token |
|
|
| `YOUTUBE_API_KEY` | youtube-adapter | YouTube Data API v3 key |
|
|
| `KEI_MCP_AUTH_TOKEN` | mcp-server | HMAC token for tool callers |
|
|
| `KEI_RUST_BIN_DIR` | mcp-server | Override directory holding Rust primitive CLIs |
|
|
|
|
All are read via `process.env`. Hardcoding tokens is **forbidden** (RULE 0.8).
|
|
|
|
## MCP server integration
|
|
|
|
The `@keisei84/mcp-server` exposes the Rust primitive CLIs as MCP tools. The
|
|
pattern is one Rust binary = one MCP tool, with the `kei` meta-tool on
|
|
top that routes natural-language queries via `kei-router`.
|
|
|
|
Stdio mode (for Claude Code native integration):
|
|
|
|
```bash
|
|
npx @keisei84/mcp-server --stdio
|
|
```
|
|
|
|
HTTP mode:
|
|
|
|
```bash
|
|
npx @keisei84/mcp-server --port 3000 --auth-token-file ~/.claude/mcp-token
|
|
```
|
|
|
|
## Verification
|
|
|
|
```bash
|
|
npm install
|
|
npm run build --workspaces
|
|
npm run test --workspaces
|
|
```
|
|
|
|
All six packages compile under `strict: true`. Total new LOC: see commit.
|
|
|
|
## Migration notes
|
|
|
|
- Zero impact on existing KeiSeiKit users unless they opt into the MCP
|
|
server (planned v0.14.1 installer flag `--enable-mcp`).
|
|
- The Rust primitives are unchanged; this layer only **wraps** them.
|
|
- Gmail and YouTube adapters are **new** (gaps in LBM).
|