Content
# 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`.
