Design Patterns MCP Server

Instructions

Implementation Reference

• src/mcp-server.ts:188-209 (registration)

  Registration of the 'search_patterns' tool in the MCP server's tool list, including description and input schema

    name: 'search_patterns',
    description: 'Search patterns by keyword or semantic similarity',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'Search query',
        },
        searchType: {
          type: 'string',
          enum: ['keyword', 'semantic', 'hybrid'],
          default: 'hybrid',
        },
        limit: {
          type: 'number',
          default: 10,
        },
      },
      required: ['query'],
    },
  },

• src/mcp-server.ts:353-383 (handler)

  Handler function for executing the search_patterns tool: validates input, performs semantic search via SemanticSearchService, and formats results as text response

  private async handleSearchPatterns(args: unknown): Promise<CallToolResult> {
    const validatedArgs = InputValidator.validateSearchPatternsArgs(args);
    const query = {
      text: validatedArgs.query,
      filters: {},
      options: {
        limit: validatedArgs.limit,
        includeMetadata: true,
      },
    };
  
    const results = await this.semanticSearch.search(query);
  
    return {
      content: [
        {
          type: 'text',
          text:
            `Search results for "${validatedArgs.query}":\n\n` +
            results
              .map(
                (result, index) =>
                  `${index + 1}. **${result.pattern.name}** (${result.pattern.category})\n` +
                  `   Score: ${(result.score * 100).toFixed(1)}%\n` +
                  `   Description: ${result.pattern.description}\n`
              )
              .join('\n'),
        },
      ],
    };
  }

• src/types/mcp-args.ts:37-51 (schema)

  TypeScript interface definition and type guard for SearchPatternsArgs used in tool input validation

  export interface SearchPatternsArgs {
    query: string;
    search_type?: 'keyword' | 'semantic' | 'hybrid';
    category_filter?: string[];
    limit?: number;
  }
  
  export function isSearchPatternsArgs(args: unknown): args is SearchPatternsArgs {
    if (typeof args !== 'object' || args === null) return false;
    const a = args as Record<string, unknown>;
    return typeof a.query === 'string' &&
      (a.search_type === undefined || ['keyword', 'semantic', 'hybrid'].includes(a.search_type as string)) &&
      (a.category_filter === undefined || Array.isArray(a.category_filter)) &&
      (a.limit === undefined || typeof a.limit === 'number');
  }

• src/lib/mcp-tools.ts:932-936 (registration)

  Tool dispatch case in MCPToolsHandler.handleToolCall that routes to handler

  case 'search_patterns':
    if (!isSearchPatternsArgs(args)) {
      throw new Error('Invalid arguments for search_patterns tool');
    }
    return await this.handleSearchPatterns(args);

• src/lib/mcp-tools.ts:1070-1122 (handler)

  Comprehensive hybrid search handler supporting keyword, semantic, and hybrid search modes with result merging (alternative implementation in lib)

  private async handleSearchPatterns(args: SearchPatternsArgs): Promise<Record<string, unknown>> {
    // Validate input
    if (!args.query || typeof args.query !== 'string' || args.query.length < 2) {
      throw new Error('Query must be at least 2 characters long');
    }
  
    const searchType = args.search_type ?? 'hybrid';
    const limit = Math.min(args.limit ?? 10, 50);
  
    try {
      let results: SearchResult[];
  
      if (searchType === 'semantic') {
        // Use semantic search
        results = await this.config.semanticSearch.search(args.query, {
          limit,
          filters: args.category_filter ? { categories: args.category_filter } : undefined,
        });
      } else if (searchType === 'keyword') {
        // Use keyword search
        results = await this.config.databaseManager.searchPatterns(args.query, {
          limit,
          filters: args.category_filter ? { categories: args.category_filter } : undefined,
        });
      } else {
        // Hybrid search
        const semanticResults = await this.config.semanticSearch.search(args.query, {
          limit: Math.ceil(limit / 2),
          filters: args.category_filter ? { categories: args.category_filter } : undefined,
        });
  
        const keywordResults = await this.config.databaseManager.searchPatterns(args.query, {
          limit: Math.ceil(limit / 2),
          filters: args.category_filter ? { categories: args.category_filter } : undefined,
        });
  
        // Merge and deduplicate results
        results = this.mergeSearchResults(semanticResults, keywordResults, limit);
      }
  
      return {
        patterns: results,
        total_results: results.length,
        search_type: searchType,
        limit,
        timestamp: new Date().toISOString(),
      };
    } catch (error) {
      throw new Error(
        `Pattern search failed: ${error instanceof Error ? error.message : String(error)}`
      );
    }
  }