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