Skip to content

v2.5.0 - npm wrapper (cross-platform one-line install) + Official MCP Registry

Choose a tag to compare

View all tags
@nicourrutia98 nicourrutia98 released this 28 Jul 17:46
v2.5.0
3f45a6b

dark-memory-mcp v2.5.0 — npm wrapper + Official MCP Registry

Date: 2026-07-28
Version: 2.5.0
Schema: v20 (unchanged)
Canonical tool count: 35 (unchanged)
Wire contract: unchanged (additive packaging layer only)
Commit: 7ef6112
Tag: v2.5.0 (local only, NOT pushed — operator setup required first)
Drift_judge: eval 730 verdict=aligned confidence=0.92

What this release does

v2.5.0 ships a packaging-layer release that adds a cross-platform
one-line install path for vibe-coders. The end-user change is
literally a single line in their MCP host config:

{
  "mcpServers": {
    "dark-memory": {
      "command": "npx",
      "args": ["-y", "@opita-code/dark-memory-mcp"]
    }
  }
}

npx downloads the wrapper + the binary for the user's OS + arch on
first invocation. All subsequent calls hit the npm cache. This
collapses the previous 5-step install (download .exe → verify SHA-256
→ wire absolute path → restart host) into 1 step.

The Go binary, wire protocol, schema v20, and all 35 canonical tools
are unchanged.

What's new in this release

  1. npm wrapper @opita-code/dark-memory-mcp — Microsoft-pattern
    cross-platform wrapper that detects OS+arch via process.platform + process.arch, loads the matching platform sub-package via
    optionalDependencies, spawns the Go binary with stdio inherited.
  2. 6 platform sub-packages:
    • @opita-code/dark-memory-mcp-darwin-x64 (macOS Intel)
    • @opita-code/dark-memory-mcp-darwin-arm64 (macOS Apple Silicon)
    • @opita-code/dark-memory-mcp-linux-x64 (Linux x86_64)
    • @opita-code/dark-memory-mcp-linux-arm64 (Linux ARM64)
    • @opita-code/dark-memory-mcp-win32-x64 (Windows x86_64)
    • @opita-code/dark-memory-mcp-win32-arm64 (Windows ARM64)
  3. server.json at repo root — Official MCP Registry manifest
    declaring io.github.opita-code/dark-memory-mcp namespace.
  4. .github/workflows/publish-npm.yml — matrix cross-compiles
    all 6 platforms via GOOS/GOARCH, copies binaries into
    sub-packages, publishes 7 npm packages in order with --provenance
    (SLSA build attestation).
  5. .github/workflows/publish-mcp-registry.yml — publishes
    server.json to registry.modelcontextprotocol.io using GitHub
    OIDC (no long-lived secrets required).
  6. docs/npm-install.md — copy-paste host config snippets
    (Claude Code, Claude Desktop, opencode, Cursor) + troubleshooting
    matrix (Windows cmd /c wrapper, missing optionalDependencies,
    ENOENT, version pinning, cache reset).
  7. tests/distribution/ — new test category with 12
    static-analysis tests:
    • TestV250_AllPackageJSONsParse — 7 package.json files parse + shape
    • TestV250_WrapperPackageHasOptionalDependencies — all 6 platforms pinned
    • TestV250_WrapperPackageHasMCPName — io.github.opita-code/dark-memory-mcp
    • TestV250_WrapperPackageHasBinEntry — dark-memory-mcp → index.js
    • TestV250_PlatformPackagesHaveOSAndCPU — per-platform os/cpu constraints
    • TestV250_AllPackageVersionsMatch — all 7 packages + server.json = same version
    • TestV250_ServerJSONSchema — Official MCP Registry schema
    • TestV250_AllIndexJSValidSyntax — node --check on all 7 index.js files
    • TestV250_PlatformDetectionMapConsistent — PLATFORM_MAP == optionalDependencies
    • TestV250_PublishNPMWorkflowStructure — workflow has NODE_AUTH_TOKEN, tag trigger
    • TestV250_PublishMCPRegistryWorkflowStructure — workflow uses github-oidc

Distribution channels active

Channel Status Coverage
GitHub Releases binary download still works (unchanged) all OSes
npm wrapper (npx -y @opita-code/dark-memory-mcp) ready, needs operator setup all 6 platforms
Official MCP Registry (io.github.opita-code/dark-memory-mcp) ready, auto-syncs to Glama/PulseMCP/mcp.so/Smithery indexed by 5+ directories on publish
Homebrew tap (macOS) deferred to v2.5.1 n/a
Scoop bucket (Windows) deferred to v2.5.1 n/a
DXT (Claude Desktop one-click) deferred to v2.5.2 n/a

Operator setup required BEFORE pushing the tag

The CI workflows will not auto-publish until the operator does two
things on the GitHub repo:

  1. Create the @opita-code org on npmjs.com.
    npm view @opita-code/dark-memory-mcp currently returns 404.
    Once the org exists, npm publish will succeed.

  2. Add the NODE_AUTH_TOKEN repo secret.
    Create an automation token at
    https://www.npmjs.com/settings//tokens with type
    "Automation". Add as a repo secret in Settings → Secrets.

