feat(mcp): implement SearchAdapter with token-efficient formatters

Implements Issue #28 - First Adapter + Formatters

## Features

### Formatters
- **CompactFormatter**: Token-efficient summaries (score, type, name, path)
- **VerboseFormatter**: Full details with signatures and metadata
- **Token Estimation**: ~4 chars/token heuristic for GPT-4

### SearchAdapter
- Implements `dev_search` MCP tool
- Semantic code search via RepositoryIndexer
- Configurable format modes (compact/verbose)
- Input validation with structured errors
- Token-aware result formatting

### API
- Format modes: `compact` (default) | `verbose`
- Configurable limits: 1-50 results (default: 10)
- Score threshold: 0-1 (default: 0)
- Token budgets: 1K (compact) | 5K (verbose)

## Benefits
- ✅ Token-efficient by default (compact mode)
- ✅ Opt-in verbosity for detailed exploration
- ✅ Type-safe metadata access
- ✅ Structured error handling
- ✅ Extensible formatter framework

## Next Steps
- Add comprehensive tests (unit + integration)
- Test with real MCP clients
- Measure token estimation accuracy

Author: prosdev

packages/mcp-server/src/adapters/built-in/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Built-in Adapters
+ * Production-ready adapters included with the MCP server
+ */
+
+export { SearchAdapter, type SearchAdapterConfig } from './search-adapter';

packages/mcp-server/src/adapters/built-in/search-adapter.ts

