stellavault 0.2.0 → 0.3.0

package/packages/core/dist/mcp/server.js

@@ -0,0 +1,151 @@
+// Design Ref: §4.1 — MCP Server (stdio + SSE)
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { searchToolDef, handleSearch } from './tools/search.js';
+import { getDocumentToolDef, handleGetDocument } from './tools/get-document.js';
+import { listTopicsToolDef, handleListTopics } from './tools/list-topics.js';
+import { getRelatedToolDef, handleGetRelated } from './tools/get-related.js';
+import { generateClaudeMdToolDef, handleGenerateClaudeMd } from './tools/generate-claude-md.js';
+import { createSnapshotToolDef, loadSnapshotToolDef, handleCreateSnapshot, handleLoadSnapshot } from './tools/snapshot.js';
+import { logDecisionToolDef, findDecisionsToolDef, handleLogDecision, handleFindDecisions } from './tools/decision-journal.js';
+import { exportToolDef, handleExport } from './tools/export.js';
+import { getDecayStatusToolDef, handleGetDecayStatus } from './tools/decay.js';
+import { getMorningBriefToolDef, handleGetMorningBrief } from './tools/brief.js';
+import { createLearningPathTool } from './tools/learning-path.js';
+import { createDetectGapsTool } from './tools/detect-gaps.js';
+import { createGetEvolutionTool } from './tools/get-evolution.js';
+import { createLinkCodeTool } from './tools/link-code.js';
+export function createMcpServer(options) {
+    const { store, searchEngine, vaultPath = '', decayEngine } = options;
+    const learningPathTool = createLearningPathTool(store);
+    const detectGapsTool = createDetectGapsTool(store);
+    const getEvolutionTool = createGetEvolutionTool(store);
+    const linkCodeTool = createLinkCodeTool(searchEngine);
+    const server = new Server({ name: 'stellavault', version: '0.2.0' }, { capabilities: { tools: {} } });
+    // List tools
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [
+            searchToolDef, getDocumentToolDef, listTopicsToolDef, getRelatedToolDef,
+            generateClaudeMdToolDef, createSnapshotToolDef, loadSnapshotToolDef,
+            logDecisionToolDef, findDecisionsToolDef, exportToolDef,
+            ...(decayEngine ? [getDecayStatusToolDef, getMorningBriefToolDef] : []),
+            { name: learningPathTool.name, description: learningPathTool.description, inputSchema: learningPathTool.inputSchema },
+            { name: detectGapsTool.name, description: detectGapsTool.description, inputSchema: detectGapsTool.inputSchema },
+            { name: getEvolutionTool.name, description: getEvolutionTool.description, inputSchema: getEvolutionTool.inputSchema },
+            { name: linkCodeTool.name, description: linkCodeTool.description, inputSchema: linkCodeTool.inputSchema },
+        ],
+    }));
+    // Call tool
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        try {
+            let result;
+            switch (name) {
+                case 'search':
+                    result = await handleSearch(searchEngine, args);
+                    // MCP 검색 이벤트 기록
+                    if (decayEngine && result && typeof result === 'object' && 'results' in result) {
+                        const now = new Date().toISOString();
+                        for (const r of result.results ?? []) {
+                            if (r.documentId)
+                                decayEngine.recordAccess({ documentId: r.documentId, type: 'mcp_query', timestamp: now }).catch(() => { });
+                        }
+                    }
+                    break;
+                case 'get-document':
+                    result = await handleGetDocument(store, args);
+                    // MCP 문서 조회 이벤트 기록
+                    if (decayEngine && result && typeof result === 'object' && 'id' in result) {
+                        decayEngine.recordAccess({ documentId: result.id, type: 'mcp_query', timestamp: new Date().toISOString() }).catch(() => { });
+                    }
+                    break;
+                case 'list-topics':
+                    result = await handleListTopics(store);
+                    break;
+                case 'get-related':
+                    result = await handleGetRelated(store, searchEngine, args);
+                    break;
+                case 'generate-claude-md':
+                    result = await handleGenerateClaudeMd(searchEngine, store, args);
+                    break;
+                case 'create-snapshot':
+                    result = await handleCreateSnapshot(searchEngine, args);
+                    break;
+                case 'load-snapshot':
+                    result = await handleLoadSnapshot(args);
+                    break;
+                case 'log-decision':
+                    result = await handleLogDecision(vaultPath, args);
+                    break;
+                case 'find-decisions':
+                    result = await handleFindDecisions(vaultPath, args);
+                    break;
+                case 'export':
+                    result = await handleExport(store, args);
+                    break;
+                case 'get-decay-status':
+                    if (!decayEngine) {
+                        result = { error: 'Decay engine not available' };
+                        break;
+                    }
+                    result = await handleGetDecayStatus(decayEngine, args);
+                    break;
+                case 'get-morning-brief':
+                    if (!decayEngine) {
+                        result = { error: 'Decay engine not available' };
+                        break;
+                    }
+                    result = await handleGetMorningBrief(decayEngine, store);
+                    break;
+                case 'get-learning-path':
+                    result = await learningPathTool.handler(args);
+                    return result;
+                case 'detect-gaps':
+                    result = await detectGapsTool.handler(args);
+                    return result;
+                case 'get-evolution':
+                    result = await getEvolutionTool.handler(args);
+                    return result;
+                case 'link-code':
+                    result = await linkCodeTool.handler(args);
+                    return result;
+                default:
+                    return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
+            }
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+        }
+    });
+    return {
+        async startStdio() {
+            const transport = new StdioServerTransport();
+            await server.connect(transport);
+        },
+        async startHttp(port = 3334) {
+            const { createServer } = await import('node:http');
+            const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => `sv-${Date.now()}` });
+            await server.connect(transport);
+            const httpServer = createServer(async (req, res) => {
+                res.setHeader('Access-Control-Allow-Origin', '*');
+                res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+                res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+                if (req.method === 'OPTIONS') {
+                    res.writeHead(204);
+                    res.end();
+                    return;
+                }
+                await transport.handleRequest(req, res);
+            });
+            httpServer.listen(port, '127.0.0.1', () => {
+                console.error(`🔌 MCP HTTP server running at http://127.0.0.1:${port}/mcp`);
+            });
+        },
+        server,
+    };
+}
+//# sourceMappingURL=server.js.map

