@iwo-szapar/data-mcp 0.2.1 → 0.3.0

package/dist/tools/memory/link-create.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { DataAdapter } from '../../adapter/types.js';
+export declare function registerLinkCreate(server: McpServer, adapter: DataAdapter): void;
+//# sourceMappingURL=link-create.d.ts.map

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

@@ -0,0 +1,67 @@
+/**
+ * Tool: link_create
+ *
+ * Creates a typed relationship between two MemoryOS entities.
+ */
+import { z } from 'zod';
+import { makeToolResponse, handleAdapterError, withGracefulDegradation } from '../shared.js';
+const ENTITY_TYPES = ['knowledge', 'decision', 'session', 'blog_post', 'prospect', 'agent_learning'];
+const RELATION_TYPES = ['supports', 'contradicts', 'derived_from', 'example_of', 'supersedes', 'part_of', 'prerequisite'];
+export function registerLinkCreate(server, adapter) {
+    server.tool('link_create', 'Create a typed relationship between two MemoryOS entities. ' +
+        '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'),
+        target_type: z.enum(ENTITY_TYPES).describe('Type of the target entity'),
+        target_id: z.string().uuid().describe('UUID of the target entity'),
+        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'),
+    }, withGracefulDegradation('knowledge_links', adapter, async (params) => {
+        try {
+            if (params.source_type === params.target_type && params.source_id === params.target_id) {
+                return makeToolResponse({
+                    created: false,
+                    message: 'Cannot create a self-link.',
+                });
+            }
+            const existing = await adapter.list('knowledge_links', {
+                filter: [[
+                        { field: 'source_type', op: 'eq', value: params.source_type },
+                        { field: 'source_id', op: 'eq', value: params.source_id },
+                        { field: 'target_type', op: 'eq', value: params.target_type },
+                        { field: 'target_id', op: 'eq', value: params.target_id },
+                        { field: 'relation_type', op: 'eq', value: params.relation_type },
+                    ]],
+                page: { limit: 1, offset: 0 },
+            });
+            if (existing.items.length > 0) {
+                return makeToolResponse({
+                    created: false,
+                    existing_link_id: existing.items[0].id,
+                    message: `Link already exists (id: ${existing.items[0].id}).`,
+                });
+            }
+            const record = await adapter.create('knowledge_links', {
+                source_type: params.source_type,
+                source_id: params.source_id,
+                target_type: params.target_type,
+                target_id: params.target_id,
+                relation_type: params.relation_type,
+                confidence: params.confidence ?? 0.8,
+                notes: params.notes ?? null,
+                auto_suggested: false,
+            });
+            return makeToolResponse({
+                created: true,
+                link: { id: record.id, source_type: params.source_type, target_type: params.target_type, relation_type: params.relation_type },
+                message: `Link created: ${params.source_type}:${params.source_id.slice(0, 8)} --[${params.relation_type}]--> ${params.target_type}:${params.target_id.slice(0, 8)}`,
+            });
+        }
+        catch (error) {
+            return handleAdapterError(error, 'link_create');
+        }
+    }));
+}
+//# sourceMappingURL=link-create.js.map

package/dist/tools/memory/link-delete.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { DataAdapter } from '../../adapter/types.js';
+export declare function registerLinkDelete(server: McpServer, adapter: DataAdapter): void;
+//# sourceMappingURL=link-delete.d.ts.map

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

@@ -0,0 +1,27 @@
+/**
+ * Tool: link_delete
+ *
+ * Deletes a knowledge link by ID.
+ */
+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'),
+    }, withGracefulDegradation('knowledge_links', adapter, async (params) => {
+        try {
+            try {
+                await adapter.getOne('knowledge_links', params.link_id);
+            }
+            catch {
+                return makeToolResponse({ deleted: false, message: `Link not found: ${params.link_id}` });
+            }
+            await adapter.delete('knowledge_links', params.link_id);
+            return makeToolResponse({ deleted: true, link_id: params.link_id, message: `Link deleted: ${params.link_id}` });
+        }
+        catch (error) {
+            return handleAdapterError(error, 'link_delete');
+        }
+    }));
+}
+//# sourceMappingURL=link-delete.js.map

package/dist/tools/memory/link-related.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { DataAdapter } from '../../adapter/types.js';
+export declare function registerLinkRelated(server: McpServer, adapter: DataAdapter): void;
+//# sourceMappingURL=link-related.d.ts.map

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

