@sfrangulov/shared-memory-mcp 1.0.0

package/lib/slugify.js

@@ -0,0 +1,77 @@
+import { transliterate } from "transliteration";
+
+/**
+ * Reserved slug names that conflict with system files/folders.
+ * These are checked in their slug form (after transliteration and normalization).
+ * Original system names: root, _meta, _shared, shared
+ * After slug processing: root, meta, shared
+ */
+const RESERVED_SLUGS = new Set(["root", "meta", "shared"]);
+
+const MAX_LENGTH = 60;
+
+/**
+ * Converts a title string into a URL/filename-safe slug.
+ *
+ * Rules (applied in order):
+ * 1. Transliterate non-Latin characters (e.g. "Привет" -> "privet")
+ * 2. Lowercase
+ * 3. Replace everything except a-z, 0-9 with hyphens
+ * 4. Remove leading/trailing hyphens and collapse duplicate hyphens
+ * 5. Truncate to max 60 characters (trim any trailing hyphen from truncation)
+ * 6. Check reserved names: root, meta, shared -> add suffix "-entry"
+ *
+ * @param {string} title - The title to convert
+ * @returns {string} The generated slug
+ */
+export function slugify(title) {
+  if (!title) return "";
+
+  // 1. Transliterate non-Latin characters
+  let slug = transliterate(title);
+
+  // 2. Lowercase
+  slug = slug.toLowerCase();
+
+  // 3. Replace everything except a-z, 0-9 with hyphens
+  slug = slug.replace(/[^a-z0-9]/g, "-");
+
+  // 4. Collapse duplicate hyphens and remove leading/trailing hyphens
+  slug = slug.replace(/-+/g, "-").replace(/^-|-$/g, "");
+
+  // 5. Truncate to max 60 characters, then trim any trailing hyphen
+  if (slug.length > MAX_LENGTH) {
+    slug = slug.slice(0, MAX_LENGTH).replace(/-$/, "");
+  }
+
+  // 6. Check reserved names
+  if (RESERVED_SLUGS.has(slug)) {
+    slug = `${slug}-entry`;
+  }
+
+  return slug;
+}
+
+/**
+ * Ensures a slug is unique among existing files.
+ * If `slug.md` already exists in the file list, appends an incrementing
+ * suffix: slug-2, slug-3, etc.
+ *
+ * @param {string} slug - The base slug to check
+ * @param {string[]} existingFiles - Array of existing filenames (e.g. ["hello.md", "world.md"])
+ * @returns {string} A unique slug
+ */
+export function ensureUnique(slug, existingFiles) {
+  const fileSet = new Set(existingFiles);
+
+  if (!fileSet.has(`${slug}.md`)) {
+    return slug;
+  }
+
+  let counter = 2;
+  while (fileSet.has(`${slug}-${counter}.md`)) {
+    counter++;
+  }
+
+  return `${slug}-${counter}`;
+}

package/lib/state-manager.js

