hermes-action-bridge 0.5.0 → 0.6.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +33 -0
- package/README.md +29 -1
- package/dist/doctor.js +4 -15
- package/dist/doctor.js.map +1 -1
- package/dist/mcp-catalog.d.ts +4 -0
- package/dist/mcp-catalog.js +21 -0
- package/dist/mcp-catalog.js.map +1 -0
- package/docs/ARCHITECTURE.md +21 -0
- package/docs/FUNCTIONAL-TESTS.md +18 -0
- package/docs/SMITHERY.md +23 -0
- package/docs/distribution-runbook.md +515 -0
- package/package.json +8 -2
- package/plugins/hermes-action/.claude-plugin/plugin.json +12 -0
- package/plugins/hermes-action/.codex-plugin/plugin.json +1 -1
- package/plugins/hermes-action/.mcp.json +1 -1
- package/plugins/hermes-action/assets/app-icon.png +0 -0
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,39 @@ All notable changes to this project are documented here. The format is based on
|
|
|
6
6
|
|
|
7
7
|
## [Unreleased]
|
|
8
8
|
|
|
9
|
+
## [0.6.2] - 2026-07-25
|
|
10
|
+
|
|
11
|
+
### Added
|
|
12
|
+
|
|
13
|
+
- Generated the MCPB tool catalog from the runtime MCP handshake and verified
|
|
14
|
+
archive/runtime parity without maintaining a second manual tool list.
|
|
15
|
+
|
|
16
|
+
## [0.6.1] - 2026-07-25
|
|
17
|
+
|
|
18
|
+
### Fixed
|
|
19
|
+
|
|
20
|
+
- Allowed the deterministic MCPB reproducibility test enough time to rebuild
|
|
21
|
+
its production bundle on GitHub-hosted runners without hitting Vitest's
|
|
22
|
+
default test or setup-hook timeouts.
|
|
23
|
+
|
|
24
|
+
## [0.6.0] - 2026-07-25
|
|
25
|
+
|
|
26
|
+
### Added
|
|
27
|
+
|
|
28
|
+
- Claude Code plugin marketplace metadata for installing the version-pinned
|
|
29
|
+
Hermes Action plugin directly from GitHub.
|
|
30
|
+
- A versioned, self-contained MCPB release artifact for Claude Desktop and
|
|
31
|
+
Smithery local-stdio distribution.
|
|
32
|
+
- A canonical `skills/hermes-action-bridge/SKILL.md` entry for skills.sh and
|
|
33
|
+
other Agent Skills-compatible clients.
|
|
34
|
+
- Distribution drift tests and release-asset automation for the marketplace,
|
|
35
|
+
Skill, and MCPB metadata.
|
|
36
|
+
|
|
37
|
+
### Changed
|
|
38
|
+
|
|
39
|
+
- Pinned the Codex marketplace plugin runtime to the matching published bridge
|
|
40
|
+
version instead of resolving an unbounded npm latest release.
|
|
41
|
+
|
|
9
42
|
## [0.5.0] - 2026-07-25
|
|
10
43
|
|
|
11
44
|
### Added
|
package/README.md
CHANGED
|
@@ -68,6 +68,32 @@ Claude Code is unavailable, conflicting, or cannot verify its user-scoped
|
|
|
68
68
|
stdio MCP entry, the command exits non-zero without installing the requested
|
|
69
69
|
skills. Use `--project` for an explicit skill-only setup.
|
|
70
70
|
|
|
71
|
+
### Other distribution channels
|
|
72
|
+
|
|
73
|
+
Choose the channel that matches the agent surface. Hermes Agent must always be
|
|
74
|
+
installed and configured on the same computer as the local bridge.
|
|
75
|
+
|
|
76
|
+
| Channel | What it configures | Install |
|
|
77
|
+
| --- | --- | --- |
|
|
78
|
+
| npm installer | Skill and verified user-scoped MCP for Codex CLI/app and Claude Code | `hermes-action install all` |
|
|
79
|
+
| Claude Code marketplace | Claude plugin with the Skill and a version-pinned MCP server | `claude plugin marketplace add TheBlueHouse75/hermes-action-bridge`, then `claude plugin install hermes-action@hermes-action-bridge` |
|
|
80
|
+
| Claude Desktop | Self-contained MCPB extension for the bridge runtime | From the [latest GitHub Release](https://github.com/TheBlueHouse75/hermes-action-bridge/releases/latest), download `hermes-action-bridge-<version>.mcpb` and open it with Claude Desktop |
|
|
81
|
+
| Agent Skills | Portable instructions for supported coding agents | `npx skills add TheBlueHouse75/hermes-action-bridge --skill hermes-action-bridge` |
|
|
82
|
+
| Smithery | The same local MCPB bundle through the Smithery catalog | Check the [latest release notes](https://github.com/TheBlueHouse75/hermes-action-bridge/releases/latest) for the verified Smithery listing or its pending status |
|
|
83
|
+
|
|
84
|
+
The standalone Agent Skill only teaches an agent when and how to delegate; it
|
|
85
|
+
does not register an MCP server. Use the npm installer, Claude marketplace, or
|
|
86
|
+
MCPB channel when MCP tools are required.
|
|
87
|
+
|
|
88
|
+
Maintainers releasing a new version should follow the
|
|
89
|
+
[distribution runbook](docs/distribution-runbook.md), which covers the
|
|
90
|
+
automated release workflow and the manual directory publication checks.
|
|
91
|
+
|
|
92
|
+
Codex CLI and the Codex surface in the ChatGPT desktop app share the local
|
|
93
|
+
Codex MCP configuration on the same host. A general ChatGPT connector is a
|
|
94
|
+
different distribution target: it requires a remotely reachable MCP server
|
|
95
|
+
and is not installed by this local stdio bundle.
|
|
96
|
+
|
|
71
97
|
<details>
|
|
72
98
|
<summary>From source (for development)</summary>
|
|
73
99
|
|
|
@@ -312,7 +338,9 @@ codex plugin marketplace add TheBlueHouse75/hermes-action-bridge
|
|
|
312
338
|
codex plugin add hermes-action@hermes-action-bridge
|
|
313
339
|
```
|
|
314
340
|
|
|
315
|
-
This registers the `hermes-action` MCP server and the Hermes delegation skill
|
|
341
|
+
This registers the `hermes-action` MCP server and the Hermes delegation skill
|
|
342
|
+
in Codex. Hermes Agent must be installed locally — the plugin runs the
|
|
343
|
+
version-pinned npm package with `npx`.
|
|
316
344
|
|
|
317
345
|
> **Faster MCP startup:** `npx` re-resolves the package on every server start.
|
|
318
346
|
> The native installer registers the absolute global launcher instead.
|
package/dist/doctor.js
CHANGED
|
@@ -1,13 +1,11 @@
|
|
|
1
1
|
import { spawnSync } from "node:child_process";
|
|
2
|
-
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
|
|
3
|
-
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
|
|
4
2
|
import { defaultConfig } from "./config.js";
|
|
3
|
+
import { listBridgeTools } from "./mcp-catalog.js";
|
|
5
4
|
import { checkHermesStatus, versionProbeTimeoutMs } from "./status.js";
|
|
6
5
|
import { buildEffectiveRun, defaultTimeoutSeconds } from "./run.js";
|
|
7
6
|
import { runHermesCli } from "./adapters/hermes-cli.js";
|
|
8
7
|
import { skillStates } from "./install/install-service.js";
|
|
9
8
|
import { inspectMcp } from "./install/mcp-service.js";
|
|
10
|
-
import { createBridgeMcpServer } from "./mcp-server.js";
|
|
11
9
|
const minNodeMajor = 20;
|
|
12
10
|
const agentCommand = { "claude-code": "claude", codex: "codex" };
|
|
13
11
|
/** Synchronous environment checks. The optional `--probe` check is added separately by the caller. */
|
|
@@ -46,27 +44,18 @@ export async function probeCheck(config) {
|
|
|
46
44
|
}
|
|
47
45
|
/** Token-free MCP initialize/list-tools handshake against the current server implementation. */
|
|
48
46
|
export async function mcpHandshakeCheck(config) {
|
|
49
|
-
const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
|
|
50
|
-
const server = createBridgeMcpServer(config);
|
|
51
|
-
const client = new Client({ name: "hermes-action-doctor", version: "1.0.0" });
|
|
52
47
|
try {
|
|
53
|
-
await
|
|
54
|
-
|
|
55
|
-
const tools = await client.listTools();
|
|
56
|
-
const names = new Set(tools.tools.map((tool) => tool.name));
|
|
48
|
+
const tools = await listBridgeTools(config);
|
|
49
|
+
const names = new Set(tools.map((tool) => tool.name));
|
|
57
50
|
const required = ["hermes_run", "hermes_plan", "hermes_capabilities", "hermes_status"];
|
|
58
51
|
const missing = required.filter((name) => !names.has(name));
|
|
59
52
|
return missing.length === 0
|
|
60
|
-
? { id: "mcp:handshake", status: "pass", detail: `${tools.
|
|
53
|
+
? { id: "mcp:handshake", status: "pass", detail: `${tools.length} tools available` }
|
|
61
54
|
: { id: "mcp:handshake", status: "fail", detail: `missing tools: ${missing.join(", ")}` };
|
|
62
55
|
}
|
|
63
56
|
catch (error) {
|
|
64
57
|
return { id: "mcp:handshake", status: "fail", detail: error instanceof Error ? error.message : String(error) };
|
|
65
58
|
}
|
|
66
|
-
finally {
|
|
67
|
-
await client.close().catch(() => undefined);
|
|
68
|
-
await server.close().catch(() => undefined);
|
|
69
|
-
}
|
|
70
59
|
}
|
|
71
60
|
export function formatDoctor(report) {
|
|
72
61
|
const label = { pass: "ok", warn: "warn", fail: "FAIL" };
|
package/dist/doctor.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,
|
|
1
|
+
{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
import type { Tool } from "@modelcontextprotocol/sdk/types.js";
|
|
2
|
+
import type { BridgeConfig } from "./types.js";
|
|
3
|
+
/** Return the current server's public tool catalog through the MCP protocol. */
|
|
4
|
+
export declare function listBridgeTools(config: BridgeConfig): Promise<Tool[]>;
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
|
|
2
|
+
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
|
|
3
|
+
import { createBridgeMcpServer, createBridgeRuntime } from "./mcp-server.js";
|
|
4
|
+
/** Return the current server's public tool catalog through the MCP protocol. */
|
|
5
|
+
export async function listBridgeTools(config) {
|
|
6
|
+
const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
|
|
7
|
+
const runtime = createBridgeRuntime(config);
|
|
8
|
+
const server = createBridgeMcpServer(config, { runtime });
|
|
9
|
+
const client = new Client({ name: "hermes-action-catalog", version: "1.0.0" });
|
|
10
|
+
try {
|
|
11
|
+
await server.connect(serverTransport);
|
|
12
|
+
await client.connect(clientTransport);
|
|
13
|
+
return (await client.listTools()).tools;
|
|
14
|
+
}
|
|
15
|
+
finally {
|
|
16
|
+
await client.close().catch(() => undefined);
|
|
17
|
+
await server.close().catch(() => undefined);
|
|
18
|
+
await runtime.dispose().catch(() => undefined);
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
//# sourceMappingURL=mcp-catalog.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"mcp-catalog.js","sourceRoot":"","sources":["../src/mcp-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAE1E,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAG7E,gFAAgF;AAChF,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,MAAoB;IACxD,MAAM,CAAC,eAAe,EAAE,eAAe,CAAC,GAAG,iBAAiB,CAAC,gBAAgB,EAAE,CAAC;IAChF,MAAM,OAAO,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAG,qBAAqB,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IAC1D,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,EAAE,IAAI,EAAE,uBAAuB,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IAC/E,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;QACtC,MAAM,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;QACtC,OAAO,CAAC,MAAM,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC;IAC1C,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC5C,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC5C,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACjD,CAAC;AACH,CAAC"}
|
package/docs/ARCHITECTURE.md
CHANGED
|
@@ -54,6 +54,27 @@ launcher path. Defaults remain conservative: never modify `CLAUDE.md` /
|
|
|
54
54
|
`AGENTS.md` without `--project-hint`, never overwrite foreign skills or
|
|
55
55
|
customized MCP entries, and stay idempotent.
|
|
56
56
|
|
|
57
|
+
## Distribution surfaces
|
|
58
|
+
|
|
59
|
+
The MCP-capable local distribution channels expose the same tools and preserve
|
|
60
|
+
the same policy behavior:
|
|
61
|
+
|
|
62
|
+
- `.agents/` and `plugins/hermes-action/.codex-plugin/` describe the Codex
|
|
63
|
+
plugin marketplace.
|
|
64
|
+
- `.claude-plugin/` and `plugins/hermes-action/.claude-plugin/` describe the
|
|
65
|
+
Claude Code marketplace.
|
|
66
|
+
- `skills/hermes-action-bridge/SKILL.md` is the canonical Agent Skills copy;
|
|
67
|
+
it provides delegation instructions only and does not configure an MCP
|
|
68
|
+
server. Tests keep it byte-identical to `skillMarkdown()` and the plugin
|
|
69
|
+
copy.
|
|
70
|
+
- `extensions/hermes-action/` is the MCPB source for Claude Desktop and
|
|
71
|
+
Smithery. The generated archive bundles the bridge and production
|
|
72
|
+
dependencies, but deliberately excludes Hermes Agent, user configuration,
|
|
73
|
+
credentials, and machine-specific paths.
|
|
74
|
+
|
|
75
|
+
The npm package version is the shared release version for plugin manifests,
|
|
76
|
+
MCP launchers, and MCPB metadata. Tests fail when these copies drift.
|
|
77
|
+
|
|
57
78
|
## Config precedence
|
|
58
79
|
|
|
59
80
|
The bridge merges config in this order:
|
package/docs/FUNCTIONAL-TESTS.md
CHANGED
|
@@ -44,6 +44,24 @@ The installer tests verify (with injected home/cwd and temp `HOME`, no real agen
|
|
|
44
44
|
- the Streamable HTTP server completes an MCP handshake on loopback and rejects
|
|
45
45
|
public binding, weak/missing authentication, and non-Tailscale addresses.
|
|
46
46
|
|
|
47
|
+
The distribution tests verify:
|
|
48
|
+
|
|
49
|
+
- Claude Code marketplace and plugin manifests use the npm package version and
|
|
50
|
+
the checked-in, version-pinned MCP configuration.
|
|
51
|
+
- The canonical skills.sh copy remains byte-identical to both the installer
|
|
52
|
+
template and the plugin Skill.
|
|
53
|
+
- The MCPB manifest matches the package version and the generated archive
|
|
54
|
+
contains the bridge runtime and its production dependencies without secrets
|
|
55
|
+
or machine-specific paths.
|
|
56
|
+
|
|
57
|
+
Build the Claude Desktop/Smithery artifact explicitly with:
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
npm run build:mcpb
|
|
61
|
+
npm run inspect:mcpb
|
|
62
|
+
npm test -- tests/mcpb-distribution.test.ts
|
|
63
|
+
```
|
|
64
|
+
|
|
47
65
|
## Live Hermes smoke test
|
|
48
66
|
|
|
49
67
|
Use a safe dry-run first:
|
package/docs/SMITHERY.md
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Smithery local stdio release
|
|
2
|
+
|
|
3
|
+
Hermes Action Bridge reaches Smithery as the same local stdio MCPB bundle used
|
|
4
|
+
by Claude Desktop. The archive contains the bridge runtime and its locked
|
|
5
|
+
production dependencies, but never Hermes Agent, user configuration,
|
|
6
|
+
credentials, or machine-specific paths.
|
|
7
|
+
|
|
8
|
+
## Maintainer procedure
|
|
9
|
+
|
|
10
|
+
[The Smithery MCPB publication section of the distribution runbook](distribution-runbook.md#6-smithery-mcpb-publication)
|
|
11
|
+
is the canonical release procedure. Follow it to build and inspect the exact
|
|
12
|
+
GitHub Release artifact, authenticate with `smithery auth login`, publish it,
|
|
13
|
+
and retain the resulting Smithery server-page URL as proof.
|
|
14
|
+
|
|
15
|
+
Smithery publication is deliberately interactive and manual: do not commit a
|
|
16
|
+
Smithery token, API key, or other credential, and do not add one to CI. There
|
|
17
|
+
is no repository-owned Smithery manifest; the inspected versioned `.mcpb`
|
|
18
|
+
archive is the submitted artifact.
|
|
19
|
+
|
|
20
|
+
## Sources
|
|
21
|
+
|
|
22
|
+
- [Smithery: Publish](https://smithery.ai/docs/build/publish)
|
|
23
|
+
- [Smithery CLI reference](https://smithery.ai/docs/concepts/cli)
|
|
@@ -0,0 +1,515 @@
|
|
|
1
|
+
# Hermes Action Bridge distribution runbook
|
|
2
|
+
|
|
3
|
+
This is the maintainer procedure for releasing one new version of Hermes Action
|
|
4
|
+
Bridge across every supported distribution surface. It is intentionally
|
|
5
|
+
procedural: do not treat a successful npm publication as proof that the MCPB,
|
|
6
|
+
registry listing, marketplaces, or directories are ready.
|
|
7
|
+
|
|
8
|
+
Use this document for a new immutable version only. Never replace an existing
|
|
9
|
+
npm version, Git tag, MCP Registry version, or release asset in order to
|
|
10
|
+
"repair" a release; publish a corrective version instead.
|
|
11
|
+
|
|
12
|
+
The release commit must first live on a dedicated `release/<version>` branch,
|
|
13
|
+
not on `main`. Its GitHub Release publishes and proves npm, MCPB, and the MCP
|
|
14
|
+
Registry. Only after those immutable artifacts succeed may that exact release
|
|
15
|
+
commit be promoted to `main`; this is what makes the Git-backed Claude
|
|
16
|
+
marketplace and Agent Skills channels public. The ordering prevents `main`
|
|
17
|
+
from ever pinning a Claude plugin to an npm package that is not yet available.
|
|
18
|
+
|
|
19
|
+
## Release model
|
|
20
|
+
|
|
21
|
+
The release version is the value in `package.json`. It must also be reflected
|
|
22
|
+
in these checked-in distribution files before the release commit is created:
|
|
23
|
+
|
|
24
|
+
| Surface | Version-bearing file |
|
|
25
|
+
| --- | --- |
|
|
26
|
+
| npm package | `package.json` and `package-lock.json` |
|
|
27
|
+
| MCP Registry | `server.json` and `server.json.packages[0]` |
|
|
28
|
+
| Codex plugin | `plugins/hermes-action/.codex-plugin/plugin.json` and `plugins/hermes-action/.mcp.json` |
|
|
29
|
+
| Claude Code marketplace | `.claude-plugin/marketplace.json` and `plugins/hermes-action/.claude-plugin/plugin.json` |
|
|
30
|
+
| Claude Desktop / Smithery MCPB | `extensions/hermes-action/manifest.json` |
|
|
31
|
+
|
|
32
|
+
The distribution tests reject drift among these files. The GitHub release
|
|
33
|
+
workflow independently rewrites `server.json` from `package.json` before MCP
|
|
34
|
+
Registry publication, but the committed `server.json` must still match so that
|
|
35
|
+
local checks and the next release start from a consistent state.
|
|
36
|
+
|
|
37
|
+
The GitHub Actions workflow runs only when a GitHub Release is published, not
|
|
38
|
+
when a tag is merely pushed. Manual dispatch is deliberately disabled because
|
|
39
|
+
the workflow publishes immutable artifacts. It builds the MCPB, publishes npm
|
|
40
|
+
through Trusted Publishing when needed, then either uploads a missing MCPB
|
|
41
|
+
asset or verifies byte-for-byte that the existing asset matches. Only then does
|
|
42
|
+
it publish or byte-for-byte verify the MCP Registry record. The workflow pins
|
|
43
|
+
the npm CLI version so that an immutable-release retry uses the same packer as
|
|
44
|
+
the initial publication; update that pin only as an intentional release change.
|
|
45
|
+
|
|
46
|
+
## Roles, authentication, and secrets
|
|
47
|
+
|
|
48
|
+
| Surface | Required authority | Secret or authentication rule |
|
|
49
|
+
| --- | --- | --- |
|
|
50
|
+
| Git and GitHub Release | Push access to `TheBlueHouse75/hermes-action-bridge` | Use normal Git/GitHub authentication; the workflow uses its scoped `GITHUB_TOKEN`. |
|
|
51
|
+
| npm | npm Trusted Publishing configured for this repository | No `NPM_TOKEN` is stored or supplied to the workflow. |
|
|
52
|
+
| MCP Registry | GitHub OIDC authority for `io.github.TheBlueHouse75/*` | No registry token; `mcp-publisher login github-oidc` runs only when a version is absent. |
|
|
53
|
+
| Claude Code marketplace | Maintainer access to the GitHub repository | The marketplace reads the checked-in manifest; no separate marketplace secret is configured. |
|
|
54
|
+
| Agent Skills / skills.sh | Public GitHub repository | No repository credential or upload token is configured. |
|
|
55
|
+
| Smithery | Account that owns the Smithery namespace | Authenticate interactively with `smithery auth login`; do not commit an API key or add it to CI. |
|
|
56
|
+
| Glama | GitHub account authorized to claim the listing | Complete GitHub OAuth in the Glama UI; do not use a personal token in the repository. |
|
|
57
|
+
|
|
58
|
+
`main` may be branch-protected. In that case, promotion requires the normal
|
|
59
|
+
approved, passing pull request; do not bypass protection for a release. A
|
|
60
|
+
fast-forward-only promotion is allowed only when direct pushes to `main` are
|
|
61
|
+
explicitly authorized and `main` is still an ancestor of the release branch.
|
|
62
|
+
|
|
63
|
+
Do not paste credentials into shell history, release notes, documentation, CI
|
|
64
|
+
variables, or the generated MCPB. The bundle test rejects obvious secrets and
|
|
65
|
+
machine-specific paths.
|
|
66
|
+
|
|
67
|
+
## Ordered end-to-end checklist
|
|
68
|
+
|
|
69
|
+
Run these steps from the repository root. Replace `<version>` with a SemVer
|
|
70
|
+
version without a leading `v` (for example, `0.5.1`).
|
|
71
|
+
|
|
72
|
+
1. Start from an up-to-date, clean `main`, create `release/<version>`, and
|
|
73
|
+
choose the release version.
|
|
74
|
+
2. Update the version-bearing files listed in [Release model](#release-model),
|
|
75
|
+
update `CHANGELOG.md`, and commit the release changes on that release
|
|
76
|
+
branch only.
|
|
77
|
+
3. Run the local validation gate and inspect the exact package and MCPB that
|
|
78
|
+
will be published.
|
|
79
|
+
4. Push the release branch and tag the release commit. Publish the GitHub
|
|
80
|
+
Release from that tag; its workflow publishes npm, MCPB, and the MCP
|
|
81
|
+
Registry.
|
|
82
|
+
5. Wait for and retain proof of all three automated artifacts. Do not merge or
|
|
83
|
+
fast-forward the release branch into `main` before this succeeds.
|
|
84
|
+
6. Promote the release commit to `main` through the protected-branch PR flow,
|
|
85
|
+
or fast-forward only when explicitly authorized. This activates the Git
|
|
86
|
+
Claude marketplace and Agent Skills channels.
|
|
87
|
+
7. Verify the Claude marketplace/plugin and Agent Skills surfaces from `main`.
|
|
88
|
+
8. Perform the manual Smithery publication, then verify it in the catalog.
|
|
89
|
+
9. Claim or update the Glama listing manually, verify its score/listing, and
|
|
90
|
+
update any external directory PR only after the listing is live.
|
|
91
|
+
10. Record the proof URLs and command output in the release notes or release
|
|
92
|
+
issue. A release is complete only when every applicable surface has proof.
|
|
93
|
+
|
|
94
|
+
## 1. Prepare the release commit
|
|
95
|
+
|
|
96
|
+
### Prerequisites
|
|
97
|
+
|
|
98
|
+
- Node.js 20 or newer; the release workflow itself uses Node.js 22.
|
|
99
|
+
- Git push access to the repository and a clean working tree.
|
|
100
|
+
- The intended version has not already been published to npm.
|
|
101
|
+
|
|
102
|
+
### Commands
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
git switch main
|
|
106
|
+
git pull --ff-only origin main
|
|
107
|
+
git status --short
|
|
108
|
+
git switch -c release/<version>
|
|
109
|
+
npm version <version> --no-git-tag-version
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
`npm version --no-git-tag-version` updates `package.json` and the lockfile. It
|
|
113
|
+
does not update the distribution manifests. Update every version-bearing file
|
|
114
|
+
in the table above and add a dated `CHANGELOG.md` entry. Do not edit a prior
|
|
115
|
+
release section.
|
|
116
|
+
|
|
117
|
+
Confirm there is no stale version string before testing:
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
rg -n '"version": "[^"]+"|hermes-action-bridge@[0-9]' \
|
|
121
|
+
package.json package-lock.json server.json plugins .claude-plugin extensions
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### Local publication gate
|
|
125
|
+
|
|
126
|
+
Run the same behavioral gate used by CI plus artifact inspection:
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
npm ci
|
|
130
|
+
npm run check
|
|
131
|
+
npm pack --dry-run
|
|
132
|
+
npm run build:mcpb
|
|
133
|
+
npm run inspect:mcpb
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Expected proof:
|
|
137
|
+
|
|
138
|
+
- `npm run check` succeeds, including the metadata, skill, MCPB, and MCP
|
|
139
|
+
handshake tests.
|
|
140
|
+
- `npm pack --dry-run` lists `dist/` and `plugins/` and does not list local
|
|
141
|
+
configuration, credentials, or `release/`.
|
|
142
|
+
- the archive exists at `release/hermes-action-bridge-<version>.mcpb`, includes
|
|
143
|
+
`dist/cli.js` and production `node_modules`, and has no user path or secret.
|
|
144
|
+
|
|
145
|
+
`release/` is ignored. Delete a local artifact only if needed for local disk
|
|
146
|
+
cleanup; it is regenerated by the workflow and is not a rollback mechanism.
|
|
147
|
+
|
|
148
|
+
### Commit and release-branch proof
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
git diff --check
|
|
152
|
+
git diff -- .github .claude-plugin assets docs extensions plugins scripts skills tests \
|
|
153
|
+
.gitignore CHANGELOG.md README.md package.json package-lock.json server.json
|
|
154
|
+
git add -- .github/workflows/release.yml .claude-plugin assets docs extensions \
|
|
155
|
+
plugins scripts skills tests .gitignore CHANGELOG.md README.md package.json \
|
|
156
|
+
package-lock.json server.json
|
|
157
|
+
git diff --cached --check
|
|
158
|
+
git diff --cached --stat
|
|
159
|
+
git diff --cached -- .github/workflows/release.yml
|
|
160
|
+
git commit -m "chore(release): <version>"
|
|
161
|
+
git push -u origin release/<version>
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
The explicit staging list is intentional: this first multi-channel release
|
|
165
|
+
adds the release workflow, MCPB builder, distribution tests, Skills, icons,
|
|
166
|
+
marketplace metadata, and maintainer documentation as one proven release
|
|
167
|
+
input. Confirm the staged workflow contains the MCPB asset upload/verification
|
|
168
|
+
step before committing. If a future release includes another distribution
|
|
169
|
+
surface, add its paths deliberately instead of assuming the version files are
|
|
170
|
+
the entire release.
|
|
171
|
+
|
|
172
|
+
Before continuing, record the pushed commit SHA:
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
git rev-parse HEAD
|
|
176
|
+
git status --short
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
If a validation fails, fix it in a new commit on `release/<version>` before
|
|
180
|
+
creating the tag. Do not tag a commit whose package and manifests disagree, and
|
|
181
|
+
do not merge the branch into `main` to test publication.
|
|
182
|
+
|
|
183
|
+
## 2. GitHub Release, npm, MCPB asset, and MCP Registry
|
|
184
|
+
|
|
185
|
+
### Prerequisites
|
|
186
|
+
|
|
187
|
+
- The release commit is pushed to `origin/release/<version>` and is not yet on
|
|
188
|
+
`main`.
|
|
189
|
+
- GitHub CLI is authenticated as a maintainer, or the maintainer can create a
|
|
190
|
+
GitHub Release in the web UI.
|
|
191
|
+
- The tag must be exactly `v<version>` and `package.json.version` must be
|
|
192
|
+
exactly `<version>`.
|
|
193
|
+
|
|
194
|
+
### Commands
|
|
195
|
+
|
|
196
|
+
Tag the release-branch commit, push both refs, then publish a GitHub Release
|
|
197
|
+
from the tag:
|
|
198
|
+
|
|
199
|
+
```bash
|
|
200
|
+
git tag -a "v<version>" -m "v<version>"
|
|
201
|
+
git push origin release/<version> "v<version>"
|
|
202
|
+
gh release create "v<version>" --title "v<version>" --generate-notes
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
The Release event starts `.github/workflows/release.yml`. Do not upload an
|
|
206
|
+
MCPB manually before the workflow: it builds and uploads the versioned asset
|
|
207
|
+
from the tagged source.
|
|
208
|
+
|
|
209
|
+
Watch and inspect the workflow:
|
|
210
|
+
|
|
211
|
+
```bash
|
|
212
|
+
gh run list --workflow release.yml --limit 5
|
|
213
|
+
gh run watch
|
|
214
|
+
gh release view "v<version>"
|
|
215
|
+
gh release download "v<version>" --pattern 'hermes-action-bridge-<version>.mcpb' --dir release --clobber
|
|
216
|
+
npm run inspect:mcpb -- release/hermes-action-bridge-<version>.mcpb
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
The automated stages are:
|
|
220
|
+
|
|
221
|
+
1. verify the tag/package version equality;
|
|
222
|
+
2. install, test, and build the MCPB;
|
|
223
|
+
3. publish npm with GitHub OIDC, or verify that the exact version already
|
|
224
|
+
exists during a retry;
|
|
225
|
+
4. upload the MCPB asset only when it is absent; on a retry, download it and
|
|
226
|
+
compare bytes with the fresh build, failing on any difference;
|
|
227
|
+
5. query the MCP Registry; publish only a missing version, otherwise compare
|
|
228
|
+
the returned server record exactly with `server.json`.
|
|
229
|
+
|
|
230
|
+
### Proof after publication
|
|
231
|
+
|
|
232
|
+
```bash
|
|
233
|
+
npm view hermes-action-bridge@<version> version
|
|
234
|
+
gh release view "v<version>" --json tagName,isDraft,isPrerelease,assets,url
|
|
235
|
+
registry_name='io.github.TheBlueHouse75/hermes-action-bridge'
|
|
236
|
+
encoded_name="$(node -p 'encodeURIComponent(process.argv[1])' "$registry_name")"
|
|
237
|
+
curl --fail --silent --show-error \
|
|
238
|
+
"https://registry.modelcontextprotocol.io/v0.1/servers/$encoded_name/versions/<version>"
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
Expected proof: npm returns `<version>`, the GitHub Release is published with
|
|
242
|
+
one `hermes-action-bridge-<version>.mcpb` asset, and the registry endpoint
|
|
243
|
+
returns the matching version. Save the workflow URL and the Release URL.
|
|
244
|
+
|
|
245
|
+
### Re-run and rollback
|
|
246
|
+
|
|
247
|
+
For a transient workflow failure, re-run the same GitHub Release workflow
|
|
248
|
+
while the release branch remains unmerged. The npm retry rebuilds the tarball
|
|
249
|
+
from the release tag and compares its SHA-512 with npm `dist.integrity`; the
|
|
250
|
+
MCPB retry compares the rebuilt archive byte-for-byte with the existing release
|
|
251
|
+
asset; the MCP Registry retry compares its existing metadata with `server.json`.
|
|
252
|
+
If any comparison fails, stop: the existing immutable publication differs from
|
|
253
|
+
this source and must not be overwritten.
|
|
254
|
+
|
|
255
|
+
There is no safe rollback by reusing `<version>`. If publication fails before
|
|
256
|
+
promotion to `main`, prepare a new corrective version on a new release branch.
|
|
257
|
+
If it fails after promotion, prepare that corrective version from `main`. A
|
|
258
|
+
GitHub Release may be marked as a draft or removed only according to the
|
|
259
|
+
project’s release authority; never delete npm or MCP Registry history as a
|
|
260
|
+
substitute for a corrective version.
|
|
261
|
+
|
|
262
|
+
## 3. Promote the proven release to main
|
|
263
|
+
|
|
264
|
+
### Prerequisites
|
|
265
|
+
|
|
266
|
+
- The GitHub Release workflow is successful and its npm, MCPB, and MCP Registry
|
|
267
|
+
proofs match `<version>`.
|
|
268
|
+
- `origin/release/<version>` is exactly the tagged release commit, not merely a
|
|
269
|
+
descendant of it.
|
|
270
|
+
- The release authority knows whether `main` requires a pull request or
|
|
271
|
+
explicitly permits a direct fast-forward.
|
|
272
|
+
|
|
273
|
+
### Protected-main promotion (default)
|
|
274
|
+
|
|
275
|
+
Open a pull request from the release branch only after the automated proof is
|
|
276
|
+
complete. First lock the branch head to the immutable tag SHA. Follow every
|
|
277
|
+
required review and status check, then merge with a merge commit so the tagged
|
|
278
|
+
release commit remains an ancestor of `main`. Do not use squash or rebase
|
|
279
|
+
merging for this promotion: either creates different commit ancestry and cannot
|
|
280
|
+
prove that the released commit itself reached `main`.
|
|
281
|
+
|
|
282
|
+
```bash
|
|
283
|
+
release_sha="$(git rev-parse "v<version>^{commit}")"
|
|
284
|
+
git fetch origin release/<version>
|
|
285
|
+
test "$(git rev-parse "origin/release/<version>")" = "$release_sha"
|
|
286
|
+
gh pr create --base main --head release/<version> \
|
|
287
|
+
--title "chore(release): <version>" \
|
|
288
|
+
--body "Promotes the proven v<version> release after npm, MCPB, and MCP Registry verification."
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
Before merging the approved PR, repeat the equality check. Use GitHub CLI’s
|
|
292
|
+
head-SHA guard so the merge fails if the PR head changed after verification:
|
|
293
|
+
|
|
294
|
+
```bash
|
|
295
|
+
pr_number="<approved-pr-number>"
|
|
296
|
+
git fetch origin release/<version>
|
|
297
|
+
test "$(git rev-parse "origin/release/<version>")" = "$release_sha"
|
|
298
|
+
gh pr merge "$pr_number" --merge --match-head-commit "$release_sha"
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
After the merge, fetch `main` and prove it contains the release tag before
|
|
302
|
+
treating Git-backed channels as published:
|
|
303
|
+
|
|
304
|
+
```bash
|
|
305
|
+
git fetch origin main
|
|
306
|
+
git merge-base --is-ancestor "v<version>" origin/main
|
|
307
|
+
git show "origin/main:plugins/hermes-action/.mcp.json"
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
### Fast-forward promotion (only when authorized)
|
|
311
|
+
|
|
312
|
+
Use this path only if branch protection permits direct pushes and `main` has
|
|
313
|
+
not advanced beyond the release branch’s base. Do not force-push.
|
|
314
|
+
|
|
315
|
+
```bash
|
|
316
|
+
git switch main
|
|
317
|
+
git pull --ff-only origin main
|
|
318
|
+
git merge --ff-only "v<version>"
|
|
319
|
+
git push origin main
|
|
320
|
+
git fetch origin main
|
|
321
|
+
git merge-base --is-ancestor "v<version>" origin/main
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
If either promotion path cannot include the tagged commit, stop and resolve the
|
|
325
|
+
branch divergence or protection requirement. If protected `main` permits only
|
|
326
|
+
squash or rebase merging, obtain an approved merge-commit exception or an
|
|
327
|
+
explicitly authorized fast-forward; do not substitute a rewritten commit.
|
|
328
|
+
Never copy only the marketplace metadata onto `main`: it must arrive with the
|
|
329
|
+
proven release commit.
|
|
330
|
+
|
|
331
|
+
### Re-run and rollback
|
|
332
|
+
|
|
333
|
+
If npm, MCPB, or MCP Registry proof fails, leave `release/<version>` out of
|
|
334
|
+
`main` and repair through a new version. If the promotion itself is blocked,
|
|
335
|
+
the immutable artifacts remain valid but the Git-backed channels are pending;
|
|
336
|
+
record that state rather than bypassing protection. After promotion, a bad pin
|
|
337
|
+
requires a new corrective release branch and version.
|
|
338
|
+
|
|
339
|
+
If `origin/release/<version>` differs from `v<version>^{commit}` at either
|
|
340
|
+
check, do not create or merge the PR. The branch is no longer the proven
|
|
341
|
+
release input; preserve it for diagnosis and prepare a new versioned release
|
|
342
|
+
branch instead of resetting, force-pushing, or promoting its newer head.
|
|
343
|
+
|
|
344
|
+
## 4. Claude Code marketplace and plugin
|
|
345
|
+
|
|
346
|
+
### Prerequisites
|
|
347
|
+
|
|
348
|
+
- The proven release commit containing `.claude-plugin/marketplace.json`,
|
|
349
|
+
`plugins/hermes-action/.claude-plugin/plugin.json`, the plugin Skill, and
|
|
350
|
+
`plugins/hermes-action/.mcp.json` is on `main` after the promotion above.
|
|
351
|
+
- The matching npm package is published: the plugin MCP configuration pins
|
|
352
|
+
`hermes-action-bridge@<version>` and resolves it at startup with `npx`.
|
|
353
|
+
- The verifier has Claude Code installed and an authenticated Claude session.
|
|
354
|
+
|
|
355
|
+
### Publication and proof
|
|
356
|
+
|
|
357
|
+
This surface is Git-backed: merging the manifest changes to `main` is the
|
|
358
|
+
publication action. It has no separate release API or secret in this
|
|
359
|
+
repository. Verify it from a disposable or test Claude Code profile with the
|
|
360
|
+
documented consumer commands:
|
|
361
|
+
|
|
362
|
+
```bash
|
|
363
|
+
claude plugin marketplace add TheBlueHouse75/hermes-action-bridge
|
|
364
|
+
claude plugin install hermes-action@hermes-action-bridge
|
|
365
|
+
claude plugin list
|
|
366
|
+
```
|
|
367
|
+
|
|
368
|
+
Then start Claude Code and confirm that the Hermes Action plugin is present,
|
|
369
|
+
the `hermes-action-bridge` Skill is discoverable, and the `hermes_*` MCP tools
|
|
370
|
+
are available. Use `hermes_status` as a token-free smoke test before asking
|
|
371
|
+
Hermes to perform work.
|
|
372
|
+
|
|
373
|
+
### Re-run and rollback
|
|
374
|
+
|
|
375
|
+
Before npm proof, correct metadata only on `release/<version>` and rerun
|
|
376
|
+
`npm run check`; do not merge it into `main`. After a promoted plugin points to
|
|
377
|
+
a bad npm version, publish a corrective package version on a new release branch
|
|
378
|
+
and promote it only after proof. Do not retag or mutate the old version. A
|
|
379
|
+
client that already installed the old plugin keeps its prior version until it
|
|
380
|
+
updates or reinstalls.
|
|
381
|
+
|
|
382
|
+
Related files: `.claude-plugin/marketplace.json`,
|
|
383
|
+
`plugins/hermes-action/.claude-plugin/plugin.json`,
|
|
384
|
+
`plugins/hermes-action/.mcp.json`, and
|
|
385
|
+
`tests/claude-plugin-distribution.test.ts`.
|
|
386
|
+
|
|
387
|
+
## 5. Agent Skills and skills.sh
|
|
388
|
+
|
|
389
|
+
### Prerequisites
|
|
390
|
+
|
|
391
|
+
- `skills/hermes-action-bridge/SKILL.md` is byte-identical to the installer
|
|
392
|
+
template and plugin Skill; `npm run check` verifies this.
|
|
393
|
+
- The proven release commit is promoted to public `main`.
|
|
394
|
+
|
|
395
|
+
### Publication and proof
|
|
396
|
+
|
|
397
|
+
The repository is the distribution source. There is no repository-owned
|
|
398
|
+
skills.sh token or manual upload step. Confirm the consumer path after the
|
|
399
|
+
release commit is public:
|
|
400
|
+
|
|
401
|
+
```bash
|
|
402
|
+
npx skills add TheBlueHouse75/hermes-action-bridge --skill hermes-action-bridge
|
|
403
|
+
```
|
|
404
|
+
|
|
405
|
+
The command must install the canonical Skill without requesting an MCP
|
|
406
|
+
configuration. This is expected: Agent Skills provide instructions only. For
|
|
407
|
+
MCP tools, validate the npm installer, Claude Code plugin, or MCPB path
|
|
408
|
+
separately.
|
|
409
|
+
|
|
410
|
+
For a public listing check, search skills.sh for `Hermes Action Bridge` and
|
|
411
|
+
open the result that points to `TheBlueHouse75/hermes-action-bridge`. The
|
|
412
|
+
listing is directory-managed, so do not claim a synchronous indexing SLA.
|
|
413
|
+
|
|
414
|
+
### Re-run and rollback
|
|
415
|
+
|
|
416
|
+
If the Skill content is incorrect, correct it in the repository and verify
|
|
417
|
+
`npm run check`; clients must update or reinstall to receive the new content.
|
|
418
|
+
Do not rewrite a published Git tag to alter the Skill. If indexing has not
|
|
419
|
+
appeared, recheck the public repository and retry the install command before
|
|
420
|
+
contacting the directory operator.
|
|
421
|
+
|
|
422
|
+
Related files: `skills/hermes-action-bridge/SKILL.md`,
|
|
423
|
+
`src/install/templates.ts`, and `tests/examples.test.ts`. See the
|
|
424
|
+
[Skills CLI documentation](https://www.skills.sh/docs/cli) for client usage.
|
|
425
|
+
|
|
426
|
+
## 6. Smithery MCPB publication
|
|
427
|
+
|
|
428
|
+
### Prerequisites
|
|
429
|
+
|
|
430
|
+
- The GitHub Release MCPB asset has passed the archive inspection above.
|
|
431
|
+
- Node.js 20 or newer and the Smithery CLI are available locally.
|
|
432
|
+
- The maintainer is authorized for the target Smithery namespace.
|
|
433
|
+
|
|
434
|
+
### Commands
|
|
435
|
+
|
|
436
|
+
Use the exact inspected artifact from the GitHub Release (or regenerate it
|
|
437
|
+
from the identical clean tag), authenticate interactively, and publish it:
|
|
438
|
+
|
|
439
|
+
```bash
|
|
440
|
+
npm install -g @smithery/cli@latest
|
|
441
|
+
smithery auth login
|
|
442
|
+
smithery mcp publish release/hermes-action-bridge-<version>.mcpb -n <namespace>/hermes-action-bridge
|
|
443
|
+
```
|
|
444
|
+
|
|
445
|
+
This channel is manual by design. The CLI login is interactive and no
|
|
446
|
+
Smithery credential belongs in CI. See the [Smithery context and official
|
|
447
|
+
sources](SMITHERY.md) appendix for channel-specific background.
|
|
448
|
+
|
|
449
|
+
### Proof, re-run, and rollback
|
|
450
|
+
|
|
451
|
+
Complete the Smithery flow and verify the resulting server page installs the
|
|
452
|
+
local MCPB artifact. Record that page URL in the GitHub Release notes. If
|
|
453
|
+
publication fails before acceptance, fix the local account/namespace state and
|
|
454
|
+
retry the exact artifact. If an accepted artifact is faulty, publish a new
|
|
455
|
+
corrective MCPB version; do not upload a different archive under the same
|
|
456
|
+
version.
|
|
457
|
+
|
|
458
|
+
## 7. Glama listing and ownership claim
|
|
459
|
+
|
|
460
|
+
### Prerequisites
|
|
461
|
+
|
|
462
|
+
- The GitHub Release, npm package, and MCP Registry record for `<version>` are
|
|
463
|
+
already public, so the listing has stable metadata to inspect.
|
|
464
|
+
- A maintainer can authenticate to GitHub in the browser used for Glama OAuth.
|
|
465
|
+
|
|
466
|
+
### Publication and proof
|
|
467
|
+
|
|
468
|
+
Glama is not automated by this repository. Open the listing and complete its
|
|
469
|
+
**Claim** flow with the authorized GitHub account:
|
|
470
|
+
|
|
471
|
+
```text
|
|
472
|
+
https://glama.ai/mcp/servers/TheBlueHouse75/hermes-action-bridge
|
|
473
|
+
```
|
|
474
|
+
|
|
475
|
+
There is no repository-owned CLI command or secret for this action. Do not
|
|
476
|
+
invent a `glama publish` command or add OAuth material to CI. After the claim,
|
|
477
|
+
wait for Glama to display the owner and score, then verify the public listing
|
|
478
|
+
shows the current server metadata. If the directory PR is still open, inspect
|
|
479
|
+
it before editing:
|
|
480
|
+
|
|
481
|
+
```bash
|
|
482
|
+
gh pr view 8988 --repo punkpeye/awesome-mcp-servers
|
|
483
|
+
```
|
|
484
|
+
|
|
485
|
+
Only after the claim and score are visible should the maintainer add the exact
|
|
486
|
+
generated score badge or update the external directory entry. Do not guess a
|
|
487
|
+
badge URL.
|
|
488
|
+
|
|
489
|
+
### Re-run and rollback
|
|
490
|
+
|
|
491
|
+
If OAuth is not authenticated, stop at the browser login boundary and retry
|
|
492
|
+
the claim after login. If the listing’s metadata or score is stale, wait for
|
|
493
|
+
the directory refresh or contact Glama support rather than changing package
|
|
494
|
+
metadata solely to force a refresh. A bad external listing is corrected by the
|
|
495
|
+
directory owner’s normal update path; the immutable package release still
|
|
496
|
+
requires a new corrective version if its own metadata is wrong.
|
|
497
|
+
|
|
498
|
+
## Final sign-off
|
|
499
|
+
|
|
500
|
+
Before declaring the release complete, retain these proofs:
|
|
501
|
+
|
|
502
|
+
- release commit SHA, tag, GitHub Release URL, and successful workflow URL;
|
|
503
|
+
- `npm view hermes-action-bridge@<version> version` output;
|
|
504
|
+
- MCP Registry endpoint response for the exact version;
|
|
505
|
+
- inspected MCPB archive or Release asset URL;
|
|
506
|
+
- merged promotion PR URL or authorized fast-forward proof that `main`
|
|
507
|
+
contains `v<version>`;
|
|
508
|
+
- the recorded `v<version>^{commit}` SHA and the matching PR head SHA, when a
|
|
509
|
+
protected-main PR was used;
|
|
510
|
+
- Claude Code plugin and Agent Skills smoke-test result;
|
|
511
|
+
- Smithery server page URL, if published for this version; and
|
|
512
|
+
- Glama claim/listing URL and score status, if applicable.
|
|
513
|
+
|
|
514
|
+
If any proof is missing, label the channel as pending rather than treating the
|
|
515
|
+
whole release as complete.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "hermes-action-bridge",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.6.2",
|
|
4
4
|
"description": "Configurable bridge for external agents to delegate actions to Hermes Agent via CLI or MCP.",
|
|
5
5
|
"mcpName": "io.github.TheBlueHouse75/hermes-action-bridge",
|
|
6
6
|
"repository": {
|
|
@@ -26,6 +26,8 @@
|
|
|
26
26
|
],
|
|
27
27
|
"scripts": {
|
|
28
28
|
"build": "tsc -p tsconfig.json",
|
|
29
|
+
"build:mcpb": "node scripts/build-mcpb.mjs",
|
|
30
|
+
"inspect:mcpb": "node scripts/inspect-mcpb.mjs",
|
|
29
31
|
"postbuild": "node -e \"require('node:fs').chmodSync('dist/cli.js', 0o755)\"",
|
|
30
32
|
"dev": "tsx src/cli.ts",
|
|
31
33
|
"pretest": "npm run build",
|
|
@@ -55,8 +57,12 @@
|
|
|
55
57
|
},
|
|
56
58
|
"devDependencies": {
|
|
57
59
|
"@types/node": "^25.0.3",
|
|
60
|
+
"@types/yauzl": "^2.10.3",
|
|
61
|
+
"@types/yazl": "^2.4.5",
|
|
58
62
|
"tsx": "^4.22.4",
|
|
59
63
|
"typescript": "^6.0.3",
|
|
60
|
-
"vitest": "^4.1.9"
|
|
64
|
+
"vitest": "^4.1.9",
|
|
65
|
+
"yauzl": "^3.2.0",
|
|
66
|
+
"yazl": "^3.3.1"
|
|
61
67
|
}
|
|
62
68
|
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "hermes-action",
|
|
3
|
+
"version": "0.6.2",
|
|
4
|
+
"description": "Delegate real-world actions to Hermes Agent through Hermes Action Bridge.",
|
|
5
|
+
"author": {
|
|
6
|
+
"name": "Cyril Guilleminot",
|
|
7
|
+
"url": "https://github.com/TheBlueHouse75"
|
|
8
|
+
},
|
|
9
|
+
"repository": "https://github.com/TheBlueHouse75/hermes-action-bridge",
|
|
10
|
+
"license": "MIT",
|
|
11
|
+
"keywords": ["hermes-agent", "mcp", "claude-code", "automation", "delegation"]
|
|
12
|
+
}
|
|
Binary file
|