@jacklika/dsh-memory-mcp 0.1.3 → 0.1.4-alpha.1

package/README.md

@@ -1,6 +1,6 @@
 # @jacklika/dsh-memory-mcp
 
-Zero-dependency MCP stdio server that exposes the memory vault to any MCP client (Claude Code, Cursor, Obsidian bridges, `dsh-mcp-client`). One process owns every write, so clients serialize through the server instead of negotiating filesystem locks — this is the "single writer" deployment of the memory suite.
+MCP stdio server that exposes the memory vault to any MCP client (Claude Code, Cursor, Obsidian bridges, `dsh-mcp-client`). One process owns every write, so clients serialize through the server instead of negotiating filesystem locks — this is the "single writer" deployment of the memory suite.
 
 ## Run
 
@@ -16,7 +16,7 @@ npx dsh-memory-mcp --vault /path/to/vault
 
 ## Surface
 
-Tools: `wiki_read`, `wiki_search`, `wiki_write`, `wiki_graph` — same contract as `@jacklika/dsh-tool-memory-filesystem` / `-graph`, including `baseVersion` optimistic concurrency on writes. Resources: `note:///<id>` over `resources/list` / `resources/read`.
+Tools: `wiki_read`, `wiki_search`, `wiki_write`, `wiki_graph` — same contract as `@jacklika/dsh-tool-memory-filesystem` / `-graph`, including `baseVersion` optimistic concurrency on writes, `mtime` + `modifiedExternally` on reads, and `+08:00` `created`/`updated` normalization on writes. Resources: `note:///<id>` over `resources/list` / `resources/read`.
 
 ## Client configuration
 

package/README.zh.md

@@ -1,6 +1,6 @@
 # @jacklika/dsh-memory-mcp
 
-零依赖的 MCP stdio 服务器，把 memory vault 暴露给任意 MCP 客户端（Claude Code、Cursor、Obsidian 桥、`dsh-mcp-client`）。单一进程持有所有写操作，因此客户端通过服务器串行化，而不是自己协商文件系统锁——这是 memory 套件的“单写者”部署形态。
+MCP stdio 服务器，把 memory vault 暴露给任意 MCP 客户端（Claude Code、Cursor、Obsidian 桥、`dsh-mcp-client`）。单一进程持有所有写操作，因此客户端通过服务器串行化，而不是自己协商文件系统锁——这是 memory 套件的“单写者”部署形态。
 
 ## 运行
 
@@ -16,7 +16,7 @@ npx dsh-memory-mcp --vault /path/to/vault
 
 ## 暴露面
 
-工具：`wiki_read`、`wiki_search`、`wiki_write`、`wiki_graph` —— 与 `@jacklika/dsh-tool-memory-filesystem` / `-graph` 的契约相同，写操作带 `baseVersion` 乐观并发控制。资源：通过 `resources/list` / `resources/read` 访问 `note:///<id>`。
+工具：`wiki_read`、`wiki_search`、`wiki_write`、`wiki_graph` —— 与 `@jacklika/dsh-tool-memory-filesystem` / `-graph` 的契约相同，写操作带 `baseVersion` 乐观并发控制，读操作返回 `mtime` + `modifiedExternally`，写入归一化 `created`/`updated` 为 `+08:00`。资源：通过 `resources/list` / `resources/read` 访问 `note:///<id>`。
 
 ## 客户端配置
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jacklika/dsh-memory-mcp",
-  "description": "Zero-dependency MCP stdio server exposing the memory vault to any MCP client — one process owns all writes.",
-  "version": "0.1.3",
+  "description": "MCP stdio server exposing the memory vault to any MCP client — one process owns all writes.",
+  "version": "0.1.4-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -30,6 +30,7 @@
     "README.zh.md"
   ],
   "dependencies": {
+    "js-yaml": "^4.2.0",
     "@jacklika/dsh-memory-time": "^0.1.0-alpha.0"
   },
   "license": "MIT"

package/src/server.mjs

@@ -1,18 +1,19 @@
 #!/usr/bin/env node
 /**
- * @jacklika/dsh-memory-mcp — a zero-dependency MCP stdio server exposing the
- * memory vault to any MCP client. One process owns all writes, so clients
- * serialize through the server instead of negotiating filesystem locks.
+ * @jacklika/dsh-memory-mcp — an MCP stdio server exposing the memory vault to
+ * any MCP client. One process owns all writes, so clients serialize through
+ * the server instead of negotiating filesystem locks.
  *
  * Usage: dsh-memory-mcp [--vault <path>] [--max-link-depth N]
  *   --vault defaults to <cwd>/.plugins/memory/ to match the Bundle default.
  */
 import { createHash, randomUUID } from 'node:crypto'
