OpeItcLoc03/claude-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(hermes): flavour-mcp-setups + installer-skill [v1.0.0-hermes]

Browse Source 
- hermes-flavour-mcp-setups: setup-projects-meta + setup-context7
  rewritten as yaml-edit ~/.hermes/config.yaml (no clone/build)
  pre-checks binary+auth.toml exist, fallback to git clone with
  extraheader-pattern. mapping: pending → manual.

- hermes-installer-skill: dist-hermes/meta/claude-skills-installer/SKILL.md
  recursive bootstrap installer. iterates dist-hermes/<cat>/<name>/,
  calls skill_manage(action='create') per skill. respects SKIPPED.md.

- dist-hermes/mcp/: both MCP setup skills generated via build-hermes.py.

- hermes-mvp-coverage: unblocked (ready → next task).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
vitya
2026-05-07 09:18:53 +03:00
parent acfc8e697f
commit 27026c5e0e
8 changed files with 756 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
.tasks/STATUS.md
View File

@@ -1,5 +1,5 @@
# Task Board # Task Board
_Updated: 2026-05-07 (tdd-criteria skill-write + mapping + build-install shipped)_ _Updated: 2026-05-07 (hermes-flavour-mcp-setups + hermes-installer-skill shipped; hermes-mvp-coverage unblocked)_
<!-- <!--
Canonical layout. One block per task. Per-task deep context lives in Canonical layout. One block per task. Per-task deep context lives in
@@ -252,12 +252,11 @@ version: 0.1.0
--- ---
## 🔵 [hermes-mvp-coverage] — Расширить `hermes/mapping.yaml` и пропустить через converter оставшиеся 9 MVP-скилов: `setup-tasks`, `using-tasks`, `setup-wiki`, `using-wiki`, `using-projects-meta`, `using-context7`, `project-bootstrap` (адаптируется последним — orchestrator). Замечания: (a) `using-wiki`/`setup-wiki` поверх Hermes built-in `research/llm-wiki` — наша schema (`.wiki/CLAUDE.md`, `entities/persons/`, `packages/`, `raw/research,transcripts`) сохраняется через override-precedence; (b) `project-bootstrap` Hermes-flavour убирает CLAUDE.md trigger-lines (Hermes auto-discover), оставляет git/gitignore/README/setup-wiki/setup-tasks orchestration. End-to-end smoke-test на фабричной Linux-машине: `git clone claude-skills` на чистую box → `skill_manage` installer → trigger «установи всё» → `hermes skills list` показывает все 13 в правильных категориях → `mcp__projects_meta__*` тулы доступны после `/reload-mcp`. Дизайн: `.wiki/concepts/hermes-skills-rollout-design.md`. ## ⚪ [hermes-mvp-coverage] — Расширить `hermes/mapping.yaml` и пропустить через converter оставшиеся 9 MVP-скилов: `setup-tasks`, `using-tasks`, `setup-wiki`, `using-wiki`, `using-projects-meta`, `using-context7`, `project-bootstrap` (адаптируется последним — orchestrator). Замечания: (a) `using-wiki`/`setup-wiki` поверх Hermes built-in `research/llm-wiki` — наша schema (`.wiki/CLAUDE.md`, `entities/persons/`, `packages/`, `raw/research,transcripts`) сохраняется через override-precedence; (b) `project-bootstrap` Hermes-flavour убирает CLAUDE.md trigger-lines (Hermes auto-discover), оставляет git/gitignore/README/setup-wiki/setup-tasks orchestration. End-to-end smoke-test на фабричной Linux-машине: `git clone claude-skills` на чистую box → `skill_manage` installer → trigger «установи всё» → `hermes skills list` показывает все 13 в правильных категориях → `mcp__projects_meta__*` тулы доступны после `/reload-mcp`. Дизайн: `.wiki/concepts/hermes-skills-rollout-design.md`.
**Status:** blocked **Status:** ready
**Where I stopped:** (not started) **Where I stopped:** unblocked 2026-05-07 — `hermes-flavour-mcp-setups` shipped (setup-projects-meta + setup-context7 в `dist-hermes/mcp/`), `hermes-installer-skill` shipped (`dist-hermes/meta/claude-skills-installer/SKILL.md`).
**Next action:** Дождаться `hermes-converter-mvp`, `hermes-flavour-mcp-setups`, `hermes-installer-skill`; расширить mapping для 9 скилов с per-skill replace-rules для Claude-tool-refs (`Read/Edit/Glob/Bash` → Hermes-эквиваленты); прогнать build; smoke-test на чистой Linux box; результат + version bump в commit. **Next action:** расширить mapping для 9 скилов с per-skill replace-rules для Claude-tool-refs (`Read/Edit/Glob/Bash` → Hermes-эквиваленты); прогнать build; smoke-test на чистой Linux box; результат + version bump в commit.
**Blocker:** hermes-flavour-mcp-setups, hermes-installer-skill
**Branch:** master **Branch:** master
<!-- created-by: OpeItcLoc03@DESKTOP-NSEF0UK / from: .meeting-room / 2026-05-06T20:21:50.307Z; partial-unblock 2026-05-07: hermes-converter-mvp shipped in 6b36b31 --> <!-- created-by: OpeItcLoc03@DESKTOP-NSEF0UK / from: .meeting-room / 2026-05-06T20:21:50.307Z; partial-unblock 2026-05-07: hermes-converter-mvp shipped in 6b36b31 -->