package/packages/core/dist/mcp/tools/agentic-graph.d.ts

@@ -0,0 +1,87 @@
+import type { VectorStore } from '../../store/types.js';
+import type { Embedder } from '../../indexer/embedder.js';
+export declare function createAgenticGraphTools(store: VectorStore, embedder: Embedder, vaultPath: string): ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            title: {
+                type: string;
+                description: string;
+            };
+            content: {
+                type: string;
+                description: string;
+            };
+            tags: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            type: {
+                type: string;
+                description: string;
+            };
+            folder: {
+                type: string;
+                description: string;
+            };
+            sourceTitle?: undefined;
+            targetTitle?: undefined;
+            context?: undefined;
+        };
+        required: string[];
+    };
+    handler(args: {
+        title: string;
+        content: string;
+        tags?: string[];
+        type?: string;
+        folder?: string;
+    }): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            sourceTitle: {
+                type: string;
+                description: string;
+            };
+            targetTitle: {
+                type: string;
+                description: string;
+            };
+            context: {
+                type: string;
+                description: string;
+            };
+            title?: undefined;
+            content?: undefined;
+            tags?: undefined;
+            type?: undefined;
+            folder?: undefined;
+        };
+        required: string[];
+    };
+    handler(args: {
+        sourceTitle: string;
+        targetTitle: string;
+        context?: string;
+    }): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+})[];
+//# sourceMappingURL=agentic-graph.d.ts.map

package/packages/core/dist/mcp/tools/agentic-graph.js

