hermes-oh-my-pi-mcp

A tiny Hermes-friendly bridge for oh-my-pi / omp.

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:

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

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

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

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

npm install
npm test
npm run doctor

Run as an MCP server

npx hermes-oh-my-pi-mcp

Or from source:

node ./src/index.js

Hermes config example

Add this to Hermes MCP config:

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

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

{
  "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:

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:

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.