kotadb 2.1.0-next.20260203224441 → 2.1.0-next.20260203233957

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kotadb",
-  "version": "2.1.0-next.20260203224441",
+  "version": "2.1.0-next.20260203233957",
   "description": "Local-only code intelligence tool for CLI agents. SQLite-backed repository indexing and code search via MCP.",
   "type": "module",
   "module": "src/index.ts",

package/src/cli/args.ts

@@ -0,0 +1,105 @@
+/**
+ * CLI argument parsing utilities
+ *
+ * Extracted for testability. Used by main CLI entry point.
+ *
+ * @module cli/args
+ */
+
+/**
+ * Valid toolset tiers for MCP tool selection
+ * - default: 8 tools (core + sync)
+ * - core: 6 tools
+ * - memory: 14 tools (core + sync + memory)
+ * - full: 20 tools (all)
+ */
+export type ToolsetTier = "default" | "core" | "memory" | "full";
+
+const VALID_TOOLSET_TIERS: ToolsetTier[] = ["default", "core", "memory", "full"];
+
+export interface CliOptions {
+	port: number;
+	help: boolean;
+	version: boolean;
+	stdio: boolean;
+	toolset: ToolsetTier;
+}
+
+/**
+ * Type guard for valid toolset tier
+ */
+export function isValidToolsetTier(value: string): value is ToolsetTier {
+	return VALID_TOOLSET_TIERS.includes(value as ToolsetTier);
+}
+
+/**
+ * Parse CLI arguments into options object
+ */
+export function parseArgs(args: string[]): CliOptions {
+	const options: CliOptions = {
+		port: Number(process.env.PORT ?? 3000),
+		help: false,
+		version: false,
+		stdio: false,
+		toolset: "default",
+	};
+
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === undefined) continue;
+
+		if (arg === "--help" || arg === "-h") {
+			options.help = true;
+		} else if (arg === "--version" || arg === "-v") {
+			options.version = true;
+		} else if (arg === "--stdio") {
+			options.stdio = true;
+		} else if (arg === "--port") {
+			const portStr = args[++i];
+			if (!portStr || Number.isNaN(Number(portStr))) {
+				process.stderr.write("Error: --port requires a valid number\n");
+				process.exit(1);
+			}
+			options.port = Number(portStr);
+		} else if (arg.startsWith("--port=")) {
+			const portStr = arg.split("=")[1];
+			if (portStr === undefined || Number.isNaN(Number(portStr))) {
+				process.stderr.write("Error: --port requires a valid number\n");
+				process.exit(1);
+			}
+			options.port = Number(portStr);
+		} else if (arg === "--toolset") {
+			const tierStr = args[++i];
+			if (!tierStr) {
+				process.stderr.write("Error: --toolset requires a tier value\n");
+				process.stderr.write("Valid tiers: default, core, memory, full\n");
+				process.exit(1);
+			}
+			if (!isValidToolsetTier(tierStr)) {
+				process.stderr.write(`Error: Invalid toolset tier '${tierStr}'\n`);
+				process.stderr.write("Valid tiers: default, core, memory, full\n");
+				process.exit(1);
+			}
+			options.toolset = tierStr;
+		} else if (arg.startsWith("--toolset=")) {
+			const tierStr = arg.split("=")[1];
+			if (tierStr === undefined || tierStr === "") {
+				process.stderr.write("Error: --toolset requires a tier value\n");
+				process.stderr.write("Valid tiers: default, core, memory, full\n");
+				process.exit(1);
+			}
+			if (!isValidToolsetTier(tierStr)) {
+				process.stderr.write(`Error: Invalid toolset tier '${tierStr}'\n`);
+				process.stderr.write("Valid tiers: default, core, memory, full\n");
+				process.exit(1);
+			}
+			options.toolset = tierStr;
+		} else if (arg.startsWith("-") && arg !== "-") {
+			process.stderr.write(`Unknown option: ${arg}\n`);
+			process.stderr.write("Use --help for usage information\n");
+			process.exit(1);
+		}
+	}
+
+	return options;
+}

package/src/cli.ts

