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

18
hermes/mapping.yaml
View File

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