@@ -0,0 +1,153 @@
+import { readFile, writeFile, rename } from "node:fs/promises";
+import { join } from "node:path";
+
+const STATE_FILENAME = ".shared-memory-state";
+const TEMP_SUFFIX = ".tmp";
+
+/**
+ * Default state returned when no state file exists or file is corrupted.
+ * @returns {{ active_project: null, version: 1 }}
+ */
+function defaultState() {
+  return { active_project: null, version: 1 };
+}
+
+/**
+ * Creates a session state manager for the given working directory.
+ *
+ * Manages the `.shared-memory-state` JSON file with atomic writes
+ * (write to temp file, then rename). Author cache is in-memory,
+ * per-project, session-only.
+ *
+ * @param {string} workdir - Absolute path to the working directory
+ * @returns {{
+ *   readState: () => Promise<{ active_project: string | null, version: number }>,
+ *   writeState: (state: object) => Promise<void>,
+ *   getAuthorCache: (project: string) => object | null,
+ *   setAuthorCache: (project: string, cache: object) => void,
+ *   invalidateAuthorCache: (project?: string) => void
+ * }}
+ */
+export function createStateManager(workdir) {
+  const statePath = join(workdir, STATE_FILENAME);
+  const tempPath = join(workdir, STATE_FILENAME + TEMP_SUFFIX);
+
+  /** @type {Map<string, object>} In-memory author cache, keyed by project */
+  const authorCacheMap = new Map();
+
+  /**
+   * Reads the session state from the state file.
+   *
+   * - File missing -> returns defaults
+   * - File corrupted (invalid JSON) -> logs warning, deletes, recreates with defaults
+   * - Version field missing or non-numeric -> treats as version 1, rewrites
+   *
+   * @returns {Promise<{ active_project: string | null, version: number }>}
+   */
+  async function readState() {
+    let raw;
+    try {
+      raw = await readFile(statePath, "utf-8");
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        return defaultState();
+      }
+      throw err;
+    }
+
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      // Corrupted JSON — log warning, delete and recreate with defaults
+      console.warn(
+        `[state-manager] Corrupted state file at ${statePath}, resetting to defaults`
+      );
+      const defaults = defaultState();
+      await atomicWrite(defaults);
+      return defaults;
+    }
+
+    // Validate version field
+    let needsRewrite = false;
+    if (typeof parsed.version !== "number") {
+      parsed.version = 1;
+      needsRewrite = true;
+    }
+
+    if (needsRewrite) {
+      await atomicWrite(parsed);
+    }
+
+    return {
+      active_project: parsed.active_project ?? null,
+      version: parsed.version,
+    };
+  }
+
+  /**
+   * Writes state to the state file atomically.
+   * Writes to a temp file first, then renames to the final path.
+   *
+   * @param {object} state - The state object to write
+   * @returns {Promise<void>}
+   */
+  async function writeState(state) {
+    await atomicWrite(state);
+  }
+
+  /**
+   * Internal: atomic write via temp file + rename.
+   *
+   * @param {object} data - JSON-serializable data
+   * @returns {Promise<void>}
+   */
+  async function atomicWrite(data) {
+    const json = JSON.stringify(data, null, 2);
+    await writeFile(tempPath, json, "utf-8");
+    await rename(tempPath, statePath);
+  }
+
+  /**
+   * Returns the author cache for a given project, or null if not cached.
+   *
+   * @param {string} project - Project identifier
+   * @returns {object | null}
+   */
+  function getAuthorCache(project) {
+    return authorCacheMap.get(project) ?? null;
+  }
+
+  /**
+   * Stores the author cache for a given project (in-memory only).
+   *
+   * @param {string} project - Project identifier
+   * @param {object} cache - Map-like object of filename -> author
+   */
+  function setAuthorCache(project, cache) {
+    authorCacheMap.set(project, cache);
+  }
+
+  /**
+   * Invalidates author cache.
+   * If project is specified, clears only that project's cache.
+   * If not specified, clears the entire cache.
+   *
+   * @param {string} [project] - Optional project identifier
+   */
+  function invalidateAuthorCache(project) {
+    if (project !== undefined) {
+      authorCacheMap.delete(project);
+    } else {
+      authorCacheMap.clear();
+    }
+  }
+
+  return {
+    readState,
+    writeState,
+    getAuthorCache,
+    setAuthorCache,
+    invalidateAuthorCache,
+  };
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@sfrangulov/shared-memory-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Claude Shared Memory — turns a GitHub repo into a shared team knowledge base",
+  "type": "module",
+  "bin": {
+    "shared-memory-mcp": "github-memory-server.js"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "github-memory-server.js",
+    "lib/"
+  ],
+  "scripts": {
+    "start": "node github-memory-server.js",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "zod": "^3.24.0",
+    "@octokit/rest": "^22.0.0",
+    "@octokit/plugin-retry": "^8.0.0",
+    "@octokit/plugin-throttling": "^11.0.0",
+    "p-limit": "^7.0.0",
+    "transliteration": "^2.6.0"
+  },
+  "devDependencies": {
+    "vitest": "^3.0.0"
+  }
+}