claude-skills/dist-hermes/mcp/setup-projects-meta/SKILL.md

name, version, description

name	version	description
setup-projects-meta	1.0.0-hermes	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

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:

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:

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:

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:

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

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.