@mnemoverse/mcp-memory-server 0.3.0 → 0.3.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/.github/workflows/release.yml +138 -0
- package/.github/workflows/verify-configs.yml +55 -0
- package/CONTRIBUTING.md +199 -0
- package/README.md +50 -21
- package/dist/index.js +82 -40
- package/dist/index.js.map +1 -1
- package/docs/configs/claude-code-cli.sh +1 -1
- package/docs/configs/claude-desktop.json +1 -1
- package/docs/configs/cursor-deep-link.txt +1 -1
- package/docs/configs/cursor.json +1 -1
- package/docs/configs/vscode-deep-link.txt +1 -1
- package/docs/configs/vscode.json +1 -1
- package/docs/configs/windsurf.json +1 -1
- package/docs/snippets/claude-code.md +9 -0
- package/docs/snippets/claude-desktop.md +20 -0
- package/docs/snippets/cursor.md +20 -0
- package/docs/snippets/vscode.md +21 -0
- package/docs/snippets/windsurf.md +20 -0
- package/package.json +2 -1
- package/scripts/generate-configs.mjs +196 -7
- package/scripts/install-hooks.mjs +76 -0
- package/server.json +10 -9
- package/smithery.yaml +1 -1
- package/src/configs/source.json +2 -2
- package/src/index.ts +114 -72
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
name: release
|
|
2
|
+
|
|
3
|
+
# Automated release pipeline for @mnemoverse/mcp-memory-server.
|
|
4
|
+
#
|
|
5
|
+
# Trigger: push a semver tag `vX.Y.Z` to main (e.g. `git tag v0.3.2 && git push origin v0.3.2`).
|
|
6
|
+
#
|
|
7
|
+
# What this workflow does, in order:
|
|
8
|
+
# 1. Checks that the tag's version matches package.json#version (catches "forgot to bump" mistakes).
|
|
9
|
+
# 2. npm ci + npm run build (prebuild regenerates every generated artifact from source.json).
|
|
10
|
+
# 3. npm run verify:configs — drift check, fails fast if anything is out of sync with source.json.
|
|
11
|
+
# 4. npm publish — uses a repo-scoped automation token stored in the NPM_TOKEN secret.
|
|
12
|
+
# 5. Installs mcp-publisher CLI (Linux amd64 bottle from the releases bucket).
|
|
13
|
+
# 6. mcp-publisher login github-oidc — uses GitHub Actions' OIDC token, NO stored PAT.
|
|
14
|
+
# 7. mcp-publisher publish — uploads the freshly-generated server.json to registry.modelcontextprotocol.io.
|
|
15
|
+
# 8. gh release create — posts a GitHub release with auto-generated notes.
|
|
16
|
+
#
|
|
17
|
+
# Why OIDC instead of a PAT:
|
|
18
|
+
# The GitHub OIDC provider issues a short-lived JWT that the MCP Registry trusts on the basis
|
|
19
|
+
# of the repo's owner (mnemoverse) and branch/tag claim. No long-lived secret sits in the repo.
|
|
20
|
+
# Prereq: `permissions: id-token: write` on the job, and the authenticating user's org
|
|
21
|
+
# membership (izgorodin in mnemoverse) must be public — already done.
|
|
22
|
+
#
|
|
23
|
+
# Prerequisite secrets you must add at repo Settings > Secrets and variables > Actions:
|
|
24
|
+
# - NPM_TOKEN — npm automation token from npmjs.com/settings/{org}/tokens/granular-access-tokens/new
|
|
25
|
+
# (select "Automation", grant publish access to @mnemoverse/mcp-memory-server).
|
|
26
|
+
#
|
|
27
|
+
# To release:
|
|
28
|
+
# 1. Bump version in package.json + src/index.ts on main (keep them in sync).
|
|
29
|
+
# 2. `npm run generate:configs` to propagate the new version to server.json.
|
|
30
|
+
# 3. Commit, push to main (through PR, drift CI passes).
|
|
31
|
+
# 4. `git tag v$(node -p "require('./package.json').version")`.
|
|
32
|
+
# 5. `git push origin v0.x.y`.
|
|
33
|
+
# The workflow does the rest.
|
|
34
|
+
|
|
35
|
+
on:
|
|
36
|
+
push:
|
|
37
|
+
tags:
|
|
38
|
+
- "v*"
|
|
39
|
+
workflow_dispatch:
|
|
40
|
+
inputs:
|
|
41
|
+
tag:
|
|
42
|
+
description: "Tag to release (e.g. v0.3.2). Must already exist."
|
|
43
|
+
required: true
|
|
44
|
+
|
|
45
|
+
jobs:
|
|
46
|
+
release:
|
|
47
|
+
runs-on: ubuntu-latest
|
|
48
|
+
permissions:
|
|
49
|
+
# contents:write — needed to create the GitHub release.
|
|
50
|
+
# id-token:write — required by `mcp-publisher login github-oidc`.
|
|
51
|
+
contents: write
|
|
52
|
+
id-token: write
|
|
53
|
+
|
|
54
|
+
steps:
|
|
55
|
+
- name: Checkout tag
|
|
56
|
+
uses: actions/checkout@v4
|
|
57
|
+
with:
|
|
58
|
+
ref: ${{ github.event.inputs.tag || github.ref }}
|
|
59
|
+
fetch-depth: 0
|
|
60
|
+
|
|
61
|
+
- name: Setup Node
|
|
62
|
+
uses: actions/setup-node@v4
|
|
63
|
+
with:
|
|
64
|
+
node-version: "20"
|
|
65
|
+
registry-url: "https://registry.npmjs.org"
|
|
66
|
+
|
|
67
|
+
- name: Verify tag matches package.json#version
|
|
68
|
+
run: |
|
|
69
|
+
set -euo pipefail
|
|
70
|
+
TAG="${{ github.event.inputs.tag || github.ref_name }}"
|
|
71
|
+
TAG_VERSION="${TAG#v}"
|
|
72
|
+
PKG_VERSION="$(node -p "require('./package.json').version")"
|
|
73
|
+
echo "tag: $TAG"
|
|
74
|
+
echo "tag version: $TAG_VERSION"
|
|
75
|
+
echo "pkg version: $PKG_VERSION"
|
|
76
|
+
if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
|
|
77
|
+
echo "::error::Tag $TAG (version $TAG_VERSION) does not match package.json version $PKG_VERSION"
|
|
78
|
+
exit 1
|
|
79
|
+
fi
|
|
80
|
+
|
|
81
|
+
- name: Install dependencies
|
|
82
|
+
run: npm ci
|
|
83
|
+
|
|
84
|
+
- name: Build (runs generate:configs via prebuild)
|
|
85
|
+
run: npm run build
|
|
86
|
+
|
|
87
|
+
- name: Verify no drift between source.json and generated artifacts
|
|
88
|
+
run: npm run verify:configs
|
|
89
|
+
|
|
90
|
+
- name: Publish to npm
|
|
91
|
+
run: npm publish --access public
|
|
92
|
+
env:
|
|
93
|
+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
|
|
94
|
+
|
|
95
|
+
- name: Install mcp-publisher CLI
|
|
96
|
+
run: |
|
|
97
|
+
set -euo pipefail
|
|
98
|
+
curl -sSL \
|
|
99
|
+
"https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_linux_amd64.tar.gz" \
|
|
100
|
+
| tar xz mcp-publisher
|
|
101
|
+
./mcp-publisher --help
|
|
102
|
+
|
|
103
|
+
- name: Authenticate with MCP Registry via GitHub OIDC
|
|
104
|
+
run: ./mcp-publisher login github-oidc
|
|
105
|
+
|
|
106
|
+
- name: Publish to Official MCP Registry
|
|
107
|
+
run: ./mcp-publisher publish
|
|
108
|
+
|
|
109
|
+
- name: Verify the registry entry shows the new version
|
|
110
|
+
run: |
|
|
111
|
+
set -euo pipefail
|
|
112
|
+
TAG="${{ github.event.inputs.tag || github.ref_name }}"
|
|
113
|
+
VERSION="${TAG#v}"
|
|
114
|
+
echo "Waiting a few seconds for the registry to propagate..."
|
|
115
|
+
sleep 3
|
|
116
|
+
RESULT="$(curl -sS "https://registry.modelcontextprotocol.io/v0.1/servers/io.github.mnemoverse%2Fmcp-memory-server/versions/$VERSION")"
|
|
117
|
+
echo "$RESULT" | python3 -m json.tool
|
|
118
|
+
echo "$RESULT" | python3 -c "
|
|
119
|
+
import sys, json
|
|
120
|
+
d = json.load(sys.stdin)
|
|
121
|
+
srv = d['server']
|
|
122
|
+
assert srv['version'] == '$VERSION', f\"registry version {srv['version']} != $VERSION\"
|
|
123
|
+
print(f'✓ Registry shows {srv[\"name\"]}@{srv[\"version\"]}')
|
|
124
|
+
"
|
|
125
|
+
|
|
126
|
+
- name: Create GitHub release
|
|
127
|
+
uses: softprops/action-gh-release@v2
|
|
128
|
+
with:
|
|
129
|
+
tag_name: ${{ github.event.inputs.tag || github.ref_name }}
|
|
130
|
+
name: ${{ github.event.inputs.tag || github.ref_name }}
|
|
131
|
+
generate_release_notes: true
|
|
132
|
+
body: |
|
|
133
|
+
Published via automated release pipeline (`.github/workflows/release.yml`).
|
|
134
|
+
|
|
135
|
+
- npm: https://www.npmjs.com/package/@mnemoverse/mcp-memory-server
|
|
136
|
+
- MCP Registry: https://registry.modelcontextprotocol.io/v0.1/servers?search=mnemoverse
|
|
137
|
+
|
|
138
|
+
Full changelog below.
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
name: verify-configs
|
|
2
|
+
|
|
3
|
+
# Mechanical drift detection for the single-source-of-truth distribution
|
|
4
|
+
# config pipeline. See CONTRIBUTING.md for the design.
|
|
5
|
+
#
|
|
6
|
+
# This workflow MUST pass before any PR can merge into main. It runs the
|
|
7
|
+
# generator in --check mode, which:
|
|
8
|
+
# 1. Re-emits all 14 generated artifacts from src/configs/source.json
|
|
9
|
+
# 2. Re-rewrites the README.md install block from the same source
|
|
10
|
+
# 3. Compares each result to what is committed
|
|
11
|
+
# 4. Exits 1 if anything differs
|
|
12
|
+
#
|
|
13
|
+
# If you see this job fail in your PR, run `npm run generate:configs` locally
|
|
14
|
+
# and commit the regenerated files. Do NOT bypass — the whole point is that
|
|
15
|
+
# bypassing leaves the README/snippets/marketplace listings drifting from
|
|
16
|
+
# the actual npm package.
|
|
17
|
+
|
|
18
|
+
on:
|
|
19
|
+
pull_request:
|
|
20
|
+
paths:
|
|
21
|
+
- "src/configs/source.json"
|
|
22
|
+
- "scripts/generate-configs.mjs"
|
|
23
|
+
- "package.json"
|
|
24
|
+
- "README.md"
|
|
25
|
+
- "docs/configs/**"
|
|
26
|
+
- "docs/snippets/**"
|
|
27
|
+
- "smithery.yaml"
|
|
28
|
+
- "server.json"
|
|
29
|
+
- ".github/workflows/verify-configs.yml"
|
|
30
|
+
push:
|
|
31
|
+
branches: [main]
|
|
32
|
+
paths:
|
|
33
|
+
- "src/configs/source.json"
|
|
34
|
+
- "scripts/generate-configs.mjs"
|
|
35
|
+
- "package.json"
|
|
36
|
+
- "README.md"
|
|
37
|
+
- "docs/configs/**"
|
|
38
|
+
- "docs/snippets/**"
|
|
39
|
+
- "smithery.yaml"
|
|
40
|
+
- "server.json"
|
|
41
|
+
- ".github/workflows/verify-configs.yml"
|
|
42
|
+
|
|
43
|
+
jobs:
|
|
44
|
+
verify:
|
|
45
|
+
runs-on: ubuntu-latest
|
|
46
|
+
steps:
|
|
47
|
+
- uses: actions/checkout@v4
|
|
48
|
+
|
|
49
|
+
- name: Setup Node
|
|
50
|
+
uses: actions/setup-node@v4
|
|
51
|
+
with:
|
|
52
|
+
node-version: "20"
|
|
53
|
+
|
|
54
|
+
- name: Verify all 15 distribution artifacts are in sync with source.json
|
|
55
|
+
run: node scripts/generate-configs.mjs --check
|
package/CONTRIBUTING.md
ADDED
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
# Contributing to mcp-memory-server
|
|
2
|
+
|
|
3
|
+
This package is the public face of Mnemoverse across every AI tool marketplace. A single typo in an install snippet breaks every Cursor / VS Code / Claude Desktop / Smithery / Official MCP Registry / GitHub README copy of it. To make that impossible, we use a **single source of truth** with mechanical drift detection.
|
|
4
|
+
|
|
5
|
+
> **Read this before editing any install snippet, config, or README install section.** The rules are short, but ignoring them produces silent breakage that we only notice when a user reports it.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## The one rule
|
|
10
|
+
|
|
11
|
+
**`src/configs/source.json` is the only file you may edit by hand for distribution metadata.** Everything else is generated and any manual edit will be overwritten — or, worse, will silently drift until CI catches it.
|
|
12
|
+
|
|
13
|
+
Files that are **generated** (never edit by hand):
|
|
14
|
+
|
|
15
|
+
| File | What it powers |
|
|
16
|
+
| ---- | -------------- |
|
|
17
|
+
| `docs/configs/cursor.json` | Cursor `.cursor/mcp.json` snippet |
|
|
18
|
+
| `docs/configs/claude-desktop.json` | Claude Desktop `claude_desktop_config.json` snippet |
|
|
19
|
+
| `docs/configs/windsurf.json` | Windsurf `mcp_config.json` snippet |
|
|
20
|
+
| `docs/configs/vscode.json` | VS Code `.vscode/mcp.json` snippet (uses `servers`, not `mcpServers`) |
|
|
21
|
+
| `docs/configs/cursor-deep-link.txt` | Base64-encoded `cursor://...` install URL |
|
|
22
|
+
| `docs/configs/vscode-deep-link.txt` | URL-encoded `vscode:mcp/install?...` URL |
|
|
23
|
+
| `docs/configs/claude-code-cli.sh` | `claude mcp add ...` shell command |
|
|
24
|
+
| `smithery.yaml` | Smithery.ai `configSchema` + `commandFunction` |
|
|
25
|
+
| `server.json` | Official MCP Registry manifest |
|
|
26
|
+
| `docs/snippets/claude-code.md` | Markdown partial — Claude Code install (consumed by README + docs site) |
|
|
27
|
+
| `docs/snippets/cursor.md` | Markdown partial — Cursor install |
|
|
28
|
+
| `docs/snippets/claude-desktop.md` | Markdown partial — Claude Desktop install |
|
|
29
|
+
| `docs/snippets/vscode.md` | Markdown partial — VS Code install |
|
|
30
|
+
| `docs/snippets/windsurf.md` | Markdown partial — Windsurf install |
|
|
31
|
+
| `README.md` (only the section between `<!-- INSTALL_SNIPPETS_START -->` and `<!-- INSTALL_SNIPPETS_END -->`) | Top-level install section, in-place rewritten by the generator |
|
|
32
|
+
|
|
33
|
+
If your editor pops up a diff in any of these files and you didn't change `src/configs/source.json`, the diff is wrong. Discard it.
|
|
34
|
+
|
|
35
|
+
## How to change a distribution config
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
# 1. Edit the source
|
|
39
|
+
$EDITOR src/configs/source.json
|
|
40
|
+
|
|
41
|
+
# 2. Regenerate everything
|
|
42
|
+
npm run generate:configs
|
|
43
|
+
|
|
44
|
+
# 3. Verify nothing else drifted
|
|
45
|
+
npm run verify:configs
|
|
46
|
+
|
|
47
|
+
# 4. Commit BOTH the source change AND every regenerated file
|
|
48
|
+
git add src/configs/source.json docs/ smithery.yaml server.json README.md
|
|
49
|
+
git commit -m "..."
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
If you forget step 2 and push only the source change, **CI will fail on the drift check** before the PR can merge. This is intentional — mechanical enforcement is the whole point.
|
|
53
|
+
|
|
54
|
+
## CI and the optional pre-push hook
|
|
55
|
+
|
|
56
|
+
There are two layers of drift detection — they catch the same problem at different points and you should not skip either.
|
|
57
|
+
|
|
58
|
+
### Layer 1: GitHub Actions (mandatory)
|
|
59
|
+
|
|
60
|
+
Every PR runs [`.github/workflows/verify-configs.yml`](.github/workflows/verify-configs.yml), which executes `node scripts/generate-configs.mjs --check`. The job fails the build if any of the 15 generated artifacts (or the README install block) does not match what would be re-emitted from `src/configs/source.json`. **The job is required for merge into `main`.** This is the authoritative gate — it works for forks, blocks PRs, can't be bypassed by `--no-verify`, and protects you from your own typos.
|
|
61
|
+
|
|
62
|
+
### Layer 2: Local pre-push hook (recommended, opt-in)
|
|
63
|
+
|
|
64
|
+
Faster feedback (~50 ms vs ~30-60 s for CI). Catches the drift before the commit even hits GitHub. Install once per clone:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
npm run install-hooks
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
This writes `.git/hooks/pre-push` (per-clone, not committed) that runs `npm run verify:configs` before every push. If it fails, your push is aborted and you get the same `✗ Drift detected: ...` message you would have seen in CI — just locally and 1000× faster.
|
|
71
|
+
|
|
72
|
+
If you ever need to bypass it for a one-off (e.g., pushing a temporary branch you don't care about), use `git push --no-verify`. **Do not bypass for branches that target `main`** — CI will reject them anyway.
|
|
73
|
+
|
|
74
|
+
We deliberately avoid `husky` and `pre-commit` — those would add a dependency and force the hook on everyone, including casual contributors who just want to fix a typo. The opt-in script is one command and zero deps.
|
|
75
|
+
|
|
76
|
+
## How `npm run generate:configs` works
|
|
77
|
+
|
|
78
|
+
`scripts/generate-configs.mjs` reads `src/configs/source.json` and emits 15 artifacts:
|
|
79
|
+
|
|
80
|
+
1. **9 distribution configs** in `docs/configs/`, plus `smithery.yaml` and `server.json` at the repo root.
|
|
81
|
+
2. **5 Markdown partials** in `docs/snippets/` — these are the same install snippets, formatted for inclusion in any Markdown context (README, mnemoverse-docs site pages, llms.txt, etc.).
|
|
82
|
+
3. **1 in-place rewrite** of the install section in `README.md`, between the `<!-- INSTALL_SNIPPETS_START -->` and `<!-- INSTALL_SNIPPETS_END -->` HTML comment markers. The rest of the README is human-prose and is left untouched.
|
|
83
|
+
|
|
84
|
+
The generator is **idempotent**: running it twice in a row produces zero changes the second time. CI relies on this property — it runs the generator with `--check`, which verifies every output matches what is committed and fails the build otherwise.
|
|
85
|
+
|
|
86
|
+
## How to add a new distribution channel
|
|
87
|
+
|
|
88
|
+
1. Add a new generator function in `scripts/generate-configs.mjs` that produces the channel's config from the data already in `source.json` (do NOT introduce a parallel data source — extend `source.json` instead if you need new fields).
|
|
89
|
+
2. Add the new artifact to the `OUTPUTS` array.
|
|
90
|
+
3. If the channel needs a Markdown install snippet, also add a `snippet*()` helper and a `docs/snippets/{channel}.md` entry. If the snippet should also appear in README, append it to `readmeInstallBlock()`.
|
|
91
|
+
4. Update this `CONTRIBUTING.md` table above with the new file.
|
|
92
|
+
5. Run `npm run generate:configs && npm run verify:configs`. Both must succeed.
|
|
93
|
+
6. Commit everything together — the source change, the new generator function, the new generated files, and the updated `CONTRIBUTING.md`.
|
|
94
|
+
|
|
95
|
+
## Things you must not do
|
|
96
|
+
|
|
97
|
+
- ❌ **Edit a generated file directly.** Even a one-character fix will be reverted on the next `generate:configs` and CI will fail in the meantime.
|
|
98
|
+
- ❌ **Bypass the drift check.** Do not pass `--no-verify` or skip CI. The check exists because we got bitten by 8 copies of the same install snippet drifting in different directions.
|
|
99
|
+
- ❌ **Hard-code distribution metadata in `src/index.ts`.** The MCP server source code only knows about tools, transport, and the API URL. Channel-specific stuff lives in `source.json`.
|
|
100
|
+
- ❌ **Create a parallel "config" file alongside `source.json`.** If `source.json` is missing a field you need, add it to `source.json` and update the generator. One source.
|
|
101
|
+
|
|
102
|
+
## Versioning and releases
|
|
103
|
+
|
|
104
|
+
`package.json#version` → `src/index.ts#version` (server name reported to MCP clients) → `server.json#version` (Official MCP Registry).
|
|
105
|
+
|
|
106
|
+
These are bumped manually in the first two files and propagated by the generator to the third. If they drift, the drift check on `server.json` catches it on every PR.
|
|
107
|
+
|
|
108
|
+
### Automated release pipeline
|
|
109
|
+
|
|
110
|
+
Releases are automated by [`.github/workflows/release.yml`](.github/workflows/release.yml). You bump the version on `main`, push a semver tag, and the workflow does the rest: npm publish, MCP Registry publish (via GitHub OIDC — no stored PAT), GitHub release.
|
|
111
|
+
|
|
112
|
+
The workflow is triggered by any tag matching `v*` pushed to the repo. To release:
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
# 1. Bump version in package.json
|
|
116
|
+
$EDITOR package.json
|
|
117
|
+
|
|
118
|
+
# 2. Match it in src/index.ts (search for version: "...")
|
|
119
|
+
$EDITOR src/index.ts
|
|
120
|
+
|
|
121
|
+
# 3. Regenerate (this updates server.json to match)
|
|
122
|
+
npm run generate:configs
|
|
123
|
+
|
|
124
|
+
# 4. Build and run any local checks you want before tagging
|
|
125
|
+
npm run build
|
|
126
|
+
npm run verify:configs
|
|
127
|
+
|
|
128
|
+
# 5. PR + squash-merge to main (drift CI runs on the PR)
|
|
129
|
+
git checkout -b release/vX.Y.Z
|
|
130
|
+
git add -A && git commit -m "release: vX.Y.Z"
|
|
131
|
+
git push -u origin release/vX.Y.Z
|
|
132
|
+
gh pr create --fill && gh pr merge --squash --delete-branch
|
|
133
|
+
git checkout main && git pull --ff-only
|
|
134
|
+
|
|
135
|
+
# 6. Tag main and push the tag
|
|
136
|
+
git tag -a vX.Y.Z -m "vX.Y.Z"
|
|
137
|
+
git push origin vX.Y.Z
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
That push fires [`.github/workflows/release.yml`](.github/workflows/release.yml), which:
|
|
141
|
+
|
|
142
|
+
1. Verifies the tag matches `package.json#version` (belt and suspenders).
|
|
143
|
+
2. Runs `npm ci && npm run build` (which also runs `generate:configs` via `prebuild`).
|
|
144
|
+
3. Runs `npm run verify:configs` for drift.
|
|
145
|
+
4. `npm publish` using the `NPM_TOKEN` secret.
|
|
146
|
+
5. Installs `mcp-publisher` from its Linux amd64 release bottle.
|
|
147
|
+
6. Authenticates to the Registry via `mcp-publisher login github-oidc` — this uses GitHub Actions' OIDC identity token. **No long-lived PAT is stored anywhere.** The prerequisite is that the authenticating GitHub account's membership in the `mnemoverse` org be **public** (already the case for `izgorodin`).
|
|
148
|
+
7. `mcp-publisher publish` uploads the freshly-generated `server.json`.
|
|
149
|
+
8. Verifies the registry entry via a direct curl against the public API.
|
|
150
|
+
9. Creates a GitHub release with auto-generated notes.
|
|
151
|
+
|
|
152
|
+
If any step fails, the release is aborted — nothing partial gets published. You can re-push the same tag after fixing the issue.
|
|
153
|
+
|
|
154
|
+
### One-time setup for the workflow
|
|
155
|
+
|
|
156
|
+
A single secret must be added at [Settings → Secrets → Actions](https://github.com/mnemoverse/mcp-memory-server/settings/secrets/actions):
|
|
157
|
+
|
|
158
|
+
| Secret | How to get it |
|
|
159
|
+
| ------ | ------------- |
|
|
160
|
+
| `NPM_TOKEN` | [npmjs.com → Settings → Access Tokens → Generate New Token](https://www.npmjs.com/settings/mnemoverse/tokens/granular-access-tokens/new) → **Automation** token, scope: publish to `@mnemoverse/mcp-memory-server`. |
|
|
161
|
+
|
|
162
|
+
Nothing else. GitHub OIDC provides the MCP Registry credential at run time, so we do not store an `MCP_GITHUB_TOKEN` secret at all.
|
|
163
|
+
|
|
164
|
+
### Manual trigger
|
|
165
|
+
|
|
166
|
+
If you need to re-run the pipeline for a tag that was already pushed (e.g. the workflow was added after the tag), use `workflow_dispatch`:
|
|
167
|
+
|
|
168
|
+
```bash
|
|
169
|
+
gh workflow run release.yml -f tag=v0.3.1
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
Or click **Run workflow** on the Actions tab and enter the tag.
|
|
173
|
+
|
|
174
|
+
## Testing changes locally
|
|
175
|
+
|
|
176
|
+
The fastest feedback loop is:
|
|
177
|
+
|
|
178
|
+
```bash
|
|
179
|
+
# Build
|
|
180
|
+
npm run build
|
|
181
|
+
|
|
182
|
+
# Pack into an installable tarball
|
|
183
|
+
npm pack
|
|
184
|
+
|
|
185
|
+
# Smoke test in an isolated dir
|
|
186
|
+
mkdir /tmp/mcp-smoke && cd /tmp/mcp-smoke
|
|
187
|
+
npm init -y >/dev/null
|
|
188
|
+
npm install /path/to/mcp-memory-server/mnemoverse-mcp-memory-server-X.Y.Z.tgz
|
|
189
|
+
MNEMOVERSE_API_KEY=mk_test_fake ./node_modules/.bin/mcp-memory-server
|
|
190
|
+
# → should print "Error: MNEMOVERSE_API_KEY environment variable is required" if unset, or start a stdio MCP server if set
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
For end-to-end testing against the live API, set a real `mk_live_*` key and pipe a few JSON-RPC messages on stdin (`initialize`, `notifications/initialized`, `tools/call`).
|
|
194
|
+
|
|
195
|
+
## Who to ask
|
|
196
|
+
|
|
197
|
+
- For the design rationale behind single-source-of-truth: see [PR #6](https://github.com/mnemoverse/mcp-memory-server/pull/6).
|
|
198
|
+
- For the README rewriter design: see [PR #11](https://github.com/mnemoverse/mcp-memory-server/pull/11).
|
|
199
|
+
- For everything else, open an issue.
|
package/README.md
CHANGED
|
@@ -1,8 +1,13 @@
|
|
|
1
1
|
# @mnemoverse/mcp-memory-server
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@mnemoverse/mcp-memory-server)
|
|
4
|
+
[](https://www.npmjs.com/package/@mnemoverse/mcp-memory-server)
|
|
5
|
+
[](https://registry.modelcontextprotocol.io/v0.1/servers?search=mnemoverse)
|
|
6
|
+
[](https://opensource.org/licenses/MIT)
|
|
4
7
|
|
|
5
|
-
|
|
8
|
+
Shared AI memory across Claude, Cursor, VS Code, ChatGPT, and any MCP client. Write once, recall anywhere.
|
|
9
|
+
|
|
10
|
+
Your agent remembers everything — across sessions, projects, and tools. One API key, one memory, everywhere.
|
|
6
11
|
|
|
7
12
|
## Quick Start
|
|
8
13
|
|
|
@@ -12,10 +17,14 @@ Sign up at [console.mnemoverse.com](https://console.mnemoverse.com) — takes 30
|
|
|
12
17
|
|
|
13
18
|
### 2. Connect to your AI tool
|
|
14
19
|
|
|
15
|
-
|
|
20
|
+
<!-- INSTALL_SNIPPETS_START — generated from src/configs/source.json. Run `npm run generate:configs` to refresh. Do not edit by hand. -->
|
|
21
|
+
|
|
22
|
+
**Claude Code** — add via CLI:
|
|
16
23
|
|
|
17
24
|
```bash
|
|
18
|
-
claude mcp add mnemoverse
|
|
25
|
+
claude mcp add mnemoverse \
|
|
26
|
+
-e MNEMOVERSE_API_KEY=mk_live_YOUR_KEY \
|
|
27
|
+
-- npx -y @mnemoverse/mcp-memory-server@latest
|
|
19
28
|
```
|
|
20
29
|
|
|
21
30
|
**Cursor** — add to `.cursor/mcp.json`:
|
|
@@ -25,7 +34,10 @@ claude mcp add mnemoverse -e MNEMOVERSE_API_KEY=mk_live_YOUR_KEY -- npx @mnemove
|
|
|
25
34
|
"mcpServers": {
|
|
26
35
|
"mnemoverse": {
|
|
27
36
|
"command": "npx",
|
|
28
|
-
"args": [
|
|
37
|
+
"args": [
|
|
38
|
+
"-y",
|
|
39
|
+
"@mnemoverse/mcp-memory-server@latest"
|
|
40
|
+
],
|
|
29
41
|
"env": {
|
|
30
42
|
"MNEMOVERSE_API_KEY": "mk_live_YOUR_KEY"
|
|
31
43
|
}
|
|
@@ -34,18 +46,20 @@ claude mcp add mnemoverse -e MNEMOVERSE_API_KEY=mk_live_YOUR_KEY -- npx @mnemove
|
|
|
34
46
|
}
|
|
35
47
|
```
|
|
36
48
|
|
|
37
|
-
**VS Code** — add to
|
|
49
|
+
**VS Code** — add to `.vscode/mcp.json` (note: VS Code uses `servers`, not `mcpServers`):
|
|
38
50
|
|
|
39
51
|
```json
|
|
40
52
|
{
|
|
41
|
-
"
|
|
42
|
-
"
|
|
43
|
-
"
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
"
|
|
47
|
-
|
|
48
|
-
|
|
53
|
+
"servers": {
|
|
54
|
+
"mnemoverse": {
|
|
55
|
+
"type": "stdio",
|
|
56
|
+
"command": "npx",
|
|
57
|
+
"args": [
|
|
58
|
+
"-y",
|
|
59
|
+
"@mnemoverse/mcp-memory-server@latest"
|
|
60
|
+
],
|
|
61
|
+
"env": {
|
|
62
|
+
"MNEMOVERSE_API_KEY": "mk_live_YOUR_KEY"
|
|
49
63
|
}
|
|
50
64
|
}
|
|
51
65
|
}
|
|
@@ -59,7 +73,10 @@ claude mcp add mnemoverse -e MNEMOVERSE_API_KEY=mk_live_YOUR_KEY -- npx @mnemove
|
|
|
59
73
|
"mcpServers": {
|
|
60
74
|
"mnemoverse": {
|
|
61
75
|
"command": "npx",
|
|
62
|
-
"args": [
|
|
76
|
+
"args": [
|
|
77
|
+
"-y",
|
|
78
|
+
"@mnemoverse/mcp-memory-server@latest"
|
|
79
|
+
],
|
|
63
80
|
"env": {
|
|
64
81
|
"MNEMOVERSE_API_KEY": "mk_live_YOUR_KEY"
|
|
65
82
|
}
|
|
@@ -68,17 +85,27 @@ claude mcp add mnemoverse -e MNEMOVERSE_API_KEY=mk_live_YOUR_KEY -- npx @mnemove
|
|
|
68
85
|
}
|
|
69
86
|
```
|
|
70
87
|
|
|
71
|
-
|
|
88
|
+
> Why `@latest`? Bare `npx @mnemoverse/mcp-memory-server` is cached indefinitely by npm and stops re-checking the registry. The `@latest` suffix forces a metadata lookup on every Claude Code / Cursor / VS Code session start (~100-300ms), so you always pick up new releases.
|
|
89
|
+
|
|
90
|
+
<!-- INSTALL_SNIPPETS_END -->
|
|
91
|
+
|
|
92
|
+
> ⚠️ **Restart your AI client** after editing the config. MCP servers are only picked up on client startup.
|
|
93
|
+
|
|
94
|
+
### 3. Try it — 30 seconds to verify it works
|
|
95
|
+
|
|
96
|
+
Paste this in your AI chat:
|
|
97
|
+
|
|
98
|
+
> **"Remember that my favourite TypeScript framework is Hono, and please call `memory_write` to save it."**
|
|
72
99
|
|
|
73
|
-
Your
|
|
100
|
+
Your agent should call `memory_write` and confirm the memory was stored.
|
|
74
101
|
|
|
75
|
-
|
|
102
|
+
Then open a **new chat / new session** (this is the whole point — memory survives restarts), and ask:
|
|
76
103
|
|
|
77
|
-
|
|
104
|
+
> **"What's my favourite TypeScript framework?"**
|
|
78
105
|
|
|
79
|
-
|
|
106
|
+
Your agent should call `memory_read`, find the entry, and answer "Hono". If it does — you're wired up. Write whatever you want next.
|
|
80
107
|
|
|
81
|
-
|
|
108
|
+
If it doesn't remember: check that the client was fully restarted and the config has your real `mk_live_...` key, not the placeholder.
|
|
82
109
|
|
|
83
110
|
## Tools
|
|
84
111
|
|
|
@@ -88,6 +115,8 @@ It remembers.
|
|
|
88
115
|
| `memory_read` | Search memories by natural language query |
|
|
89
116
|
| `memory_feedback` | Rate memories as helpful or not (improves future recall) |
|
|
90
117
|
| `memory_stats` | Check how many memories stored, which domains exist |
|
|
118
|
+
| `memory_delete` | Permanently delete a single memory by `atom_id` |
|
|
119
|
+
| `memory_delete_domain` | Wipe an entire domain (requires `confirm: true` safety interlock) |
|
|
91
120
|
|
|
92
121
|
## Ideas: What to Remember
|
|
93
122
|
|