@@ -0,0 +1,88 @@
+// Agentic Graph Construction (P3-F23)
+// AI가 MCP 세션 중 실시간으로 그래프 노드/엣지 생성
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+export function createAgenticGraphTools(store, embedder, vaultPath) {
+    return [
+        {
+            name: 'create-knowledge-node',
+            description: 'Create a new knowledge note in the vault. AI agents use this to capture decisions, insights, or summaries during a conversation. The note is automatically indexed and appears in the knowledge graph.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    title: { type: 'string', description: 'Note title' },
+                    content: { type: 'string', description: 'Note content (markdown)' },
+                    tags: { type: 'array', items: { type: 'string' }, description: 'Tags for categorization' },
+                    type: { type: 'string', description: 'Note type: note, decision, insight, summary' },
+                    folder: { type: 'string', description: 'Vault subfolder (default: 01_Knowledge)' },
+                },
+                required: ['title', 'content'],
+            },
+            async handler(args) {
+                const { title, content, tags = [], type = 'note', folder = '01_Knowledge' } = args;
+                // frontmatter 생성
+                const date = new Date().toISOString().slice(0, 10);
+                const fm = [
+                    '---',
+                    `title: "${title}"`,
+                    `type: ${type}`,
+                    `source: agent`,
+                    `tags: [${tags.map(t => `"${t}"`).join(', ')}]`,
+                    `created: ${date}`,
+                    `auto_generated: true`,
+                    '---',
+                ].join('\n');
+                const fullContent = `${fm}\n\n# ${title}\n\n${content}`;
+                // vault에 파일 저장
+                const safeTitle = title.replace(/[<>:"/\\|?*]/g, '').replace(/\s+/g, ' ').trim().slice(0, 80);
+                const dir = join(vaultPath, folder);
+                mkdirSync(dir, { recursive: true });
+                const filePath = join(dir, `${safeTitle}.md`);
+                writeFileSync(filePath, fullContent, 'utf-8');
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `Created knowledge node: "${title}" at ${folder}/${safeTitle}.md\nTags: ${tags.join(', ') || 'none'}\nType: ${type}\n\nRun 'stellavault index' to add to the graph.`,
+                        }],
+                };
+            },
+        },
+        {
+            name: 'create-knowledge-link',
+            description: 'Create a link between two existing notes by adding a wiki-link reference. Strengthens connections in the knowledge graph.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    sourceTitle: { type: 'string', description: 'Title of the source note' },
+                    targetTitle: { type: 'string', description: 'Title of the target note to link to' },
+                    context: { type: 'string', description: 'Why these notes are related (added as a comment)' },
+                },
+                required: ['sourceTitle', 'targetTitle'],
+            },
+            async handler(args) {
+                const docs = await store.getAllDocuments();
+                const source = docs.find(d => d.title.toLowerCase().includes(args.sourceTitle.toLowerCase()));
+                if (!source) {
+                    return { content: [{ type: 'text', text: `Source note "${args.sourceTitle}" not found.` }] };
+                }
+                // 소스 노트에 링크 추가
+                const { readFileSync } = await import('node:fs');
+                const fullPath = join(vaultPath, source.filePath);
+                let existing = '';
+                try {
+                    existing = readFileSync(fullPath, 'utf-8');
+                }
+                catch { /* new file */ }
+                const linkSection = `\n\n## Related\n\n- [[${args.targetTitle}]]${args.context ? ` — ${args.context}` : ''}\n`;
+                writeFileSync(fullPath, existing + linkSection, 'utf-8');
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `Linked "${source.title}" → "${args.targetTitle}"${args.context ? ` (${args.context})` : ''}`,
+                        }],
+                };
+            },
+        },
+    ];
+}
+//# sourceMappingURL=agentic-graph.js.map

package/packages/core/dist/mcp/tools/brief.d.ts

@@ -0,0 +1,31 @@
+import type { DecayEngine } from '../../intelligence/decay-engine.js';
+import type { VectorStore } from '../../store/types.js';
+export declare const getMorningBriefToolDef: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {};
+    };
+};
+export declare function handleGetMorningBrief(decayEngine: DecayEngine, store: VectorStore): Promise<{
+    greeting: string;
+    summary: {
+        totalDocs: number;
+        averageR: number;
+        decaying: number;
+        critical: number;
+    };
+    reviewSuggestions: {
+        title: string;
+        retrievability: number;
+        daysSinceAccess: number;
+    }[];
+    unhealthyClusters: {
+        label: string;
+        avgR: number;
+        count: number;
+    }[];
+    tip: string;
+}>;
+//# sourceMappingURL=brief.d.ts.map

package/packages/core/dist/mcp/tools/brief.js

