bluera-knowledge 0.9.21

package/src/mcp/schemas/index.test.ts

@@ -0,0 +1,315 @@
+import { describe, it, expect } from 'vitest';
+import {
+  SearchArgsSchema,
+  GetFullContextArgsSchema,
+  ListStoresArgsSchema,
+  GetStoreInfoArgsSchema,
+  CreateStoreArgsSchema,
+  IndexStoreArgsSchema,
+  DeleteStoreArgsSchema,
+  CheckJobStatusArgsSchema,
+  ListJobsArgsSchema,
+  CancelJobArgsSchema
+} from './index.js';
+
+describe('MCP Schema Validation', () => {
+  describe('SearchArgsSchema', () => {
+    it('should validate valid search args', () => {
+      const result = SearchArgsSchema.parse({
+        query: 'test query',
+        detail: 'minimal',
+        limit: 10
+      });
+
+      expect(result.query).toBe('test query');
+      expect(result.detail).toBe('minimal');
+      expect(result.limit).toBe(10);
+    });
+
+    it('should use defaults for optional fields', () => {
+      const result = SearchArgsSchema.parse({ query: 'test' });
+
+      expect(result.detail).toBe('minimal');
+      expect(result.limit).toBe(10);
+    });
+
+    it('should reject empty query', () => {
+      expect(() => SearchArgsSchema.parse({ query: '' }))
+        .toThrow('Query must be a non-empty string');
+    });
+
+    it('should validate detail enum', () => {
+      expect(() => SearchArgsSchema.parse({ query: 'test', detail: 'invalid' }))
+        .toThrow();
+
+      const minimal = SearchArgsSchema.parse({ query: 'test', detail: 'minimal' });
+      expect(minimal.detail).toBe('minimal');
+
+      const contextual = SearchArgsSchema.parse({ query: 'test', detail: 'contextual' });
+      expect(contextual.detail).toBe('contextual');
+
+      const full = SearchArgsSchema.parse({ query: 'test', detail: 'full' });
+      expect(full.detail).toBe('full');
+    });
+
+    it('should validate intent enum', () => {
+      const result = SearchArgsSchema.parse({
+        query: 'test',
+        intent: 'find-implementation'
+      });
+
+      expect(result.intent).toBe('find-implementation');
+    });
+
+    it('should validate stores array', () => {
+      const result = SearchArgsSchema.parse({
+        query: 'test',
+        stores: ['store1', 'store2']
+      });
+
+      expect(result.stores).toEqual(['store1', 'store2']);
+    });
+
+    it('should reject invalid limit', () => {
+      expect(() => SearchArgsSchema.parse({ query: 'test', limit: -1 }))
+        .toThrow();
+
+      expect(() => SearchArgsSchema.parse({ query: 'test', limit: 0 }))
+        .toThrow();
+
+      expect(() => SearchArgsSchema.parse({ query: 'test', limit: 1.5 }))
+        .toThrow();
+    });
+  });
+
+  describe('GetFullContextArgsSchema', () => {
+    it('should validate valid resultId', () => {
+      const result = GetFullContextArgsSchema.parse({ resultId: 'doc123' });
+      expect(result.resultId).toBe('doc123');
+    });
+
+    it('should reject empty resultId', () => {
+      expect(() => GetFullContextArgsSchema.parse({ resultId: '' }))
+        .toThrow('Result ID must be a non-empty string');
+    });
+
+    it('should reject missing resultId', () => {
+      expect(() => GetFullContextArgsSchema.parse({}))
+        .toThrow();
+    });
+  });
+
+  describe('ListStoresArgsSchema', () => {
+    it('should validate without type filter', () => {
+      const result = ListStoresArgsSchema.parse({});
+      expect(result.type).toBeUndefined();
+    });
+
+    it('should validate with valid type filter', () => {
+      const file = ListStoresArgsSchema.parse({ type: 'file' });
+      expect(file.type).toBe('file');
+
+      const repo = ListStoresArgsSchema.parse({ type: 'repo' });
+      expect(repo.type).toBe('repo');
+
+      const web = ListStoresArgsSchema.parse({ type: 'web' });
+      expect(web.type).toBe('web');
+    });
+
+    it('should reject invalid type', () => {
+      expect(() => ListStoresArgsSchema.parse({ type: 'invalid' }))
+        .toThrow();
+    });
+  });
+
+  describe('GetStoreInfoArgsSchema', () => {
+    it('should validate valid store', () => {
+      const result = GetStoreInfoArgsSchema.parse({ store: 'my-store' });
+      expect(result.store).toBe('my-store');
+    });
+
+    it('should reject empty store', () => {
+      expect(() => GetStoreInfoArgsSchema.parse({ store: '' }))
+        .toThrow('Store name or ID must be a non-empty string');
+    });
+
+    it('should reject missing store', () => {
+      expect(() => GetStoreInfoArgsSchema.parse({}))
+        .toThrow();
+    });
+  });
+
+  describe('CreateStoreArgsSchema', () => {
+    it('should validate minimal valid args', () => {
+      const result = CreateStoreArgsSchema.parse({
+        name: 'test-store',
+        type: 'file',
+        source: '/path/to/source'
+      });
+
+      expect(result.name).toBe('test-store');
+      expect(result.type).toBe('file');
+      expect(result.source).toBe('/path/to/source');
+    });
+
+    it('should validate with optional fields', () => {
+      const result = CreateStoreArgsSchema.parse({
+        name: 'test-repo',
+        type: 'repo',
+        source: 'https://github.com/test/repo',
+        branch: 'main',
+        description: 'Test repository'
+      });
+
+      expect(result.name).toBe('test-repo');
+      expect(result.type).toBe('repo');
+      expect(result.source).toBe('https://github.com/test/repo');
+      expect(result.branch).toBe('main');
+      expect(result.description).toBe('Test repository');
+    });
+
+    it('should reject empty name', () => {
+      expect(() => CreateStoreArgsSchema.parse({
+        name: '',
+        type: 'file',
+        source: '/path'
+      })).toThrow('Store name must be a non-empty string');
+    });
+
+    it('should reject invalid type', () => {
+      expect(() => CreateStoreArgsSchema.parse({
+        name: 'test',
+        type: 'invalid',
+        source: '/path'
+      })).toThrow();
+    });
+
+    it('should reject missing required fields', () => {
+      expect(() => CreateStoreArgsSchema.parse({
+        name: 'test',
+        type: 'file'
+      })).toThrow();
+
+      expect(() => CreateStoreArgsSchema.parse({
+        name: 'test',
+        source: '/path'
+      })).toThrow();
+
+      expect(() => CreateStoreArgsSchema.parse({
+        type: 'file',
+        source: '/path'
+      })).toThrow();
+    });
+  });
+
+  describe('IndexStoreArgsSchema', () => {
+    it('should validate valid store', () => {
+      const result = IndexStoreArgsSchema.parse({ store: 'my-store' });
+      expect(result.store).toBe('my-store');
+    });
+
+    it('should reject empty store', () => {
+      expect(() => IndexStoreArgsSchema.parse({ store: '' }))
+        .toThrow('Store name or ID must be a non-empty string');
+    });
+
+    it('should reject missing store', () => {
+      expect(() => IndexStoreArgsSchema.parse({}))
+        .toThrow();
+    });
+  });
+
+  describe('DeleteStoreArgsSchema', () => {
+    it('should validate valid store name', () => {
+      const result = DeleteStoreArgsSchema.parse({ store: 'my-store' });
+      expect(result.store).toBe('my-store');
+    });
+
+    it('should validate valid store ID', () => {
+      const result = DeleteStoreArgsSchema.parse({ store: 'abc123-def456' });
+      expect(result.store).toBe('abc123-def456');
+    });
+
+    it('should reject empty store', () => {
+      expect(() => DeleteStoreArgsSchema.parse({ store: '' }))
+        .toThrow('Store name or ID must be a non-empty string');
+    });
+
+    it('should reject missing store', () => {
+      expect(() => DeleteStoreArgsSchema.parse({}))
+        .toThrow();
+    });
+  });
+
+  describe('CheckJobStatusArgsSchema', () => {
+    it('should validate valid jobId', () => {
+      const result = CheckJobStatusArgsSchema.parse({ jobId: 'job_123' });
+      expect(result.jobId).toBe('job_123');
+    });
+
+    it('should reject empty jobId', () => {
+      expect(() => CheckJobStatusArgsSchema.parse({ jobId: '' }))
+        .toThrow('Job ID must be a non-empty string');
+    });
+
+    it('should reject missing jobId', () => {
+      expect(() => CheckJobStatusArgsSchema.parse({}))
+        .toThrow();
+    });
+  });
+
+  describe('ListJobsArgsSchema', () => {
+    it('should validate with defaults', () => {
+      const result = ListJobsArgsSchema.parse({});
+      expect(result.activeOnly).toBeUndefined();
+      expect(result.status).toBeUndefined();
+    });
+
+    it('should validate activeOnly', () => {
+      const active = ListJobsArgsSchema.parse({ activeOnly: true });
+      expect(active.activeOnly).toBe(true);
+
+      const all = ListJobsArgsSchema.parse({ activeOnly: false });
+      expect(all.activeOnly).toBe(false);
+    });
+
+    it('should validate status filter', () => {
+      const pending = ListJobsArgsSchema.parse({ status: 'pending' });
+      expect(pending.status).toBe('pending');
+
+      const running = ListJobsArgsSchema.parse({ status: 'running' });
+      expect(running.status).toBe('running');
+
+      const completed = ListJobsArgsSchema.parse({ status: 'completed' });
+      expect(completed.status).toBe('completed');
+
+      const failed = ListJobsArgsSchema.parse({ status: 'failed' });
+      expect(failed.status).toBe('failed');
+
+      const cancelled = ListJobsArgsSchema.parse({ status: 'cancelled' });
+      expect(cancelled.status).toBe('cancelled');
+    });
+
+    it('should reject invalid status', () => {
+      expect(() => ListJobsArgsSchema.parse({ status: 'invalid' }))
+        .toThrow();
+    });
+  });
+
+  describe('CancelJobArgsSchema', () => {
+    it('should validate valid jobId', () => {
+      const result = CancelJobArgsSchema.parse({ jobId: 'job_123' });
+      expect(result.jobId).toBe('job_123');
+    });
+
+    it('should reject empty jobId', () => {
+      expect(() => CancelJobArgsSchema.parse({ jobId: '' }))
+        .toThrow('Job ID must be a non-empty string');
+    });
+
+    it('should reject missing jobId', () => {
+      expect(() => CancelJobArgsSchema.parse({}))
+        .toThrow();
+    });
+  });
+});

