@kibhq/cli 0.1.0 → 0.3.0

package/README.md

@@ -0,0 +1,130 @@
+# kib
+
+The Headless Knowledge Compiler. A CLI-first, LLM-powered tool that turns raw source material into a structured, queryable markdown wiki — maintained entirely by AI.
+
+`git` for knowledge — ingest, compile, query, lint, all from the terminal.
+
+## Install
+
+```bash
+# Requires Bun (https://bun.sh)
+npm i -g @kibhq/cli
+
+# or run without installing
+npx @kibhq/cli init
+```
+
+Standalone binaries for macOS and Linux are available on the [releases page](https://github.com/keeganthomp/kib/releases).
+
+## Quick Start
+
+```bash
+# Initialize a vault
+kib init
+
+# Ingest sources (URLs, files, PDFs, YouTube, GitHub repos)
+kib ingest https://arxiv.org/abs/1706.03762
+kib ingest ./papers/*.pdf
+kib ingest https://www.youtube.com/watch?v=...
+
+# Compile into wiki articles
+kib compile
+
+# Search your knowledge base
+kib search "attention mechanisms"
+
+# Ask questions (RAG over your wiki)
+kib query "what are the tradeoffs between MoE and dense models?"
+
+# Interactive chat
+kib chat
+```
+
+## Commands
+
+```
+CORE
+  init                Create a new vault in the current directory
+  ingest <source>     Ingest sources into raw/ (URLs, files, PDFs, etc.)
+  compile             Compile raw sources into wiki articles via LLM
+  query <question>    Ask a question against the knowledge base (RAG)
+  search <term>       Fast BM25 text search across the vault
+  chat                Interactive REPL with conversation history
+  lint                Run health checks on the wiki
+  status              Vault health dashboard
+
+INTEGRATION
+  serve --mcp         Start MCP server for AI tool integration
+  watch               Watch inbox/ and auto-ingest new files
+
+MANAGEMENT
+  config [key] [val]  Get or set configuration
+  skill <sub> [name]  Manage skills (list, run)
+  export              Export wiki to markdown or HTML
+```
+
+## LLM Providers
+
+On first use, kib walks you through provider setup interactively. Or set via environment:
+
+| Provider | Env Variable | Default Model |
+|----------|-------------|---------------|
+| Anthropic | `ANTHROPIC_API_KEY` | claude-sonnet-4-20250514 |
+| OpenAI | `OPENAI_API_KEY` | gpt-4o |
+| Ollama | (auto-detect localhost:11434) | llama3 |
+
+## Vault Structure
+
+```
+my-vault/
+├── .kb/                  # Config, manifest, cache
+├── raw/                  # Ingested source material (never modified by compile)
+│   ├── articles/
+│   ├── papers/
+│   ├── transcripts/
+│   └── repos/
+├── wiki/                 # LLM-compiled knowledge base
+│   ├── INDEX.md          # Master index
+│   ├── GRAPH.md          # Article relationship graph
+│   ├── concepts/
+│   ├── topics/
+│   ├── references/
+│   └── outputs/
+└── inbox/                # Drop zone for kib watch
+```
+
+The vault is just files. View it in any editor. Version it with git. No lock-in.
+
+## MCP Server
+
+Expose your vault as MCP tools for AI tool integration:
+
+```bash
+kib serve --mcp
+```
+
+8 tools: `kib_status`, `kib_list`, `kib_read`, `kib_search`, `kib_query`, `kib_ingest`, `kib_compile`, `kib_lint`
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "kib": {
+      "command": "kib",
+      "args": ["serve", "--mcp"],
+      "cwd": "/path/to/your/vault"
+    }
+  }
+}
+```
+
+## Links
+
+- [GitHub](https://github.com/keeganthomp/kib)
+- [Roadmap](https://github.com/keeganthomp/kib/blob/main/ROADMAP.md)
+- [@kibhq/core](https://www.npmjs.com/package/@kibhq/core) — core engine (for programmatic use)
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,7 @@
 {
 	"name": "@kibhq/cli",
-	"version": "0.1.0",
+	"version": "0.3.0",
+	"description": "The Headless Knowledge Compiler — turn raw sources into a structured, queryable wiki with AI",
 	"type": "module",
 	"bin": {
 		"kib": "./bin/kib.ts"
@@ -8,6 +9,7 @@
 	"files": [
 		"bin",
 		"src",
+		"README.md",
 		"package.json"
 	],
 	"repository": {
@@ -16,6 +18,9 @@
 		"directory": "packages/cli"
 	},
 	"license": "MIT",
+	"publishConfig": {
+		"access": "public"
+	},
 	"keywords": [
 		"knowledge-base",
 		"wiki",
@@ -30,9 +35,10 @@
 		"test": "bun test"
 	},
 	"dependencies": {
-		"@kibhq/core": "workspace:*",
-		"commander": "^14.0.0",
+		"@kibhq/core": "^0.1.0",
+		"@modelcontextprotocol/sdk": "^1.29.0",
 		"chalk": "^5.4.1",
+		"commander": "^14.0.0",
 		"ora": "^8.2.0"
 	},
 	"devDependencies": {

package/src/commands/chat.ts

@@ -1,5 +1,5 @@
 import * as readline from "node:readline";
-import type { Message } from "@kibhq/core";
+import type { LLMProvider, Message } from "@kibhq/core";
 import {
 	createProvider,
 	loadConfig,
@@ -25,7 +25,7 @@ export async function chat() {
 	const config = await loadConfig(root);
 
 	// Create provider
-	let provider;
+	let provider: LLMProvider;
 	try {
 		provider = await createProvider(config.provider.default, config.provider.model);
 	} catch (err) {

package/src/commands/compile.ts

@@ -1,3 +1,4 @@
+import type { LLMProvider } from "@kibhq/core";
 import {
 	createProvider,
 	loadConfig,
@@ -33,7 +34,7 @@ export async function compile(opts: CompileOpts) {
 	log.header("compiling wiki");
 
 	// Create LLM provider
-	let provider;
+	let provider: LLMProvider;
 	const providerSpinner = createSpinner("Connecting to LLM provider...");
 	providerSpinner.start();
 	try {

package/src/commands/config.ts

@@ -45,28 +45,32 @@ export async function config(key?: string, value?: string, opts?: { list?: boole
 	}
 }
 
-function getNestedValue(obj: any, path: string): unknown {
+function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
 	const parts = path.split(".");
-	let current = obj;
+	let current: unknown = obj;
 	for (const part of parts) {
 		if (current == null || typeof current !== "object") return undefined;
-		current = current[part];
+		current = (current as Record<string, unknown>)[part];
 	}
 	return current;
 }
 
-function setNestedValue(obj: any, path: string, value: unknown): boolean {
+function setNestedValue(obj: Record<string, unknown>, path: string, value: unknown): boolean {
 	const parts = path.split(".");
-	let current = obj;
+	let current: unknown = obj;
 	for (let i = 0; i < parts.length - 1; i++) {
 		if (current == null || typeof current !== "object") return false;
-		current = current[parts[i]!];
+		current = (current as Record<string, unknown>)[parts[i]!];
 	}
 	const lastKey = parts[parts.length - 1]!;
-	if (current == null || typeof current !== "object" || !(lastKey in current)) {
+	if (
+		current == null ||
+		typeof current !== "object" ||
+		!(lastKey in (current as Record<string, unknown>))
+	) {
 		return false;
 	}
-	current[lastKey] = value;
+	(current as Record<string, unknown>)[lastKey] = value;
 	return true;
 }
 
@@ -78,7 +82,7 @@ function parseValue(val: string): unknown {
 	return val;
 }
 
-function printConfig(obj: any, prefix: string) {
+function printConfig(obj: Record<string, unknown>, prefix: string) {
 	for (const [key, val] of Object.entries(obj)) {
 		const fullKey = prefix ? `${prefix}.${key}` : key;
 		if (val != null && typeof val === "object" && !Array.isArray(val)) {

package/src/commands/init.ts

@@ -19,7 +19,7 @@ export async function init(opts: InitOpts) {
 		const provider = opts.provider ?? detected.name;
 		const model = detected.model;
 
-		const { root, manifest } = await initVault(cwd, {
+		await initVault(cwd, {
 			name: opts.name,
 			provider,
 			model,

package/src/commands/query.ts

@@ -1,3 +1,4 @@
+import type { LLMProvider } from "@kibhq/core";
 import {
 	createProvider,
 	loadConfig,
@@ -30,7 +31,7 @@ export async function query(question: string, opts: QueryOpts) {
 	const config = await loadConfig(root);
 
 	// Create provider
-	let provider;
+	let provider: LLMProvider;
 	try {
 		provider = await createProvider(config.provider.default, config.provider.model);
 	} catch (err) {

package/src/commands/serve.ts

@@ -0,0 +1,31 @@
+import { resolveVaultRoot, VaultNotFoundError } from "@kibhq/core";
+
+interface ServeOpts {
+	mcp?: boolean;
+}
+
+export async function serve(opts: ServeOpts) {
+	if (!opts.mcp) {
+		console.error("Usage: kib serve --mcp");
+		console.error("  Starts an MCP server over stdio for AI tool integration.");
+		process.exit(1);
+	}
+
+	let root: string;
+	try {
+		root = resolveVaultRoot();
+	} catch (e) {
+		if (e instanceof VaultNotFoundError) {
+			console.error(e.message);
+			process.exit(1);
+		}
+		throw e;
+	}
+
+	// Load saved API keys before starting server
+	const { loadCredentials } = await import("../ui/setup-provider.js");
+	loadCredentials();
+
+	const { startMcpServer } = await import("../mcp/server.js");
+	await startMcpServer(root);
+}

package/src/commands/skill.ts

@@ -1,3 +1,4 @@
+import type { LLMProvider } from "@kibhq/core";
 import {
 	createProvider,
 	loadConfig,
@@ -52,7 +53,7 @@ export async function skill(subcommand: string, name?: string, _opts?: unknown)
 
 			log.header(`running skill: ${s.name}`);
 
-			let provider;
+			let provider: LLMProvider | undefined;
 			if (s.llm?.required) {
 				const config = await loadConfig(root);
 				const modelKey = s.llm.model === "fast" ? "fast_model" : "model";

package/src/commands/watch.ts

@@ -1,7 +1,7 @@
 import { watch as fsWatch } from "node:fs";
 import { readdir, stat } from "node:fs/promises";
 import { join, resolve } from "node:path";
-import { INBOX_DIR, loadConfig, resolveVaultRoot, VaultNotFoundError } from "@kibhq/core";
+import { loadConfig, resolveVaultRoot, VaultNotFoundError } from "@kibhq/core";
 import * as log from "../ui/logger.js";
 
 export async function watch() {
@@ -40,7 +40,7 @@ export async function watch() {
 	const server = startHttpServer(root, ingestSource);
 
 	// Watch for new files
-	const watcher = fsWatch(inboxPath, { recursive: false }, async (event, filename) => {
+	const watcher = fsWatch(inboxPath, { recursive: false }, async (_event, filename) => {
 		if (!filename || processed.has(filename)) return;
 		if (filename.startsWith(".")) return; // skip dotfiles
 

package/src/index.ts

@@ -114,6 +114,15 @@ program
 		await watch();
 	});
 
+program
+	.command("serve")
+	.description("Start an MCP server for AI tool integration")
+	.option("--mcp", "expose vault as MCP tools over stdio")
+	.action(async (opts) => {
+		const { serve } = await import("./commands/serve.js");
+		await serve(opts);
+	});
+
 program
 	.command("export")
 	.description("Export wiki to other formats")

package/src/mcp/server.ts

@@ -0,0 +1,332 @@
+import {
+	compileVault,
+	createProvider,
+	ingestSource,
+	type LLMProvider,
+	lintVault,
+	listRaw,
+	listWiki,
+	loadConfig,
+	loadManifest,
+	type Manifest,
+	queryVault,
+	readGraph,
+	readIndex,
+	readRaw,
+	readWiki,
+	SearchIndex,
+	type VaultConfig,
+} from "@kibhq/core";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// ─── Context ────────────────────────────────────────────────────
+
+interface McpContext {
+	root: string;
+	getConfig(): Promise<VaultConfig>;
+	getManifest(): Promise<Manifest>;
+	getProvider(): Promise<LLMProvider>;
+	getSearchIndex(): Promise<SearchIndex>;
+	invalidateSearch(): void;
+}
+
+function createContext(root: string): McpContext {
+	let cachedConfig: VaultConfig | null = null;
+	let cachedProvider: LLMProvider | null = null;
+	let cachedIndex: SearchIndex | null = null;
+
+	return {
+		root,
+		async getConfig() {
+			if (!cachedConfig) cachedConfig = await loadConfig(root);
+			return cachedConfig;
+		},
+		async getManifest() {
+			// Always re-read — vault mutates
+			return loadManifest(root);
+		},
+		async getProvider() {
+			if (!cachedProvider) {
+				const config = await this.getConfig();
+				cachedProvider = await createProvider(config.provider.default, config.provider.model);
+			}
+			return cachedProvider;
+		},
+		async getSearchIndex() {
+			if (!cachedIndex) {
+				cachedIndex = new SearchIndex();
+				const loaded = await cachedIndex.load(root);
+				if (!loaded) {
+					await cachedIndex.build(root, "all");
+					await cachedIndex.save(root);
+				}
+			}
+			return cachedIndex;
+		},
+		invalidateSearch() {
+			cachedIndex = null;
+		},
+	};
+}
+
+// ─── Helpers ────────────────────────────────────────────────────
+
+function ok(text: string) {
+	return { content: [{ type: "text" as const, text }] };
+}
+
+function err(text: string) {
+	return { content: [{ type: "text" as const, text }], isError: true as const };
+}
+
+function json(data: unknown) {
+	return ok(JSON.stringify(data, null, 2));
+}
+
+// ─── Server ─────────────────────────────────────────────────────
+
+export async function startMcpServer(root: string) {
+	const ctx = createContext(root);
+
+	const server = new McpServer({
+		name: "kib",
+		version: "0.2.0",
+	});
+
+	// ── kib_status ────────────────────────────────────────────
+
+	server.tool(
+		"kib_status",
+		"Get vault status: source count, article count, provider, and config",
+		{},
+		async () => {
+			try {
+				const manifest = await ctx.getManifest();
+				const config = await ctx.getConfig();
+				return json({
+					name: manifest.vault.name,
+					provider: config.provider.default,
+					model: config.provider.model,
+					totalSources: manifest.stats.totalSources,
+					totalArticles: manifest.stats.totalArticles,
+					totalWords: manifest.stats.totalWords,
+					lastCompiled: manifest.vault.lastCompiled,
+					lastLint: manifest.stats.lastLintAt,
+				});
+			} catch (e) {
+				return err((e as Error).message);
+			}
+		},
+	);
+
+	// ── kib_list ──────────────────────────────────────────────
+
+	server.tool(
+		"kib_list",
+		"List all wiki articles or raw sources in the knowledge base",
+		{
+			scope: z.enum(["wiki", "raw"]).default("wiki").describe("List wiki articles or raw sources"),
+		},
+		async ({ scope }) => {
+			try {
+				const files = scope === "wiki" ? await listWiki(root) : await listRaw(root);
+				// Strip absolute path prefix to return vault-relative paths
+				const prefix = `${root}/`;
+				const relative = files.map((f) => f.replace(prefix, ""));
+				return json(relative);
+			} catch (e) {
+				return err((e as Error).message);
+			}
+		},
+	);
+
+	// ── kib_read ──────────────────────────────────────────────
+
+	server.tool(
+		"kib_read",
+		"Read a specific wiki article or raw source from the knowledge base",
+		{
+			path: z.string().describe("Relative path, e.g. 'concepts/attention.md'"),
+			scope: z.enum(["wiki", "raw"]).default("wiki").describe("Read from wiki/ or raw/"),
+		},
+		async ({ path, scope }) => {
+			try {
+				const content = scope === "wiki" ? await readWiki(root, path) : await readRaw(root, path);
+				return ok(content);
+			} catch (_e) {
+				return err(`File not found: ${path}`);
+			}
+		},
+	);
+
+	// ── kib_search ────────────────────────────────────────────
+
+	server.tool(
+		"kib_search",
+		"Search the knowledge base using full-text BM25 search",
+		{
+			query: z.string().describe("Search query"),
+			limit: z.number().int().positive().max(50).default(10).describe("Max results"),
+		},
+		async ({ query, limit }) => {
+			try {
+				const index = await ctx.getSearchIndex();
+				const results = index.search(query, { limit });
+				const prefix = `${root}/`;
+				return json(
+					results.map((r) => ({
+						title: r.title,
+						path: r.path.replace(prefix, ""),
+						score: r.score,
+						snippet: r.snippet,
+					})),
+				);
+			} catch (e) {
+				return err((e as Error).message);
+			}
+		},
+	);
+
+	// ── kib_query ─────────────────────────────────────────────
+
+	server.tool(
+		"kib_query",
+		"Ask a question against the knowledge base using RAG (retrieval-augmented generation)",
+		{
+			question: z.string().describe("Question to ask"),
+			max_articles: z
+				.number()
+				.int()
+				.positive()
+				.max(10)
+				.default(5)
+				.describe("Max articles to use as context"),
+		},
+		async ({ question, max_articles }) => {
+			try {
+				const provider = await ctx.getProvider();
+				const result = await queryVault(root, question, provider, {
+					maxArticles: max_articles,
+				});
+				return ok(`${result.answer}\n\n---\nSources: ${result.sourcePaths.join(", ") || "none"}`);
+			} catch (e) {
+				return err((e as Error).message);
+			}
+		},
+	);
+
+	// ── kib_ingest ────────────────────────────────────────────
+
+	server.tool(
+		"kib_ingest",
+		"Ingest a source (URL or file path) into the knowledge base",
+		{
+			source: z.string().describe("URL or file path to ingest"),
+			category: z
+				.string()
+				.optional()
+				.describe("Raw subdirectory override (e.g. 'papers', 'articles')"),
+			tags: z.string().optional().describe("Comma-separated tags"),
+		},
+		async ({ source, category, tags }) => {
+			try {
+				const result = await ingestSource(root, source, {
+					category,
+					tags: tags?.split(",").map((t) => t.trim()),
+				});
+				ctx.invalidateSearch();
+				return json({
+					path: result.path,
+					title: result.metadata?.title,
+					wordCount: result.metadata?.wordCount,
+					skipped: result.skipped,
+					skipReason: result.skipReason,
+				});
+			} catch (e) {
+				return err((e as Error).message);
+			}
+		},
+	);
+
+	// ── kib_compile ───────────────────────────────────────────
+
+	server.tool(
+		"kib_compile",
+		"Compile pending raw sources into wiki articles using the configured LLM",
+		{
+			force: z.boolean().default(false).describe("Recompile all sources"),
+			source: z.string().optional().describe("Compile only a specific source"),
+			dry_run: z.boolean().default(false).describe("Preview without writing"),
+		},
+		async ({ force, source, dry_run }) => {
+			try {
+				const provider = await ctx.getProvider();
+				const config = await ctx.getConfig();
+				const result = await compileVault(root, provider, config, {
+					force,
+					dryRun: dry_run,
+					sourceFilter: source,
+				});
+				ctx.invalidateSearch();
+				return json({
+					sourcesCompiled: result.sourcesCompiled,
+					articlesCreated: result.articlesCreated,
+					articlesUpdated: result.articlesUpdated,
+					articlesDeleted: result.articlesDeleted,
+					operations: result.operations,
+				});
+			} catch (e) {
+				return err((e as Error).message);
+			}
+		},
+	);
+
+	// ── kib_lint ──────────────────────────────────────────────
+
+	server.tool(
+		"kib_lint",
+		"Run health checks on the wiki and report issues",
+		{
+			rule: z
+				.string()
+				.optional()
+				.describe("Run only a specific rule: orphan, stale, missing, broken-link, frontmatter"),
+		},
+		async ({ rule }) => {
+			try {
+				const result = await lintVault(root, { ruleFilter: rule });
+				return json({
+					errors: result.errors,
+					warnings: result.warnings,
+					infos: result.infos,
+					diagnostics: result.diagnostics,
+				});
+			} catch (e) {
+				return err((e as Error).message);
+			}
+		},
+	);
+
+	// ── Resources ─────────────────────────────────────────────
+
+	server.resource("wiki-index", "wiki://index", { mimeType: "text/markdown" }, async () => {
+		const content = await readIndex(root);
+		return {
+			contents: [{ uri: "wiki://index", text: content || "(no index yet — run kib compile)" }],
+		};
+	});
+
+	server.resource("wiki-graph", "wiki://graph", { mimeType: "text/markdown" }, async () => {
+		const content = await readGraph(root);
+		return {
+			contents: [{ uri: "wiki://graph", text: content || "(no graph yet — run kib compile)" }],
+		};
+	});
+
+	// ── Start ─────────────────────────────────────────────────
+
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+}

package/src/ui/setup-provider.ts

@@ -148,7 +148,7 @@ async function saveCredential(key: string, value: string): Promise<void> {
 	const updated = lines.filter((l) => !l.startsWith(`${key}=`));
 	updated.push(`${key}=${value}`);
 
-	await writeFile(CREDENTIALS_FILE, updated.join("\n") + "\n", { mode: 0o600 });
+	await writeFile(CREDENTIALS_FILE, `${updated.join("\n")}\n`, { mode: 0o600 });
 }
 
 /**