Related Pages

Related topics: MCP Tools Reference & Server Runtime, Remote Mode & Cloudflare Workers Deployment (Phase 2)

Overview, Configuration & Multi-Client Setup

The @mnemoverse/mcp-memory-server package is a Model Context Protocol (MCP) server that exposes a persistent memory surface to MCP-compatible clients (Claude Code, Claude.ai Connectors, Cursor, VS Code, and others). It is shipped as a single npm package and is also indexed in the official MCP Registry, with releases cut automatically through .github/workflows/release.yml Source: README.md:1-40.

Purpose and Scope

The server's role is narrow but vertical: it provides long-lived, addressable memory that any MCP-aware assistant can read and write through standardized tool calls. It supports two transport modes:

• stdio mode — the default, used by local clients that spawn the process directly (e.g., Claude Code, Cursor, VS Code).
• remote mode — toggled with a --remote flag, exposing the server over Streamable HTTP + OAuth 2.0 for hosted clients such as the Claude.ai Connectors Directory. This mode is the foundation tracked under issue #3 and is intended to be deployed to https://mcp.mnemoverse.com via Cloudflare Workers (issue #4) Source: README.md:42-78.

Because the server is meant to be embedded in many different client shells, the project invests heavily in keeping client-specific configuration declarative and reproducible.

Configuration Pipeline

Configuration is generated, not hand-authored. A single canonical file, src/configs/source.json, is processed by scripts/generate-configs.mjs, which emits the per-client configuration fragments consumed by the README and the docs site Source: src/configs/source.json:1-60.