@@ -9,6 +9,7 @@
  *   kotadb              Start the MCP server (default port 3000)
  *   kotadb --stdio      Start in stdio mode (for Claude Code integration)
  *   kotadb --port 4000  Start on custom port
+ *   kotadb --toolset full  Select tool tier (default, core, memory, full)
  *   kotadb --version    Show version
  *   kotadb --help       Show help
  *   kotadb deps         Query dependency information for a file
@@ -25,11 +26,23 @@ import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+/**
+ * Valid toolset tiers for MCP tool selection
+ * - default: 8 tools (core + sync)
+ * - core: 6 tools
+ * - memory: 14 tools (core + sync + memory)
+ * - full: 20 tools (all)
+ */
+export type ToolsetTier = "default" | "core" | "memory" | "full";
+
+const VALID_TOOLSET_TIERS: ToolsetTier[] = ["default", "core", "memory", "full"];
+
 interface CliOptions {
   port: number;
   help: boolean;
   version: boolean;
   stdio: boolean;
+  toolset: ToolsetTier;
 }
 
 function getVersion(): string {
@@ -70,6 +83,12 @@ COMMANDS:
 OPTIONS:
   --stdio           Use stdio transport (for Claude Code integration)
   --port <number>   Port to listen on (default: 3000, env: PORT)
+  --toolset <tier>  Select tool tier (default: default)
+                    Tiers:
+                      default  8 tools (core + sync)
+                      core     6 tools (search, index, deps, impact)
+                      memory   14 tools (core + sync + memory layer)
+                      full     20 tools (all available tools)
   --version, -v     Show version number
   --help, -h        Show this help message
 
@@ -81,6 +100,8 @@ ENVIRONMENT VARIABLES:
 
 EXAMPLES:
   kotadb --stdio                              Start in stdio mode (for Claude Code)
+  kotadb --stdio --toolset full               Start with all tools enabled
+  kotadb --stdio --toolset core               Start with minimal core tools
   kotadb                                      Start HTTP server on port 3000
   kotadb --port 4000                          Start HTTP server on port 4000
   kotadb deps --file src/db/client.ts         Query deps for a file (text)
@@ -99,6 +120,17 @@ MCP CONFIGURATION (stdio mode - RECOMMENDED):
     }
   }
 
+  With toolset selection:
+
+  {
+    "mcpServers": {
+      "kotadb": {
+        "command": "bunx",
+        "args": ["kotadb@next", "--stdio", "--toolset", "full"]
+      }
+    }
+  }
+
 MCP CONFIGURATION (HTTP mode - legacy):
   Add to your .mcp.json or Claude Code settings:
 
@@ -126,12 +158,17 @@ function printVersion(): void {
   process.stdout.write(`kotadb v${version}\n`);
 }
 
