@mnemoverse/mcp-memory-server 0.3.2 → 0.3.3
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/LICENSE +21 -0
- package/README.md +4 -1
- package/package.json +12 -1
- package/.github/workflows/release.yml +0 -138
- package/.github/workflows/verify-configs.yml +0 -55
- package/CONTRIBUTING.md +0 -199
- package/docs/configs/claude-code-cli.sh +0 -4
- package/docs/configs/claude-desktop.json +0 -14
- package/docs/configs/cursor-deep-link.txt +0 -1
- package/docs/configs/cursor.json +0 -14
- package/docs/configs/vscode-deep-link.txt +0 -1
- package/docs/configs/vscode.json +0 -15
- package/docs/configs/windsurf.json +0 -14
- package/docs/snippets/claude-code.md +0 -9
- package/docs/snippets/claude-desktop.md +0 -20
- package/docs/snippets/cursor.md +0 -20
- package/docs/snippets/vscode.md +0 -21
- package/docs/snippets/windsurf.md +0 -20
- package/llms.txt +0 -52
- package/scripts/generate-configs.mjs +0 -495
- package/scripts/install-hooks.mjs +0 -76
- package/server.json +0 -29
- package/smithery.yaml +0 -24
- package/src/configs/source.json +0 -28
- package/src/index.ts +0 -464
- package/tsconfig.json +0 -15
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Mnemoverse
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -154,7 +154,10 @@ The same API key works across all tools. Write a memory in Claude Code — read
|
|
|
154
154
|
- [API Reference](https://mnemoverse.com/docs/api/reference)
|
|
155
155
|
- [Console (get API key)](https://console.mnemoverse.com)
|
|
156
156
|
- [GitHub](https://github.com/mnemoverse/mcp-memory-server)
|
|
157
|
+
- [Releases](https://github.com/mnemoverse/mcp-memory-server/releases)
|
|
158
|
+
- [MCP Registry entry](https://registry.modelcontextprotocol.io/v0.1/servers?search=mnemoverse)
|
|
159
|
+
- [Contributing](CONTRIBUTING.md)
|
|
157
160
|
|
|
158
161
|
## License
|
|
159
162
|
|
|
160
|
-
MIT
|
|
163
|
+
[MIT](LICENSE) © Mnemoverse
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mnemoverse/mcp-memory-server",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.3",
|
|
4
4
|
"description": "MCP server for Mnemoverse Memory API — persistent AI memory across Claude Code, Cursor, VS Code, and any MCP client",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -8,6 +8,12 @@
|
|
|
8
8
|
},
|
|
9
9
|
"main": "./dist/index.js",
|
|
10
10
|
"types": "./dist/index.d.ts",
|
|
11
|
+
"files": [
|
|
12
|
+
"dist",
|
|
13
|
+
"README.md",
|
|
14
|
+
"LICENSE",
|
|
15
|
+
"package.json"
|
|
16
|
+
],
|
|
11
17
|
"scripts": {
|
|
12
18
|
"build": "tsc",
|
|
13
19
|
"dev": "tsc --watch",
|
|
@@ -23,10 +29,15 @@
|
|
|
23
29
|
"mcp",
|
|
24
30
|
"memory",
|
|
25
31
|
"ai",
|
|
32
|
+
"ai-agent",
|
|
26
33
|
"claude",
|
|
27
34
|
"cursor",
|
|
35
|
+
"vscode",
|
|
36
|
+
"chatgpt",
|
|
28
37
|
"mnemoverse",
|
|
29
38
|
"persistent-memory",
|
|
39
|
+
"shared-memory",
|
|
40
|
+
"cross-tool",
|
|
30
41
|
"model-context-protocol"
|
|
31
42
|
],
|
|
32
43
|
"author": "Mnemoverse <hello@mnemoverse.com>",
|
|
@@ -1,138 +0,0 @@
|
|
|
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.
|
|
@@ -1,55 +0,0 @@
|
|
|
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
DELETED
|
@@ -1,199 +0,0 @@
|
|
|
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.
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
cursor://anysphere.cursor-deeplink/mcp/install?name=mnemoverse&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBtbmVtb3ZlcnNlL21jcC1tZW1vcnktc2VydmVyQGxhdGVzdCJdLCJlbnYiOnsiTU5FTU9WRVJTRV9BUElfS0VZIjoibWtfbGl2ZV9ZT1VSX0tFWSJ9fQ==
|
package/docs/configs/cursor.json
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
vscode:mcp/install?%7B%22name%22%3A%22mnemoverse%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40mnemoverse%2Fmcp-memory-server%40latest%22%5D%2C%22env%22%3A%7B%22MNEMOVERSE_API_KEY%22%3A%22mk_live_YOUR_KEY%22%7D%7D
|
package/docs/configs/vscode.json
DELETED
|
@@ -1,9 +0,0 @@
|
|
|
1
|
-
<!-- AUTO-GENERATED from src/configs/source.json. Run `npm run generate:configs`. Do not edit by hand. -->
|
|
2
|
-
|
|
3
|
-
**Claude Code** — add via CLI:
|
|
4
|
-
|
|
5
|
-
```bash
|
|
6
|
-
claude mcp add mnemoverse \
|
|
7
|
-
-e MNEMOVERSE_API_KEY=mk_live_YOUR_KEY \
|
|
8
|
-
-- npx -y @mnemoverse/mcp-memory-server@latest
|
|
9
|
-
```
|
|
@@ -1,20 +0,0 @@
|
|
|
1
|
-
<!-- AUTO-GENERATED from src/configs/source.json. Run `npm run generate:configs`. Do not edit by hand. -->
|
|
2
|
-
|
|
3
|
-
**Claude Desktop** — add to `claude_desktop_config.json`:
|
|
4
|
-
|
|
5
|
-
```json
|
|
6
|
-
{
|
|
7
|
-
"mcpServers": {
|
|
8
|
-
"mnemoverse": {
|
|
9
|
-
"command": "npx",
|
|
10
|
-
"args": [
|
|
11
|
-
"-y",
|
|
12
|
-
"@mnemoverse/mcp-memory-server@latest"
|
|
13
|
-
],
|
|
14
|
-
"env": {
|
|
15
|
-
"MNEMOVERSE_API_KEY": "mk_live_YOUR_KEY"
|
|
16
|
-
}
|
|
17
|
-
}
|
|
18
|
-
}
|
|
19
|
-
}
|
|
20
|
-
```
|
package/docs/snippets/cursor.md
DELETED
|
@@ -1,20 +0,0 @@
|
|
|
1
|
-
<!-- AUTO-GENERATED from src/configs/source.json. Run `npm run generate:configs`. Do not edit by hand. -->
|
|
2
|
-
|
|
3
|
-
**Cursor** — add to `.cursor/mcp.json`:
|
|
4
|
-
|
|
5
|
-
```json
|
|
6
|
-
{
|
|
7
|
-
"mcpServers": {
|
|
8
|
-
"mnemoverse": {
|
|
9
|
-
"command": "npx",
|
|
10
|
-
"args": [
|
|
11
|
-
"-y",
|
|
12
|
-
"@mnemoverse/mcp-memory-server@latest"
|
|
13
|
-
],
|
|
14
|
-
"env": {
|
|
15
|
-
"MNEMOVERSE_API_KEY": "mk_live_YOUR_KEY"
|
|
16
|
-
}
|
|
17
|
-
}
|
|
18
|
-
}
|
|
19
|
-
}
|
|
20
|
-
```
|
package/docs/snippets/vscode.md
DELETED
|
@@ -1,21 +0,0 @@
|
|
|
1
|
-
<!-- AUTO-GENERATED from src/configs/source.json. Run `npm run generate:configs`. Do not edit by hand. -->
|
|
2
|
-
|
|
3
|
-
**VS Code** — add to `.vscode/mcp.json` (note: VS Code uses `servers`, not `mcpServers`):
|
|
4
|
-
|
|
5
|
-
```json
|
|
6
|
-
{
|
|
7
|
-
"servers": {
|
|
8
|
-
"mnemoverse": {
|
|
9
|
-
"type": "stdio",
|
|
10
|
-
"command": "npx",
|
|
11
|
-
"args": [
|
|
12
|
-
"-y",
|
|
13
|
-
"@mnemoverse/mcp-memory-server@latest"
|
|
14
|
-
],
|
|
15
|
-
"env": {
|
|
16
|
-
"MNEMOVERSE_API_KEY": "mk_live_YOUR_KEY"
|
|
17
|
-
}
|
|
18
|
-
}
|
|
19
|
-
}
|
|
20
|
-
}
|
|
21
|
-
```
|
|
@@ -1,20 +0,0 @@
|
|
|
1
|
-
<!-- AUTO-GENERATED from src/configs/source.json. Run `npm run generate:configs`. Do not edit by hand. -->
|
|
2
|
-
|
|
3
|
-
**Windsurf** — add to `~/.codeium/windsurf/mcp_config.json`:
|
|
4
|
-
|
|
5
|
-
```json
|
|
6
|
-
{
|
|
7
|
-
"mcpServers": {
|
|
8
|
-
"mnemoverse": {
|
|
9
|
-
"command": "npx",
|
|
10
|
-
"args": [
|
|
11
|
-
"-y",
|
|
12
|
-
"@mnemoverse/mcp-memory-server@latest"
|
|
13
|
-
],
|
|
14
|
-
"env": {
|
|
15
|
-
"MNEMOVERSE_API_KEY": "mk_live_YOUR_KEY"
|
|
16
|
-
}
|
|
17
|
-
}
|
|
18
|
-
}
|
|
19
|
-
}
|
|
20
|
-
```
|