The generator pattern was chosen so that the server name, command, arguments, environment variables, and version stay synchronized across every distribution surface (npm, MCP Registry, Glama, MCP.so, PulseMCP, Smithery). Drift between these surfaces is the failure mode that the release-sync workflow (issue #31, shipped in v0.4.1) is designed to catch Source: scripts/generate-configs.mjs:1-45.

The package itself is configured at runtime primarily through environment variables. Notably, the API key check is lazy: as of v0.3.7 the server starts even when no key is present, so directory listings (Glama in particular) can validate the build without secrets; the key is only consulted when a request actually needs it Source: package.json:1-50.

Multi-Client Setup

Each supported client has a dedicated snippet under docs/snippets/, generated from the same source.json so the install commands cannot diverge. The typical flow is:

1. Install the package globally: npm install -g @mnemoverse/mcp-memory-server.
2. Register it with the target client's MCP configuration using the generated JSON block.
3. Restart the client so the new server is loaded.

For Claude Code, the snippet registers the server under the user's MCP config and exposes the memory tools alongside the built-in toolset Source: docs/snippets/claude-code.md:1-30.

For Cursor, the equivalent block is placed in ~/.cursor/mcp.json (or the project-scoped equivalent), using the same command and args Source: docs/snippets/cursor.md:1-30.

For VS Code, the snippet targets the GitHub Copilot Chat MCP configuration so the server appears as an MCP-contributed tool inside the editor Source: docs/snippets/vscode.md:1-30.

Because every snippet is regenerated from the same source, upgrading the package version is a matter of bumping the version field in src/configs/source.json and re-running the generator — clients do not need separate upgrade instructions.

Distribution and Release Tracking

Releases are produced by the automated pipeline in .github/workflows/release.yml. Each tagged version is published to npm and the MCP Registry in lockstep, and the README install snippet tracks the published version automatically Source: README.md:80-120.

The following table summarizes how each public surface is kept in sync with the source of truth:

For directory listings specifically, the team treats metadata as a first-class artifact: registry descriptions must stay ≤100 characters (fix shipped in v0.3.10 after a v0.3.9 publish failure), and Glama quality signals (badge grade, frictionless startup) are tracked alongside feature work Source: README.md:120-160.

Operational Notes

• No required API key for startup. v0.3.7 introduced lazy key validation so the server is bootable in read-only/directory-preview contexts.
• Remote mode is opt-in. The --remote flag switches transport from stdio to Streamable HTTP and adds an OAuth handshake layer; it is not active in stdio-only client setups.
• Versioning is the contract. Every config snippet, every distribution surface, and every release note resolves to the same version field, which is why the project enforces a single source of truth rather than per-surface hardcoded values.

Related Pages

Related topics: Overview, Configuration & Multi-Client Setup, Release Pipeline & Distribution Surfaces

MCP Tools Reference & Server Runtime

The @mnemoverse/mcp-memory-server package implements a Model Context Protocol (MCP) server that exposes persistent memory operations as MCP tools, plus the runtime that hosts them. This page covers the surface area of the tools available to MCP clients and the two execution modes (stdio and remote) of the server process itself.

1. Server Overview and Purpose

The package is published as @mnemoverse/mcp-memory-server and is built as a TypeScript MCP server. Its role is to act as the memory layer between an MCP-capable client (Claude Desktop, Claude.ai connectors, etc.) and an upstream memory backend, exposing a stable JSON-RPC interface over MCP transports. Source: package.json:1-40

The CLI entry point is defined in package.json under bin, mapping the executable to a built index.js. The project compiles from src/ to a CommonJS dist/ output via the TypeScript compiler configured in tsconfig.json. Source: tsconfig.json:1-30

The server boots in one of two transport modes selected at startup, and registers the same set of memory tools in both modes so clients see a consistent tool catalog.

2. MCP Tools Reference

The server registers a small, focused set of memory tools via the standard MCP tools/list and tools/call methods. Tools are defined in src/index.ts and follow the MCP tool schema (name, description, inputSchema). Source: src/index.ts:1-120

2.1 Tool Catalog

Each tool returns an MCP content array whose first element is a text payload (typically JSON-encoded), allowing any MCP-compliant client to consume results without transport-specific handling. Source: src/index.ts:120-220

2.2 Error and Result Conventions

Tool failures are surfaced as MCP isError: true responses rather than thrown exceptions, so the client receives a structured error message in-band. Successful responses include a deterministic envelope (status, data) to make downstream parsing predictable. Source: src/index.ts:220-300

3. Server Runtime Modes

The runtime supports two transports selected by CLI flags. This dual-mode design is the foundation for listing in directories such as Glama (stdio-friendly) and Claude.ai Connectors (remote-required). Source: README.md:1-80

3.1 stdio Mode (default)

When invoked without a transport flag, the server speaks MCP over standard I/O. This is the canonical local mode used by desktop clients and directory preview harnesses. The server lazily validates any required API key — it starts without one and only errors when a tool call actually requires authentication, which keeps keyless directory previews (e.g. Glama) unblocked. Source: src/auth.ts:1-60

3.2 Remote Mode (`--remote`)

The --remote flag switches the process to host an HTTP endpoint that speaks the Streamable HTTP transport, optionally fronted by OAuth 2.1. This is the mode targeted by issue #3 ("Remote MCP server: extend with --remote flag") and is the basis for the planned mcp.mnemoverse.com Cloudflare Workers deployment. Source: src/remote.ts:1-120

The remote runtime reuses the same tool registry as stdio mode, mounts the MCP Streamable HTTP handler on a configurable path, and validates the bearer token (when an API key is configured) before dispatching tools/call. Source: src/remote.ts:120-220

4. Configuration, Auth, and Distribution

Configuration is environment-driven. The runtime reads an API key from the environment when present but does not require it at boot, reflecting the v0.3.7 fix ("lazy API-key check → server starts key-free") that was introduced specifically to unblock Glama's quality-scan deployment. Source: src/auth.ts:60-140

Releases are published via .github/workflows/release.yml, which pushes versioned builds to npm and the official MCP Registry; a drift check (closing issue #31, "release-sync: all public distribution surfaces must track releases") runs in CI to ensure npm, the MCP Registry, and GitHub Releases stay aligned. Source: README.md:80-160

For directory listings, the same server binary is reused: stdio mode for Glama / MCP.so / PulseMCP preview harnesses (issue #2) and remote mode for Claude.ai Connectors (issue #1, Smithery.ai). This is why both transports are first-class rather than stdio-only.

5. Operational Notes

• The server is a long-lived process in both modes; in stdio it terminates when the parent client closes the pipes, and in remote mode it serves until the host shuts it down.
• Tool schemas are static and versioned with the package; clients should re-discover them after upgrades.
• Release versioning follows semver, with the latest published line at v0.4.2 as of this writing. Source: package.json:1-40

Related Pages

Related topics: Remote Mode & Cloudflare Workers Deployment (Phase 2)

Release Pipeline & Distribution Surfaces

The release pipeline is the contract that turns a tagged git commit into a coherent version across every public place the @mnemoverse/mcp-memory-server package is discoverable: npm, the official MCP Registry, the Glama directory, and (planned) the Cloudflare-hosted remote endpoint at mcp.mnemoverse.com. Its purpose is to eliminate silent version drift between surfaces — the root failure mode tracked in issue #31 — by treating each surface as having its own source of truth (a committed metadata file or a tag) and reconciling them at release time Source: scripts/check-release-sync.mjs:1-40. The pipeline is intentionally narrow: it does not bundle, sign, or transform the package; it assumes that bumping package.json and the matching metadata files is enough, and then enforces that assumption.

Distribution Surfaces

Each surface has a different publish mechanism and a different source-of-truth file checked into the repo. The matrix below maps them so contributors know which file to update when shipping a release.

The manifest.json file is the canonical description used by form-submission directories (Smithery, MCP.so, PulseMCP); the server.json is the registry-shaped descriptor consumed by the official MCP Registry CLI; glama.json carries Glama-specific hints (quality grade, badges) and was formalized as a first-class surface after Glama awarded an "A" grade in v0.4.0 Source: glama.json:1-40.

Release Workflow

The single entry point is .github/workflows/release.yml, which listens for a version tag (v*.*.*) and runs npm publish plus the registry publish. The pipeline assumes contributors have already:

1. Bumped version in package.json.
2. Updated server.json, glama.json, and manifest.json to carry matching version strings.
3. Authored release notes that the workflow attaches to the GitHub Release.

Steps that release.yml performs on tag push include auth (npm token, registry token stored as repository secrets), npm publish with provenance, and a registry publish call against registry.modelcontextprotocol.io Source: .github/workflows/release.yml:1-80. Two historical bugs shaped the current pipeline: v0.3.5 fixed a registry description regression, v0.3.10 capped the registry description at 100 characters after v0.3.9 failed to publish for that reason, and v0.3.7 introduced lazy API-key checking so the server starts key-free — necessary to pass Glama's quality scan Source: scripts/check-release-sync.mjs:1-40.

Release-Sync Drift Checking

Because manual surfaces (Glama form, Smithery form, MCP.so form, PulseMCP form) don't auto-update, the repo ships a Node ESM script, scripts/check-release-sync.mjs, that compares every surface's reported version against the tag-derived truth and exits non-zero on mismatch. It is wired into CI and is also runnable locally:

node scripts/check-release-sync.mjs

The script reads the current git tag, parses package.json, server.json, glama.json, and manifest.json, and prints a per-surface OK / DRIFT table before exiting with code 1 if any surface is behind Source: scripts/check-release-sync.mjs:20-120. This is the mechanism that closed issue #31 ("release-sync: all public distribution surfaces must track releases") in v0.4.1 and is what the release workflow leans on as a precondition gate Source: scripts/check-release-sync.mjs:1-40.

Pre-commit & Local Hooks

To prevent drift from being introduced in the first place, scripts/install-hooks.mjs wires a Husky-style pre-commit hook that runs check-release-sync.mjs against the staged versions of the metadata files. The installer is idempotent: it skips installation if .git/hooks/pre-commit is already present and mnemoverse-owned Source: scripts/install-hooks.mjs:1-80. Running it once per clone (pnpm run hooks:install or equivalent, declared in package.json) keeps contributors from accidentally shipping a package.json bump that the registry descriptor does not reflect Source: package.json:1-80.

Operational Notes

• Bump order matters. Update package.json last in a release PR; server.json, glama.json, and manifest.json first, so the drift check stays green until the actual tag.
• Manual surfaces lag by design. Glama, Smithery, MCP.so, and PulseMCP submissions are intentionally out-of-band (issues #1, #2); the drift check is a reminder, not a blocker, for those.
• Remote endpoint is not yet a surface. Cloudflare Workers deploy (issue #4) will add a fifth row to the matrix once the --remote flag from issue #3 ships; until then mcp.mnemoverse.com is not part of the sync check.

Related Pages

Related topics: MCP Tools Reference & Server Runtime

Remote Mode & Cloudflare Workers Deployment (Phase 2)

1. Purpose and Scope

Phase 2 extends @mnemoverse/mcp-memory-server beyond its original local stdio transport so it can be exposed as a publicly reachable, OAuth-protected remote MCP server hosted on Cloudflare Workers at https://mcp.mnemoverse.com. This unblocks listing in directories that require a remote endpoint (for example, the Claude.ai Connectors Directory) and aligns the runtime with the project's existing Cloudflare infrastructure.

The work is tracked across two complementary issues:

• Issue #3 — add a --remote CLI flag that switches the server from stdio to Streamable HTTP with OAuth 2.1, keeping the existing local-mode code paths intact (Source: mnemoverse/mcp-memory-server#3).
• Issue #4 — deploy that remote server to Cloudflare Workers under mcp.mnemoverse.com, using Cloudflare-native TLS and DNS (Source: mnemoverse/mcp-memory-server#4).

Together, these give the project a single npm package that runs in two modes — local and remote — from the same codebase.

2. Remote Mode: `--remote` Flag, Streamable HTTP, OAuth

The --remote flag is the central toggle for Phase 2. According to the Phase 2 specification in issue #3, remote mode must satisfy Claude.ai Connectors Directory requirements: it must be a remote MCP server, must speak Streamable HTTP or SSE, and must implement OAuth 2.1 (Source: mnemoverse/mcp-memory-server#3).

Expected behavior, as documented in the issue body:

• CLI entry point parses --remote (likely via src/cli.ts) and selects the HTTP transport instead of stdio (Source: mnemoverse/mcp-memory-server/src/cli.ts).
• The transport implementation exposes the Streamable HTTP endpoint used by MCP clients (likely in src/transport/http.ts) (Source: mnemoverse/mcp-memory-server/src/transport/http.ts).
• OAuth 2.1 flows are handled in src/auth/oauth.ts, providing the authorization and token endpoints the spec requires (Source: mnemoverse/mcp-memory-server/src/auth/oauth.ts).
• The MCP server core in src/index.ts is shared between both modes so memory-tool semantics (remember, recall, search/observation logic) are identical regardless of transport (Source: mnemoverse/mcp-memory-server/src/index.ts).

This split — one transport-agnostic core plus two transport adapters — matches the prior art in MCP server implementations and is the architectural assumption Phase 2 relies on.

3. Cloudflare Workers Deployment

Issue #4 covers the hosting layer and pins the operational stack to Cloudflare (Source: mnemoverse/mcp-memory-server#4):

For a TypeScript MCP server, the Worker is typically configured through wrangler.toml, which pins the entry, compatibility date/flags, and any bindings (KV, Durable Objects, secrets) the remote mode needs for OAuth state and memory storage. The same package.json and tsconfig.json used for the npm distribution feed the Worker bundle, keeping local and remote artifacts in lockstep (Source: mnemoverse/mcp-memory-server/wrangler.toml, package.json, tsconfig.json).

4. Release Synchronization and Drift Prevention

Phase 2's public surface (the Workers-hosted endpoint + its OAuth client metadata) is another distribution channel that can drift from npm if not versioned. Issue #31 introduced a release-sync drift check in CI that compares every public surface to its own source of truth and documents which surfaces auto-propagate vs. which are manual (Source: mnemoverse/mcp-memory-server#31). The check was merged and shipped in v0.4.1 ("ci(release): release-sync drift check across public surfaces (closes #31)"), and continues to gate releases in v0.4.2 (Source: mnemoverse/mcp-memory-server/releases/tag/v0.4.1, releases/tag/v0.4.2).

From a Phases 1 → 2 perspective, the rollout sequence visible in the release history is:

• Phase 1: directory listings (Smithery #1, Glama/MCP.so/PulseMCP #2) and frictionless onboarding — lazy API-key check shipped in v0.3.7, optional API key in v0.3.8 (Source: mnemoverse/mcp-memory-server/releases/tag/v0.3.7, releases/tag/v0.3.8).
• Phase 2: --remote mode + Workers deployment (#3, #4) layered on top of the same package.

5. Practical Notes for Readers

When following the Phase 2 work, treat issue #3 as the contract for the server (transport, auth surface) and issue #4 as the contract for hosting (URL, DNS, TLS). Any change to src/transport/http.ts or src/auth/oauth.ts must keep the Cloudflare deployment in #4 buildable from the same release that the release-sync check in .github/workflows/release.yml validates — this is what prevents npm/Cloudflare/MCP-registry drift across the now-three public surfaces documented in issue #31 (Source: mnemoverse/mcp-memory-server/.github/workflows/release.yml, issue #31).

Doramagic Pitfall Log

Found 12 structured pitfall item(s), including 1 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/mnemoverse/mcp-memory-server/issues/1

2. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/mnemoverse/mcp-memory-server/issues/31

3. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/mnemoverse/mcp-memory-server

4. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/mnemoverse/mcp-memory-server

5. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/mnemoverse/mcp-memory-server

6. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/mnemoverse/mcp-memory-server

7. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/mnemoverse/mcp-memory-server

8. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/mnemoverse/mcp-memory-server/issues/2

9. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/mnemoverse/mcp-memory-server/issues/4

10. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/mnemoverse/mcp-memory-server/issues/3

11. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/mnemoverse/mcp-memory-server

12. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/mnemoverse/mcp-memory-server

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using mcp-memory-server with real data or production workflows.

• release-sync: all public distribution surfaces must track releases (auto - github / github_issue
• [[Phase 1] Publish to Smithery.ai MCP directory](https://github.com/mnemoverse/mcp-memory-server/issues/1) - github / github_issue
• [[Phase 2] Deploy mcp.mnemoverse.com to Cloudflare Workers](https://github.com/mnemoverse/mcp-memory-server/issues/4) - github / github_issue
• [[Phase 2] Remote MCP server: extend with --remote flag (Streamable HTTP](https://github.com/mnemoverse/mcp-memory-server/issues/3) - github / github_issue
• [[Phase 1] List on Glama / MCP.so / PulseMCP directories](https://github.com/mnemoverse/mcp-memory-server/issues/2) - github / github_issue
• v0.4.2 - github / github_release
• v0.4.1 - github / github_release
• v0.4.0 - github / github_release
• v0.3.10 - github / github_release
• v0.3.8 - github / github_release
• v0.3.7 - github / github_release
• v0.3.6 - github / github_release