+function isValidToolsetTier(value: string): value is ToolsetTier {
+  return VALID_TOOLSET_TIERS.includes(value as ToolsetTier);
+}
+
 function parseArgs(args: string[]): CliOptions {
   const options: CliOptions = {
     port: Number(process.env.PORT ?? 3000),
     help: false,
     version: false,
     stdio: false,
+    toolset: "default",
   };
 
   for (let i = 0; i < args.length; i++) {
@@ -158,6 +195,32 @@ function parseArgs(args: string[]): CliOptions {
         process.exit(1);
       }
       options.port = Number(portStr);
+    } else if (arg === "--toolset") {
+      const tierStr = args[++i];
+      if (!tierStr) {
+        process.stderr.write("Error: --toolset requires a tier value\n");
+        process.stderr.write("Valid tiers: default, core, memory, full\n");
+        process.exit(1);
+      }
+      if (!isValidToolsetTier(tierStr)) {
+        process.stderr.write(`Error: Invalid toolset tier '${tierStr}'\n`);
+        process.stderr.write("Valid tiers: default, core, memory, full\n");
+        process.exit(1);
+      }
+      options.toolset = tierStr;
+    } else if (arg.startsWith("--toolset=")) {
+      const tierStr = arg.split("=")[1];
+      if (tierStr === undefined || tierStr === "") {
+        process.stderr.write("Error: --toolset requires a tier value\n");
+        process.stderr.write("Valid tiers: default, core, memory, full\n");
+        process.exit(1);
+      }
+      if (!isValidToolsetTier(tierStr)) {
+        process.stderr.write(`Error: Invalid toolset tier '${tierStr}'\n`);
+        process.stderr.write("Valid tiers: default, core, memory, full\n");
+        process.exit(1);
+      }
+      options.toolset = tierStr;
     } else if (arg.startsWith("-") && arg !== "-") {
       process.stderr.write(`Unknown option: ${arg}\n`);
       process.stderr.write("Use --help for usage information\n");
@@ -168,7 +231,7 @@ function parseArgs(args: string[]): CliOptions {
   return options;
 }
 
-async function runStdioMode(): Promise<void> {
+async function runStdioMode(toolset: ToolsetTier): Promise<void> {
   // Redirect logger to stderr in stdio mode
   // This is CRITICAL - stdout is reserved for JSON-RPC protocol
   const logger = createLogger({
@@ -178,11 +241,13 @@ async function runStdioMode(): Promise<void> {
 
   logger.info("KotaDB MCP server starting in stdio mode", {
     version: getVersion(),
+    toolset,
   });
 
-  // Create MCP server with local-only context
+  // Create MCP server with local-only context and toolset
   const context: McpServerContext = {
     userId: "local", // Local-only mode uses fixed user ID
+    toolset,
   };
   const server = createMcpServer(context);
 
@@ -192,7 +257,7 @@ async function runStdioMode(): Promise<void> {
   // Connect server to transport
   await server.connect(transport);
 
-  logger.info("KotaDB MCP server connected via stdio");
+  logger.info("KotaDB MCP server connected via stdio", { toolset });
 
   // Server lifecycle is managed by the transport
   // Process will stay alive until stdin closes (when Claude Code terminates it)
@@ -234,7 +299,7 @@ async function main(): Promise<void> {
 
   // Handle stdio mode
   if (options.stdio) {
-    await runStdioMode();
+    await runStdioMode(options.toolset);
     return; // runStdioMode() keeps process alive
   }
 
@@ -247,6 +312,7 @@ async function main(): Promise<void> {
     mode: envConfig.mode,
     port: options.port,
     localDbPath: envConfig.localDbPath,
+    toolset: options.toolset,
   });
 
   const app = createExpressApp();
@@ -256,6 +322,7 @@ async function main(): Promise<void> {
       port: options.port,
       mcp_endpoint: `http://localhost:${options.port}/mcp`,
       health_endpoint: `http://localhost:${options.port}/health`,
+      toolset: options.toolset,
     });
 
     // Print user-friendly startup message
@@ -265,6 +332,7 @@ async function main(): Promise<void> {
     process.stdout.write(`  MCP Endpoint:    http://localhost:${options.port}/mcp\n`);
     process.stdout.write(`  Health Check:    http://localhost:${options.port}/health\n`);
     process.stdout.write(`  Database:        ${envConfig.localDbPath}\n`);
+    process.stdout.write(`  Toolset:         ${options.toolset}\n`);
     process.stdout.write(`\n`);
     process.stdout.write(`Press Ctrl+C to stop\n`);
     process.stdout.write(`\n`);

package/src/mcp/server.ts

@@ -57,10 +57,21 @@ import {
 	executeValidateExpertise,
 	executeSyncExpertise,
 	executeGetRecentPatterns,
+	// Tool filtering
+	filterToolsByTier,
 } from "./tools";
 
 const logger = createLogger({ module: "mcp-server" });
 
+/**
+ * Valid toolset tiers for MCP tool selection
+ * - default: 8 tools (core + sync)
+ * - core: 6 tools
+ * - memory: 14 tools (core + sync + memory)
+ * - full: 20 tools (all)
+ */
+export type ToolsetTier = "default" | "core" | "memory" | "full";
+
 /**
  * MCP Server context passed to tool handlers via closure
  *
@@ -68,6 +79,7 @@ const logger = createLogger({ module: "mcp-server" });
  */
 export interface McpServerContext {
 	userId: string;
+	toolset?: ToolsetTier;
 }
 
 /**
@@ -107,35 +119,20 @@ export function createMcpServer(context: McpServerContext): Server {
 		},
 	);
 
-	// Register tools/list handler - local-only tools
+	// Register tools/list handler - filter by toolset tier
 	server.setRequestHandler(ListToolsRequestSchema, async () => {
+		const tier = context.toolset || "default";
+		const filteredTools = filterToolsByTier(tier);
+		
+		logger.debug("Listing MCP tools", { 
+			tier, 
+			tool_count: filteredTools.length 
+		});
+		
 		return {
-			tools: [
-				SEARCH_CODE_TOOL,
-				INDEX_REPOSITORY_TOOL,
-				LIST_RECENT_FILES_TOOL,
-				SEARCH_DEPENDENCIES_TOOL,
-				ANALYZE_CHANGE_IMPACT_TOOL,
-				VALIDATE_IMPLEMENTATION_SPEC_TOOL,
-				SYNC_EXPORT_TOOL,
-				SYNC_IMPORT_TOOL,
-				GENERATE_TASK_CONTEXT_TOOL,
-				// Memory Layer tools
-				SEARCH_DECISIONS_TOOL,
-				RECORD_DECISION_TOOL,
-				SEARCH_FAILURES_TOOL,
-				RECORD_FAILURE_TOOL,
-				SEARCH_PATTERNS_TOOL,
-				RECORD_INSIGHT_TOOL,
-				// Dynamic Expertise tools
-				GET_DOMAIN_KEY_FILES_TOOL,
-				VALIDATE_EXPERTISE_TOOL,
-				SYNC_EXPERTISE_TOOL,
-				GET_RECENT_PATTERNS_TOOL,
-			],
+			tools: filteredTools,
 		};
 	});
-
 	// Register tools/call handler
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {
 		const { name, arguments: toolArgs } = request.params;

package/src/mcp/tools.ts

@@ -34,8 +34,14 @@ const logger = createLogger({ module: "mcp-tools" });
 /**
  * MCP Tool Definition
  */
+/**
+ * Tool tier for categorizing tools by feature set
+ */
+export type ToolTier = "core" | "sync" | "memory" | "expertise";
+
 export interface ToolDefinition {
 	name: string;
+	tier: ToolTier;
 	description: string;
 	inputSchema: {
 		type: "object";
@@ -45,11 +51,60 @@ export interface ToolDefinition {
 }
 
 /**
+ * Toolset tier for CLI selection (maps to tool tiers)
+ */
+export type ToolsetTier = "default" | "core" | "memory" | "full";
+
+/**
+ * Filter tools by the requested toolset tier
+ *
+ * Tier mapping:
+ * - core: 6 tools (core tier only)
+ * - default: 8 tools (core + sync tiers)
+ * - memory: 14 tools (core + sync + memory tiers)
+ * - full: all tools
+ *
+ * @param tier - The toolset tier to filter by
+ * @param tools - Optional array of tools (defaults to all tool definitions)
+ */
+export function filterToolsByTier(tier: ToolsetTier, tools?: ToolDefinition[]): ToolDefinition[] {
+	const allTools = tools ?? getToolDefinitions();
+	switch (tier) {
+		case "core":
+			return allTools.filter((t) => t.tier === "core");
+		case "default":
+			return allTools.filter((t) => t.tier === "core" || t.tier === "sync");
+		case "memory":
+			return allTools.filter((t) => t.tier === "core" || t.tier === "sync" || t.tier === "memory");
+		case "full":
+			return allTools;
+		default:
+			// Default to "default" tier if unknown
+			return allTools.filter((t) => t.tier === "core" || t.tier === "sync");
+	}
+}
+
+/**
+ * Alias for filterToolsByTier - get tool definitions filtered by toolset
+ *
+ * @param toolset - The toolset tier to filter by
+ */
+export function getToolsByTier(toolset: ToolsetTier): ToolDefinition[] {
+	return filterToolsByTier(toolset);
+}
 
+/**
+ * Validate if a string is a valid toolset tier
+ */
+export function isValidToolset(value: string): value is ToolsetTier {
+	return value === "default" || value === "core" || value === "memory" || value === "full";
+}
+/**
 /**
  * Tool: search_code
  */
 export const SEARCH_CODE_TOOL: ToolDefinition = {
+	tier: "core",
 	name: "search_code",
 	description:
 		"Search indexed code files for a specific term. Returns matching files with context snippets.",
@@ -77,6 +132,7 @@ export const SEARCH_CODE_TOOL: ToolDefinition = {
  * Tool: index_repository
  */
 export const INDEX_REPOSITORY_TOOL: ToolDefinition = {
+	tier: "core",
 	name: "index_repository",
 	description:
 		"Index a git repository by cloning/updating it and extracting code files. Performs synchronous indexing and returns immediately with status 'completed' and full indexing stats.",
@@ -104,6 +160,7 @@ export const INDEX_REPOSITORY_TOOL: ToolDefinition = {
  * Tool: list_recent_files
  */
 export const LIST_RECENT_FILES_TOOL: ToolDefinition = {
+	tier: "core",
 	name: "list_recent_files",
 	description:
 		"List recently indexed files, ordered by indexing timestamp. Useful for seeing what code is available.",
@@ -126,6 +183,7 @@ export const LIST_RECENT_FILES_TOOL: ToolDefinition = {
  * Tool: search_dependencies
  */
 export const SEARCH_DEPENDENCIES_TOOL: ToolDefinition = {
+	tier: "core",
 	name: "search_dependencies",
 	description:
 		"Search the dependency graph to find files that depend on (dependents) or are depended on by (dependencies) a target file. Useful for impact analysis before refactoring, test scope discovery, and circular dependency detection.",
@@ -174,6 +232,7 @@ export const SEARCH_DEPENDENCIES_TOOL: ToolDefinition = {
  * Tool: analyze_change_impact
  */
 export const ANALYZE_CHANGE_IMPACT_TOOL: ToolDefinition = {
+	tier: "core",
 	name: "analyze_change_impact",
 	description:
 		"Analyze the impact of proposed code changes by examining dependency graphs, test scope, and potential conflicts. Returns comprehensive analysis including affected files, test recommendations, architectural warnings, and risk assessment. Useful for planning implementations and avoiding breaking changes.",
@@ -221,6 +280,7 @@ export const ANALYZE_CHANGE_IMPACT_TOOL: ToolDefinition = {
  * Tool: validate_implementation_spec
  */
 export const VALIDATE_IMPLEMENTATION_SPEC_TOOL: ToolDefinition = {
+	tier: "expertise",
 	name: "validate_implementation_spec",
 	description:
 		"Validate an implementation specification against KotaDB conventions and repository state. Checks for file conflicts, naming conventions, path alias usage, test coverage, and dependency compatibility. Returns validation errors, warnings, and approval conditions checklist.",
@@ -303,6 +363,7 @@ export const VALIDATE_IMPLEMENTATION_SPEC_TOOL: ToolDefinition = {
  * Tool: kota_sync_export
  */
 export const SYNC_EXPORT_TOOL: ToolDefinition = {
+	tier: "sync",
 	name: "kota_sync_export",
 	description:
 		"Export local SQLite database to JSONL files for git sync. Uses hash-based change detection to skip unchanged tables. Exports to .kotadb/export/ by default.",
@@ -325,6 +386,7 @@ export const SYNC_EXPORT_TOOL: ToolDefinition = {
  * Tool: kota_sync_import
  */
 export const SYNC_IMPORT_TOOL: ToolDefinition = {
+	tier: "sync",
 	name: "kota_sync_import",
 	description:
 		"Import JSONL files into local SQLite database. Applies deletion manifest first, then imports all tables transactionally. Typically run after git pull to sync remote changes.",
@@ -347,6 +409,7 @@ export const SYNC_IMPORT_TOOL: ToolDefinition = {
  * Target: <100ms response time
  */
 export const GENERATE_TASK_CONTEXT_TOOL: ToolDefinition = {
+	tier: "core",
 	name: "generate_task_context",
 	description:
 		"Generate structured context for a set of files including dependency counts, impacted files, test files, and recent changes. Designed for hook-based context injection with <100ms performance target.",
@@ -387,6 +450,7 @@ export const GENERATE_TASK_CONTEXT_TOOL: ToolDefinition = {
  * Tool: search_decisions
  */
 export const SEARCH_DECISIONS_TOOL: ToolDefinition = {
+	tier: "memory",
 	name: "search_decisions",
 	description:
 		"Search past architectural decisions using FTS5. Returns decisions with relevance scores.",
@@ -419,6 +483,7 @@ export const SEARCH_DECISIONS_TOOL: ToolDefinition = {
  * Tool: record_decision
  */
 export const RECORD_DECISION_TOOL: ToolDefinition = {
+	tier: "memory",
 	name: "record_decision",
 	description:
 		"Record a new architectural decision for future reference. Decisions are searchable via search_decisions.",
@@ -469,6 +534,7 @@ export const RECORD_DECISION_TOOL: ToolDefinition = {
  * Tool: search_failures
  */
 export const SEARCH_FAILURES_TOOL: ToolDefinition = {
+	tier: "memory",
 	name: "search_failures",
 	description:
 		"Search failed approaches to avoid repeating mistakes. Returns failures with relevance scores.",
@@ -496,6 +562,7 @@ export const SEARCH_FAILURES_TOOL: ToolDefinition = {
  * Tool: record_failure
  */
 export const RECORD_FAILURE_TOOL: ToolDefinition = {
+	tier: "memory",
 	name: "record_failure",
 	description:
 		"Record a failed approach for future reference. Helps agents avoid repeating mistakes.",
@@ -536,6 +603,7 @@ export const RECORD_FAILURE_TOOL: ToolDefinition = {
  * Tool: search_patterns
  */
 export const SEARCH_PATTERNS_TOOL: ToolDefinition = {
+	tier: "memory",
 	name: "search_patterns",
 	description:
 		"Find codebase patterns by type or file. Returns discovered patterns for consistency.",
@@ -570,6 +638,7 @@ export const SEARCH_PATTERNS_TOOL: ToolDefinition = {
  * Tool: record_insight
  */
 export const RECORD_INSIGHT_TOOL: ToolDefinition = {
+	tier: "memory",
 	name: "record_insight",
 	description:
 		"Store a session insight for future agents. Insights are discoveries, failures, or workarounds.",
@@ -611,6 +680,7 @@ export const RECORD_INSIGHT_TOOL: ToolDefinition = {
  * Tool: get_domain_key_files
  */
 export const GET_DOMAIN_KEY_FILES_TOOL: ToolDefinition = {
+	tier: "expertise",
 	name: "get_domain_key_files",
 	description:
 		"Get the most-depended-on files for a domain. Key files are core infrastructure that many other files depend on.",
@@ -638,6 +708,7 @@ export const GET_DOMAIN_KEY_FILES_TOOL: ToolDefinition = {
  * Tool: validate_expertise
  */
 export const VALIDATE_EXPERTISE_TOOL: ToolDefinition = {
+	tier: "expertise",
 	name: "validate_expertise",
 	description:
 		"Validate that key_files defined in expertise.yaml exist in the indexed codebase. Checks for stale or missing file references.",
@@ -657,6 +728,7 @@ export const VALIDATE_EXPERTISE_TOOL: ToolDefinition = {
  * Tool: sync_expertise
  */
 export const SYNC_EXPERTISE_TOOL: ToolDefinition = {
+	tier: "expertise",
 	name: "sync_expertise",
 	description:
 		"Sync patterns from expertise.yaml files to the patterns table. Extracts pattern definitions and stores them for future reference.",
@@ -679,6 +751,7 @@ export const SYNC_EXPERTISE_TOOL: ToolDefinition = {
  * Tool: get_recent_patterns
  */
 export const GET_RECENT_PATTERNS_TOOL: ToolDefinition = {
+	tier: "expertise",
 	name: "get_recent_patterns",
 	description:
 		"Get recently observed patterns from the patterns table. Useful for understanding codebase conventions.",
@@ -734,7 +807,6 @@ export function getToolDefinitions(): ToolDefinition[] {
 		GET_RECENT_PATTERNS_TOOL,
 	];
 }
-
 /**
 
 /**