---
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.