-import { mkdir, readdir, readFile, realpath, rename, rm, writeFile } from 'node:fs/promises'
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { mkdir, readdir, readFile, realpath, rename, rm, stat, writeFile } from 'node:fs/promises'
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
 import process from 'node:process'
 import readline from 'node:readline'
 import { formatBeijingTime } from '@jacklika/dsh-memory-time'
+import yaml from 'js-yaml'
 
 const PROTOCOL_VERSION = '2024-11-05'
 const SERVER_INFO = { name: 'dsh-memory-mcp', version: '0.1.0' }
@@ -66,28 +67,128 @@ async function containedPathReal(candidate) {
   }
 }
 
+// Mirrors splitFrontmatter in @jacklika/dsh-tool-memory-filesystem so notes
+// written by external editors (CRLF, unquoted timestamps, YAML lists) read
+// the same through MCP as through the dsh tools.
 function splitFrontmatter(text) {
-  if (!text.startsWith('---\n')) return { frontmatter: {}, body: text }
-  const end = text.indexOf('\n---\n', 4)
-  if (end < 0) return { frontmatter: {}, body: text }
-  const frontmatter = {}
-  for (const line of text.slice(4, end).split('\n')) {
-    const m = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line)
-    if (m) frontmatter[m[1]] = m[2]
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/.exec(text)
+  if (match === null) return { frontmatter: {}, body: text }
+  const frontmatterText = match[1] ?? ''
+  const bodyText = match[2] ?? ''
+  try {
+    const parsed = yaml.load(frontmatterText)
+    const frontmatter = parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? parsed
+      : {}
+    for (const [key, value] of Object.entries(frontmatter)) {
+      if (value instanceof Date) frontmatter[key] = formatBeijingTime(value)
+    }
+    return { frontmatter, body: bodyText }
+  } catch {
+    return { frontmatter: {}, body: text }
   }
-  return { frontmatter, body: text.slice(end + 5) }
 }
 
 function noteVersion(text) {
   return createHash('sha1').update(text).digest('hex')
 }
 
+// Mirrors the mtime tracking and timestamp normalization in
+// @jacklika/dsh-tool-memory-filesystem so MCP clients see the same
+// modifiedExternally flag and +08:00 write normalization as the dsh tools.
+const observedMtimes = new Map()
+const OBSERVED_MTIME_LIMIT = 256
+
+function recordMtime(path, mtimeMs) {
+  observedMtimes.delete(path)
+  observedMtimes.set(path, mtimeMs)
+  if (observedMtimes.size > OBSERVED_MTIME_LIMIT) {
+    const oldest = observedMtimes.keys().next().value
+    if (oldest !== undefined) observedMtimes.delete(oldest)
+  }
+}
+
+function detectExternalChange(path, mtimeMs) {
+  const seen = observedMtimes.get(path)
+  recordMtime(path, mtimeMs)
+  return seen !== undefined && seen !== mtimeMs
+}
+
+function normalizeNoteTimestamps(frontmatter) {
+  for (const key of ['created', 'updated']) {
+    const value = frontmatter[key]
+    if (typeof value !== 'string') continue
+    const parsed = new Date(value)
+    if (Number.isNaN(parsed.getTime())) continue
+    const normalized = formatBeijingTime(parsed)
+    if (normalized !== value) frontmatter[key] = normalized
+  }
+}
+
+function normalizeTextTimestamps(text) {
+  const { frontmatter, body } = splitFrontmatter(text)
+  if (Object.keys(frontmatter).length === 0) return text
+  normalizeNoteTimestamps(frontmatter)
+  return `---\n${yaml.dump(frontmatter).trim()}\n---\n${body}`
+}
+
 function extractLinks(text) {
   const links = []
-  for (const m of text.matchAll(/\[\[([^\]|]+)(?:\|[^\]]*)?\]\]/g)) links.push(m[1].trim())
+  for (const m of stripCode(text).matchAll(/\[\[([^\]|]+)(?:\|[^\]]*)?\]\]/g)) links.push(m[1].trim())
   return links
 }
 
