Metadata-Version: 2.4
Name: hermes-prime-mcp
Version: 0.2.1a2
Summary: Read-only stdio MCP server for a versioned convention card in Claude Code.
Author-email: Rolando Bosch <roli@hermes-labs.ai>
License: MIT
Project-URL: Homepage, https://github.com/hermes-labs-ai/hermes-prime
Project-URL: Repository, https://github.com/hermes-labs-ai/hermes-prime
Project-URL: Issues, https://github.com/hermes-labs-ai/hermes-prime/issues
Keywords: mcp,model-context-protocol,claude-code,agent-conventions,session-bootstrap
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# hermes-prime MCP server

Native Claude Code surface for `hermes-prime`. Exposes the session-priming
conventions as MCP tools so a fresh session can call `get_conventions` once
at the top instead of relying on `CLAUDE.md` injection.

Pure stdlib. No third-party runtime dependencies.

mcp-name: io.github.hermes-labs-ai/hermes-prime

## Tools

- `get_conventions(scope_class?)` — returns the CLAUDE-fragment as raw markdown.
  Optional `scope_class` returns `fragments/<scope_class>.md` if it exists,
  else falls back to the default fragment.
- `list_scopes` — enumerates available scoped fragments.

## Install from PyPI (packaged console script)

Once published (see [Packaging status](#packaging-status) below), the server
installs as a standalone console script with no repo checkout required:

```bash
pip install hermes-prime-mcp
hermes-prime-mcp   # speaks MCP JSON-RPC over stdio
```

or run it without installing, via `uvx`:

```bash
uvx --from hermes-prime-mcp hermes-prime-mcp
```

Register the installed script directly with Claude Code:

```bash
claude mcp add --scope local hermes-prime -- hermes-prime-mcp
```

The packaged server reads the versioned convention card bundled in its wheel.
Set `HERMES_PRIME_FRAGMENT_ROOT=/path/to/your/project` only when you want it
to read a trusted custom `CLAUDE-fragment.md` instead (see
[Configuration](#configuration)).

## Register in Claude Code (from a repo checkout)

Run from the repository root. Local scope loads the command for your sessions
in the current project:

```bash
claude mcp add --scope local hermes-prime -- python3 "$PWD/mcp-server/hermes_prime_mcp.py"
```

For a private command available to your sessions across projects, use user
scope:

```bash
claude mcp add --scope user hermes-prime -- python3 "$PWD/mcp-server/hermes_prime_mcp.py"
```

Use `claude mcp get hermes-prime` or `claude mcp list` to verify registration;
both should report the server as Connected (verified with Claude Code 2.1.268
on 2026-09-11). The tools appear in sessions covered by the selected scope,
and the server's `initialize` instructions tell the session to call
`get_conventions` once before recursive or emergent work.

## Verify it works

```bash
printf '%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_conventions","arguments":{}}}' \
  | python3 "$PWD/mcp-server/hermes_prime_mcp.py"
```

Two JSON-RPC responses; second one contains the fragment markdown.

## Uninstall

```bash
claude mcp remove hermes-prime
```

Remove it from the same project/scope in which it was registered.

## Configuration

`HERMES_PRIME_FRAGMENT_ROOT` overrides the directory containing the default
`CLAUDE-fragment.md`. In a repository checkout the default is the repository
root; in a packaged install it is the immutable card bundled with the wheel.
Scoped fragments are bundled at
`mcp-server/fragments/<scope_class>.md` in a checkout.

## Tests

```bash
python3 -m pytest mcp-server/test_hermes_prime_mcp.py -v
```

13 tests, stdlib-only (subprocess + json), no `mcp` SDK dependency.

## Packaging status

- `pyproject.toml` (repo root) builds an sdist/wheel named `hermes-prime-mcp`
  exposing the `hermes-prime-mcp` console script via `python -m build`.
- `server.json` (repo root) is the MCP Registry manifest, matching the
  registry's `2025-12-11` `server.schema.json`.
- Before publishing, run `mcp-publisher validate server.json`; this verifies
  the live Registry contract without creating a listing.
- The package version declared by `server.json` is published to PyPI before
  Registry dispatch. The Registry listing is submitted only through the
  manually dispatched **Publish MCP Registry listing** GitHub Actions
  workflow. It checks the selected `server.json` version and its live PyPI
  artifact, validates the manifest, then uses short-lived GitHub Actions
  OIDC—no stored Registry token.