@@ -0,0 +1,91 @@
+/**
+ * Tool: link_related
+ *
+ * Get all links for an entity — traverse the knowledge graph.
+ */
+import { z } from 'zod';
+import { makeToolResponse, handleAdapterError, withGracefulDegradation } from '../shared.js';
+const ENTITY_TYPES = ['knowledge', 'decision', 'session', 'blog_post', 'prospect', 'agent_learning'];
+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'),
+        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'),
+    }, withGracefulDegradation('knowledge_links', adapter, async (params) => {
+        try {
+            const outgoing = [];
+            const incoming = [];
+            if (params.direction === 'both' || params.direction === 'outgoing') {
+                const filter = [
+                    { field: 'source_type', op: 'eq', value: params.entity_type },
+                    { field: 'source_id', op: 'eq', value: params.entity_id },
+                ];
+                if (params.relation_type) {
+                    filter.push({ field: 'relation_type', op: 'eq', value: params.relation_type });
+                }
+                const result = await adapter.list('knowledge_links', {
+                    filter: [filter],
+                    sort: [{ field: 'created_at', direction: 'desc' }],
+                    page: { limit: 50, offset: 0 },
+                });
+                for (const link of result.items) {
+                    let targetTitle = null;
+                    try {
+                        const col = link.target_type === 'decision' ? 'decisions' : link.target_type;
+                        targetTitle = (await adapter.getOne(col, link.target_id)).title ?? null;
+                    }
+                    catch { /* skip */ }
+                    outgoing.push({
+                        link_id: link.id, direction: 'outgoing',
+                        linked_type: link.target_type, linked_id: link.target_id,
+                        linked_title: targetTitle, relation_type: link.relation_type,
+                        confidence: link.confidence, notes: link.notes,
+                    });
+                }
+            }
+            if (params.direction === 'both' || params.direction === 'incoming') {
+                const filter = [
+                    { field: 'target_type', op: 'eq', value: params.entity_type },
+                    { field: 'target_id', op: 'eq', value: params.entity_id },
+                ];
+                if (params.relation_type) {
+                    filter.push({ field: 'relation_type', op: 'eq', value: params.relation_type });
+                }
+                const result = await adapter.list('knowledge_links', {
+                    filter: [filter],
+                    sort: [{ field: 'created_at', direction: 'desc' }],
+                    page: { limit: 50, offset: 0 },
+                });
+                for (const link of result.items) {
+                    let sourceTitle = null;
+                    try {
+                        const col = link.source_type === 'decision' ? 'decisions' : link.source_type;
+                        sourceTitle = (await adapter.getOne(col, link.source_id)).title ?? null;
+                    }
+                    catch { /* skip */ }
+                    incoming.push({
+                        link_id: link.id, direction: 'incoming',
+                        linked_type: link.source_type, linked_id: link.source_id,
+                        linked_title: sourceTitle, relation_type: link.relation_type,
+                        confidence: link.confidence, notes: link.notes,
+                    });
+                }
+            }
+            const allLinks = [...outgoing, ...incoming];
+            return makeToolResponse({
+                entity_type: params.entity_type, entity_id: params.entity_id,
+                total_links: allLinks.length, outgoing_count: outgoing.length, incoming_count: incoming.length,
+                links: allLinks,
+                message: allLinks.length === 0
+                    ? `No links found. Use link_suggest to find potential connections.`
+                    : `Found ${allLinks.length} links (${outgoing.length} outgoing, ${incoming.length} incoming).`,
+            });
+        }
+        catch (error) {
+            return handleAdapterError(error, 'link_related');
+        }
+    }));
+}
+//# sourceMappingURL=link-related.js.map

package/dist/tools/memory/link-suggest.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { DataAdapter } from '../../adapter/types.js';
+export declare function registerLinkSuggest(server: McpServer, adapter: DataAdapter): void;
+//# sourceMappingURL=link-suggest.d.ts.map

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