package/src/mcp/schemas/index.ts

@@ -0,0 +1,138 @@
+import { z } from 'zod';
+
+/**
+ * Validation schemas for all MCP tool inputs
+ *
+ * These schemas provide runtime type validation and better error messages
+ * compared to manual type assertions.
+ */
+
+// ============================================================================
+// Search Tool Schemas
+// ============================================================================
+
+/**
+ * Schema for search tool arguments
+ */
+export const SearchArgsSchema = z.object({
+  query: z.string().min(1, 'Query must be a non-empty string'),
+  intent: z
+    .enum(['find-pattern', 'find-implementation', 'find-usage', 'find-definition', 'find-documentation'])
+    .optional(),
+  detail: z.enum(['minimal', 'contextual', 'full']).default('minimal'),
+  limit: z.number().int().positive().default(10),
+  stores: z.array(z.string()).optional()
+});
+
+export type SearchArgs = z.infer<typeof SearchArgsSchema>;
+
+/**
+ * Schema for get_full_context tool arguments
+ */
+export const GetFullContextArgsSchema = z.object({
+  resultId: z.string().min(1, 'Result ID must be a non-empty string')
+});
+
+export type GetFullContextArgs = z.infer<typeof GetFullContextArgsSchema>;
+
+// ============================================================================
+// Store Tool Schemas
+// ============================================================================
+
+/**
+ * Schema for list_stores tool arguments
+ */
+export const ListStoresArgsSchema = z.object({
+  type: z.enum(['file', 'repo', 'web']).optional()
+});
+
+export type ListStoresArgs = z.infer<typeof ListStoresArgsSchema>;
+
+/**
+ * Schema for get_store_info tool arguments
+ */
+export const GetStoreInfoArgsSchema = z.object({
+  store: z.string().min(1, 'Store name or ID must be a non-empty string')
+});
+
+export type GetStoreInfoArgs = z.infer<typeof GetStoreInfoArgsSchema>;
+
+/**
+ * Schema for create_store tool arguments
+ */
+export const CreateStoreArgsSchema = z.object({
+  name: z.string().min(1, 'Store name must be a non-empty string'),
+  type: z.enum(['file', 'repo']),
+  source: z.string().min(1, 'Source path or URL must be a non-empty string'),
+  branch: z.string().optional(),
+  description: z.string().optional()
+});
+
+export type CreateStoreArgs = z.infer<typeof CreateStoreArgsSchema>;
+
+/**
+ * Schema for index_store tool arguments
+ */
+export const IndexStoreArgsSchema = z.object({
+  store: z.string().min(1, 'Store name or ID must be a non-empty string')
+});
+
+export type IndexStoreArgs = z.infer<typeof IndexStoreArgsSchema>;
+
+/**
+ * Schema for delete_store tool arguments
+ */
+export const DeleteStoreArgsSchema = z.object({
+  store: z.string().min(1, 'Store name or ID must be a non-empty string')
+});
+
+export type DeleteStoreArgs = z.infer<typeof DeleteStoreArgsSchema>;
+
+// ============================================================================
+// Job Tool Schemas
+// ============================================================================
+
+/**
+ * Schema for check_job_status tool arguments
+ */
+export const CheckJobStatusArgsSchema = z.object({
+  jobId: z.string().min(1, 'Job ID must be a non-empty string')
+});
+
+export type CheckJobStatusArgs = z.infer<typeof CheckJobStatusArgsSchema>;
+
+/**
+ * Schema for list_jobs tool arguments
+ */
+export const ListJobsArgsSchema = z.object({
+  activeOnly: z.boolean().optional(),
+  status: z.enum(['pending', 'running', 'completed', 'failed', 'cancelled']).optional()
+});
+
+export type ListJobsArgs = z.infer<typeof ListJobsArgsSchema>;
+
+/**
+ * Schema for cancel_job tool arguments
+ */
+export const CancelJobArgsSchema = z.object({
+  jobId: z.string().min(1, 'Job ID must be a non-empty string')
+});
+
+export type CancelJobArgs = z.infer<typeof CancelJobArgsSchema>;
+
+// ============================================================================
+// Execute Meta-Tool Schema
+// ============================================================================
+
+/**
+ * Schema for execute meta-tool arguments
+ *
+ * The execute tool consolidates store and job management commands
+ * into a single tool, reducing context overhead.
+ */
+export const ExecuteArgsSchema = z.object({
+  command: z.string().min(1, 'Command name is required'),
+  args: z.record(z.string(), z.unknown()).optional()
+});
+
+export type ExecuteArgs = z.infer<typeof ExecuteArgsSchema>;