@@ -0,0 +1,39 @@
+// MCP tool: get-morning-brief — Claude 세션 시작 시 자동 브리핑
+export const getMorningBriefToolDef = {
+    name: 'get-morning-brief',
+    description: '오늘의 지식 브리핑을 제공합니다. 감쇠 상태, 리뷰 대상, 최근 활동을 요약합니다. 세션 시작 시 호출하면 유용합니다.',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+    },
+};
+export async function handleGetMorningBrief(decayEngine, store) {
+    const stats = await store.getStats();
+    const report = await decayEngine.computeAll();
+    const reviewList = report.topDecaying.slice(0, 5).map(d => ({
+        title: d.title,
+        retrievability: Math.round(d.retrievability * 100) / 100,
+        daysSinceAccess: d.daysSinceAccess,
+    }));
+    const unhealthyClusters = report.clusterHealth
+        .filter(c => c.avgR < 0.6)
+        .slice(0, 3)
+        .map(c => ({ label: c.label, avgR: c.avgR, count: c.count }));
+    return {
+        greeting: `📚 ${stats.documentCount}개 노트, 전체 건강도 R=${report.averageR}`,
+        summary: {
+            totalDocs: stats.documentCount,
+            averageR: report.averageR,
+            decaying: report.decayingCount,
+            critical: report.criticalCount,
+        },
+        reviewSuggestions: reviewList,
+        unhealthyClusters,
+        tip: report.criticalCount > 0
+            ? `⚠️ ${report.criticalCount}개 노트가 위험 수준입니다. 'stellavault review'로 리뷰하세요.`
+            : report.decayingCount > 0
+                ? `📋 ${report.decayingCount}개 노트가 감쇠 중입니다.`
+                : '✨ 모든 지식이 건강합니다!',
+    };
+}
+//# sourceMappingURL=brief.js.map

package/packages/core/dist/mcp/tools/decay.d.ts

@@ -0,0 +1,33 @@
+import type { DecayEngine } from '../../intelligence/decay-engine.js';
+export declare const getDecayStatusToolDef: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            threshold: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+        };
+    };
+};
+export declare function handleGetDecayStatus(decayEngine: DecayEngine, args: {
+    threshold?: number;
+    limit?: number;
+}): Promise<{
+    count: number;
+    threshold: number;
+    notes: {
+        title: string;
+        retrievability: number;
+        stability: number;
+        lastAccess: string;
+    }[];
+    tip: string;
+}>;
+//# sourceMappingURL=decay.d.ts.map

package/packages/core/dist/mcp/tools/decay.js

@@ -0,0 +1,32 @@
+// Design Ref: §4.2 — MCP tool: get-decay-status
+// Plan SC: SC-04
+export const getDecayStatusToolDef = {
+    name: 'get-decay-status',
+    description: '잊어가는 지식 노트를 조회합니다. 기억 강도(retrievability)가 낮은 노트 목록을 반환하여 리마인드합니다.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            threshold: { type: 'number', description: '감쇠 임계값 (0~1, default: 0.5). 이 값 이하인 노트를 반환' },
+            limit: { type: 'number', description: '반환할 최대 노트 수 (default: 20)' },
+        },
+    },
+};
+export async function handleGetDecayStatus(decayEngine, args) {
+    const threshold = args.threshold ?? 0.5;
+    const limit = args.limit ?? 20;
+    const decaying = await decayEngine.getDecaying(threshold, limit);
+    return {
+        count: decaying.length,
+        threshold,
+        notes: decaying.map(d => ({
+            title: d.title,
+            retrievability: Math.round(d.retrievability * 100) / 100,
+            stability: Math.round(d.stability * 10) / 10,
+            lastAccess: d.lastAccess,
+        })),
+        tip: decaying.length > 0
+            ? `${decaying.length}개의 노트를 잊어가고 있습니다. 리뷰를 권장합니다.`
+            : '모든 지식이 건강한 상태입니다!',
+    };
+}
+//# sourceMappingURL=decay.js.map

package/packages/core/dist/mcp/tools/decision-journal.d.ts

@@ -0,0 +1,78 @@
+export declare const logDecisionToolDef: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            title: {
+                type: string;
+                description: string;
+            };
+            context: {
+                type: string;
+                description: string;
+            };
+            decision: {
+                type: string;
+                description: string;
+            };
+            alternatives: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            reasoning: {
+                type: string;
+                description: string;
+            };
+            project: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare const findDecisionsToolDef: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleLogDecision(vaultPath: string, args: {
+    title: string;
+    context?: string;
+    decision: string;
+    alternatives?: string[];
+    reasoning: string;
+    project?: string;
+}): Promise<{
+    saved: string;
+    fileName: string;
+}>;
+export declare function handleFindDecisions(vaultPath: string, args: {
+    query: string;
+}): Promise<{
+    decisions: never[];
+    message: string;
+    total?: undefined;
+} | {
+    decisions: {
+        file: string;
+        content: string;
+        score: number;
+    }[];
+    total: number;
+    message?: undefined;
+}>;
+//# sourceMappingURL=decision-journal.d.ts.map