@@ -0,0 +1,83 @@
+/**
+ * Tool: link_suggest
+ *
+ * Find similar items and suggest links using keyword matching.
+ */
+import { z } from 'zod';
+import { makeToolResponse, handleAdapterError, withGracefulDegradation } from '../shared.js';
+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'),
+        limit: z.number().min(1).max(20).optional().default(5).describe('Max suggestions'),
+    }, withGracefulDegradation('knowledge', adapter, async (params) => {
+        try {
+            let sourceItem;
+            try {
+                sourceItem = await adapter.getOne('knowledge', params.item_id);
+            }
+            catch {
+                return makeToolResponse({ suggestions: [], message: `Item not found: ${params.item_id}` });
+            }
+            // Get already-linked IDs to exclude
+            const linkedIds = new Set();
+            try {
+                const out = await adapter.list('knowledge_links', {
+                    filter: [[{ field: 'source_type', op: 'eq', value: 'knowledge' }, { field: 'source_id', op: 'eq', value: params.item_id }]],
+                    page: { limit: 100, offset: 0 },
+                });
+                const inc = await adapter.list('knowledge_links', {
+                    filter: [[{ field: 'target_type', op: 'eq', value: 'knowledge' }, { field: 'target_id', op: 'eq', value: params.item_id }]],
+                    page: { limit: 100, offset: 0 },
+                });
+                for (const l of out.items) linkedIds.add(l.target_id);
+                for (const l of inc.items) linkedIds.add(l.source_id);
+            }
+            catch { /* knowledge_links may not exist */ }
+            const searchTerms = extractKeyTerms(sourceItem.title, sourceItem.content);
+            let suggestions = [];
+            if (searchTerms) {
+                const results = await adapter.textSearch('knowledge', searchTerms, {
+                    limit: (params.limit ?? 5) + linkedIds.size + 1,
+                });
+                suggestions = results
+                    .filter(item => item.id !== params.item_id && !linkedIds.has(item.id))
+                    .slice(0, params.limit ?? 5)
+                    .map(item => ({
+                    id: item.id, type: item.type, title: item.title,
+                    summary: item.summary ?? (item.content?.slice(0, 100) + '...'),
+                    suggested_relation: suggestRelationType(sourceItem, item),
+                }));
+            }
+            return makeToolResponse({
+                source: { id: sourceItem.id, type: sourceItem.type, title: sourceItem.title },
+                suggestions, already_linked: linkedIds.size,
+                message: suggestions.length === 0
+                    ? `No unlinked similar items found for "${sourceItem.title}".`
+                    : `Found ${suggestions.length} suggestions. Use link_create to connect them.`,
+            });
+        }
+        catch (error) {
+            return handleAdapterError(error, 'link_suggest');
+        }
+    }));
+}
+function extractKeyTerms(title, content) {
+    const stopWords = new Set(['the', 'a', 'an', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+        'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'could', 'should', 'may',
+        'might', 'can', 'to', 'of', 'in', 'for', 'on', 'with', 'at', 'by', 'from', 'as',
+        'and', 'but', 'or', 'not', 'so', 'if', 'when', 'how', 'what', 'which', 'who',
+        'this', 'that', 'these', 'those', 'it', 'its']);
+    const text = `${title} ${(content ?? '').slice(0, 200)}`;
+    const words = text.toLowerCase().replace(/[^a-z0-9\s]/g, ' ').split(/\s+/)
+        .filter(w => w.length > 2 && !stopWords.has(w));
+    return [...new Set(words)].slice(0, 5).join(' ');
+}
+function suggestRelationType(source, target) {
+    if (source.type === target.type) return 'supports';
+    if ((source.type === 'lesson' && target.type === 'decision') || (source.type === 'decision' && target.type === 'lesson')) return 'derived_from';
+    if (source.type === 'insight' && target.type === 'pattern') return 'derived_from';
+    if (source.type === 'pattern' && target.type === 'insight') return 'example_of';
+    return 'supports';
+}
+//# sourceMappingURL=link-suggest.js.map

package/dist/tools/register.js

@@ -1,7 +1,7 @@
 /**
- * Tool registration — imports and calls all 35 register functions.
+ * Tool registration — imports and calls all 39 register functions.
  */
-// Memory tools (22)
+// Memory tools (26)
 import { registerKnowledgeStore } from './memory/knowledge-store.js';
 import { registerKnowledgeRecall } from './memory/knowledge-recall.js';
 import { registerKnowledgeLearn } from './memory/knowledge-learn.js';
@@ -24,6 +24,10 @@ import { registerContactList } from './memory/contact-list.js';
 import { registerContactSearch } from './memory/contact-search.js';
 import { registerBrainStats } from './memory/brain-stats.js';
 import { registerBrainDecay } from './memory/brain-decay.js';
+import { registerLinkCreate } from './memory/link-create.js';
+import { registerLinkDelete } from './memory/link-delete.js';
+import { registerLinkRelated } from './memory/link-related.js';
+import { registerLinkSuggest } from './memory/link-suggest.js';
 // Setup tools (3)
 import { registerSetupStatus } from './setup/setup-status.js';
 import { registerSetupMigrate } from './setup/setup-migrate.js';