@@ -0,0 +1,217 @@
+/**
+ * Search Adapter
+ * Provides semantic code search via the dev_search tool
+ */
+
+import type { RepositoryIndexer } from '@lytics/dev-agent-core';
+import { CompactFormatter, type FormatMode, VerboseFormatter } from '../../formatters';
+import { ToolAdapter } from '../tool-adapter';
+import type { AdapterContext, ToolDefinition, ToolExecutionContext, ToolResult } from '../types';
+
+/**
+ * Search adapter configuration
+ */
+export interface SearchAdapterConfig {
+  /**
+   * Repository indexer instance
+   */
+  repositoryIndexer: RepositoryIndexer;
+
+  /**
+   * Default format mode
+   */
+  defaultFormat?: FormatMode;
+
+  /**
+   * Default result limit
+   */
+  defaultLimit?: number;
+}
+
+/**
+ * Search Adapter
+ * Implements the dev_search tool for semantic code search
+ */
+export class SearchAdapter extends ToolAdapter {
+  readonly metadata = {
+    name: 'search-adapter',
+    version: '1.0.0',
+    description: 'Semantic code search adapter',
+    author: 'Dev-Agent Team',
+  };
+
+  private indexer: RepositoryIndexer;
+  private compactFormatter: CompactFormatter;
+  private verboseFormatter: VerboseFormatter;
+  private config: Required<SearchAdapterConfig>;
+
+  constructor(config: SearchAdapterConfig) {
+    super();
+    this.indexer = config.repositoryIndexer;
+    this.config = {
+      repositoryIndexer: config.repositoryIndexer,
+      defaultFormat: config.defaultFormat ?? 'compact',
+      defaultLimit: config.defaultLimit ?? 10,
+    };
+
+    // Initialize formatters
+    this.compactFormatter = new CompactFormatter({
+      maxResults: this.config.defaultLimit,
+      tokenBudget: 1000,
+    });
+
+    this.verboseFormatter = new VerboseFormatter({
+      maxResults: this.config.defaultLimit,
+      tokenBudget: 5000,
+    });
+  }
+
+  async initialize(context: AdapterContext): Promise<void> {
+    context.logger.info('SearchAdapter initialized', {
+      defaultFormat: this.config.defaultFormat,
+      defaultLimit: this.config.defaultLimit,
+    });
+  }
+
+  getToolDefinition(): ToolDefinition {
+    return {
+      name: 'dev_search',
+      description:
+        'Semantic search for code components (functions, classes, interfaces) in the indexed repository',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          query: {
+            type: 'string',
+            description:
+              'Natural language search query (e.g., "authentication middleware", "database connection logic")',
+          },
+          format: {
+            type: 'string',
+            enum: ['compact', 'verbose'],
+            description:
+              'Output format: "compact" for summaries (default), "verbose" for full details',
+            default: this.config.defaultFormat,
+          },
+          limit: {
+            type: 'number',
+            description: `Maximum number of results to return (default: ${this.config.defaultLimit})`,
+            minimum: 1,
+            maximum: 50,
+            default: this.config.defaultLimit,
+          },
+          scoreThreshold: {
+            type: 'number',
+            description: 'Minimum similarity score (0-1). Lower = more results (default: 0)',
+            minimum: 0,
+            maximum: 1,
+            default: 0,
+          },
+        },
+        required: ['query'],
+      },
+    };
+  }
+
+  async execute(args: Record<string, unknown>, context: ToolExecutionContext): Promise<ToolResult> {
+    const {
+      query,
+      format = this.config.defaultFormat,
+      limit = this.config.defaultLimit,
+      scoreThreshold = 0,
+    } = args;
+
+    // Validate query
+    if (typeof query !== 'string' || query.trim().length === 0) {
+      return {
+        success: false,
+        error: {
+          code: 'INVALID_QUERY',
+          message: 'Query must be a non-empty string',
+        },
+      };
+    }
+
+    // Validate format
+    if (format !== 'compact' && format !== 'verbose') {
+      return {
+        success: false,
+        error: {
+          code: 'INVALID_FORMAT',
+          message: 'Format must be either "compact" or "verbose"',
+        },
+      };
+    }
+
+    // Validate limit
+    if (typeof limit !== 'number' || limit < 1 || limit > 50) {
+      return {
+        success: false,
+        error: {
+          code: 'INVALID_LIMIT',
+          message: 'Limit must be a number between 1 and 50',
+        },
+      };
+    }
+
+    // Validate scoreThreshold
+    if (typeof scoreThreshold !== 'number' || scoreThreshold < 0 || scoreThreshold > 1) {
+      return {
+        success: false,
+        error: {
+          code: 'INVALID_SCORE_THRESHOLD',
+          message: 'Score threshold must be a number between 0 and 1',
+        },
+      };
+    }
+
+    try {
+      context.logger.debug('Executing search', { query, format, limit, scoreThreshold });
+
+      // Perform search
+      const results = await this.indexer.search(query as string, {
+        limit: limit as number,
+        scoreThreshold: scoreThreshold as number,
+      });
+
+      // Format results
+      const formatter = format === 'verbose' ? this.verboseFormatter : this.compactFormatter;
+      const formatted = formatter.formatResults(results);
+
+      context.logger.info('Search completed', {
+        query,
+        resultCount: results.length,
+        tokenEstimate: formatted.tokenEstimate,
+      });
+
+      return {
+        success: true,
+        data: {
+          query,
+          resultCount: results.length,
+          format,
+          results: formatted.content,
+          tokenEstimate: formatted.tokenEstimate,
+        },
+      };
+    } catch (error) {
+      context.logger.error('Search failed', { error });
+      return {
+        success: false,
+        error: {
+          code: 'SEARCH_FAILED',
+          message: error instanceof Error ? error.message : 'Unknown error',
+          details: error,
+        },
+      };
+    }
+  }
+
+  estimateTokens(args: Record<string, unknown>): number {
+    const { format = this.config.defaultFormat, limit = this.config.defaultLimit } = args;
+
+    // Rough estimate based on format and limit
+    const tokensPerResult = format === 'verbose' ? 100 : 20;
+    return (limit as number) * tokensPerResult + 50; // +50 for overhead
+  }
+}

packages/mcp-server/src/formatters/compact-formatter.ts