package/packages/core/dist/mcp/tools/decision-journal.js

@@ -0,0 +1,79 @@
+// Design Ref: §12.1 F14 — 결정 저널 (기술 결정 자동 기록)
+import { writeFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+export const logDecisionToolDef = {
+    name: 'log-decision',
+    description: '기술적 결정을 구조화하여 기록합니다. 나중에 "왜 이 선택을 했지?"에 답변할 수 있습니다.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            title: { type: 'string', description: '결정 제목 (예: Zustand 대신 Jotai 선택)' },
+            context: { type: 'string', description: '결정 배경/상황' },
+            decision: { type: 'string', description: '선택한 내용' },
+            alternatives: { type: 'array', items: { type: 'string' }, description: '고려한 대안들' },
+            reasoning: { type: 'string', description: '선택 이유' },
+            project: { type: 'string', description: '관련 프로젝트명' },
+        },
+        required: ['title', 'decision', 'reasoning'],
+    },
+};
+export const findDecisionsToolDef = {
+    name: 'find-decisions',
+    description: '과거 기술 결정을 검색합니다.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: { type: 'string', description: '검색 쿼리' },
+        },
+        required: ['query'],
+    },
+};
+export async function handleLogDecision(vaultPath, args) {
+    const decisionsDir = join(vaultPath, 'decisions');
+    mkdirSync(decisionsDir, { recursive: true });
+    const date = new Date().toISOString().slice(0, 10);
+    const slug = args.title.replace(/[^a-zA-Z가-힣0-9\s-]/g, '').replace(/\s+/g, '-').slice(0, 50);
+    if (!slug)
+        throw new Error('Invalid decision title');
+    const fileName = `${date}-${slug}.md`;
+    const content = [
+        '---',
+        `title: "${args.title}"`,
+        `date: ${date}`,
+        `project: "${args.project ?? ''}"`,
+        'type: decision',
+        '---',
+        '',
+        `# ${args.title}`,
+        '',
+        args.context ? `## 배경\n\n${args.context}\n` : '',
+        `## 결정\n\n${args.decision}\n`,
+        args.alternatives?.length
+            ? `## 고려한 대안\n\n${args.alternatives.map(a => `- ${a}`).join('\n')}\n`
+            : '',
+        `## 이유\n\n${args.reasoning}\n`,
+    ].filter(Boolean).join('\n');
+    const filePath = resolve(decisionsDir, fileName);
+    if (!filePath.startsWith(resolve(decisionsDir))) {
+        throw new Error('Path traversal detected');
+    }
+    writeFileSync(filePath, content, 'utf-8');
+    return { saved: filePath, fileName };
+}
+export async function handleFindDecisions(vaultPath, args) {
+    const decisionsDir = join(vaultPath, 'decisions');
+    if (!existsSync(decisionsDir))
+        return { decisions: [], message: 'No decisions directory' };
+    const files = readdirSync(decisionsDir).filter(f => f.endsWith('.md'));
+    const query = args.query.toLowerCase();
+    const matches = files
+        .map(f => {
+        const content = readFileSync(join(decisionsDir, f), 'utf-8');
+        const score = content.toLowerCase().includes(query) ? 1 : 0;
+        return { file: f, content: content.slice(0, 300), score };
+    })
+        .filter(m => m.score > 0)
+        .slice(0, 10);
+    return { decisions: matches, total: files.length };
+}
+//# sourceMappingURL=decision-journal.js.map

package/packages/core/dist/mcp/tools/detect-gaps.d.ts

@@ -0,0 +1,24 @@
+import type { VectorStore } from '../../store/types.js';
+export declare function createDetectGapsTool(store: VectorStore): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            minSeverity: {
+                type: "string";
+                description: string;
+                enum: string[];
+            };
+        };
+    };
+    handler: (args: {
+        minSeverity?: string;
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+};
+//# sourceMappingURL=detect-gaps.d.ts.map