# hermes-oh-my-pi-mcp

A tiny Hermes-friendly bridge for [oh-my-pi / omp](https://omp.sh/).

This repository now includes both the working MCP bridge and the full integration explanation for GitHub readers.

## What this repo provides

It exposes two MCP tools:

- `prompt` — run `omp` in one-shot mode and return the output
- `doctor` — verify `omp` and `bun` are available locally

## Why this exists

Hermes works well with MCP, plugins, and custom tools. oh-my-pi already provides a strong CLI/runtime, so this bridge lets Hermes users call it without reimplementing the agent stack.

The recommended operating model is:

```text
User → Hermes → MCP bridge → bun → omp → result
```

### Hermes vs MCP vs Skill

- **Hermes**: decides what to do
- **MCP bridge**: actually calls `omp`
- **omp**: performs the coding task
- **Skill**: teaches Hermes when to prefer `omp` and how to fall back when needed

In other words, the skill is helpful but optional; the MCP bridge is the execution layer.

## Detailed integration guide

See the full explanation here:

- [docs/hermes-omp-integration.md](docs/hermes-omp-integration.md)

That guide covers:

- call structure
- why MCP is the right wrapper
- when a skill helps
- example Hermes configuration
- troubleshooting and usage policy

## Release notes

- [RELEASE_NOTES.md](RELEASE_NOTES.md)

Use this file to see what changed in each published version.

## Requirements

- Node.js 20+
- `omp` installed and on `PATH`
- `bun` installed and on `PATH` because `omp` is Bun-based

## Install oh-my-pi

```bash
npm install -g @oh-my-pi/pi-coding-agent
```

If the `omp` binary fails with `bun: No such file or directory`, install Bun 1.3.14+ and retry.

## Local development

```bash
npm install
npm test
npm run doctor
```

## Run as an MCP server

```bash
npx hermes-oh-my-pi-mcp
```

Or from source:

```bash
node ./src/index.js
```

## Hermes config example

Add this to Hermes MCP config:

```json
{
  "mcpServers": {
    "oh-my-pi": {
      "command": "npx",
      "args": ["-y", "hermes-oh-my-pi-mcp"]
    }
  }
}
```

If you want to point Hermes at a local checkout instead:

```json
{
  "mcpServers": {
    "oh-my-pi": {
      "command": "node",
      "args": ["/absolute/path/to/hermes-oh-my-pi-mcp/src/index.js"]
    }
  }
}
```

## Verified local setup

On this machine, Hermes is actually connected to `oh-my-pi` and the MCP server is enabled.

The working registration looks like this:

```bash
hermes mcp add oh-my-pi \
  --command node \
  --args /home/ubuntu/oh-my-pi-hermes-mcp/src/index.js \
  --env OMP_BIN=/home/ubuntu/.local/share/mise/installs/node/24.16.0/lib/node_modules/@oh-my-pi/pi-coding-agent/dist/cli.js \
  --env BUN_BIN=/home/ubuntu/.bun/bin/bun
```

That setup was verified with:

```bash
hermes mcp test oh-my-pi
```

If your machine uses different paths, keep the same shape but replace the absolute values with your own `OMP_BIN` and `BUN_BIN` locations.

## Suggested skill policy

If you also want Hermes to *prefer* `omp` for coding requests, add a small skill that says:

1. Code generation / refactoring / analysis requests should consider `omp` first.
2. If the environment looks broken, run `doctor` first.
3. If `omp` output is insufficient, Hermes should supplement it with its own reasoning and tools.

That skill is not required for the bridge to work; it just makes the usage pattern consistent.

## Notes

- The bridge runs `omp` in a one-shot JSON-friendly mode and returns the text response.
- Set `OMP_BIN` if your binary is not just `omp`.
- Set `BUN_BIN` if Bun is installed somewhere custom.
- The long-form architecture and usage notes live in `docs/hermes-omp-integration.md`.