@teknologika/chisel-knowledge-mcp 0.1.0 → 0.1.1

package/README.md

@@ -2,7 +2,7 @@
 
 Standalone MCP server and library for building and managing knowledge workspaces.
 
-Canonical behavior documentation lives in [docs/chisel-knowledge-mcp.md](./docs/chisel-knowledge-mcp.md).
+Canonical behavior documentation lives in [docs/chisel-knowledge-mcp.md](./docs/chisel-knowledge-mcp.md) and is routed from [docs/CANONICAL_DOCS.md](./docs/CANONICAL_DOCS.md).
 
 ## Requirements
 
@@ -25,6 +25,17 @@ import { WorkspaceService, KnowledgeIndex } from '@teknologika/chisel-knowledge-
 
 The MCP server remains available from the `server` subpath and through the published binary.
 
+## Workspace Workflow
+
+The workspace service and MCP server expose a deterministic inbox pipeline:
+
+- `knowledge_get_next_inbox_file` returns the first unprocessed inbox file with its content.
+- `knowledge_get_dedupe_context` returns search results from both `knowledge/` and `inbox/` for a file-specific query.
+- `knowledge_compile_new` writes a new article into `knowledge/`, updates `knowledge/index.md`, appends `knowledge/log.md`, and archives the source inbox file.
+- `knowledge_compile_extend` writes a revised article into `knowledge/`, updates the article's `Updated` entry in `knowledge/index.md`, appends `knowledge/log.md`, and archives the source inbox file.
+
+These tools are deterministic. The LLM that consumes the MCP server decides the article content and the dedupe outcome; the server only performs file and index updates.
+
 ## Build
 
 ```bash

package/dist/domains/workspace/anthropic-adapter.js

@@ -0,0 +1,18 @@
+import Anthropic from '@anthropic-ai/sdk';
+export function createAnthropicAdapter(model = 'claude-haiku-4-5-20251001') {
+    const client = new Anthropic();
+    return {
+        async complete(prompt) {
+            const message = await client.messages.create({
+                model,
+                max_tokens: 4096,
+                messages: [{ role: 'user', content: prompt }],
+            });
+            const block = message.content[0];
+            if (!block || block.type !== 'text') {
+                throw new Error('Unexpected response type from Anthropic API');
+            }
+            return block.text;
+        },
+    };
+}

package/dist/domains/workspace/inbox-index.js

@@ -0,0 +1,96 @@
+import { readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { chunkMarkdown, normalizeFtsQuery } from './indexing.js';
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS chunks (
+    id       INTEGER PRIMARY KEY,
+    path     TEXT NOT NULL,
+    heading  TEXT,
+    body     TEXT NOT NULL,
+    mtime    INTEGER NOT NULL
+  );
+  CREATE VIRTUAL TABLE IF NOT EXISTS chunks_fts USING fts5(
+    path, heading, body,
+    content='chunks', content_rowid='id'
+  );
+  CREATE TRIGGER IF NOT EXISTS chunks_ai AFTER INSERT ON chunks BEGIN
+    INSERT INTO chunks_fts(rowid, path, heading, body)
+    VALUES (new.id, new.path, new.heading, new.body);
+  END;
+  CREATE TRIGGER IF NOT EXISTS chunks_ad AFTER DELETE ON chunks BEGIN
+    INSERT INTO chunks_fts(chunks_fts, rowid, path, heading, body)
+    VALUES ('delete', old.id, old.path, old.heading, old.body);
+  END;
+  CREATE TRIGGER IF NOT EXISTS chunks_au AFTER UPDATE ON chunks BEGIN
+    INSERT INTO chunks_fts(chunks_fts, rowid, path, heading, body)
+    VALUES ('delete', old.id, old.path, old.heading, old.body);
+    INSERT INTO chunks_fts(rowid, path, heading, body)
+    VALUES (new.id, new.path, new.heading, new.body);
+  END;
+`;
+export class InboxIndex {
+    workspacePath;
+    db;
+    constructor(workspacePath) {
+        this.workspacePath = workspacePath;
+        const dbPath = join(workspacePath, '.inbox-index.db');
+        this.db = new DatabaseSync(dbPath);
+        this.db.exec('PRAGMA journal_mode = WAL');
+        this.db.exec(SCHEMA);
+    }
+    indexFile(absPath) {
+        const path = relative(this.workspacePath, absPath);
+        const mtime = statSync(absPath).mtimeMs;
+        const existing = this.db
+            .prepare('SELECT mtime FROM chunks WHERE path = ? LIMIT 1')
+            .get(path);
+        if (existing && existing.mtime === mtime)
+            return;
+        this.db.prepare('DELETE FROM chunks WHERE path = ?').run(path);
+        const raw = readFileSync(absPath, 'utf8');
+        const chunks = chunkMarkdown(raw);
+        const insert = this.db.prepare('INSERT INTO chunks (path, heading, body, mtime) VALUES (?, ?, ?, ?)');
+        this.db.exec('BEGIN');
+        try {
+            for (const chunk of chunks) {
+                insert.run(path, chunk.heading ?? null, chunk.body, mtime);
+            }
+            this.db.exec('COMMIT');
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    removeFile(absPath) {
+        const path = relative(this.workspacePath, absPath);
+        this.db.prepare('DELETE FROM chunks WHERE path = ?').run(path);
+    }
+    search(query, limit = 10) {
+        const normalized = normalizeFtsQuery(query);
+        if (!normalized)
+            return { results: [] };
+        const rows = this.db
+            .prepare(`
+        SELECT c.path, c.heading,
+               snippet(chunks_fts, 2, '[', ']', '...', 16) AS excerpt
+        FROM chunks_fts f
+        JOIN chunks c ON c.id = f.rowid
+        WHERE chunks_fts MATCH ?
+        ORDER BY bm25(chunks_fts)
+        LIMIT ?
+      `)
+            .all(normalized, limit);
+        return {
+            results: rows.map((row, index) => ({
+                file: row.path,
+                excerpt: row.heading ? `**${row.heading}**\n${row.excerpt}` : row.excerpt,
+                score: 1 - index / Math.max(rows.length, 1),
+            })),
+        };
+    }
+    close() {
+        this.db.close();
+    }
+}

package/dist/domains/workspace/indexing.js

@@ -0,0 +1,56 @@
+export function chunkMarkdown(content) {
+    const stripped = content.replace(/^---[\s\S]*?---\n?/, '');
+    const cleaned = stripped
+        .replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1')
+        .replace(/<!--[\s\S]*?-->/g, '')
+        .trim();
+    const lines = cleaned.split('\n');
+    const chunks = [];
+    let currentHeading = null;
+    let currentLines = [];
+    const flush = () => {
+        const body = currentLines.join('\n').trim();
+        if (!body)
+            return;
+        if (body.length > 1500) {
+            const paragraphs = body.split(/\n{2,}/);
+            let acc = '';
+            for (const para of paragraphs) {
+                if (acc.length + para.length > 1500 && acc.length > 0) {
+                    chunks.push({ heading: currentHeading, body: acc.trim() });
+                    acc = para;
+                }
+                else {
+                    acc = acc ? `${acc}\n\n${para}` : para;
+                }
+            }
+            if (acc.trim())
+                chunks.push({ heading: currentHeading, body: acc.trim() });
+        }
+        else {
+            chunks.push({ heading: currentHeading, body });
+        }
+        currentLines = [];
+    };
+    for (const line of lines) {
+        const headingMatch = /^(#{1,3})\s+(.+)/.exec(line);
+        if (headingMatch) {
+            flush();
+            currentHeading = headingMatch[2].trim();
+        }
+        else {
+            currentLines.push(line);
+        }
+    }
+    flush();
+    return chunks;
+}
+export function normalizeFtsQuery(query) {
+    return query
+        .trim()
+        .split(/\s+/)
+        .map((token) => token.replace(/[^a-zA-Z0-9_]/g, ''))
+        .filter((token) => token.length > 0)
+        .map((token) => `${token}*`)
+        .join(' ');
+}

package/dist/domains/workspace/knowledge-index.js

@@ -1,6 +1,7 @@
 import { readFileSync, statSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
+import { chunkMarkdown, normalizeFtsQuery } from './indexing.js';
 const SCHEMA = `
   CREATE TABLE IF NOT EXISTS chunks (
     id       INTEGER PRIMARY KEY,
@@ -93,59 +94,3 @@ export class KnowledgeIndex {
         this.db.close();
     }
 }
-function chunkMarkdown(content) {
-    const stripped = content.replace(/^---[\s\S]*?---\n?/, '');
-    const cleaned = stripped
-        .replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1')
-        .replace(/<!--[\s\S]*?-->/g, '')
-        .trim();
-    const lines = cleaned.split('\n');
-    const chunks = [];
-    let currentHeading = null;
-    let currentLines = [];
-    const flush = () => {
-        const body = currentLines.join('\n').trim();
-        if (!body)
-            return;
-        if (body.length > 1500) {
-            const paragraphs = body.split(/\n{2,}/);
-            let acc = '';
-            for (const para of paragraphs) {
-                if (acc.length + para.length > 1500 && acc.length > 0) {
-                    chunks.push({ heading: currentHeading, body: acc.trim() });
-                    acc = para;
-                }
-                else {
-                    acc = acc ? `${acc}\n\n${para}` : para;
-                }
-            }
-            if (acc.trim())
-                chunks.push({ heading: currentHeading, body: acc.trim() });
-        }
-        else {
-            chunks.push({ heading: currentHeading, body });
-        }
-        currentLines = [];
-    };
-    for (const line of lines) {
-        const headingMatch = /^(#{1,3})\s+(.+)/.exec(line);
-        if (headingMatch) {
-            flush();
-            currentHeading = headingMatch[2].trim();
-        }
-        else {
-            currentLines.push(line);
-        }
-    }
-    flush();
-    return chunks;
-}
-function normalizeFtsQuery(query) {
-    return query
-        .trim()
-        .split(/\s+/)
-        .map((token) => token.replace(/[^a-zA-Z0-9_]/g, ''))
-        .filter((token) => token.length > 0)
-        .map((token) => `${token}*`)
-        .join(' ');
-}

package/dist/domains/workspace/llm-adapter.js

@@ -0,0 +1 @@
+export {};

package/dist/domains/workspace/process-inbox.js

@@ -0,0 +1,275 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+function buildDedupePrompt(fileContent, filePath, knowledgeMatches, inboxMatches) {
+    return `You are classifying an inbox file to decide how to compile it into a knowledge base.
+
+FILE: ${filePath}
+
+CONTENT:
+${fileContent}
+
+EXISTING KNOWLEDGE MATCHES (from knowledge/ FTS search):
+${knowledgeMatches || 'none'}
+
+EXISTING INBOX MATCHES (from inbox/ FTS search, excluding this file):
+${inboxMatches || 'none'}
+
+Based on the content and search results, respond with ONLY this block and nothing else:
+
+FILE: ${filePath}
+DECISION: new | extend | skip
+TYPE: concept | connection
+TARGET: <existing knowledge article path under knowledge/, or "none">
+REASON: <one sentence>
+
+Rules:
+- new: no meaningful overlap in search results
+- extend: an existing knowledge article covers the same ground
+- skip: content already fully captured, nothing to add
+- concept: atomic knowledge, pattern, lesson, or reference
+- connection: reveals a non-obvious relationship between 2+ existing concepts`;
+}
+function buildCompileNewPrompt(fileContent, filePath, articleType) {
+    const isConnection = articleType === 'connection';
+    const frontmatterExample = isConnection
+        ? `---\ntitle: "Connection: X and Y"\nconnects:\n  - "concepts/concept-x"\n  - "concepts/concept-y"\nsources:\n  - "${filePath}"\ncreated: ${todayISO()}\nupdated: ${todayISO()}\n---`
+        : `---\ntitle: "Concept Name"\ntags: []\nsources:\n  - "${filePath}"\ncreated: ${todayISO()}\nupdated: ${todayISO()}\n---`;
+    return `You are compiling an inbox file into a knowledge base article.
+
+SOURCE FILE: ${filePath}
+ARTICLE TYPE: ${articleType}
+
+SOURCE CONTENT:
+${fileContent}
+
+Write a complete markdown article. Return ONLY the article content, no explanation.
+
+Requirements:
+- Start with YAML frontmatter using this structure:
+${frontmatterExample}
+
+- Then the article body containing:
+  - # Title
+  - ## Detail  (preserve source prose verbatim if already well-structured - do not paraphrase)
+  - ## Key Takeaways  (3-5 bullets - ONLY if source is raw unstructured notes)
+  - ## Related  ([[wikilinks]] to related concepts if known)
+  - ## Source
+    - ${filePath}
+
+Content fidelity rule: if the source is already well-structured prose, preserve it
+verbatim or near-verbatim. Add structure around it, do not replace it.
+Only summarise into bullets if the source is raw unstructured notes.`;
+}
+function buildCompileExtendPrompt(fileContent, filePath, existingContent, targetPath) {
+    return `You are extending an existing knowledge base article with new information from an inbox file.
+
+INBOX FILE: ${filePath}
+EXISTING ARTICLE: ${targetPath}
+
+INBOX CONTENT:
+${fileContent}
+
+EXISTING ARTICLE CONTENT:
+${existingContent}
+
+Identify what is genuinely new in the inbox file not already covered in the existing article.
+If nothing is new, respond with exactly: NOTHING_NEW
+
+Otherwise return the COMPLETE updated article with:
+- New content appended or inserted (never rewrite content that is still accurate)
+- ${filePath} added to sources list in YAML frontmatter
+- Updated date in YAML frontmatter set to ${todayISO()}
+- ${filePath} added to ## Source section
+
+Return ONLY the complete updated article content, no explanation.`;
+}
+function parseDedupeResult(response, filePath) {
+    const lines = response.trim().split('\n');
+    const get = (key) => {
+        const line = lines.find((value) => value.startsWith(`${key}:`));
+        return line ? line.slice(key.length + 1).trim().replace(/^["']|["']$/g, '') : '';
+    };
+    const rawDecision = get('DECISION').toLowerCase();
+    const decision = rawDecision === 'extend' ? 'extend' :
+        rawDecision === 'skip' ? 'skip' : 'new';
+    const rawType = get('TYPE').toLowerCase();
+    const type = rawType === 'connection' ? 'connection' : 'concept';
+    const rawTarget = get('TARGET');
+    const target = rawTarget === 'none' || !rawTarget
+        ? null
+        : rawTarget.startsWith('knowledge/')
+            ? rawTarget
+            : `knowledge/${rawTarget.replace(/^\/+/, '')}`;
+    const reason = get('REASON') || 'No reason provided';
+    return { file: filePath, decision, type, target, reason };
+}
+function deriveArticlePath(filePath, type, articleContent) {
+    const titleMatch = /^title:\s*["']?(.+?)["']?\s*$/m.exec(articleContent);
+    const title = titleMatch ? titleMatch[1].trim() : '';
+    const slug = slugify(title || filePath.split('/').pop()?.replace(/\.md$/, '') || 'untitled');
+    const dir = type === 'connection' ? 'connections' : 'concepts';
+    return `knowledge/${dir}/${slug}.md`;
+}
+function appendLog(logPath, entry) {
+    mkdirSync(dirname(logPath), { recursive: true });
+    if (!existsSync(logPath)) {
+        writeFileSync(logPath, '# Build Log\n\n', 'utf8');
+    }
+    const current = readFileSync(logPath, 'utf8');
+    writeFileSync(logPath, `${current}\n${entry}\n`, 'utf8');
+}
+function updateIndex(indexPath, articlePath, type, summary, sourceFile) {
+    const header = '# Knowledge Base Index\n\n| Article | Type | Summary | Sources | Updated |\n|---------|------|---------|---------|---------|';
+    const safeSummary = summary.replace(/\|/g, '\\|');
+    const safeSource = sourceFile.replace(/\|/g, '\\|');
+    const row = `| [[${articlePath.replace(/\.md$/, '')}]] | ${type} | ${safeSummary} | ${safeSource} | ${todayISO()} |`;
+    mkdirSync(dirname(indexPath), { recursive: true });
+    if (!existsSync(indexPath)) {
+        writeFileSync(indexPath, `${header}\n${row}\n`, 'utf8');
+        return;
+    }
+    const current = readFileSync(indexPath, 'utf8');
+    writeFileSync(indexPath, `${current.trimEnd()}\n${row}\n`, 'utf8');
+}
+function updateIndexRow(indexPath, articlePath) {
+    if (!existsSync(indexPath))
+        return;
+    const ref = articlePath.replace(/\.md$/, '');
+    const today = todayISO();
+    const current = readFileSync(indexPath, 'utf8');
+    const updated = current.replace(new RegExp(`(\\|\\s*\\[\\[${escapeRegex(ref)}\\]\\][^|]*\\|[^|]*\\|[^|]*\\|[^|]*\\|)([^|]*)\\|`), `$1 ${today} |`);
+    writeFileSync(indexPath, updated, 'utf8');
+}
+function extractSummary(articleContent) {
+    const takeawaysMatch = /## Key Takeaways\s*\n([\s\S]*?)(?=\n##|$)/.exec(articleContent);
+    if (takeawaysMatch) {
+        const firstBullet = /^[-*]\s+(.+)$/m.exec(takeawaysMatch[1]);
+        if (firstBullet)
+            return firstBullet[1].trim().slice(0, 100);
+    }
+    const detailMatch = /## Detail\s*\n([\s\S]*?)(?=\n##|$)/.exec(articleContent);
+    if (detailMatch) {
+        return detailMatch[1].trim().split('\n')[0]?.slice(0, 100) ?? '';
+    }
+    return '';
+}
+function todayISO() {
+    return new Date().toISOString().slice(0, 10);
+}
+function nowISO() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, '')
+        .trim()
+        .replace(/\s+/g, '-')
+        .replace(/-+/g, '-')
+        .slice(0, 60) || 'untitled';
+}
+function escapeRegex(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function extractKeyTerms(content) {
+    const stripped = content
+        .replace(/^---[\s\S]*?---\n?/, '')
+        .replace(/[#*`[\]()]/g, ' ')
+        .toLowerCase();
+    const stopWords = new Set([
+        'the', 'and', 'for', 'are', 'but', 'not', 'you', 'all', 'can',
+        'has', 'was', 'this', 'that', 'with', 'from', 'they', 'will',
+        'have', 'been', 'when', 'what', 'how', 'its', 'one', 'out',
+    ]);
+    const freq = new Map();
+    for (const word of stripped.split(/\s+/)) {
+        const clean = word.replace(/[^a-z0-9-]/g, '');
+        if (clean.length >= 4 && !stopWords.has(clean)) {
+            freq.set(clean, (freq.get(clean) ?? 0) + 1);
+        }
+    }
+    return [...freq.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 3)
+        .map(([word]) => word);
+}
+export async function processInbox(service, llm, workspaceName, limit) {
+    const workspace = service.resolve(workspaceName);
+    const logPath = join(workspace.path, 'knowledge', 'log.md');
+    const indexPath = join(workspace.path, 'knowledge', 'index.md');
+    mkdirSync(join(workspace.path, 'knowledge'), { recursive: true });
+    const results = [];
+    let fileCount = 0;
+    while (true) {
+        if (limit !== undefined && fileCount >= limit)
+            break;
+        const inbox = service.listInbox(workspaceName);
+        if (inbox.files.length === 0)
+            break;
+        const nextFile = inbox.files[0];
+        const filePath = nextFile.path;
+        fileCount++;
+        try {
+            const { content: fileContent } = service.read(workspaceName, filePath);
+            const keyTerms = extractKeyTerms(fileContent);
+            const query = keyTerms.join(' ');
+            const knowledgeMatches = service.search(workspaceName, query, 5);
+            const inboxMatches = service.searchInbox(workspaceName, query, 5);
+            const knowledgeMatchText = knowledgeMatches.results
+                .map((result) => `- ${result.file}: ${result.excerpt.slice(0, 100)}`)
+                .join('\n');
+            const inboxMatchText = inboxMatches.results
+                .filter((result) => result.file !== filePath)
+                .map((result) => `- ${result.file}: ${result.excerpt.slice(0, 100)}`)
+                .join('\n');
+            const dedupePrompt = buildDedupePrompt(fileContent, filePath, knowledgeMatchText, inboxMatchText);
+            const dedupeResponse = await llm.complete(dedupePrompt);
+            const dedupe = parseDedupeResult(dedupeResponse, filePath);
+            if (dedupe.decision === 'skip') {
+                appendLog(logPath, `## [${nowISO()}] skip\n- Source: ${filePath}\n- Reason: ${dedupe.reason}`);
+                service.archive(workspaceName, filePath);
+                results.push({ file: filePath, decision: 'skip', articlePath: null, reason: dedupe.reason });
+                continue;
+            }
+            if (dedupe.decision === 'extend' && dedupe.target) {
+                const { content: existingContent } = service.read(workspaceName, dedupe.target);
+                const extendPrompt = buildCompileExtendPrompt(fileContent, filePath, existingContent, dedupe.target);
+                const extendResponse = await llm.complete(extendPrompt);
+                if (extendResponse.trim() === 'NOTHING_NEW') {
+                    appendLog(logPath, `## [${nowISO()}] skip\n- Source: ${filePath}\n- Reason: Nothing new vs ${dedupe.target}`);
+                    service.archive(workspaceName, filePath);
+                    results.push({ file: filePath, decision: 'skip', articlePath: dedupe.target, reason: 'Nothing new' });
+                    continue;
+                }
+                service.write(workspaceName, dedupe.target.replace(/^knowledge\//, ''), extendResponse);
+                updateIndexRow(indexPath, dedupe.target);
+                appendLog(logPath, `## [${nowISO()}] extend\n- Source: ${filePath}\n- Updated: [[${dedupe.target.replace(/\.md$/, '')}]]`);
+                service.archive(workspaceName, filePath);
+                results.push({ file: filePath, decision: 'extend', articlePath: dedupe.target, reason: dedupe.reason });
+                continue;
+            }
+            const compilePrompt = buildCompileNewPrompt(fileContent, filePath, dedupe.type);
+            const articleContent = await llm.complete(compilePrompt);
+            const resolvedArticlePath = deriveArticlePath(filePath, dedupe.type, articleContent);
+            service.write(workspaceName, resolvedArticlePath.replace(/^knowledge\//, ''), articleContent);
+            const summary = extractSummary(articleContent);
+            updateIndex(indexPath, resolvedArticlePath, dedupe.type, summary, filePath);
+            appendLog(logPath, `## [${nowISO()}] compile\n- Source: ${filePath}\n- Created: [[${resolvedArticlePath.replace(/\.md$/, '')}]]\n- Updated: index.md, log.md`);
+            service.archive(workspaceName, filePath);
+            results.push({ file: filePath, decision: 'new', articlePath: resolvedArticlePath, reason: dedupe.reason });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            results.push({ file: filePath, decision: 'skip', articlePath: null, reason: 'error', error: message });
+        }
+    }
+    const completed = results.filter((result) => result.error === undefined);
+    return {
+        processed: results,
+        total: results.length,
+        compiled: completed.filter((result) => result.decision === 'new').length,
+        extended: completed.filter((result) => result.decision === 'extend').length,
+        skipped: completed.filter((result) => result.decision === 'skip').length,
+        errors: results.filter((result) => result.error !== undefined).length,
+    };
+}

package/dist/domains/workspace/workspace.service.js

@@ -1,8 +1,9 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
-import { basename, dirname, resolve, join, relative } from 'node:path';
+import { basename, dirname, resolve, join, relative, sep } from 'node:path';
 import { execSync } from 'node:child_process';
 import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 import { KnowledgeIndex } from './knowledge-index.js';
+import { InboxIndex } from './inbox-index.js';
 import { loadConfig } from '../../shared/config/index.js';
 export class WorkspaceService {
     config;
@@ -28,11 +29,19 @@ export class WorkspaceService {
     status(name) {
         const workspace = this.resolve(name);
         const exists = existsSync(workspace.path);
+        const inboxRoot = join(workspace.path, 'inbox');
+        const knowledgeRoot = join(workspace.path, 'knowledge');
+        const inboxCount = exists && existsSync(inboxRoot)
+            ? this.collectMarkdownFiles(workspace.path, inboxRoot, ['archived']).length
+            : 0;
+        const knowledgeCount = exists && existsSync(knowledgeRoot)
+            ? this.collectMarkdownFiles(workspace.path, knowledgeRoot).length
+            : 0;
         return {
             ...workspace,
             exists,
-            inboxCount: 0,
-            knowledgeCount: 0,
+            inboxCount,
+            knowledgeCount,
             lastCompiled: null,
         };
     }
@@ -42,13 +51,26 @@ export class WorkspaceService {
         mkdirSync(inboxPath, { recursive: true });
         const filePath = join(inboxPath, `${currentDateStamp()}-${slugify(title)}.md`);
         writeFileSync(filePath, content, 'utf8');
+        const index = new InboxIndex(workspace.path);
+        try {
+            index.indexFile(filePath);
+        }
+        finally {
+            index.close();
+        }
         return {
             file: relative(workspace.path, filePath),
             workspace: workspace.name,
         };
     }
     ingestClipboard(name, title) {
-        const clipboard = execSync('pbpaste', { encoding: 'utf8' });
+        let clipboard;
+        try {
+            clipboard = execSync('pbpaste', { encoding: 'utf8' });
+        }
+        catch {
+            throw new McpError(ErrorCode.InternalError, 'knowledge_ingest_clipboard requires macOS (pbpaste unavailable)');
+        }
         return this.ingestText(name, clipboard, title);
     }
     async ingestUrl(name, url, title) {
@@ -87,9 +109,97 @@ export class WorkspaceService {
             index.close();
         }
     }
+    searchInbox(name, query, limit = 10) {
+        const workspace = this.resolve(name);
+        const inboxRoot = join(workspace.path, 'inbox');
+        if (!existsSync(inboxRoot)) {
+            return { results: [] };
+        }
+        const index = new InboxIndex(workspace.path);
+        try {
+            const files = this.collectMarkdownFiles(workspace.path, inboxRoot, ['archived']);
+            for (const file of files) {
+                index.indexFile(join(workspace.path, file.path));
+            }
+            return index.search(query, limit);
+        }
+        finally {
+            index.close();
+        }
+    }
+    getNextInboxFile(name) {
+        const workspace = this.resolve(name);
+        const inboxRoot = join(workspace.path, 'inbox');
+        if (!existsSync(inboxRoot)) {
+            return null;
+        }
+        const files = this.collectMarkdownFiles(workspace.path, inboxRoot, ['archived']);
+        if (files.length === 0) {
+            return null;
+        }
+        const first = files[0];
+        const absPath = join(workspace.path, first.path);
+        const content = readFileSync(absPath, 'utf8');
+        return {
+            file: first.path,
+            content,
+            size: first.size,
+            modified: first.modified,
+        };
+    }
+    getDedupeContext(name, file, query) {
+        const knowledgeMatches = this.search(name, query, 5);
+        const inboxMatches = this.searchInbox(name, query, 5);
+        return {
+            file,
+            knowledgeMatches: knowledgeMatches.results.filter((result) => result.file !== file),
+            inboxMatches: inboxMatches.results.filter((result) => result.file !== file),
+        };
+    }
+    compileNew(name, inboxFile, articlePath, content) {
+        const workspace = this.resolve(name);
+        const knowledgeRoot = join(workspace.path, 'knowledge');
+        mkdirSync(knowledgeRoot, { recursive: true });
+        this.write(name, articlePath, content);
+        const indexPath = join(knowledgeRoot, 'index.md');
+        const summary = extractSummary(content);
+        const today = todayISO();
+        const ref = `knowledge/${articlePath}`.replace(/\.md$/, '');
+        const row = `| [[${ref}]] | ${summary} | ${inboxFile} | ${today} |`;
+        if (!existsSync(indexPath)) {
+            writeFileSync(indexPath, '# Knowledge Base Index\n\n| Article | Summary | Sources | Updated |\n|---------|---------|---------|---------|\n' + row + '\n', 'utf8');
+        }
+        else {
+            const current = readFileSync(indexPath, 'utf8');
+            writeFileSync(indexPath, current.trimEnd() + '\n' + row + '\n', 'utf8');
+        }
+        appendLog(join(knowledgeRoot, 'log.md'), `## [${nowISO()}] compile\n- Source: ${inboxFile}\n- Created: [[${ref}]]\n- Updated: index.md, log.md`);
+        this.archive(name, inboxFile);
+        return { articlePath: `knowledge/${articlePath}`, inboxFile, workspace: name };
+    }
+    compileExtend(name, inboxFile, targetPath, updatedContent) {
+        const workspace = this.resolve(name);
+        const knowledgeRoot = join(workspace.path, 'knowledge');
+        this.write(name, targetPath.replace(/^knowledge\//, ''), updatedContent);
+        const indexPath = join(knowledgeRoot, 'index.md');
+        if (existsSync(indexPath)) {
+            const ref = targetPath.replace(/\.md$/, '');
+            const today = todayISO();
+            const current = readFileSync(indexPath, 'utf8');
+            const updated = current.replace(new RegExp(`(\\|\\s*\\[\\[${escapeRegex(ref)}\\]\\][^|]*\\|[^|]*\\|[^|]*\\|)([^|]*)\\|`), `$1 ${today} |`);
+            writeFileSync(indexPath, updated, 'utf8');
+        }
+        const ref = targetPath.replace(/\.md$/, '');
+        appendLog(join(knowledgeRoot, 'log.md'), `## [${nowISO()}] extend\n- Source: ${inboxFile}\n- Updated: [[${ref}]]`);
+        this.archive(name, inboxFile);
+        return { targetPath, inboxFile, workspace: name };
+    }
     read(name, pathName) {
         const workspace = this.resolve(name);
         const filePath = resolve(workspace.path, pathName);
+        if (!filePath.startsWith(workspace.path + sep)) {
+            throw new McpError(ErrorCode.InvalidParams, 'Path escapes workspace boundary');
+        }
         const content = readFileSync(filePath, 'utf8');
         return {
             content,
@@ -120,7 +230,11 @@ export class WorkspaceService {
     }
     write(name, pathName, content) {
         const workspace = this.resolve(name);
-        const target = join(workspace.path, 'knowledge', pathName);
+        const knowledgeRoot = join(workspace.path, 'knowledge');
+        const target = join(knowledgeRoot, pathName);
+        if (!target.startsWith(knowledgeRoot + sep)) {
+            throw new McpError(ErrorCode.InvalidParams, 'Path escapes knowledge boundary');
+        }
         mkdirSync(dirname(target), { recursive: true });
         writeFileSync(target, content, 'utf8');
         return {
@@ -130,17 +244,31 @@ export class WorkspaceService {
     }
     archive(name, file) {
         const workspace = this.resolve(name);
-        const source = join(workspace.path, file);
+        const inboxRoot = join(workspace.path, 'inbox');
+        const source = resolve(workspace.path, file);
+        if (!source.startsWith(inboxRoot + sep)) {
+            throw new McpError(ErrorCode.InvalidParams, 'File must be within inbox/');
+        }
+        if (source.startsWith(join(inboxRoot, 'archived') + sep)) {
+            throw new McpError(ErrorCode.InvalidParams, 'File is already archived');
+        }
         if (!existsSync(source)) {
             throw new McpError(ErrorCode.InvalidParams, `File not found: ${file}`);
         }
-        const archivedDir = join(workspace.path, 'inbox', 'archived');
+        const archivedDir = join(inboxRoot, 'archived');
         mkdirSync(archivedDir, { recursive: true });
         let destination = join(archivedDir, basename(source));
         if (existsSync(destination)) {
             destination = join(archivedDir, `${Date.now()}-${basename(source)}`);
         }
         renameSync(source, destination);
+        const index = new InboxIndex(workspace.path);
+        try {
+            index.removeFile(source);
+        }
+        finally {
+            index.close();
+        }
         return {
             original: relative(workspace.path, source),
             archived: relative(workspace.path, destination),
@@ -196,3 +324,31 @@ function extractJinaTitle(content) {
     const match = /^Title:\s*(.+)$/m.exec(content);
     return match ? match[1].trim() : null;
 }
+function todayISO() {
+    return new Date().toISOString().slice(0, 10);
+}
+function nowISO() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+function escapeRegex(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function extractSummary(content) {
+    const takeaways = /## Key Takeaways\s*\n([\s\S]*?)(?=\n##|$)/.exec(content);
+    if (takeaways) {
+        const bullet = /^[-*]\s+(.+)$/m.exec(takeaways[1]);
+        if (bullet)
+            return bullet[1].trim().slice(0, 100).replace(/\|/g, '\\|');
+    }
+    const detail = /## Detail\s*\n([\s\S]*?)(?=\n##|$)/.exec(content);
+    if (detail)
+        return detail[1].trim().split('\n')[0]?.slice(0, 100).replace(/\|/g, '\\|') ?? '';
+    return '';
+}
+function appendLog(logPath, entry) {
+    if (!existsSync(logPath)) {
+        writeFileSync(logPath, '# Build Log\n\n', 'utf8');
+    }
+    const current = readFileSync(logPath, 'utf8');
+    writeFileSync(logPath, current.trimEnd() + '\n\n' + entry + '\n', 'utf8');
+}

package/dist/index.js

@@ -2,3 +2,4 @@
 // and other consumers without requiring the MCP protocol.
 export { WorkspaceService } from './domains/workspace/workspace.service.js';
 export { KnowledgeIndex } from './domains/workspace/knowledge-index.js';
+export { InboxIndex } from './domains/workspace/inbox-index.js';

package/dist/infrastructure/mcp/mcp-server.js

@@ -1,7 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { WorkspaceService } from '../../domains/workspace/index.js';
-import { KnowledgeArchiveSchema, KnowledgeIngestClipboardSchema, KnowledgeIngestTextSchema, KnowledgeIngestUrlSchema, KnowledgeListInboxSchema, KnowledgeListSchema, KnowledgeListWorkspacesSchema, KnowledgeReadSchema, KnowledgeSearchSchema, KnowledgeWorkspaceStatusSchema, KnowledgeWriteSchema, } from './tool-schemas.js';
+import { KnowledgeArchiveSchema, KnowledgeCompileExtendSchema, KnowledgeCompileNewSchema, KnowledgeGetDedupeContextSchema, KnowledgeGetNextInboxFileSchema, KnowledgeIngestClipboardSchema, KnowledgeIngestTextSchema, KnowledgeIngestUrlSchema, KnowledgeListInboxSchema, KnowledgeListSchema, KnowledgeListWorkspacesSchema, KnowledgeReadSchema, KnowledgeSearchInboxSchema, KnowledgeSearchSchema, KnowledgeWorkspaceStatusSchema, KnowledgeWriteSchema, } from './tool-schemas.js';
 function textContent(value) {
     return {
         content: [
@@ -24,6 +24,11 @@ export function createMcpServer() {
     server.tool('knowledge_ingest_clipboard', 'Read clipboard text and write it into a workspace inbox.', KnowledgeIngestClipboardSchema, async ({ workspace, title }) => textContent(service.ingestClipboard(workspace, title)));
     server.tool('knowledge_ingest_url', 'Ingest a URL into a workspace inbox.', KnowledgeIngestUrlSchema, async ({ workspace, url, title }) => textContent(await service.ingestUrl(workspace, url, title)));
     server.tool('knowledge_search', 'Search workspace knowledge.', KnowledgeSearchSchema, async ({ workspace, query, limit }) => textContent(service.search(workspace, query, limit)));
+    server.tool('knowledge_search_inbox', 'Full-text search over uncompiled inbox files in a workspace. Use this before compiling to check if an inbox file overlaps with existing inbox content.', KnowledgeSearchInboxSchema, async ({ workspace, query, limit }) => textContent(service.searchInbox(workspace, query, limit)));
+    server.tool('knowledge_get_next_inbox_file', 'Get the next unprocessed inbox file and its content. Returns null when inbox is empty. Call this to start processing one file.', KnowledgeGetNextInboxFileSchema, async ({ workspace }) => textContent(service.getNextInboxFile(workspace)));
+    server.tool('knowledge_get_dedupe_context', 'Run FTS searches against knowledge/ and inbox/ for a given query and return results. Call this after reading an inbox file to check for overlap before deciding whether to compile new, extend, or skip.', KnowledgeGetDedupeContextSchema, async ({ workspace, file, query }) => textContent(service.getDedupeContext(workspace, file, query)));
+    server.tool('knowledge_compile_new', 'Write a compiled article to knowledge/, update index.md, append to log.md, and archive the inbox file. Call this when decision is "new". Provide the article content you have written and the target path within knowledge/.', KnowledgeCompileNewSchema, async ({ workspace, inbox_file, article_path, content }) => textContent(service.compileNew(workspace, inbox_file, article_path, content)));
+    server.tool('knowledge_compile_extend', 'Write an updated article to knowledge/, update the Updated column in index.md, append to log.md, and archive the inbox file. Call this when decision is "extend". Provide the full updated article content.', KnowledgeCompileExtendSchema, async ({ workspace, inbox_file, target_path, content }) => textContent(service.compileExtend(workspace, inbox_file, target_path, content)));
     server.tool('knowledge_list_inbox', 'List uncompiled files in a workspace inbox.', KnowledgeListInboxSchema, async ({ workspace }) => textContent(service.listInbox(workspace)));
     server.tool('knowledge_write', 'Write a compiled article into the workspace knowledge directory.', KnowledgeWriteSchema, async ({ workspace, path, content }) => textContent(service.write(workspace, path, content)));
     server.tool('knowledge_archive', 'Move a processed inbox file to inbox/archived/.', KnowledgeArchiveSchema, async ({ workspace, file }) => textContent(service.archive(workspace, file)));

package/dist/infrastructure/mcp/tool-schemas.js

@@ -22,6 +22,31 @@ const KnowledgeSearchInputSchema = z.object({
     query: z.string(),
     limit: z.number().int().positive().optional(),
 });
+const KnowledgeSearchInboxInputSchema = z.object({
+    workspace: z.string(),
+    query: z.string(),
+    limit: z.number().int().positive().optional(),
+});
+const KnowledgeGetNextInboxFileInputSchema = z.object({
+    workspace: z.string(),
+});
+const KnowledgeGetDedupeContextInputSchema = z.object({
+    workspace: z.string(),
+    file: z.string().describe('Inbox file path relative to workspace root'),
+    query: z.string().describe('2-3 key terms extracted from the file content'),
+});
+const KnowledgeCompileNewInputSchema = z.object({
+    workspace: z.string(),
+    inbox_file: z.string().describe('Inbox file path to archive after compile'),
+    article_path: z.string().describe('Target path relative to knowledge/ e.g. "concepts/my-article.md"'),
+    content: z.string().describe('Full compiled article markdown including YAML frontmatter'),
+});
+const KnowledgeCompileExtendInputSchema = z.object({
+    workspace: z.string(),
+    inbox_file: z.string().describe('Inbox file path to archive after extend'),
+    target_path: z.string().describe('Existing article path relative to workspace root e.g. "knowledge/concepts/existing.md"'),
+    content: z.string().describe('Full updated article markdown including YAML frontmatter'),
+});
 const KnowledgeListInboxInputSchema = z.object({
     workspace: z.string(),
 });
@@ -48,6 +73,11 @@ export const KnowledgeIngestTextSchema = KnowledgeIngestTextInputSchema.shape;
 export const KnowledgeIngestClipboardSchema = KnowledgeIngestClipboardInputSchema.shape;
 export const KnowledgeIngestUrlSchema = KnowledgeIngestUrlInputSchema.shape;
 export const KnowledgeSearchSchema = KnowledgeSearchInputSchema.shape;
+export const KnowledgeSearchInboxSchema = KnowledgeSearchInboxInputSchema.shape;
+export const KnowledgeGetNextInboxFileSchema = KnowledgeGetNextInboxFileInputSchema.shape;
+export const KnowledgeGetDedupeContextSchema = KnowledgeGetDedupeContextInputSchema.shape;
+export const KnowledgeCompileNewSchema = KnowledgeCompileNewInputSchema.shape;
+export const KnowledgeCompileExtendSchema = KnowledgeCompileExtendInputSchema.shape;
 export const KnowledgeListInboxSchema = KnowledgeListInboxInputSchema.shape;
 export const KnowledgeWriteSchema = KnowledgeWriteInputSchema.shape;
 export const KnowledgeArchiveSchema = KnowledgeArchiveInputSchema.shape;
@@ -60,6 +90,11 @@ export const ToolSchemas = {
     knowledge_ingest_clipboard: KnowledgeIngestClipboardSchema,
     knowledge_ingest_url: KnowledgeIngestUrlSchema,
     knowledge_search: KnowledgeSearchSchema,
+    knowledge_search_inbox: KnowledgeSearchInboxSchema,
+    knowledge_get_next_inbox_file: KnowledgeGetNextInboxFileSchema,
+    knowledge_get_dedupe_context: KnowledgeGetDedupeContextSchema,
+    knowledge_compile_new: KnowledgeCompileNewSchema,
+    knowledge_compile_extend: KnowledgeCompileExtendSchema,
     knowledge_list_inbox: KnowledgeListInboxSchema,
     knowledge_write: KnowledgeWriteSchema,
     knowledge_archive: KnowledgeArchiveSchema,

package/dist/server.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import { startMcpServer } from './infrastructure/mcp/index.js';
 startMcpServer().catch((err) => {
     const message = err instanceof Error ? err.message : String(err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teknologika/chisel-knowledge-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Standalone MCP server and library for building and managing knowledge workspaces.",
   "type": "module",
   "exports": {