limbo-ai 1.0.0

package/mcp-server/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "limbo-vault-mcp",
+  "version": "1.0.0",
+  "description": "Vault MCP server for Limbo — exposes vault_search, vault_read, vault_write_note, vault_update_map",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/mcp-server/tools/read.js

@@ -0,0 +1,30 @@
+import { readFile } from "fs/promises";
+import { join } from "path";
+
+const VAULT_PATH = process.env.VAULT_PATH || "/data/vault";
+const NOTES_DIR = join(VAULT_PATH, "notes");
+
+/**
+ * vault_read(noteId): reads full content of a note by ID.
+ * Returns the raw markdown content including YAML frontmatter.
+ * Returns null if the note doesn't exist.
+ */
+export async function vaultRead(noteId) {
+  if (!noteId || typeof noteId !== "string") {
+    throw new Error("noteId must be a non-empty string");
+  }
+
+  // Sanitize: only allow alphanumeric, dashes, underscores
+  const safe = noteId.replace(/[^a-zA-Z0-9_\-]/g, "");
+  if (safe !== noteId) {
+    throw new Error("noteId contains invalid characters");
+  }
+
+  const filePath = join(NOTES_DIR, `${safe}.md`);
+  try {
+    return await readFile(filePath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+}

package/mcp-server/tools/search.js

@@ -0,0 +1,85 @@
+import { readdir, readFile } from "fs/promises";
+import { join, basename } from "path";
+
+const VAULT_PATH = process.env.VAULT_PATH || "/data/vault";
+const NOTES_DIR = join(VAULT_PATH, "notes");
+
+/**
+ * Extracts the title from YAML frontmatter or first H1 heading.
+ */
+function extractTitle(content) {
+  const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (fmMatch) {
+    const titleMatch = fmMatch[1].match(/^title:\s*["']?(.+?)["']?\s*$/m);
+    if (titleMatch) return titleMatch[1];
+  }
+  const h1Match = content.match(/^#\s+(.+)$/m);
+  if (h1Match) return h1Match[1];
+  return null;
+}
+
+/**
+ * Finds a short snippet around the first match.
+ */
+function extractSnippet(content, regex, maxLen = 150) {
+  regex.lastIndex = 0;
+  const match = regex.exec(content);
+  regex.lastIndex = 0;
+  if (!match) return "";
+  const start = Math.max(0, match.index - 60);
+  const end = Math.min(content.length, match.index + maxLen);
+  let snippet = content.slice(start, end).replace(/\n/g, " ").trim();
+  if (start > 0) snippet = "..." + snippet;
+  if (end < content.length) snippet += "...";
+  return snippet;
+}
+
+/**
+ * vault_search(query): regex search across all .md files in /data/vault/notes/.
+ * Returns [{noteId, title, snippet, score}] sorted by score desc.
+ *
+ * NOTE: Current implementation is a linear scan (O(n) per query). This is fine
+ * for small vaults (hundreds of notes), but will need optimization at scale —
+ * consider an inverted index (e.g. SQLite FTS5) when the vault grows large.
+ */
+export async function vaultSearch(query) {
+  let files;
+  try {
+    files = await readdir(NOTES_DIR);
+  } catch {
+    return [];
+  }
+
+  const mdFiles = files.filter((f) => f.endsWith(".md"));
+  let regex;
+  try {
+    regex = new RegExp(query, "gi");
+  } catch {
+    // Fallback to literal search if invalid regex
+    regex = new RegExp(query.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "gi");
+  }
+
+  const results = [];
+  for (const file of mdFiles) {
+    const filePath = join(NOTES_DIR, file);
+    let content;
+    try {
+      content = await readFile(filePath, "utf8");
+    } catch {
+      continue;
+    }
+
+    const matches = content.match(regex);
+    if (!matches) continue;
+
+    const noteId = basename(file, ".md");
+    const title = extractTitle(content) || noteId;
+    const score = matches.length;
+    const snippet = extractSnippet(content, regex);
+
+    results.push({ noteId, title, snippet, score });
+  }
+
+  results.sort((a, b) => b.score - a.score);
+  return results;
+}

package/mcp-server/tools/update-map.js

@@ -0,0 +1,74 @@
+import { readFile, writeFile, mkdir } from "fs/promises";
+import { join } from "path";
+
+const VAULT_PATH = process.env.VAULT_PATH || "/data/vault";
+const MAPS_DIR = join(VAULT_PATH, "maps");
+
+/**
+ * Sanitizes a map name (filename without extension).
+ */
+function sanitizeName(name) {
+  const safe = name.replace(/[^a-zA-Z0-9_\-]/g, "");
+  if (safe !== name) throw new Error(`Invalid characters in name: ${name}`);
+  return safe;
+}
+
+/**
+ * Finds or creates a section in markdown content.
+ * Returns the updated content string.
+ */
+function upsertSection(content, section, entries) {
+  const sectionHeader = `## ${section}`;
+  const lines = content.split("\n");
+
+  const sectionIdx = lines.findIndex((l) => l.trim() === sectionHeader);
+
+  if (sectionIdx === -1) {
+    // Section doesn't exist — append it
+    const toAdd = ["", sectionHeader, "", ...entries, ""];
+    return lines.concat(toAdd).join("\n");
+  }
+
+  // Find where the section ends (next ## or EOF)
+  let insertIdx = sectionIdx + 1;
+  while (insertIdx < lines.length && !lines[insertIdx].startsWith("## ")) {
+    insertIdx++;
+  }
+
+  // Insert entries before the next section (or EOF)
+  lines.splice(insertIdx, 0, ...entries);
+  return lines.join("\n");
+}
+
+/**
+ * vault_update_map(map, section, entries): appends entries to a MOC section.
+ * Creates the section if it doesn't exist.
+ * Entries are markdown link strings, e.g. ["[[note-id|Note Title]]"]
+ *
+ * @param {string} map - map filename without extension
+ * @param {string} section - section heading text
+ * @param {string[]} entries - array of markdown link strings to append
+ */
+export async function vaultUpdateMap(map, section, entries) {
+  if (!map || typeof map !== "string") throw new Error("map must be a non-empty string");
+  if (!section || typeof section !== "string") throw new Error("section must be a non-empty string");
+  if (!Array.isArray(entries) || entries.length === 0) throw new Error("entries must be a non-empty array");
+
+  const safeMap = sanitizeName(map);
+  await mkdir(MAPS_DIR, { recursive: true });
+
+  const filePath = join(MAPS_DIR, `${safeMap}.md`);
+
+  let existing = "";
+  try {
+    existing = await readFile(filePath, "utf8");
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+    // New map — start with a title
+    existing = `# ${map}\n`;
+  }
+
+  const updated = upsertSection(existing, section, entries);
+  await writeFile(filePath, updated, "utf8");
+  return { map: safeMap, section, added: entries.length };
+}

package/mcp-server/tools/write.js

@@ -0,0 +1,52 @@
+import { writeFile, mkdir } from "fs/promises";
+import { join } from "path";
+
+const VAULT_PATH = process.env.VAULT_PATH || "/data/vault";
+const NOTES_DIR = join(VAULT_PATH, "notes");
+
+const REQUIRED_FIELDS = ["id", "title", "type", "description", "content"];
+
+/**
+ * Builds YAML frontmatter string from note metadata.
+ */
+function buildFrontmatter(note) {
+  const lines = ["---"];
+  lines.push(`id: ${note.id}`);
+  lines.push(`title: "${note.title.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`);
+  lines.push(`type: ${note.type}`);
+  lines.push(`description: "${note.description.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`);
+  if (note.map) {
+    lines.push(`map: ${note.map}`);
+  }
+  lines.push(`created: ${new Date().toISOString().split("T")[0]}`);
+  lines.push("---");
+  return lines.join("\n");
+}
+
+/**
+ * vault_write_note(note): creates a markdown file with YAML frontmatter.
+ * Input: {id, title, type, description, content, map?}
+ * Writes to /data/vault/notes/{id}.md
+ */
+export async function vaultWriteNote(note) {
+  for (const field of REQUIRED_FIELDS) {
+    if (!note[field] || typeof note[field] !== "string") {
+      throw new Error(`Missing or invalid required field: ${field}`);
+    }
+  }
+
+  // Sanitize id
+  const safe = note.id.replace(/[^a-zA-Z0-9_\-]/g, "");
+  if (safe !== note.id) {
+    throw new Error("note.id contains invalid characters");
+  }
+
+  await mkdir(NOTES_DIR, { recursive: true });
+
+  const frontmatter = buildFrontmatter(note);
+  const fileContent = `${frontmatter}\n\n${note.content}\n`;
+  const filePath = join(NOTES_DIR, `${safe}.md`);
+
+  await writeFile(filePath, fileContent, "utf8");
+  return { id: safe, path: filePath };
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "limbo-ai",
+  "version": "1.0.0",
+  "description": "Your personal AI memory agent — install and manage Limbo via npx",
+  "type": "commonjs",
+  "bin": {
+    "limbo": "./cli.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node cli.js start"
+  },
+  "keywords": [
+    "limbo",
+    "ai",
+    "memory",
+    "agent",
+    "openclaw",
+    "personal"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TomasWard1/limbo.git"
+  }
+}