@iwo-szapar/data-mcp 0.3.2 → 0.4.0

package/dist/adapter/factory.js

@@ -5,12 +5,16 @@
  */
 import { PocketBaseAdapter } from './pocketbase.js';
 import { SupabaseAdapter } from './supabase.js';
+import { MarkdownAdapter } from './markdown.js';
 import { SchemaMap, SchemaMapProxy } from './schema-map.js';
 export function createAdapter(config) {
     let adapter;
     if (config.backend === 'pocketbase') {
         adapter = new PocketBaseAdapter(config.pocketbaseUrl, config.pocketbaseAdminEmail, config.pocketbaseAdminPassword);
     }
+    else if (config.backend === 'markdown') {
+        adapter = new MarkdownAdapter(config.markdownRoot);
+    }
     else {
         adapter = new SupabaseAdapter(config.supabaseUrl, config.supabaseKey);
     }

package/dist/adapter/markdown.d.ts

@@ -0,0 +1,29 @@
+import type { DataAdapter, ListResult, PageOptions, SortClause, Filter } from './types.js';
+export declare class MarkdownAdapter implements DataAdapter {
+    private root;
+    readonly backend: 'markdown';
+    constructor(root: string);
+    private collectionDir;
+    private recordPath;
+    private ensureCollection;
+    private readRecord;
+    private writeRecord;
+    create<T extends Record<string, unknown>>(collection: string, data: Record<string, unknown>): Promise<T>;
+    getOne<T extends Record<string, unknown>>(collection: string, id: string): Promise<T>;
+    list<T extends Record<string, unknown>>(collection: string, options?: {
+        filter?: Filter;
+        sort?: SortClause[];
+        page?: PageOptions;
+    }): Promise<ListResult<T>>;
+    textSearch<T extends Record<string, unknown>>(collection: string, query: string, options?: {
+        fields?: string[];
+        filter?: Filter;
+        limit?: number;
+    }): Promise<T[]>;
+    update<T extends Record<string, unknown>>(collection: string, id: string, data: Record<string, unknown>): Promise<T>;
+    delete(collection: string, id: string): Promise<void>;
+    upsert<T extends Record<string, unknown>>(collection: string, data: Record<string, unknown>, uniqueFields: string[]): Promise<T>;
+    count(collection: string, filter?: Filter): Promise<number>;
+    collectionExists(collection: string): Promise<boolean>;
+    listCollections(): Promise<string[]>;
+}

package/dist/adapter/markdown.js

@@ -0,0 +1,406 @@
+/**
+ * Markdown adapter — stores records as YAML-frontmatter markdown files.
+ *
+ * Per-collection layout:
+ *   <root>/<collection>/<id>.md
+ *
+ * Soft-deletes move files to <root>/_archive/<collection>/<id>.md.
+ *
+ * No external YAML library — we ship a minimal frontmatter parser inline
+ * to avoid a new dependency. The frontmatter format we support is a strict
+ * subset of YAML (scalar key:value, string arrays, simple lists). Anything
+ * the brain writes via this adapter is round-trippable; arbitrary
+ * hand-edited YAML is best-effort.
+ *
+ * Spec: docs/prds/active/PRD-SB3-DUAL-MODE-A3-DATA-MCP-MARKDOWN.md
+ * (factory-dev repo)
+ */
+
+import { promises as fs } from 'node:fs';
+import { join, basename } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { AdapterError } from '../errors/adapter-error.js';
+
+export class MarkdownAdapter {
+    root;
+    backend = 'markdown';
+
+    constructor(root) {
+        if (!root) {
+            throw new AdapterError('config', 'MarkdownAdapter requires a non-empty root path');
+        }
+        this.root = root;
+    }
+
+    collectionDir(collection) {
+        validateName(collection, 'collection');
+        return join(this.root, collection);
+    }
+
+    recordPath(collection, id) {
+        validateName(id, 'id');
+        return join(this.collectionDir(collection), `${id}.md`);
+    }
+
+    async ensureCollection(collection) {
+        await fs.mkdir(this.collectionDir(collection), { recursive: true });
+    }
+
+    async readRecord(collection, id) {
+        let raw;
+        try {
+            raw = await fs.readFile(this.recordPath(collection, id), 'utf8');
+        }
+        catch (err) {
+            if (err && err.code === 'ENOENT') {
+                throw new AdapterError('not_found', `record ${collection}/${id} not found`);
+            }
+            throw new AdapterError('io', `failed to read ${collection}/${id}: ${err?.message || err}`);
+        }
+        const { frontmatter, body } = parseFrontmatter(raw);
+        return { ...frontmatter, id, body };
+    }
+
+    async writeRecord(collection, id, data) {
+        await this.ensureCollection(collection);
+        const { body = '', id: _ignored, ...frontmatter } = data;
+        const payload = stringifyFrontmatter({ ...frontmatter, id }, String(body ?? ''));
+        try {
+            await fs.writeFile(this.recordPath(collection, id), payload, 'utf8');
+        }
+        catch (err) {
+            throw new AdapterError('io', `failed to write ${collection}/${id}: ${err?.message || err}`);
+        }
+    }
+
+    async create(collection, data) {
+        const id = (data.id && String(data.id)) || randomUUID();
+        validateName(id, 'id');
+        const now = new Date().toISOString();
+        const record = {
+            ...data,
+            id,
+            created: data.created || now,
+            updated: now,
+        };
+        await this.writeRecord(collection, id, record);
+        return record;
+    }
+
+    async getOne(collection, id) {
+        return this.readRecord(collection, id);
+    }
+
+    async list(collection, options = {}) {
+        const dir = this.collectionDir(collection);
+        const limit = options.page?.limit ?? 50;
+        const offset = options.page?.offset ?? 0;
+        let entries;
+        try {
+            entries = (await fs.readdir(dir)).filter((f) => f.endsWith('.md'));
+        }
+        catch (err) {
+            if (err && err.code === 'ENOENT') {
+                return { items: [], totalItems: 0, page: 0, perPage: limit };
+            }
+            throw new AdapterError('io', `failed to list ${collection}: ${err?.message || err}`);
+        }
+        const all = [];
+        for (const f of entries) {
+            const id = basename(f, '.md');
+            try {
+                all.push(await this.readRecord(collection, id));
+            }
+            catch {
+                // Skip malformed file, continue
+            }
+        }
+        const filtered = options.filter ? applyFilter(all, options.filter) : all;
+        const sorted = options.sort ? applySort(filtered, options.sort) : filtered;
+        const items = sorted.slice(offset, offset + limit);
+        return {
+            items,
+            totalItems: sorted.length,
+            page: Math.floor(offset / limit),
+            perPage: limit,
+        };
+    }
+
+    async textSearch(collection, query, options = {}) {
+        const all = await this.list(collection, { filter: options.filter });
+        const q = String(query).toLowerCase();
+        if (q.length === 0) return [];
+        const fields = options.fields;
+        const ranked = all.items
+            .map((item) => ({ item, score: scoreItem(item, q, fields) }))
+            .filter((r) => r.score > 0)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, options.limit ?? 50)
+            .map((r) => r.item);
+        return ranked;
+    }
+
+    async update(collection, id, data) {
+        const existing = await this.readRecord(collection, id);
+        const merged = { ...existing, ...data, id, updated: new Date().toISOString() };
+        await this.writeRecord(collection, id, merged);
+        return merged;
+    }
+
+    async delete(collection, id) {
+        const src = this.recordPath(collection, id);
+        const archiveDir = join(this.root, '_archive', collection);
+        try {
+            await fs.mkdir(archiveDir, { recursive: true });
+            await fs.rename(src, join(archiveDir, `${id}.md`));
+        }
+        catch (err) {
+            if (err && err.code === 'ENOENT') {
+                throw new AdapterError('not_found', `record ${collection}/${id} not found`);
+            }
+            throw new AdapterError('io', `failed to delete ${collection}/${id}: ${err?.message || err}`);
+        }
+    }
+
+    async upsert(collection, data, uniqueFields) {
+        if (!uniqueFields || uniqueFields.length === 0) {
+            throw new AdapterError('validation', 'upsert requires at least one uniqueField');
+        }
+        const filter = [
+            uniqueFields.map((field) => ({ field, op: 'eq', value: data[field] ?? null })),
+        ];
+        const existing = await this.list(collection, { filter, page: { limit: 1 } });
+        if (existing.items.length > 0) {
+            return this.update(collection, existing.items[0].id, data);
+        }
+        return this.create(collection, data);
+    }
+
+    async count(collection, filter) {
+        // Lightweight count — reuses list() so it respects the same filter semantics.
+        const all = await this.list(collection, { filter });
+        return all.totalItems;
+    }
+
+    async collectionExists(collection) {
+        try {
+            const s = await fs.stat(this.collectionDir(collection));
+            return s.isDirectory();
+        }
+        catch {
+            return false;
+        }
+    }
+
+    async listCollections() {
+        try {
+            const entries = await fs.readdir(this.root, { withFileTypes: true });
+            return entries
+                .filter((e) => e.isDirectory() && !e.name.startsWith('_'))
+                .map((e) => e.name);
+        }
+        catch (err) {
+            if (err && err.code === 'ENOENT') return [];
+            throw new AdapterError('io', `failed to list collections: ${err?.message || err}`);
+        }
+    }
+}
+
+// ─── helpers ────────────────────────────────────────────────────────────────
+
+// Path-traversal guard: ids and collection names cannot contain separators,
+// leading dots, or null bytes. Match PocketBase's record-id constraints
+// loosely; we just need to refuse anything that could escape <root>.
+function validateName(value, label) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new AdapterError('validation', `${label} must be a non-empty string`);
+    }
+    if (value.includes('/') || value.includes('\\') || value.includes('\0') || value.startsWith('.')) {
+        throw new AdapterError('validation', `${label} contains forbidden characters: ${value}`);
+    }
+}
+
+function scoreItem(item, q, fields) {
+    // Default ranking: tag-match (3pts) > title-match (2pts) > body-match (1pt).
+    // If `fields` is specified, only those are searched (with title>body>everything-else fallback).
+    if (fields && fields.length > 0) {
+        for (const f of fields) {
+            const v = item[f];
+            if (typeof v === 'string' && v.toLowerCase().includes(q)) return f === 'tags' ? 3 : f === 'title' ? 2 : 1;
+            if (Array.isArray(v) && v.some((x) => String(x).toLowerCase().includes(q))) return 3;
+        }
+        return 0;
+    }
+    const tags = Array.isArray(item.tags) ? item.tags.map((t) => String(t).toLowerCase()) : [];
+    if (tags.some((t) => t.includes(q))) return 3;
+    if (typeof item.title === 'string' && item.title.toLowerCase().includes(q)) return 2;
+    if (typeof item.body === 'string' && item.body.toLowerCase().includes(q)) return 1;
+    if (typeof item.content === 'string' && item.content.toLowerCase().includes(q)) return 1;
+    return 0;
+}
+
+function applyFilter(items, filter) {
+    // Filter is OR-of-AND groups (matching the existing Filter type).
+    return items.filter((item) =>
+        filter.some((andGroup) => andGroup.every((clause) => matchClause(item, clause))),
+    );
+}
+
+function matchClause(item, clause) {
+    const v = item[clause.field];
+    const target = clause.value;
+    switch (clause.op) {
+        case 'eq': return v === target;
+        case 'neq': return v !== target;
+        case 'gt': return typeof v === 'number' && typeof target === 'number' && v > target;
+        case 'gte': return typeof v === 'number' && typeof target === 'number' && v >= target;
+        case 'lt': return typeof v === 'number' && typeof target === 'number' && v < target;
+        case 'lte': return typeof v === 'number' && typeof target === 'number' && v <= target;
+        case 'like':
+            return typeof v === 'string' && typeof target === 'string'
+                && v.toLowerCase().includes(target.toLowerCase());
+        case 'in':
+            return Array.isArray(target) && target.includes(v);
+        case 'contains':
+            return Array.isArray(v) && v.includes(target);
+        default: return false;
+    }
+}
+
+function applySort(items, sort) {
+    return [...items].sort((a, b) => {
+        for (const s of sort) {
+            const av = a[s.field];
+            const bv = b[s.field];
+            if (av === bv) continue;
+            if (av == null) return s.direction === 'desc' ? 1 : -1;
+            if (bv == null) return s.direction === 'desc' ? -1 : 1;
+            const cmp = av < bv ? -1 : 1;
+            return s.direction === 'desc' ? -cmp : cmp;
+        }
+        return 0;
+    });
+}
+
+// ─── minimal YAML frontmatter parser/serializer ────────────────────────────
+
+function parseFrontmatter(raw) {
+    // Format: `---\n<yaml>\n---\n<body>` (LF or CRLF tolerated).
+    // If no opening `---`, treat entire content as body with no frontmatter.
+    const normalized = raw.replace(/\r\n/g, '\n');
+    if (!normalized.startsWith('---\n') && normalized !== '---' && !normalized.startsWith('---\r')) {
+        return { frontmatter: {}, body: normalized.trim() };
+    }
+    const rest = normalized.slice(4);
+    const endIdx = rest.indexOf('\n---');
+    if (endIdx === -1) {
+        return { frontmatter: {}, body: normalized.trim() };
+    }
+    const yamlBlock = rest.slice(0, endIdx);
+    let body = rest.slice(endIdx + 4);
+    if (body.startsWith('\n')) body = body.slice(1);
+    return { frontmatter: parseSimpleYaml(yamlBlock), body: body.trim() };
+}
+
+function parseSimpleYaml(block) {
+    const out = {};
+    const lines = block.split('\n');
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        const trimmed = line.replace(/\s+$/, '');
+        if (!trimmed || trimmed.startsWith('#')) { i++; continue; }
+        const colonIdx = trimmed.indexOf(':');
+        if (colonIdx === -1) { i++; continue; }
+        const key = trimmed.slice(0, colonIdx).trim();
+        const rawValue = trimmed.slice(colonIdx + 1).trim();
+        if (rawValue === '') {
+            // List (next lines starting with `- `) or empty value
+            const list = [];
+            let j = i + 1;
+            while (j < lines.length && /^\s*-\s+/.test(lines[j])) {
+                list.push(parseScalar(lines[j].replace(/^\s*-\s+/, '').trim()));
+                j++;
+            }
+            if (list.length > 0) {
+                out[key] = list;
+                i = j;
+                continue;
+            }
+            out[key] = null;
+            i++;
+            continue;
+        }
+        if (rawValue.startsWith('[') && rawValue.endsWith(']')) {
+            // Inline array: [a, b, c]
+            const inner = rawValue.slice(1, -1).trim();
+            out[key] = inner === '' ? [] : inner.split(',').map((s) => parseScalar(s.trim()));
+        }
+        else {
+            out[key] = parseScalar(rawValue);
+        }
+        i++;
+    }
+    return out;
+}
+
+function parseScalar(v) {
+    if (v === '' || v === '~' || v === 'null') return null;
+    if (v === 'true') return true;
+    if (v === 'false') return false;
+    // Quoted string
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+        return v.slice(1, -1);
+    }
+    // Number
+    if (/^-?\d+(\.\d+)?$/.test(v)) {
+        const n = Number(v);
+        if (!Number.isNaN(n)) return n;
+    }
+    return v;
+}
+
+function stringifyFrontmatter(frontmatter, body) {
+    const lines = ['---'];
+    for (const [key, value] of Object.entries(frontmatter)) {
+        if (value === undefined) continue;
+        if (value === null) {
+            lines.push(`${key}: null`);
+        }
+        else if (Array.isArray(value)) {
+            if (value.length === 0) {
+                lines.push(`${key}: []`);
+            }
+            else {
+                lines.push(`${key}:`);
+                for (const item of value) {
+                    lines.push(`  - ${stringifyScalar(item)}`);
+                }
+            }
+        }
+        else if (typeof value === 'object') {
+            // Nested object — serialize as JSON to preserve roundtrip.
+            // The brain's frontmatter rarely uses nested objects; this is a
+            // pragmatic fallback that the parser will read back as a string.
+            lines.push(`${key}: ${JSON.stringify(value)}`);
+        }
+        else {
+            lines.push(`${key}: ${stringifyScalar(value)}`);
+        }
+    }
+    lines.push('---');
+    lines.push('');
+    return lines.join('\n') + body + (body.endsWith('\n') ? '' : '\n');
+}
+
+function stringifyScalar(v) {
+    if (v === null || v === undefined) return 'null';
+    if (typeof v === 'boolean') return v ? 'true' : 'false';
+    if (typeof v === 'number') return String(v);
+    const s = String(v);
+    // Quote if contains special chars
+    if (/[:#\n\[\]{}"',&*!|>%@`]/.test(s) || s.trim() !== s || s === '') {
+        return JSON.stringify(s);
+    }
+    return s;
+}

package/dist/adapter/types.d.ts

@@ -34,7 +34,7 @@ export interface ListResult<T> {
 }
 export interface DataAdapter {
     /** Backend identifier */
-    readonly backend: 'pocketbase' | 'supabase';
+    readonly backend: 'pocketbase' | 'supabase' | 'markdown';
     /** Create a record in a collection */
     create<T extends Record<string, unknown>>(collection: string, data: Record<string, unknown>): Promise<T>;
     /** Get a single record by ID */

package/dist/config.js

@@ -1,19 +1,21 @@
 /**
  * Configuration parsing from environment variables.
  *
- * SB_BACKEND: 'pocketbase' | 'supabase' (required)
+ * SB_BACKEND: 'pocketbase' | 'supabase' | 'markdown' (required)
  * SB_POCKETBASE_URL: PocketBase server URL (required if backend=pocketbase)
  * SB_POCKETBASE_ADMIN_EMAIL: PocketBase admin email (required if backend=pocketbase)
  * SB_POCKETBASE_ADMIN_PASSWORD: PocketBase admin password (required if backend=pocketbase)
  * SB_SUPABASE_URL: Supabase project URL (required if backend=supabase)
  * SB_SUPABASE_KEY: Supabase service role key (required if backend=supabase)
+ * SB_MARKDOWN_ROOT: filesystem path to the memory/ folder (required if backend=markdown)
  * SB_SCHEMA_MAP: JSON string mapping logical names to actual table names (optional)
  * SB_RESEND_API_KEY: Resend API key for email sending (optional)
  */
+const ALLOWED_BACKENDS = ['pocketbase', 'supabase', 'markdown'];
 export function parseConfig() {
     const backend = requireEnv('SB_BACKEND');
-    if (backend !== 'pocketbase' && backend !== 'supabase') {
-        throw new Error(`SB_BACKEND must be 'pocketbase' or 'supabase', got '${backend}'`);
+    if (!ALLOWED_BACKENDS.includes(backend)) {
+        throw new Error(`SB_BACKEND must be one of ${ALLOWED_BACKENDS.join('|')}, got '${backend}'`);
     }
     const schemaMap = parseSchemaMap(process.env.SB_SCHEMA_MAP);
     const resendApiKey = process.env.SB_RESEND_API_KEY || undefined;
@@ -27,6 +29,14 @@ export function parseConfig() {
             resendApiKey,
         };
     }
+    if (backend === 'markdown') {
+        return {
+            backend,
+            markdownRoot: requireEnv('SB_MARKDOWN_ROOT'),
+            schemaMap,
+            resendApiKey,
+        };
+    }
     return {
         backend,
         supabaseUrl: requireEnv('SB_SUPABASE_URL'),

package/dist/server.js

@@ -30,7 +30,7 @@ const SERVER_INSTRUCTIONS = `You are the user's AI Second Brain data layer. This
 export function createServer(adapter) {
     const server = new McpServer({
         name: '@iwo-szapar/data-mcp',
-        version: '0.3.2',
+        version: '0.3.3',
     }, {
         instructions: SERVER_INSTRUCTIONS,
     });

package/dist/tools/memory/link-create.js

@@ -12,9 +12,9 @@ export function registerLinkCreate(server, adapter) {
         'Links express how knowledge items relate: supports, contradicts, derived_from, etc. ' +
         'Deduplicates by (source, target, relation_type).', {
         source_type: z.enum(ENTITY_TYPES).describe('Type of the source entity'),
-        source_id: z.string().uuid().describe('UUID of the source entity'),
+        source_id: z.string().min(1).max(50).describe('ID of the source entity (UUID on Supabase, 15-char native ID on PocketBase)'),
         target_type: z.enum(ENTITY_TYPES).describe('Type of the target entity'),
-        target_id: z.string().uuid().describe('UUID of the target entity'),
+        target_id: z.string().min(1).max(50).describe('ID of the target entity (UUID on Supabase, 15-char native ID on PocketBase)'),
         relation_type: z.enum(RELATION_TYPES).describe('Type of relationship'),
         confidence: z.number().min(0).max(1).optional().default(0.8).describe('Confidence in this relationship (0-1)'),
         notes: z.string().max(500).optional().describe('Optional context for why this link exists'),

package/dist/tools/memory/link-delete.js

@@ -7,7 +7,7 @@ import { z } from 'zod';
 import { makeToolResponse, handleAdapterError, withGracefulDegradation } from '../shared.js';
 export function registerLinkDelete(server, adapter) {
     server.tool('link_delete', 'Delete a knowledge link by its ID.', {
-        link_id: z.string().uuid().describe('UUID of the link to delete'),
+        link_id: z.string().min(1).max(50).describe('ID of the link to delete'),
     }, withGracefulDegradation('knowledge_links', adapter, async (params) => {
         try {
             try {

package/dist/tools/memory/link-related.js

@@ -9,7 +9,7 @@ const ENTITY_TYPES = ['knowledge', 'decision', 'session', 'blog_post', 'prospect
 export function registerLinkRelated(server, adapter) {
     server.tool('link_related', 'Get all links for an entity. Shows outgoing and incoming relationships with resolved titles.', {
         entity_type: z.enum(ENTITY_TYPES).describe('Type of the entity'),
-        entity_id: z.string().uuid().describe('UUID of the entity'),
+        entity_id: z.string().min(1).max(50).describe('ID of the entity (UUID on Supabase, 15-char native ID on PocketBase)'),
         direction: z.enum(['both', 'outgoing', 'incoming']).optional().default('both').describe('Filter direction'),
         relation_type: z.enum(['supports', 'contradicts', 'derived_from', 'example_of', 'supersedes', 'part_of', 'prerequisite'])
             .optional().describe('Filter by relation type'),

package/dist/tools/memory/link-suggest.js

@@ -8,7 +8,7 @@ import { makeToolResponse, handleAdapterError, withGracefulDegradation } from '.
 export function registerLinkSuggest(server, adapter) {
     server.tool('link_suggest', 'Find knowledge items similar to a given item and suggest links. ' +
         'Uses text search to find related items. Returns matches with suggested relation types.', {
-        item_id: z.string().uuid().describe('UUID of the knowledge item to find suggestions for'),
+        item_id: z.string().min(1).max(50).describe('ID of the knowledge item to find suggestions for'),
         limit: z.number().min(1).max(20).optional().default(5).describe('Max suggestions'),
     }, withGracefulDegradation('knowledge', adapter, async (params) => {
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iwo-szapar/data-mcp",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Unified data MCP server for Second Brain — PocketBase and Supabase adapters. 40 tools: knowledge, sessions, goals, tasks, contacts, CRM, blog, email, content calendar.",
   "author": "Iwo Szapar <iwo.szapar@gmail.com> (https://iwoszapar.com)",
   "homepage": "https://iwoszapar.com/second-brain-ai",