package/src/mcp/server.test.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect } from 'vitest';
+import { createMCPServer } from './server.js';
+
+// MCP Server tests - server creation only since the SDK doesn't expose handlers for testing
+describe('MCP Server', () => {
+  describe('Server creation and initialization', () => {
+    it('creates server with default options', () => {
+      const server = createMCPServer({});
+      expect(server).toBeDefined();
+    });
+
+    it('creates server with custom dataDir', () => {
+      const server = createMCPServer({ dataDir: '/custom/path' });
+      expect(server).toBeDefined();
+    });
+
+    it('creates server with config path', () => {
+      const server = createMCPServer({ config: '/path/to/config.json' });
+      expect(server).toBeDefined();
+    });
+
+    it('creates server with project root', () => {
+      const server = createMCPServer({ projectRoot: '/project' });
+      expect(server).toBeDefined();
+    });
+
+    it('creates server with all options', () => {
+      const server = createMCPServer({
+        dataDir: '/data',
+        config: '/config.json',
+        projectRoot: '/project'
+      });
+      expect(server).toBeDefined();
+    });
+  });
+});

package/src/mcp/server.ts

@@ -0,0 +1,162 @@
+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 { createServices } from '../services/index.js';
+import { tools } from './handlers/index.js';
+import { handleExecute } from './handlers/execute.handler.js';
+import { ExecuteArgsSchema } from './schemas/index.js';
+import type { MCPServerOptions } from './types.js';
+
+// eslint-disable-next-line @typescript-eslint/no-deprecated
+export function createMCPServer(options: MCPServerOptions): Server {
+  // eslint-disable-next-line @typescript-eslint/no-deprecated
+  const server = new Server(
+    {
+      name: 'bluera-knowledge',
+      version: '1.0.0',
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    }
+  );
+
+  // List available tools - consolidated from 10 tools to 3 for reduced context overhead
+  server.setRequestHandler(ListToolsRequestSchema, () => {
+    return Promise.resolve({
+      tools: [
+        // Native search tool with full schema (most used, benefits from detailed params)
+        {
+          name: 'search',
+          description: 'Search all indexed knowledge stores with pattern detection and AI-optimized results. Returns structured code units with progressive context layers.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              query: {
+                type: 'string',
+                description: 'Search query (can include type signatures, constraints, or natural language)'
+              },
+              intent: {
+                type: 'string',
+                enum: ['find-pattern', 'find-implementation', 'find-usage', 'find-definition', 'find-documentation'],
+                description: 'Search intent for better ranking'
+              },
+              detail: {
+                type: 'string',
+                enum: ['minimal', 'contextual', 'full'],
+                default: 'minimal',
+                description: 'Context detail level: minimal (summary only), contextual (+ imports/types), full (+ complete code)'
+              },
+              limit: {
+                type: 'number',
+                default: 10,
+                description: 'Maximum number of results'
+              },
+              stores: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Specific store IDs to search (optional)'
+              }
+            },
+            required: ['query']
+          }
+        },
+        // Native get_full_context tool (frequently used after search)
+        {
+          name: 'get_full_context',
+          description: 'Get complete code and context for a specific search result by ID. Use this after search to get full implementation details.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              resultId: {
+                type: 'string',
+                description: 'Result ID from previous search'
+              }
+            },
+            required: ['resultId']
+          }
+        },
+        // Meta-tool for store and job management (consolidates 8 tools into 1)
+        {
+          name: 'execute',
+          description: 'Execute store/job management commands. Commands: stores, store:info, store:create, store:index, store:delete, jobs, job:status, job:cancel, help, commands',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              command: {
+                type: 'string',
+                description: 'Command to execute (e.g., "stores", "store:create", "jobs", "help")'
+              },
+              args: {
+                type: 'object',
+                description: 'Command arguments (e.g., {store: "mystore"} for store:info)'
+              }
+            },
+            required: ['command']
+          }
+        }
+      ]
+    });
+  });
+
+  // Handle tool calls
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+
+    // Create services once (needed by all handlers)
+    const services = await createServices(
+      options.config,
+      options.dataDir,
+      options.projectRoot
+    );
+    const context = { services, options };
+
+    // Handle execute meta-tool
+    if (name === 'execute') {
+      const validated = ExecuteArgsSchema.parse(args ?? {});
+      return handleExecute(validated, context);
+    }
+
+    // Find handler in registry for native tools (search, get_full_context)
+    const tool = tools.find(t => t.name === name);
+    if (tool === undefined) {
+      throw new Error(`Unknown tool: ${name}`);
+    }
+
+    // Validate arguments with Zod
+    const validated = tool.schema.parse(args ?? {});
+
+    // Execute handler with context
+    return tool.handler(validated, context);
+  });
+
+  return server;
+}
+
+export async function runMCPServer(options: MCPServerOptions): Promise<void> {
+  const server = createMCPServer(options);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  console.error('Bluera Knowledge MCP server running on stdio');
+}
+
+// Run the server only when this file is executed directly (not imported by CLI)
+// Check if we're running as the mcp/server entry point vs being imported by index.js
+const scriptPath = process.argv[1] ?? '';
+const isMCPServerEntry = scriptPath.endsWith('mcp/server.js') || scriptPath.endsWith('mcp/server');
+
+if (isMCPServerEntry) {
+  runMCPServer({
+    dataDir: process.env['DATA_DIR'],
+    config: process.env['CONFIG_PATH'],
+    projectRoot: process.env['PROJECT_ROOT'] ?? process.env['PWD']
+  }).catch((error: unknown) => {
+    console.error('Failed to start MCP server:', error);
+    process.exit(1);
+  });
+}

package/src/mcp/types.ts

@@ -0,0 +1,41 @@
+import type { ServiceContainer } from '../services/index.js';
+
+/**
+ * Configuration options for the MCP server
+ */
+export interface MCPServerOptions {
+  dataDir?: string | undefined;
+  config?: string | undefined;
+  projectRoot?: string | undefined;
+}
+
+/**
+ * Context passed to each handler containing services and options
+ */
+export interface HandlerContext {
+  services: ServiceContainer;
+  options: MCPServerOptions;
+}
+
+/**
+ * Standard MCP tool response format
+ */
+export interface ToolResponse {
+  content: Array<{
+    type: 'text';
+    text: string;
+  }>;
+  [x: string]: unknown;
+}
+
+/**
+ * Tool handler function signature
+ *
+ * @param args - Validated input arguments (typed with Zod schema)
+ * @param context - Handler context with services and options
+ * @returns Promise resolving to MCP tool response
+ */
+export type ToolHandler<TInput = unknown> = (
+  args: TInput,
+  context: HandlerContext
+) => Promise<ToolResponse>;