2
dist-hermes/SKIPPED.md
View File

@@ -18,8 +18,6 @@ Do not edit by hand — edit the mapping and re-run the build.
- **project-bootstrap** — Pending hermes-mvp-coverage. Orchestrator — adapts last; CLAUDE.md trigger-lines drop (Hermes auto-discovers). → intended: `mode: auto, category: software-development` - **project-bootstrap** — Pending hermes-mvp-coverage. Orchestrator — adapts last; CLAUDE.md trigger-lines drop (Hermes auto-discovers). → intended: `mode: auto, category: software-development`
- **recommend-dont-menu** — Added 2026-05-06 after the original audit. Cross-agent applicability claimed (response-style rule) — Hermes-side audit not yet done. → intended: `mode: auto, category: productivity` - **recommend-dont-menu** — Added 2026-05-06 after the original audit. Cross-agent applicability claimed (response-style rule) — Hermes-side audit not yet done. → intended: `mode: auto, category: productivity`
- **setup-context7** — Pending hermes-flavour-mcp-setups: rewrite as yaml-edit ~/.hermes/config.yaml. → intended: `mode: manual, category: mcp`
- **setup-projects-meta** — Pending hermes-flavour-mcp-setups: rewrite as yaml-edit ~/.hermes/config.yaml plus pre-check + extraheader fallback. → intended: `mode: manual, category: mcp`
- **setup-tasks** — Pending hermes-mvp-coverage. → intended: `mode: auto, category: productivity` - **setup-tasks** — Pending hermes-mvp-coverage. → intended: `mode: auto, category: productivity`
- **setup-wiki** — Pending hermes-mvp-coverage. Hermes ships research/llm-wiki — our schema is preserved via override-precedence. → intended: `mode: auto, category: research` - **setup-wiki** — Pending hermes-mvp-coverage. Hermes ships research/llm-wiki — our schema is preserved via override-precedence. → intended: `mode: auto, category: research`
- **using-context7** — Pending hermes-mvp-coverage. → intended: `mode: auto, category: mcp` - **using-context7** — Pending hermes-mvp-coverage. → intended: `mode: auto, category: mcp`

140
dist-hermes/mcp/setup-context7/SKILL.md Normal file
View File

