# hermes-mcp

An MCP server that turns internal **Hermes** documents (HashiCorp PRDs, RFCs, specs, memos) into agent tools — relevance search, document metadata, related resources, and full document bodies — plus a companion **skill** that makes your agent cross-check specs against the code in your editor.

## Tools
`hermes_search` · `hermes_get_document` · `hermes_get_document_content` · `hermes_get_related_resources` · `hermes_recently_viewed_docs` · `hermes_check_auth` · `hermes_login` · `hermes_sharepoint_login`

## Requirements
- **Node.js 18+** (developed on 26)
- **Google Chrome** (for the sign-in / browser-content helpers)
- An MCP-capable agent (bob, Claude Desktop, VS Code, …)

## Quick start
```bash
git clone https://github.com/yummydirtx/hermes-mcp.git
cd hermes-mcp
node install.js
```
The installer:
1. runs `npm install`,
2. copies the **hermes** skill into `~/.bob/skills/hermes/`,
3. adds a **hermes** server to `~/.bob/settings/mcp.json` (existing servers/secrets are preserved).

Then authenticate and reload your agent (below).

> Claude Desktop or VS Code instead of bob? Run `node install.js --claude`, or copy a snippet from [`examples/`](examples/).

## Authenticate to Hermes
Hermes sits behind SSO. Capture your session one of two ways:

- **Automatic (recommended):**
  ```bash
  npm run attach
  ```
  A normal Chrome opens — sign in. Your session cookie is written to `.hermes-cookie` and hot-reloaded by the server. Keep that window open (it's also used for reading document bodies).

- **Manual:** in a logged-in Hermes tab, DevTools → Network → click a request → copy the `Cookie:` request header into `.hermes-cookie`:
  ```bash
  # macOS
  pbpaste > .hermes-cookie
  # Windows (PowerShell)
  Get-Clipboard | Set-Content -NoNewline .hermes-cookie
  ```

Verify with the `hermes_check_auth` tool.

## Reading full document bodies
Bodies live in SharePoint. `hermes_get_document_content` tries, in order (`source: "auto"`):
1. **Search index** — the body Hermes already indexed. No extra permissions. Often enough.
2. **Your browser session** (`source: "browser"`) — reads the file through the Chrome you signed into (`npm run attach`), over the DevTools protocol. **No Microsoft Graph, no admin, no extra scopes** — just the access you already have. Keep the document open in that Chrome.
3. **Microsoft Graph** (`source: "sharepoint"`, via `hermes_sharepoint_login`) — needs `Files.Read.All`/`Sites.Read.All`. The built-in client can't obtain these in a locked-down tenant; use a **dedicated Azure AD app** (below).

Test the browser path directly:
```bash
npm run sp-browser "<sharepoint-document-url>"
```

### Optional: dedicated Azure AD app (for the Graph path)
Azure Portal → **App registrations** → **New registration** → Redirect URI = *Public client/native* `http://localhost` → **API permissions** → Microsoft Graph → **Delegated**: `Files.Read.All`, `Sites.Read.All`, `offline_access` → **Grant admin consent**. Then set `SP_CLIENT_ID` and `SP_TENANT_ID` in the server `env` and run `hermes_sharepoint_login`.

## Manual setup (no installer)
Add this to your agent's MCP config, fixing the path (see [`examples/`](examples/) for bob / Claude / VS Code variants):
```jsonc
{
  "mcpServers": {
    "hermes": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/hermes-mcp/hermes-mcp.js"],
      "env": {
        "HERMES_BASE_URL": "https://hermes-sharepoint.hashicorp.services",
        "HERMES_COOKIE_FILE": "/ABSOLUTE/PATH/TO/hermes-mcp/.hermes-cookie"
      }
    }
  }
}
```
Then copy `skills/hermes/SKILL.md` into your agent's skills folder.

## Windows notes
- Use PowerShell; `node install.js` works the same.
- `npm run attach` launches your installed Chrome/Edge. If it isn't found, set `HERMES_CHROME` to the browser's `.exe`.
- Absolute paths in `args` use backslashes — the installer writes them correctly; if editing by hand use `\\` or forward slashes.

## Configuration (env)
| Var | Default | Purpose |
|-----|---------|---------|
| `HERMES_BASE_URL` | `https://hermes-sharepoint.hashicorp.services` | Hermes host |
| `HERMES_COOKIE_FILE` | `./.hermes-cookie` | Session cookie (hot-reloaded) |
| `HERMES_CDP_PORT` | `9222` | Debug-Chrome port for `attach` + browser content |
| `HERMES_CHROME` | auto-detect | Path to Chrome/Edge executable |
| `SP_CLIENT_ID`, `SP_TENANT_ID` | – | Dedicated Azure AD app for the Graph path |
| `SHAREPOINT_TOKEN_FILE` | `./.sharepoint-token` | Optional pasted Graph token |

## Scripts
- `npm start` — run the server (stdio)
- `npm run attach` — capture the Hermes session from a real Chrome
- `npm run sp-browser "<url>"` — read a document via your browser session
- `node install.js` — set up + register with your agent

## Security
Never commit `.hermes-cookie`, `.sharepoint-*`, or the browser profiles — they hold your live session. `.gitignore` already excludes them.