|
| 1 | +# INSTALL_FOR_AGENTS.md — `elnora-plugins` setup |
| 2 | + |
| 3 | +> **Step 0 — Identity gate.** If you are NOT an autonomous coding agent (Claude |
| 4 | +> Code, Codex CLI, Cursor, Aider, Continue, Amp, Jules, Roo, Windsurf, etc.), |
| 5 | +> stop reading this file and open `README.md` instead. This file walks an agent |
| 6 | +> through connecting the Elnora MCP server, authenticating (OAuth or an API key |
| 7 | +> you help the user create in a browser), copying the skill files, and running |
| 8 | +> a live smoke test against the Elnora Platform. Humans should follow the |
| 9 | +> README's Installation section. |
| 10 | +
|
| 11 | +You are the agent handing off after the user decided to install the Elnora |
| 12 | +plugin / MCP server. Your job: confirm the MCP connection is registered, get |
| 13 | +the user authenticated, make sure the 9 skills are where your harness reads |
| 14 | +them, run one read-only tool call to prove the stack works end to end, and hand |
| 15 | +back a working environment. |
| 16 | + |
| 17 | +Be transparent: announce each step before you run it, show the output, and |
| 18 | +explain what you found. The user may not know what an MCP server or an Agent |
| 19 | +Skill is — keep the language plain and ask one question at a time. Never paste, |
| 20 | +echo, or commit an API key. |
| 21 | + |
| 22 | +**Universal:** the MCP endpoint (`https://mcp.elnora.ai/mcp`) and the tool names |
| 23 | +(`elnora_*`) are identical under every harness. The only harness-specific parts |
| 24 | +are *where* the MCP server is registered and *where* skills are copied — the |
| 25 | +per-harness table in Step 3 covers that. |
| 26 | + |
| 27 | +## Browser steps — offer to drive, don't assume |
| 28 | + |
| 29 | +Two steps below happen in a web browser: completing OAuth (Step 2, option A) |
| 30 | +and creating an API key at `platform.elnora.ai` (Step 2, option B). How you |
| 31 | +handle them depends on what your harness can do: |
| 32 | + |
| 33 | +- **If you have the Chrome DevTools MCP server available** (tools under |
| 34 | + `mcp__chrome-devtools__*`, e.g. Claude Code with it enabled): *offer* to open |
| 35 | + and drive the page for the user — "I can open `platform.elnora.ai` in your |
| 36 | + Chrome and walk the key-creation with you, or you can do it yourself and paste |
| 37 | + the result. Which do you prefer?" Only drive the browser if the user says yes. |
| 38 | + Never submit a login form or read back a secret without the user watching. |
| 39 | +- **If you do not have a browser-automation tool**, give the user the exact URL |
| 40 | + and click-path and wait for them to paste the result. Do not try to fetch an |
| 41 | + authenticated page yourself. |
| 42 | + |
| 43 | +Either way the user stays in control of their own credentials. |
| 44 | + |
| 45 | +## Step 1 — Verify the MCP connection is registered |
| 46 | + |
| 47 | +The plugin declares the Elnora MCP server; a manual `mcp add` registers it |
| 48 | +directly. Confirm your harness sees a server named `elnora` pointed at |
| 49 | +`https://mcp.elnora.ai/mcp` before going further. |
| 50 | + |
| 51 | +- **Claude Code (plugin path).** Confirm the plugin loaded: |
| 52 | + |
| 53 | + ```sh |
| 54 | + ls .claude/plugins 2>/dev/null || ls ~/.claude/plugins 2>/dev/null |
| 55 | + ``` |
| 56 | + |
| 57 | + You should see `elnora` (or `elnora-plugins`) listed. If not, the |
| 58 | + `/plugin install elnora@elnora-plugins` didn't complete — ask the user to |
| 59 | + rerun it. You can also list MCP servers with `claude mcp list` and confirm an |
| 60 | + `elnora` entry appears. |
| 61 | + |
| 62 | +- **Claude Code (API-key MCP path, no plugin).** Register it: |
| 63 | + |
| 64 | + ```sh |
| 65 | + claude mcp add elnora --transport http --scope user \ |
| 66 | + https://mcp.elnora.ai/mcp \ |
| 67 | + --header "X-API-Key: <key-from-Step-2>" |
| 68 | + ``` |
| 69 | + |
| 70 | + If you register this AND enable the plugin, you'll have two servers both named |
| 71 | + `elnora` — keep one, not both. |
| 72 | + |
| 73 | +- **Other harnesses (Codex / Cursor / VS Code Copilot / Gemini).** Confirm the |
| 74 | + MCP config block exists in the right file (see Step 3). There is no CLI to |
| 75 | + `--version` here — the check is "is the `elnora` server in my MCP config and |
| 76 | + does a tool call reach it," which Step 4 proves. |
| 77 | + |
| 78 | +Gate: your harness lists an `elnora` MCP server. If it doesn't, stop and fix the |
| 79 | +registration before spending an auth round-trip. |
| 80 | + |
| 81 | +## Step 2 — Authenticate |
| 82 | + |
| 83 | +The Elnora MCP server accepts two auth methods. Ask the user which they want: |
| 84 | + |
| 85 | +> Elnora authenticates two ways. (A) **OAuth** — recommended; a browser popup |
| 86 | +> opens on the first call, you click approve, and your client stores and |
| 87 | +> refreshes the token for you. Nothing to paste. (B) **API key** — better for |
| 88 | +> CI or non-interactive setups; you create a key once at platform.elnora.ai and |
| 89 | +> it's passed as a header. Which do you want? |
| 90 | +
|
| 91 | +### Option A — OAuth 2.1 (recommended) |
| 92 | + |
| 93 | +No key handling. The first tool call (Step 4) triggers the browser popup |
| 94 | +automatically; the user approves once and the token is cached by their MCP |
| 95 | +client. There is nothing to persist in this repo. |
| 96 | + |
| 97 | +- If you have the Chrome DevTools MCP server, you may *offer* to bring the |
| 98 | + approval page forward and confirm the redirect completes — but the user |
| 99 | + approves; you don't. If you don't have it, just tell the user "a browser |
| 100 | + window will open on the first Elnora call — approve it there," and continue. |
| 101 | + |
| 102 | +Gate: none yet. OAuth is validated by the smoke test in Step 4 succeeding |
| 103 | +without a `401`. |
| 104 | + |
| 105 | +### Option B — API key |
| 106 | + |
| 107 | +1. **Create the key.** Tell the user, verbatim: |
| 108 | + |
| 109 | + > Open https://platform.elnora.ai in your browser, go to account settings → |
| 110 | + > API keys, click **Create key**, name it something like "mcp-<harness>", |
| 111 | + > and copy the value. It starts with `elnora_live_`. |
| 112 | +
|
| 113 | + Follow the browser-step rules above: if you have Chrome DevTools MCP, offer |
| 114 | + to open the page and walk the click-path with the user watching; otherwise |
| 115 | + wait for them to paste the key. |
| 116 | + |
| 117 | +2. **Store it in the client's secret store or an env var — never in this repo.** |
| 118 | + The key goes in your MCP client's header config (`X-API-Key` or |
| 119 | + `Authorization: Bearer <key>`), your OS keychain, or an environment variable. |
| 120 | + Do NOT write it into any file under the repository, a skill file, or a commit |
| 121 | + — `.env` and `*.local` are gitignored precisely so a stray key can't be |
| 122 | + committed, but the safest place is the client secret store. |
| 123 | + |
| 124 | + For Claude Code's API-key MCP path, the key is passed on the |
| 125 | + `claude mcp add` command from Step 1 (`--header "X-API-Key: <key>"`), which |
| 126 | + stores it in the user-scope MCP config, not in this repo. |
| 127 | + |
| 128 | +Gate: the key is set in the client's auth config (verified by Step 4), starts |
| 129 | +with `elnora_live_`, and appears in NO file tracked by git. If the user pasted |
| 130 | +it into a chat or a repo file, tell them to rotate it. |
| 131 | + |
| 132 | +## Step 3 — Register MCP + copy skills (non-Claude harnesses) |
| 133 | + |
| 134 | +Claude Code users who installed the plugin can skip this — the plugin ships both |
| 135 | +the MCP declaration and the skills. Everyone else does both halves: |
| 136 | + |
| 137 | +| Harness | MCP config file | Skills directory | |
| 138 | +|---|---|---| |
| 139 | +| Cursor | `.cursor/mcp.json` | `.cursor/skills/` | |
| 140 | +| OpenAI Codex | `codex mcp add elnora -- https://mcp.elnora.ai/mcp` | `.codex/skills/` | |
| 141 | +| VS Code Copilot | `.vscode/mcp.json` | `.vscode/skills/` | |
| 142 | +| Gemini CLI | Gemini settings | `.gemini/skills/` | |
| 143 | +| Generic MCP client | point at `https://mcp.elnora.ai/mcp` | your tool's skills dir | |
| 144 | + |
| 145 | +MCP block for the JSON-config harnesses: |
| 146 | + |
| 147 | +```json |
| 148 | +{ "mcpServers": { "elnora": { "type": "http", "url": "https://mcp.elnora.ai/mcp" } } } |
| 149 | +``` |
| 150 | + |
| 151 | +Copy the skills: |
| 152 | + |
| 153 | +```sh |
| 154 | +cp -r elnora/skills/* <skills-dir>/ |
| 155 | +``` |
| 156 | + |
| 157 | +Gate: all 9 skill directories (`elnora-platform`, `elnora-orgs`, |
| 158 | +`elnora-projects`, `elnora-tasks`, `elnora-files`, `elnora-folders`, |
| 159 | +`elnora-search`, `elnora-admin`, `elnora-agent`) landed in the target dir, each |
| 160 | +containing a `SKILL.md`. |
| 161 | + |
| 162 | +## Step 4 — Smoke test |
| 163 | + |
| 164 | +Two tool calls, in order. The first needs no auth; the second proves auth works. |
| 165 | + |
| 166 | +1. **Liveness.** Call `elnora_health_check` (via the `elnora-admin` / |
| 167 | + `elnora-platform` skill, or the raw MCP tool). |
| 168 | + |
| 169 | + Gate: it returns a healthy status. A transport error here means the MCP |
| 170 | + server isn't registered — go back to Step 1. This call does not prove auth. |
| 171 | + |
| 172 | +2. **Authenticated read.** Call `elnora_account_get` (whoami) or |
| 173 | + `elnora_projects_list`. |
| 174 | + |
| 175 | + Gates: |
| 176 | + - **OAuth (Option A):** the first call opens the approval popup. After the |
| 177 | + user approves, the call returns account/project data. If it keeps failing |
| 178 | + with `401`, the OAuth flow didn't complete — have the user re-approve. |
| 179 | + - **API key (Option B):** the call returns data immediately. A `401` means |
| 180 | + the key is wrong or not reaching the header — re-check Step 2. Do NOT retry |
| 181 | + with a key you guessed or reconstructed; ask the user to paste it again or |
| 182 | + regenerate it. |
| 183 | + - An empty projects list is a valid result (a new account may have none) — |
| 184 | + distinguish "empty, exit ok" from "error." |
| 185 | + |
| 186 | +If you have the Chrome DevTools MCP server and OAuth stalls, you may offer to |
| 187 | +bring the approval tab forward so the user can complete it — but they click |
| 188 | +approve, not you. |
| 189 | + |
| 190 | +## Step 5 — Handoff summary |
| 191 | + |
| 192 | +Tell the user, in this order: |
| 193 | + |
| 194 | +1. **What's connected** — the `elnora` MCP server at |
| 195 | + `https://mcp.elnora.ai/mcp`, and (non-Claude harnesses) where the 9 skills |
| 196 | + were copied. |
| 197 | +2. **How they're authenticated** — OAuth (token cached by their client) or API |
| 198 | + key (stored in the client's secret store / header config). If API key, remind |
| 199 | + them it's never stored in this repo and to rotate it if it ever leaks. |
| 200 | +3. **How to use it** — one entry point that matches the harness: |
| 201 | + - **Claude Code with the plugin:** `/elnora:protocol <description>`, or just |
| 202 | + ask in natural language ("use Elnora to list my projects"). |
| 203 | + - **Any other harness:** ask in natural language; the skills route the intent |
| 204 | + to the right `elnora_*` MCP tool. Dispatch table in [`AGENTS.md`](AGENTS.md). |
| 205 | +4. **Where auth lives** — their MCP client's config / secret store, never this |
| 206 | + repo. |
| 207 | + |
| 208 | +## Completion checklist |
| 209 | + |
| 210 | +Verify ALL of these before declaring done. If any fails, finish it first. |
| 211 | + |
| 212 | +1. The harness lists an `elnora` MCP server pointed at |
| 213 | + `https://mcp.elnora.ai/mcp`. |
| 214 | +2. `elnora_health_check` returns a healthy status. |
| 215 | +3. `elnora_account_get` (or `elnora_projects_list`) returns data — no `401` |
| 216 | + (empty project list is OK; an auth error is not). |
| 217 | +4. **Non-Claude harnesses:** all 9 skill directories are present in the target |
| 218 | + skills dir, each with a `SKILL.md`. |
| 219 | +5. If the user chose the API key: it is set in the client's auth config, and it |
| 220 | + appears in NO git-tracked file. You did not echo it into chat or a repo file. |
| 221 | +6. You wrote nothing to the repository that the user didn't ask for — no keys, |
| 222 | + no local config committed. |
| 223 | + |
| 224 | +When all applicable items pass, print `ELNORA_PLUGINS_READY` on its own line so |
| 225 | +the user (and any wrapping harness) can grep for it. |
0 commit comments