@@ -0,0 +1,140 @@
---
name: setup-context7
version: 1.0.0-hermes
description: Hermes-flavour context7 setup. Edits `~/.hermes/config.yaml` to register the official context7 MCP server via stdio (`npx @upstash/context7-mcp`). Requires `CONTEXT7_API_KEY` env var (user sets it manually or you prompt for it). Use when user says "install context7", "setup context7", or whenever `mcp__context7__*` tools are missing. Mutates Hermes config; pauses for confirmation before writing.
---
# setup-context7 (Hermes)
> One-time Hermes skill that registers context7 in `~/.hermes/config.yaml`. Context7 is a third-party MCP server (Upstash); this skill only adds the stdio command entry.
## When to use
- User explicitly asks: install / set up / configure context7 on Hermes.
- A `using-context7`-driven task fails because `mcp__context7__*` tools aren't available.
## Out of scope
- Creating API keys — user must have a Context7 API key (get it from https://context7.com or via `npx ctx7 setup`).
- Rolling back to manual config.
- Any non-context7 MCP server.
## Hard rule: don't auto-mutate config
Edits `~/.hermes/config.yaml`. **Always pause for explicit confirmation between Phase 1 (discovery) and Phase 2 (plan), and again before Phase 3 (writes).**
## Procedure
### Phase 0 — Environment sanity
- Confirm Hermes is the current agent.
- Confirm `npx` is on `PATH` (stdio command uses it).
### Phase 1 — Discovery (read-only)
**API key.** Check env var `CONTEXT7_API_KEY`. If missing → report MISSING, will ask user.
**Existing MCP entry.** Read `~/.hermes/config.yaml` and check `mcp_servers.context7`. Note if present.
Report:
```
API key: <set in CONTEXT7_API_KEY | MISSING → will ask>
MCP entry: <present | will add>
```
### Phase 2 — Plan + confirm
Present the plan:
```
API key: <user will set CONTEXT7_API_KEY | already set>
MCP entry: <will add | will update>
Config: ~/.hermes/config.yaml
Backup: ~/.hermes/config.yaml.bak-<ts>
```
If API key is missing → ask: "Set CONTEXT7_API_KEY env var, or paste your key and I'll add it to config.yaml via env." Wait for confirmation before proceeding.
### Phase 3 — Backup
```bash
TS=$(date +%Y%m%d-%H%M%S)
cp ~/.hermes/config.yaml ~/.hermes/config.yaml.bak-$TS
```
### Phase 4 — Edit `~/.hermes/config.yaml`
Add or update the `mcp_servers` section:
**Option A — user has CONTEXT7_API_KEY env var (recommended):**
```yaml
mcp_servers:
context7:
command: npx
args:
- -y
- @upstash/context7-mcp
- --api-key
- $CONTEXT7_API_KEY
env:
CONTEXT7_API_KEY: $CONTEXT7_API_KEY
```
**Option B — user wants key embedded (not recommended, but acceptable if env var is hard):**
```yaml
mcp_servers:
context7:
command: npx
args:
- -y
- @upstash/context7-mcp
- --api-key
- <PASTE_KEY_HERE>
```
Use Option A by default. Only Option B if user explicitly says "embed the key" or env vars don't work on their setup.
Validate YAML:
```bash
python -c "import yaml; yaml.safe_load(open('~/.hermes/config.yaml'))"
```
If validation fails → restore from `.bak-*` and abort.
### Phase 5 — Reload MCP
```
/reload-mcp
```
### Phase 6 — Smoke test
Call `mcp__context7__resolve-library-id` with a benign query (e.g. `libraryName: "React"`, `query: "smoke test"`). If it returns library IDs → success.
### Phase 7 — Final report
```
✅ Setup complete. context7 registered in ~/.hermes/config.yaml.
After /reload-mcp:
• mcp__context7__* tools serve from npx @upstash/context7-mcp
• API key from CONTEXT7_API_KEY env var (or embedded)
• Backup saved at ~/.hermes/config.yaml.bak-<ts>
If something breaks:
• Restore from .bak-* and tell me.
```
## Rollback procedure
```bash
cp ~/.hermes/config.yaml.bak-<ts> ~/.hermes/config.yaml
/reload-mcp
```
## Common mistakes
- **Forgetting to set CONTEXT7_API_KEY.** The MCP server will fail to start without it.
- **Embedding the key when env var works.** Env var is cleaner for rotation.
- **Forgetting /reload-mcp.** Config changes don't take effect until reload.

152
dist-hermes/mcp/setup-projects-meta/SKILL.md Normal file
View File

@@ -0,0 +1,152 @@
---
name: setup-projects-meta
version: 1.0.0-hermes
description: Hermes-flavour projects-meta setup. Edits `~/.hermes/config.yaml` to register the local `projects-meta-mcp` stdio server. Pre-checks that the binary exists at `~/projects/.common/lib/projects-meta-mcp/dist/server.js` and that `~/.config/projects-mcp/auth.toml` exists — both are shared across Claude Code and Hermes. If pre-checks fail, falls back to git clone (applies extraheader-pattern for safety). Use when user says "install projects-meta", "setup projects-meta", or whenever `mcp__projects-meta__*` tools are missing. Mutates Hermes config; pauses for confirmation before writing.
---
# setup-projects-meta (Hermes)
> One-time Hermes skill that registers `projects-meta-mcp` in `~/.hermes/config.yaml`. The binary and credentials are pre-existing (shared with Claude Code); this skill only adds the MCP server entry.
## When to use
- User explicitly asks: install / set up / configure projects-meta on Hermes.
- A `using-projects-meta`-driven task fails because `mcp__projects-meta__*` tools aren't available.
- New Hermes machine where Claude Code's projects-meta is already installed but Hermes config isn't updated.
## Out of scope
- Cloning or building `projects-meta-mcp` — that's Claude Code's responsibility. This skill assumes `~/projects/.common/lib/projects-meta-mcp/dist/server.js` already exists.
- Creating or rotating Gitea tokens — assume `~/.config/projects-mcp/auth.toml` exists.
- Running `projects-meta-mcp` itself — Hermes spawns it via `config.yaml`.
## Hard rule: don't auto-mutate config
Edits `~/.hermes/config.yaml`. **Always pause for explicit confirmation between Phase 1 (discovery) and Phase 2 (plan), and again before Phase 3 (writes).**
## Procedure
### Phase 0 — Environment sanity
- Confirm Hermes is the current agent (need `~/.hermes/config.yaml`).
- Confirm `node` is on `PATH` (the stdio command uses `node`).
- Pick paths: `~/projects/.common/lib/projects-meta-mcp/dist/server.js`, `~/.config/projects-mcp/auth.toml`, `~/.hermes/config.yaml`. POSIX `~/...` resolves on Hermes (Linux).
### Phase 1 — Discovery (read-only)
**Binary pre-check.** Verify `~/projects/.common/lib/projects-meta-mcp/dist/server.js` exists.
**Credentials pre-check.** Verify `~/.config/projects-mcp/auth.toml` exists and contains `gitea_token = "..."` (don't echo the token value).
**Existing MCP entry.** Read `~/.hermes/config.yaml` and check `mcp_servers.projects-meta`. Note if present.
Report:
```
Binary: <present | MISSING → will fallback to git clone>
Auth: <present | MISSING → will ask user>
MCP entry: <present | will add>
```
### Phase 2 — Plan + confirm
Present the plan:
```
Binary: <exists | will clone from https://git.kzntsv.site/OpeItcLoc03/projects-meta-mcp>
Auth: <exists | MISSING — STOP>
MCP entry: <will add | will update>
Config: ~/.hermes/config.yaml
Backup: ~/.hermes/config.yaml.bak-<ts>
```
Wait for explicit confirmation. If auth is missing → stop and ask the user to run Claude Code's `setup-projects-meta` first (it creates `auth.toml`).
### Phase 3 — Backup
```bash
TS=$(date +%Y%m%d-%H%M%S)
cp ~/.hermes/config.yaml ~/.hermes/config.yaml.bak-$TS
```
### Phase 4 — Fallback clone (only if binary missing)
If `~/projects/.common/lib/projects-meta-mcp/dist/server.js` does NOT exist:
```bash
mkdir -p ~/projects/.common/lib
git clone https://git.kzntsv.site/OpeItcLoc03/projects-meta-mcp ~/projects/.common/lib/projects-meta-mcp
cd ~/projects/.common/lib/projects-meta-mcp
npm install
npm run build
```
**Security:** before cloning, apply extraheader-pattern to prevent credential leakage:
```bash
git config --global http.https://git.kzntsv.site.extraheader "AUTHORIZATION: Basic ***"
```
Verify `dist/server.js` exists after build. If not → abort.
### Phase 5 — Edit `~/.hermes/config.yaml`
Add or update the `mcp_servers` section:
```yaml
mcp_servers:
projects-meta:
command: node
args:
- /home/<USER>/projects/.common/lib/projects-meta-mcp/dist/server.js
env:
GITEA_TOKEN_FILE: /home/<USER>/.config/projects-mcp/auth.toml
```
**Note:** Hermes supports `GITEA_TOKEN_FILE` env var (projects-meta-mcp reads it and extracts `gitea_token`). This avoids hardcoding the token in args.
If `mcp_servers.projects-meta` already exists, update `args[0]` to the absolute path.
Validate YAML syntax:
```bash
python -c "import yaml; yaml.safe_load(open('~/.hermes/config.yaml'))"
```
If validation fails → restore from `.bak-*` and abort.
### Phase 6 — Reload MCP
Tell Hermes to reload MCP servers:
```
/reload-mcp
```
Or invoke the native MCP reload tool if available.
### Phase 7 — Smoke test
Call `mcp__projects-meta__meta_status`. If it returns JSON with `synced_at` / `wiki_pages_count` → success.
### Phase 8 — Final report
```
✅ Setup complete. projects-meta registered in ~/.hermes/config.yaml.
After /reload-mcp:
• mcp__projects-meta__* tools serve from ~/projects/.common/lib/projects-meta-mcp
• Credentials from ~/.config/projects-mcp/auth.toml (shared with Claude Code)
• Backup saved at ~/.hermes/config.yaml.bak-<ts>
If something breaks:
• Restore from .bak-* and tell me.
```
## Rollback procedure
```bash
cp ~/.hermes/config.yaml.bak-<ts> ~/.hermes/config.yaml
/reload-mcp
```
## Common mistakes
- **Skipping auth.toml pre-check.** If `auth.toml` is missing, the server will fail to start. Don't proceed without it.
- **Hardcoding token in args.** Use `GITEA_TOKEN_FILE` env var instead — `auth.toml` is the source of truth.
- **Forgetting /reload-mcp.** Edits to `config.yaml` don't take effect until MCP reloads.

161
dist-hermes/meta/claude-skills-installer/SKILL.md Normal file
View File

@@ -0,0 +1,161 @@
---
name: claude-skills-installer
version: 1.0.0
description: Recursive bootstrap installer for claude-skills on Hermes. Iterates over `dist-hermes/<category>/<name>/` and installs each via `skill_manage(action='create')`. Respects `dist-hermes/SKIPPED.md` — skipped skills are not installed. Run once manually to bootstrap (`skill_manage(action='create', from='...')`), thereafter trigger «обнови claude-skills» to refresh all skills. The installer updates itself recursively — no separate update step.
---
# claude-skills-installer
> Bootstrap installer for the claude-skills suite on Hermes. One-time manual registration, then «обнови claude-skills» keeps everything in sync.
## When to use
- **Bootstrap phase:** First-time setup on a Hermes machine. Run manually:
```
skill_manage(action='create', from='dist-hermes/meta/claude-skills-installer/SKILL.md')
```
- **Update phase:** Whenever user says «обнови claude-skills», «refresh claude-skills», or after `git pull` in the claude-skills repo.
## What it does
Iterates over `dist-hermes/<category>/<name>/` (all except `meta/`). For each:
1. Reads `SKILL.md` (frontmatter: name, version, description).
2. Collects assets (README.md, SECURITY.md, scripts/, etc.) if present.
3. Calls `skill_manage(action='create', category=<cat>, name=<name>, content=<SKILL.md>, assets=<...>)`.
Skips anything listed in `dist-hermes/SKIPPED.md` (these are intentionally not part of Hermes rollout).
**Recursive by design:** the installer lives in `meta/` and updates itself along with everything else.
## Prerequisites
- `dist-hermes/` tree exists (from `git clone claude-skills` + `python scripts/build-hermes.py`).
- Hermes has `skill_manage()` native tool.
- Working directory is `claude-skills` root (where `dist-hermes/` lives).
## Procedure
### Phase 0 — Verify dist-hermes
```bash
ls dist-hermes/
```
Should list: `software-development/`, `productivity/`, `mcp/`, `meta/`, `SKIPPED.md`.
If missing → run `python scripts/build-hermes.py` first.
### Phase 1 — Load SKIPPED.md
Read `dist-hermes/SKIPPED.md`. Parse the skip list — these categories/names will NOT be installed.
Example SKIPPED.md entry:
```
caveman (category: software-development)
Reason: Hermes runs on glm-5.1 (cheap local model); token-compression motive disappears.
```
### Phase 2 — Scan dist-hermes
Walk `dist-hermes/<category>/<name>/`. Collect:
```
category: software-development | productivity | mcp | research
name: <directory name>
skill_file: dist-hermes/<category>/<name>/SKILL.md
assets:
- dist-hermes/<category>/<name>/README.md (if exists)
- dist-hermes/<category>/<name>/SECURITY.md (if exists)
- dist-hermes/<category>/<name>/scripts/* (if exists)
```
**Skip conditions:**
- `category/name` is in SKIPPED.md
- `name == "claude-skills-installer"` (don't install yourself recursively)
Report the scan result:
```
Found N skills to install:
software-development: pulling-before-work, active-platform, project-discipline, tdd-criteria
productivity: using-markitdown
mcp: setup-projects-meta, setup-context7
Skipped M entries (see dist-hermes/SKIPPED.md)
```
### Phase 3 — Confirm
Ask user:
```
Will install N skills. Proceed? (y/n)
```
Wait for explicit confirmation. This is a bulk operation — permission is required.
### Phase 4 — Install loop
For each skill in the scan list:
```
skill_manage(
action='create',
category='<category>',
name='<name>',
content='<SKILL.md content>',
assets={
'README.md': '<README.md content if exists>',
'SECURITY.md': '<SECURITY.md content if exists>',
'scripts/*': '<script files if exist>'
}
)
```
**Important:** `skill_manage(action='create')` is idempotent. If a skill already exists, it updates to the new content.
Report progress per skill:
```
✓ pulling-before-work (v1.x.x)
✓ active-platform (v1.x.x)
...
✗ <name> failed: <error>
```
If any skill fails → stop, report the error, and ask whether to continue or rollback.
### Phase 5 — Verify
After the loop completes, ask user to verify:
```
hermes > skills_list()
```
Should show all installed skills under their categories. Count should match N.
### Phase 6 — Final report
```
✅ Installed N skills. Update complete.
Installed:
software-development: <list>
productivity: <list>
mcp: <list>
Skipped:
<list from SKIPPED.md>
To refresh: run this skill again after 'git pull' in claude-skills.
```
## Out of scope
- Creating `dist-hermes/` — that's `build-hermes.py` job.
- Installing skills NOT in dist-hermes (manual `skill_manage` calls).
- Uninstalling skills (use `skill_manage(action='delete')` manually).
## Common mistakes
- **Running from wrong directory.** Must be in claude-skills root where `dist-hermes/` lives.
- **Forgetting to rebuild dist-hermes.** After `git pull` in claude-skills, run `python scripts/build-hermes.py` before running installer.
- **Installing skipped skills.** SKIPPED.md is the source of truth. If a skill is there, don't install it.
- **Not verifying after install.** Always run `skills_list()` to confirm.

18
hermes/mapping.yaml
View File

@@ -121,12 +121,9 @@ skills:
category: research category: research
setup-projects-meta: setup-projects-meta:
mode: pending mode: manual
reason: "Pending hermes-flavour-mcp-setups: rewrite as yaml-edit ~/.hermes/config.yaml plus pre-check + extraheader fallback." source: hermes/skills/setup-projects-meta
intended: category: mcp
mode: manual
source: hermes/skills/setup-projects-meta
category: mcp
using-projects-meta: using-projects-meta:
mode: pending mode: pending
@@ -136,12 +133,9 @@ skills:
category: mcp category: mcp
setup-context7: setup-context7:
mode: pending mode: manual
reason: "Pending hermes-flavour-mcp-setups: rewrite as yaml-edit ~/.hermes/config.yaml." source: hermes/skills/setup-context7
intended: category: mcp
mode: manual
source: hermes/skills/setup-context7
category: mcp
using-context7: using-context7:
mode: pending mode: pending

140
hermes/skills/setup-context7/SKILL.md Normal file
View File

@@ -0,0 +1,140 @@
---
name: setup-context7
version: 1.0.0-hermes
description: Hermes-flavour context7 setup. Edits `~/.hermes/config.yaml` to register the official context7 MCP server via stdio (`npx @upstash/context7-mcp`). Requires `CONTEXT7_API_KEY` env var (user sets it manually or you prompt for it). Use when user says "install context7", "setup context7", or whenever `mcp__context7__*` tools are missing. Mutates Hermes config; pauses for confirmation before writing.
---
# setup-context7 (Hermes)
> One-time Hermes skill that registers context7 in `~/.hermes/config.yaml`. Context7 is a third-party MCP server (Upstash); this skill only adds the stdio command entry.
## When to use
- User explicitly asks: install / set up / configure context7 on Hermes.
- A `using-context7`-driven task fails because `mcp__context7__*` tools aren't available.
## Out of scope
- Creating API keys — user must have a Context7 API key (get it from https://context7.com or via `npx ctx7 setup`).
- Rolling back to manual config.
- Any non-context7 MCP server.
## Hard rule: don't auto-mutate config
Edits `~/.hermes/config.yaml`. **Always pause for explicit confirmation between Phase 1 (discovery) and Phase 2 (plan), and again before Phase 3 (writes).**
## Procedure
### Phase 0 — Environment sanity
- Confirm Hermes is the current agent.
- Confirm `npx` is on `PATH` (stdio command uses it).
### Phase 1 — Discovery (read-only)
**API key.** Check env var `CONTEXT7_API_KEY`. If missing → report MISSING, will ask user.
**Existing MCP entry.** Read `~/.hermes/config.yaml` and check `mcp_servers.context7`. Note if present.
Report:
```
API key: <set in CONTEXT7_API_KEY | MISSING → will ask>
MCP entry: <present | will add>
```
### Phase 2 — Plan + confirm
Present the plan:
```
API key: <user will set CONTEXT7_API_KEY | already set>
MCP entry: <will add | will update>
Config: ~/.hermes/config.yaml
Backup: ~/.hermes/config.yaml.bak-<ts>
```
If API key is missing → ask: "Set CONTEXT7_API_KEY env var, or paste your key and I'll add it to config.yaml via env." Wait for confirmation before proceeding.
### Phase 3 — Backup
```bash
TS=$(date +%Y%m%d-%H%M%S)
cp ~/.hermes/config.yaml ~/.hermes/config.yaml.bak-$TS
```
### Phase 4 — Edit `~/.hermes/config.yaml`
Add or update the `mcp_servers` section:
**Option A — user has CONTEXT7_API_KEY env var (recommended):**
```yaml
mcp_servers:
context7:
command: npx
args:
- -y
- @upstash/context7-mcp
- --api-key
- $CONTEXT7_API_KEY
env:
CONTEXT7_API_KEY: $CONTEXT7_API_KEY
```
**Option B — user wants key embedded (not recommended, but acceptable if env var is hard):**
```yaml
mcp_servers:
context7:
command: npx
args:
- -y
- @upstash/context7-mcp
- --api-key
- <PASTE_KEY_HERE>
```
Use Option A by default. Only Option B if user explicitly says "embed the key" or env vars don't work on their setup.
Validate YAML:
```bash
python -c "import yaml; yaml.safe_load(open('~/.hermes/config.yaml'))"
```
If validation fails → restore from `.bak-*` and abort.
### Phase 5 — Reload MCP
```
/reload-mcp
```
### Phase 6 — Smoke test
Call `mcp__context7__resolve-library-id` with a benign query (e.g. `libraryName: "React"`, `query: "smoke test"`). If it returns library IDs → success.
### Phase 7 — Final report
```
✅ Setup complete. context7 registered in ~/.hermes/config.yaml.
After /reload-mcp:
• mcp__context7__* tools serve from npx @upstash/context7-mcp
• API key from CONTEXT7_API_KEY env var (or embedded)
• Backup saved at ~/.hermes/config.yaml.bak-<ts>
If something breaks:
• Restore from .bak-* and tell me.
```
## Rollback procedure
```bash
cp ~/.hermes/config.yaml.bak-<ts> ~/.hermes/config.yaml
/reload-mcp
```
## Common mistakes
- **Forgetting to set CONTEXT7_API_KEY.** The MCP server will fail to start without it.
- **Embedding the key when env var works.** Env var is cleaner for rotation.
- **Forgetting /reload-mcp.** Config changes don't take effect until reload.

152
hermes/skills/setup-projects-meta/SKILL.md Normal file
View File

@@ -0,0 +1,152 @@
---
name: setup-projects-meta
version: 1.0.0-hermes
description: Hermes-flavour projects-meta setup. Edits `~/.hermes/config.yaml` to register the local `projects-meta-mcp` stdio server. Pre-checks that the binary exists at `~/projects/.common/lib/projects-meta-mcp/dist/server.js` and that `~/.config/projects-mcp/auth.toml` exists — both are shared across Claude Code and Hermes. If pre-checks fail, falls back to git clone (applies extraheader-pattern for safety). Use when user says "install projects-meta", "setup projects-meta", or whenever `mcp__projects-meta__*` tools are missing. Mutates Hermes config; pauses for confirmation before writing.
---
# setup-projects-meta (Hermes)
> One-time Hermes skill that registers `projects-meta-mcp` in `~/.hermes/config.yaml`. The binary and credentials are pre-existing (shared with Claude Code); this skill only adds the MCP server entry.
## When to use
- User explicitly asks: install / set up / configure projects-meta on Hermes.
- A `using-projects-meta`-driven task fails because `mcp__projects-meta__*` tools aren't available.
- New Hermes machine where Claude Code's projects-meta is already installed but Hermes config isn't updated.
## Out of scope
- Cloning or building `projects-meta-mcp` — that's Claude Code's responsibility. This skill assumes `~/projects/.common/lib/projects-meta-mcp/dist/server.js` already exists.
- Creating or rotating Gitea tokens — assume `~/.config/projects-mcp/auth.toml` exists.
- Running `projects-meta-mcp` itself — Hermes spawns it via `config.yaml`.
## Hard rule: don't auto-mutate config
Edits `~/.hermes/config.yaml`. **Always pause for explicit confirmation between Phase 1 (discovery) and Phase 2 (plan), and again before Phase 3 (writes).**
## Procedure
### Phase 0 — Environment sanity
- Confirm Hermes is the current agent (need `~/.hermes/config.yaml`).
- Confirm `node` is on `PATH` (the stdio command uses `node`).
- Pick paths: `~/projects/.common/lib/projects-meta-mcp/dist/server.js`, `~/.config/projects-mcp/auth.toml`, `~/.hermes/config.yaml`. POSIX `~/...` resolves on Hermes (Linux).
### Phase 1 — Discovery (read-only)
**Binary pre-check.** Verify `~/projects/.common/lib/projects-meta-mcp/dist/server.js` exists.
**Credentials pre-check.** Verify `~/.config/projects-mcp/auth.toml` exists and contains `gitea_token = "..."` (don't echo the token value).
**Existing MCP entry.** Read `~/.hermes/config.yaml` and check `mcp_servers.projects-meta`. Note if present.
Report:
```
Binary: <present | MISSING → will fallback to git clone>
Auth: <present | MISSING → will ask user>
MCP entry: <present | will add>
```
### Phase 2 — Plan + confirm
Present the plan:
```
Binary: <exists | will clone from https://git.kzntsv.site/OpeItcLoc03/projects-meta-mcp>
Auth: <exists | MISSING — STOP>
MCP entry: <will add | will update>
Config: ~/.hermes/config.yaml
Backup: ~/.hermes/config.yaml.bak-<ts>
```
Wait for explicit confirmation. If auth is missing → stop and ask the user to run Claude Code's `setup-projects-meta` first (it creates `auth.toml`).
### Phase 3 — Backup
```bash
TS=$(date +%Y%m%d-%H%M%S)
cp ~/.hermes/config.yaml ~/.hermes/config.yaml.bak-$TS
```
### Phase 4 — Fallback clone (only if binary missing)
If `~/projects/.common/lib/projects-meta-mcp/dist/server.js` does NOT exist:
```bash
mkdir -p ~/projects/.common/lib
git clone https://git.kzntsv.site/OpeItcLoc03/projects-meta-mcp ~/projects/.common/lib/projects-meta-mcp
cd ~/projects/.common/lib/projects-meta-mcp
npm install
npm run build
```
**Security:** before cloning, apply extraheader-pattern to prevent credential leakage:
```bash
git config --global http.https://git.kzntsv.site.extraheader "AUTHORIZATION: Basic ***"
```
Verify `dist/server.js` exists after build. If not → abort.
### Phase 5 — Edit `~/.hermes/config.yaml`
Add or update the `mcp_servers` section:
```yaml
mcp_servers:
projects-meta:
command: node
args:
- /home/<USER>/projects/.common/lib/projects-meta-mcp/dist/server.js
env:
GITEA_TOKEN_FILE: /home/<USER>/.config/projects-mcp/auth.toml
```
**Note:** Hermes supports `GITEA_TOKEN_FILE` env var (projects-meta-mcp reads it and extracts `gitea_token`). This avoids hardcoding the token in args.
If `mcp_servers.projects-meta` already exists, update `args[0]` to the absolute path.
Validate YAML syntax:
```bash
python -c "import yaml; yaml.safe_load(open('~/.hermes/config.yaml'))"
```
If validation fails → restore from `.bak-*` and abort.
### Phase 6 — Reload MCP
Tell Hermes to reload MCP servers:
```
/reload-mcp
```
Or invoke the native MCP reload tool if available.
### Phase 7 — Smoke test
Call `mcp__projects-meta__meta_status`. If it returns JSON with `synced_at` / `wiki_pages_count` → success.
### Phase 8 — Final report
```
✅ Setup complete. projects-meta registered in ~/.hermes/config.yaml.
After /reload-mcp:
• mcp__projects-meta__* tools serve from ~/projects/.common/lib/projects-meta-mcp
• Credentials from ~/.config/projects-mcp/auth.toml (shared with Claude Code)
• Backup saved at ~/.hermes/config.yaml.bak-<ts>
If something breaks:
• Restore from .bak-* and tell me.
```
## Rollback procedure
```bash
cp ~/.hermes/config.yaml.bak-<ts> ~/.hermes/config.yaml
/reload-mcp
```
## Common mistakes
- **Skipping auth.toml pre-check.** If `auth.toml` is missing, the server will fail to start. Don't proceed without it.
- **Hardcoding token in args.** Use `GITEA_TOKEN_FILE` env var instead — `auth.toml` is the source of truth.
- **Forgetting /reload-mcp.** Edits to `config.yaml` don't take effect until MCP reloads.