+/**
+ * Remove fenced code blocks and inline code spans so literal `[[...]]` inside
+ * them is not treated as a link. Fences follow CommonMark: a closing fence
+ * must use the same marker character and be at least as long as the opener —
+ * a rule a regex backreference cannot express, so fences are scanned line by
+ * line. Inline spans treat backtick runs as maximal units: a run closes only
+ * at a later run of exactly equal length; an unmatched run is literal text.
+ */
+function stripCode(text) {
+  const kept = []
+  let fenceChar = ''
+  let fenceLen = 0
+  for (const line of text.split('\n')) {
+    if (fenceChar === '') {
+      const open = /^( {0,3})(`{3,}|~{3,})/.exec(line)
+      if (open?.[2] !== undefined) {
+        fenceChar = open[2][0] ?? ''
+        fenceLen = open[2].length
+        continue
+      }
+      kept.push(line)
+    } else if (new RegExp(`^ {0,3}${fenceChar === '`' ? '`' : '~'}{${fenceLen},}[ \t]*$`).test(line)) {
+      fenceChar = ''
+    }
+  }
+  const body = kept.join('\n')
+  let out = ''
+  let i = 0
+  while (i < body.length) {
+    if (body[i] !== '`') {
+      out += body[i]
+      i++
+      continue
+    }
+    let j = i
+    while (body[j] === '`') j++
+    const run = body.slice(i, j)
+    let close = body.indexOf(run, j)
+    while (close !== -1 && (body[close - 1] === '`' || body[close + run.length] === '`')) {
+      close = body.indexOf(run, close + 1)
+    }
+    if (close === -1) {
+      out += run
+      i = j
+      continue
+    }
+    i = close + run.length
+  }
+  return out
+}
+
 async function listNotePaths(dir = VAULT) {
   const results = []
   let entries
@@ -105,7 +206,66 @@ async function listNotePaths(dir = VAULT) {
   return results
 }
 
-async function resolveLinkTarget(link) {
+/**
+ * Build a resolver over the known note ids, matching Obsidian semantics: an
+ * exact vault-relative path first, then a path-suffix match, then a bare
+ * basename match — each tier tolerates the target carrying or omitting the
+ * extension. Ambiguity within a tier resolves to the id with the fewest path
+ * segments, ties by code-unit order, so results are identical across hosts.
+ */
+function createLinkResolver(ids) {
+  const entries = ids.map(id => {
+    const stem = id.replace(/\.[^./]+$/, '')
+    return {
+      id,
+      stem,
+      basenameId: id.slice(id.lastIndexOf('/') + 1),
+      basenameStem: stem.slice(stem.lastIndexOf('/') + 1),
+      segments: id.split('/').length,
+    }
+  })
+  // O(1) lookup tables keyed by every segment-boundary suffix of each id and
+  // stem: an exact hit is the full-string key, a path-suffix hit is a proper
+  // suffix, and a basename hit is the last segment.
+  const exact = new Map()
+  const suffix = new Map()
+  const basename = new Map()
+  const add = (table, key, entry) => {
+    const list = table.get(key)
+    if (list === undefined) table.set(key, [entry])
+    else list.push(entry)
+  }
+  for (const entry of entries) {
+    add(basename, entry.basenameId, entry)
+    add(basename, entry.basenameStem, entry)
+    for (const s of [entry.id, entry.stem]) {
+      let boundary = -1
+      while ((boundary = s.indexOf('/', boundary + 1)) !== -1) {
+        add(suffix, s.slice(boundary + 1), entry)
+      }
+      add(exact, s, entry)
+    }
+  }
+  const pick = matches => {
+    if (matches === undefined || matches.length === 0) return undefined
+    matches.sort((a, b) => a.segments - b.segments || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+    return matches[0].id
+  }
+  return target => {
+    const t = target.replace(/\\/g, '/')
+    return pick(exact.get(t)) ?? pick(suffix.get(t)) ?? pick(basename.get(t))
+  }
+}
+
+async function vaultLinkResolver() {
+  return createLinkResolver((await listNotePaths()).map(p => vaultRelativeId(p)))
+}
+
+async function resolveLinkTarget(link, resolve) {
+  if (resolve !== undefined) {
+    const id = resolve(link)
+    if (id !== undefined) return containedPathReal(id)
+  }
   for (const candidate of [link, ...EXTENSIONS.map(ext => `${link}${ext}`)]) {
     try {
       const p = await containedPathReal(candidate)
@@ -115,15 +275,10 @@ async function resolveLinkTarget(link) {
       if (error?.code !== 'ENOENT') throw error
     }
   }
-  // search by basename among indexed notes
-  const want = basename(link).replace(/\.[^.]+$/, '')
-  for (const p of await listNotePaths()) {
-    if (basename(p).replace(/\.[^.]+$/, '') === want) return p
-  }
   return undefined
 }
 
-async function readNote(absolutePath, depth, visited = new Set()) {
+async function readNote(absolutePath, depth, visited = new Set(), resolve) {
   const id = vaultRelativeId(absolutePath)
   if (visited.has(absolutePath)) {
     return { id, frontmatter: {}, body: '', links: [], version: '', linkedNotes: [] }
@@ -135,9 +290,10 @@ async function readNote(absolutePath, depth, visited = new Set()) {
   const links = extractLinks(text)
   const linkedNotes = []
   if (depth > 0) {
+    resolve ??= await vaultLinkResolver()
     for (const link of links) {
-      const target = await resolveLinkTarget(link)
-      if (target !== undefined) linkedNotes.push(await readNote(target, depth - 1, next))
+      const target = await resolveLinkTarget(link, resolve)
+      if (target !== undefined) linkedNotes.push(await readNote(target, depth - 1, next, resolve))
     }
   }
   return { id, frontmatter, body, links, version: noteVersion(text), linkedNotes }
@@ -157,7 +313,7 @@ async function searchNotes(query, maxResults = 20) {
     const haystack = `${n.id} ${n.title} ${n.body}`.toLowerCase()
     return terms.every(t => haystack.includes(t))
   })
-  hits.sort((a, b) => a.id.localeCompare(b.id))
+  hits.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
   return hits.slice(0, maxResults).map(({ id, title }) => ({ id, title }))
 }
 
@@ -178,11 +334,12 @@ async function writeNote(id, content, mode = 'append', baseVersion) {
   }
   let finalBody
   if (mode === 'overwrite') {
-    finalBody = content
+    finalBody = normalizeTextTimestamps(content)
   } else {
     const { frontmatter, body } = splitFrontmatter(existing ?? '')
+    normalizeNoteTimestamps(frontmatter)
     const fm = Object.keys(frontmatter).length > 0
-      ? `---\n${Object.entries(frontmatter).map(([k, v]) => `${k}: ${v}`).join('\n')}\n---\n\n`
+      ? `---\n${yaml.dump(frontmatter).trimEnd()}\n---\n\n`
       : ''
     finalBody = `${fm}${body}\n\n## ${formatBeijingTime(new Date())}\n\n${content}\n`
   }
@@ -194,6 +351,7 @@ async function writeNote(id, content, mode = 'append', baseVersion) {
     await rm(tmp, { force: true }).catch(() => undefined)
     throw error
   }
+  recordMtime(absolutePath, (await stat(absolutePath)).mtimeMs)
   return { id: vaultRelativeId(absolutePath), mode, bytes: Buffer.byteLength(finalBody, 'utf8') }
 }
 
@@ -204,6 +362,7 @@ async function buildGraph(id, depth = 1, maxNodes = 200) {
     return /^#\s+(.+)$/m.exec(body)?.[1]?.trim() ?? idOf(p).replace(/\.[^.]+$/, '')
   }
   let paths
+  const resolve = await vaultLinkResolver()
   if (id === undefined) {
     paths = await listNotePaths()
   } else {
@@ -214,7 +373,7 @@ async function buildGraph(id, depth = 1, maxNodes = 200) {
       const next = []
       for (const p of frontier) {
         for (const link of extractLinks(await readFile(p, 'utf8'))) {
-          const t = await resolveLinkTarget(link)
+          const t = await resolveLinkTarget(link, resolve)
           if (t !== undefined && !seen.has(idOf(t))) { seen.set(idOf(t), t); next.push(t) }
         }
       }
@@ -230,7 +389,7 @@ async function buildGraph(id, depth = 1, maxNodes = 200) {
   for (const p of capped) {
     nodes.push({ id: idOf(p), title: await title(p) })
     for (const link of extractLinks(await readFile(p, 'utf8'))) {
-      const t = await resolveLinkTarget(link)
+      const t = await resolveLinkTarget(link, resolve)
       if (t !== undefined && idSet.has(idOf(t))) edges.push({ from: idOf(p), to: idOf(t) })
     }
   }
@@ -242,7 +401,7 @@ async function buildGraph(id, depth = 1, maxNodes = 200) {
 const TOOLS = [
   {
     name: 'wiki_read',
-    description: 'Read one Markdown note from the wiki vault, following Obsidian-style [[link]] references up to the configured depth.',
+    description: 'Read one Markdown note from the wiki vault, following Obsidian-style [[link]] references up to the configured depth. Returns mtime and modifiedExternally alongside frontmatter, body, links, and version.',
     inputSchema: {
       type: 'object',
       properties: { id: { type: 'string', description: 'Vault-relative path of the note (e.g. "concepts/RAG.md").' } },
@@ -287,8 +446,16 @@ const TOOLS = [
 
 async function callTool(name, a = {}) {
   switch (name) {
-    case 'wiki_read':
-      return readNote(await containedPathReal(a.id), MAX_LINK_DEPTH)
+    case 'wiki_read': {
+      const absolutePath = await containedPathReal(a.id)
+      const note = await readNote(absolutePath, MAX_LINK_DEPTH)
+      const info = await stat(absolutePath)
+      return {
+        ...note,
+        mtime: formatBeijingTime(info.mtime),
+        modifiedExternally: detectExternalChange(absolutePath, info.mtimeMs),
+      }
+    }
     case 'wiki_search':
       return searchNotes(a.query ?? '')
     case 'wiki_write':