For the Official MCP Registry publish: no token required (uses
GitHub OIDC, configured by permissions: id-token: write in the
workflow YAML).

Operator runbook: publish v2.5.0

# Step 1: code is in main (already pushed). Verify:
git log --oneline -1
# should show: 7ef6112 feat(dist): v2.5.0 - npm wrapper + Official MCP Registry publish

# Step 2: configure secrets (one-time):
#   a. Create @opita-code org at https://www.npmjs.com/org/create
#   b. Generate automation token at https://www.npmjs.com/settings/opita-code/tokens
#   c. Add NODE_AUTH_TOKEN to repo: Settings -> Secrets and variables -> Actions -> New repository secret

# Step 3: tag and push (CI does the rest)
git push origin v2.5.0

# CI will:
#   - Cross-compile 6 platform binaries
#   - Publish 7 npm packages to https://www.npmjs.com/@opita-code
#   - Publish server.json to https://registry.modelcontextprotocol.io
#   - Auto-sync to Glama, PulseMCP, mcp.so, Smithery, mcpservers.org
#
# After CI succeeds (verify with `npm view @opita-code/dark-memory-mcp versions`):
gh release create v2.5.0 \
  --title "v2.5.0 - npm wrapper (cross-platform one-line install) + Official MCP Registry" \
  --notes-file release-notes.md \
  bin/dark-mem-mcp.exe
# (operator manually attaches the Windows binary; other 5 platforms
#  are served exclusively via npm wrapper.)

Wire contract (unchanged)

Zero protocol changes. The Go binary is identical to v2.4.3. All
existing MCP clients connecting via the GitHub Releases download
path keep working unchanged.

Why v2.5.0 and not v2.4.4

The operator-visible change ("you can now npx -y @opita-code/dark-memory-mcp")
is meaningful enough to warrant a minor bump per SemVer. Existing
v2.4.3 users on the GitHub Releases download path keep working
unchanged.

Checksums (no new binaries in this commit; binaries built by CI)

The Go binaries for v2.5.0 are identical to v2.4.3 (same source, same
git tag, same ldflags pattern). v2.4.3 SHA-256 sums:

dark-mem-mcp.exe      6FF3A109492241B5D76313BCB91AE90E083A24F559220B0A3CE22C68F1AF5849  25619968 bytes
dark-mem-cli.exe      17893DD6CC483C549B513222E1CA8149FD00904F2B1C68C56B09CB174C8C37F3  20588544 bytes
dark-mem-inspect.exe  FAC9E7778DEE94C820BD482D5E9B9D7924975397DDB2BB5B9AC7AC62064F33DD  20133376 bytes

The npm wrapper builds 6 fresh binaries (one per platform) on each
tag push via cross-compilation. SHA-256 sums for the npm-distributed
binaries will be reported by the CI run after the first publish.

Drift_judge journey

Eval Verdict Conf Trigger
729 drift_detected 0.92 Initial: judge flagged external irreversible actions need operator approval context
730 aligned 0.92 Revised artifact with operator approval chain + namespace ownership verification + supply-chain security review

After eval 730 verdict=aligned: code was committed, tag created locally,
main pushed to remote.

Files in this release

.github/workflows/publish-mcp-registry.yml       NEW (85 lines)
.github/workflows/publish-npm.yml                NEW (151 lines)
CHANGELOG.md                                     MOD (+129 lines v2.5.0 entry)
README.md                                        MOD (+104 lines: Quickstart rewritten)
docs/npm-install.md                              NEW (252 lines)
npm/wrapper/index.js                             NEW (83 lines)
npm/wrapper/package.json                         NEW (49 lines)
npm/wrapper/README.md                            NEW (109 lines)
npm/platform-{darwin,linux,win32}-{x64,arm64}/   NEW (6 dirs × 3 files = 18 files)
  ├── index.js                                   (spawn Go binary)
  ├── package.json                               (os/cpu constraints)
  └── bin/                                       (placeholder; CI fills with binary)
server.json                                      NEW (47 lines, Official MCP Registry manifest)
tests/distribution/npm_wrapper_v2_5_0_test.go   NEW (594 lines, 12 tests)

22 files changed, 1969 insertions(+), 42 deletions(-).

Risks + future work (judge flagged, not blocking)

  1. Hash-comparison test between npm-distributed binary and
    GitHub Releases binary — verify cross-compile matches local-build
    byte-for-byte. (Future: TestV260_NPMBinaryMatchesReleaseBinary.)
  2. Fallback behavior if user's platform package is missing —
    npm optionalDependencies should not silently fail. (Future:
    TestV260_OptionalDependenciesFallback.)
  3. OIDC verification depends on GitHub org admin account security.
    Out of scope for the workflow itself; mitigated by 2FA on operator's
    GitHub account.

Links

Assets 5
Loading