@@ -0,0 +1,78 @@
+/**
+ * Compact Formatter
+ * Token-efficient formatter that returns summaries only
+ */
+
+import type { SearchResult } from '@lytics/dev-agent-core';
+import type { FormattedResult, FormatterOptions, ResultFormatter } from './types';
+import { estimateTokensForText } from './utils';
+
+/**
+ * Compact formatter - optimized for token efficiency
+ * Returns: path, type, name, score
+ */
+export class CompactFormatter implements ResultFormatter {
+  private options: Required<FormatterOptions>;
+
+  constructor(options: FormatterOptions = {}) {
+    this.options = {
+      maxResults: options.maxResults ?? 10,
+      includePaths: options.includePaths ?? true,
+      includeLineNumbers: options.includeLineNumbers ?? true,
+      includeTypes: options.includeTypes ?? true,
+      includeSignatures: options.includeSignatures ?? false, // Compact mode excludes signatures
+      tokenBudget: options.tokenBudget ?? 1000,
+    };
+  }
+
+  formatResult(result: SearchResult): string {
+    const parts: string[] = [];
+
+    // Score (2 decimals)
+    parts.push(`[${(result.score * 100).toFixed(0)}%]`);
+
+    // Type
+    if (this.options.includeTypes && typeof result.metadata.type === 'string') {
+      parts.push(`${result.metadata.type}:`);
+    }
+
+    // Name
+    if (typeof result.metadata.name === 'string') {
+      parts.push(result.metadata.name);
+    }
+
+    // Path
+    if (this.options.includePaths && typeof result.metadata.path === 'string') {
+      const pathPart =
+        this.options.includeLineNumbers && typeof result.metadata.startLine === 'number'
+          ? `(${result.metadata.path}:${result.metadata.startLine})`
+          : `(${result.metadata.path})`;
+      parts.push(pathPart);
+    }
+
+    return parts.join(' ');
+  }
+
+  formatResults(results: SearchResult[]): FormattedResult {
+    // Respect max results
+    const limitedResults = results.slice(0, this.options.maxResults);
+
+    // Format each result
+    const formatted = limitedResults.map((result, index) => {
+      return `${index + 1}. ${this.formatResult(result)}`;
+    });
+
+    // Calculate total tokens
+    const content = formatted.join('\n');
+    const tokenEstimate = estimateTokensForText(content);
+
+    return {
+      content,
+      tokenEstimate,
+    };
+  }
+
+  estimateTokens(result: SearchResult): number {
+    return estimateTokensForText(this.formatResult(result));
+  }
+}

packages/mcp-server/src/formatters/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Formatters
+ * Token-efficient result formatters for MCP responses
+ */
+
+export { CompactFormatter } from './compact-formatter';
+export * from './types';
+export * from './utils';
+export { VerboseFormatter } from './verbose-formatter';

packages/mcp-server/src/formatters/types.ts

@@ -0,0 +1,74 @@
+/**
+ * Formatter Types
+ * Types for result formatting and token estimation
+ */
+
+import type { SearchResult } from '@lytics/dev-agent-core';
+
+/**
+ * Format mode for search results
+ */
+export type FormatMode = 'compact' | 'verbose';
+
+/**
+ * Formatted search result
+ */
+export interface FormattedResult {
+  content: string;
+  tokenEstimate: number;
+}
+
+/**
+ * Result formatter interface
+ */
+export interface ResultFormatter {
+  /**
+   * Format a single search result
+   */
+  formatResult(result: SearchResult): string;
+
+  /**
+   * Format multiple search results
+   */
+  formatResults(results: SearchResult[]): FormattedResult;
+
+  /**
+   * Estimate tokens for a search result
+   */
+  estimateTokens(result: SearchResult): number;
+}
+
+/**
+ * Formatter options
+ */
+export interface FormatterOptions {
+  /**
+   * Maximum number of results to include
+   */
+  maxResults?: number;
+
+  /**
+   * Include file paths in output
+   */
+  includePaths?: boolean;
+
+  /**
+   * Include line numbers
+   */
+  includeLineNumbers?: boolean;
+
+  /**
+   * Include type information
+   */
+  includeTypes?: boolean;
+
+  /**
+   * Include signatures
+   */
+  includeSignatures?: boolean;
+
+  /**
+   * Token budget (soft limit)
+   */
+  tokenBudget?: number;
+}