@@ -64,6 +68,10 @@ export function registerAllTools(server, adapter) {
     registerContactSearch(server, adapter);
     registerBrainStats(server, adapter);
     registerBrainDecay(server, adapter);
+    registerLinkCreate(server, adapter);
+    registerLinkDelete(server, adapter);
+    registerLinkRelated(server, adapter);
+    registerLinkSuggest(server, adapter);
     // Setup tools
     registerSetupStatus(server, adapter);
     registerSetupMigrate(server, adapter);

package/migrations/pocketbase/008_knowledge_links.js

@@ -0,0 +1,38 @@
+/**
+ * PocketBase migration: knowledge_links collection
+ *
+ * Creates the knowledge_links collection for typed relationships
+ * between MemoryOS entities.
+ *
+ * Note: PocketBase does not support pgvector.
+ * Link suggestions use keyword-based text search fallback.
+ */
+module.exports = {
+    async up(db) {
+        const collection = new Collection({
+            name: 'knowledge_links',
+            type: 'base',
+            schema: [
+                { name: 'owner_id', type: 'text', required: true, options: { maxSize: 100 } },
+                { name: 'source_type', type: 'text', required: true, options: { maxSize: 50 } },
+                { name: 'source_id', type: 'text', required: true, options: { maxSize: 36 } },
+                { name: 'target_type', type: 'text', required: true, options: { maxSize: 50 } },
+                { name: 'target_id', type: 'text', required: true, options: { maxSize: 36 } },
+                { name: 'relation_type', type: 'text', required: true, options: { maxSize: 50 } },
+                { name: 'confidence', type: 'number', options: { min: 0, max: 1 } },
+                { name: 'notes', type: 'text', options: { maxSize: 500 } },
+                { name: 'auto_suggested', type: 'bool' },
+            ],
+            indexes: [
+                'CREATE INDEX idx_kl_source ON knowledge_links (owner_id, source_type, source_id)',
+                'CREATE INDEX idx_kl_target ON knowledge_links (owner_id, target_type, target_id)',
+                'CREATE UNIQUE INDEX idx_kl_unique ON knowledge_links (owner_id, source_type, source_id, target_type, target_id, relation_type)',
+            ],
+        });
+        return db.save(collection);
+    },
+    async down(db) {
+        const collection = await db.findCollectionByNameOrId('knowledge_links');
+        return db.delete(collection);
+    },
+};

package/migrations/supabase/010_knowledge_links.sql

@@ -0,0 +1,47 @@
+-- Migration 010: Knowledge Links + pgvector embeddings
+-- Adds graph-lite relationship system between MemoryOS entities
+
+-- 1. Enable pgvector extension
+CREATE EXTENSION IF NOT EXISTS vector;
+
+-- 2. Add embedding column to knowledge
+ALTER TABLE knowledge ADD COLUMN IF NOT EXISTS embedding vector(384);
+
+-- 3. HNSW index for cosine similarity
+CREATE INDEX IF NOT EXISTS idx_knowledge_embedding
+  ON knowledge USING hnsw (embedding vector_cosine_ops)
+  WITH (m = 16, ef_construction = 64);
+
+-- 4. Knowledge links table
+CREATE TABLE IF NOT EXISTS knowledge_links (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  owner_id text NOT NULL DEFAULT 'default',
+
+  source_type text NOT NULL,
+  source_id uuid NOT NULL,
+  target_type text NOT NULL,
+  target_id uuid NOT NULL,
+  relation_type text NOT NULL,
+
+  confidence numeric DEFAULT 0.8 CHECK (confidence >= 0 AND confidence <= 1),
+  notes text,
+  auto_suggested boolean DEFAULT false,
+  created_at timestamptz DEFAULT now(),
+
+  CONSTRAINT knowledge_links_source_type_check CHECK (source_type IN ('knowledge', 'decision', 'session', 'blog_post', 'prospect', 'agent_learning')),
+  CONSTRAINT knowledge_links_target_type_check CHECK (target_type IN ('knowledge', 'decision', 'session', 'blog_post', 'prospect', 'agent_learning')),
+  CONSTRAINT knowledge_links_relation_type_check CHECK (relation_type IN ('supports', 'contradicts', 'derived_from', 'example_of', 'supersedes', 'part_of', 'prerequisite')),
+  CONSTRAINT knowledge_links_no_self_link CHECK (NOT (source_type = target_type AND source_id = target_id)),
+  CONSTRAINT knowledge_links_unique_link UNIQUE (owner_id, source_type, source_id, target_type, target_id, relation_type)
+);
+
+-- 5. Indexes
+CREATE INDEX idx_knowledge_links_source ON knowledge_links (owner_id, source_type, source_id);
+CREATE INDEX idx_knowledge_links_target ON knowledge_links (owner_id, target_type, target_id);
+CREATE INDEX idx_knowledge_links_relation ON knowledge_links (relation_type);
+
+-- 6. RLS
+ALTER TABLE knowledge_links ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY "owner_all_access" ON knowledge_links
+  FOR ALL USING (owner_id = current_setting('app.owner_id', true) OR current_setting('app.owner_id', true) IS NULL);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iwo-szapar/data-mcp",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Unified data MCP server for Second Brain \u2014 PocketBase and Supabase adapters",
   "type": "module",
   "bin": {