@fractalizer/mcp-search 0.1.0

package/README.md

@@ -0,0 +1,408 @@
+# @fractalizer/mcp-search
+
+**Advanced Tool Search Engine with compile-time indexing and 5 search strategies**
+
+[![npm version](https://img.shields.io/npm/v/@fractalizer/mcp-search.svg)](https://www.npmjs.com/package/@fractalizer/mcp-search)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## 🎯 Purpose
+
+**Principle:** Fast, intelligent tool discovery with compile-time indexing
+
+**Key Features:**
+- ✅ **Compile-time indexing** — zero runtime overhead for index generation
+- ✅ **5 search strategies** — name, description, category, fuzzy, weighted-combined
+- ✅ **LRU cache** — fast repeated searches
+- ✅ **MCP tool included** — `search_tools` for Claude to discover tools
+
+**Architecture rule:** Search depends ONLY on `@fractalizer/mcp-core`
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @fractalizer/mcp-search
+```
+
+**Dependencies:**
+- `@fractalizer/mcp-core` (BaseTool, utilities)
+- `@fractalizer/mcp-infrastructure` (via core)
+- `lru-cache` (caching)
+
+---
+
+## 📁 Structure
+
+```
+src/
+├── engine/
+│   └── tool-search-engine.ts        # Main search engine with LRU cache
+├── strategies/                       # 5 search strategies
+│   ├── search-strategy.interface.ts
+│   ├── name-search.strategy.ts      # Match by tool name
+│   ├── description-search.strategy.ts # Match in description
+│   ├── category-search.strategy.ts  # Match by category
+│   ├── fuzzy-search.strategy.ts     # Fuzzy matching
+│   └── weighted-combined.strategy.ts # Combine all strategies
+├── scoring/
+│   └── strategy-weights.ts          # Configurable weights
+├── tools/                            # MCP tool for search
+│   ├── search-tools.tool.ts
+│   ├── search-tools.metadata.ts     # Metadata
+│   ├── search-tools.definition.ts
+│   └── search-tools.schema.ts
+├── utils/                            # Utilities
+│   ├── build-index-from-registry.ts # Index builder
+│   └── text-utils.ts                # Text processing
+├── constants.ts                      # Constants
+├── types.ts                          # Type definitions
+└── index.ts                          # Public exports
+```
+
+---
+
+## 🔧 Core Components
+
+### ToolSearchEngine
+
+**Main search engine** with LRU cache and strategy selection.
+
+**Usage:**
+```typescript
+import { ToolSearchEngine } from '@fractalizer/mcp-search';
+
+// Create engine with tool metadata
+const engine = new ToolSearchEngine(toolMetadataArray);
+
+// Search with default strategy (weighted-combined)
+const results = engine.search('find issues');
+
+// Search with specific strategy
+const nameResults = engine.search('get_issue', 'name');
+const fuzzyResults = engine.search('isue', 'fuzzy');
+
+console.log(results);
+// [
+//   { tool: ToolMetadata, score: 0.95 },
+//   { tool: ToolMetadata, score: 0.78 },
+//   ...
+// ]
+```
+
+**Cache:**
+- LRU cache with max 100 entries
+- Cache key: `${query}_${strategy}`
+- Automatic eviction of least recently used
+
+### Search Strategies
+
+**5 strategies with different matching algorithms:**
+
+#### 1. NameSearchStrategy
+Matches query against tool name.
+
+**Example:**
+```typescript
+Query: "get_issue"
+Matches: "get_issue" (exact), "get_issues" (partial)
+```
+
+#### 2. DescriptionSearchStrategy
+Matches query words in tool description.
+
+**Example:**
+```typescript
+Query: "retrieve task details"
+Matches tools with descriptions containing "retrieve", "task", "details"
+```
+
+#### 3. CategorySearchStrategy
+Matches query against tool category.
+
+**Example:**
+```typescript
+Query: "api"
+Matches all tools with category: "api"
+```
+
+#### 4. FuzzySearchStrategy
+Fuzzy matching using Levenshtein distance.
+
+**Example:**
+```typescript
+Query: "isue" (typo)
+Matches: "issue" (distance: 1)
+```
+
+#### 5. WeightedCombinedStrategy (Default)
+Combines all strategies with configurable weights.
+
+**Default weights:**
+```typescript
+{
+  name: 0.4,        // 40% - name match most important
+  description: 0.3, // 30% - description match
+  category: 0.2,    // 20% - category match
+  fuzzy: 0.1,       // 10% - fuzzy fallback
+}
+```
+
+**Usage:**
+```typescript
+import { WeightedCombinedStrategy, STRATEGY_WEIGHTS } from '@fractalizer/mcp-search';
+
+// Custom weights
+const customWeights = {
+  ...STRATEGY_WEIGHTS,
+  fuzzy: 0.2, // Increase fuzzy matching importance
+};
+
+const strategy = new WeightedCombinedStrategy(customWeights);
+```
+
+---
+
+## 🛠️ Compile-time Indexing
+
+**Automatic index generation at build time:**
+
+1. **prebuild script** (in package.json):
+   ```json
+   {
+     "scripts": {
+       "prebuild": "tsx scripts/generate-tool-index.ts"
+     }
+   }
+   ```
+
+2. **Script scans** `TOOL_CLASSES` and extracts `METADATA`:
+   ```typescript
+   // scripts/generate-tool-index.ts
+   const TOOL_CLASSES = [
+     GetIssueTool,
+     FindIssuesTool,
+     // ...
+   ];
+
+   // Generates: src/generated-index.ts
+   export const TOOL_INDEX = [
+     { name: 'get_issue', category: 'api', description: '...' },
+     { name: 'find_issues', category: 'api', description: '...' },
+   ];
+   ```
+
+3. **Search engine** uses pre-generated index (no runtime reflection):
+   ```typescript
+   import { TOOL_INDEX } from './generated-index.js';
+
+   const engine = new ToolSearchEngine(TOOL_INDEX);
+   ```
+
+**Benefits:**
+- ⚡ Zero runtime overhead for index generation
+- 🔒 Type-safe (compile-time validation)
+- 📦 Smaller bundle (no reflection code)
+
+---
+
+## 🔍 MCP Tool: search_tools
+
+**Included MCP tool** for Claude to discover available tools.
+
+**Tool name:** `search_tools`
+
+**Usage in Claude:**
+```
+User: "What tools are available for working with issues?"
+Claude uses: search_tools { query: "issues" }
+```
+
+**Parameters:**
+```typescript
+{
+  query: string;           // Search query
+  strategy?: string;       // Optional: 'name' | 'description' | 'category' | 'fuzzy' | 'weighted'
+  limit?: number;          // Optional: max results (default: 10)
+}
+```
+
+**Example response:**
+```json
+{
+  "results": [
+    {
+      "name": "get_issue",
+      "category": "api",
+      "description": "Retrieve issue details by key",
+      "score": 0.95
+    },
+    {
+      "name": "find_issues",
+      "category": "api",
+      "description": "Search issues using JQL query",
+      "score": 0.82
+    }
+  ]
+}
+```
+
+---
+
+## 🚨 Critical Rules
+
+### 1. Always regenerate index after adding tools
+
+```bash
+# Index is regenerated automatically on build
+npm run build
+
+# Or manually:
+npm run prebuild
+```
+
+### 2. METADATA is required for all tools
+
+```typescript
+// ✅ CORRECT
+class MyTool extends BaseTool<TFacade> {
+  static readonly METADATA: StaticToolMetadata = {
+    name: 'my_tool',
+    category: 'api',
+    description: 'Tool description',
+  };
+}
+
+// ❌ WRONG (no METADATA)
+class MyTool extends BaseTool<TFacade> {
+  // Search won't find this tool
+}
+```
+
+### 3. Use WeightedCombinedStrategy for best results
+
+```typescript
+// ✅ CORRECT (default, best accuracy)
+const results = engine.search('find tasks');
+
+// ⚠️ OK (specific strategy for special cases)
+const exactMatch = engine.search('get_issue', 'name');
+```
+
+---
+
+## 📖 API Reference
+
+### Exports
+
+```typescript
+// Engine
+export { ToolSearchEngine } from './engine/tool-search-engine.js';
+
+// Strategies
+export type { SearchStrategy } from './strategies/search-strategy.interface.js';
+export { NameSearchStrategy } from './strategies/name-search.strategy.js';
+export { DescriptionSearchStrategy } from './strategies/description-search.strategy.js';
+export { CategorySearchStrategy } from './strategies/category-search.strategy.js';
+export { FuzzySearchStrategy } from './strategies/fuzzy-search.strategy.js';
+export { WeightedCombinedStrategy } from './strategies/weighted-combined.strategy.js';
+
+// Scoring
+export { STRATEGY_WEIGHTS } from './scoring/strategy-weights.js';
+
+// Tools
+export { SearchToolsTool } from './tools/search-tools.tool.js';
+export { SearchToolsDefinition } from './tools/search-tools.definition.js';
+
+// Generated index
+export { TOOL_INDEX } from './generated-index.js';
+
+// Types
+export type { ToolMetadata, SearchResult, StrategyWeights } from './types.js';
+```
+
+---
+
+## 🧪 Testing
+
+**Run tests:**
+```bash
+cd packages/framework/search
+npm run test
+```
+
+**With coverage:**
+```bash
+npm run test:coverage
+```
+
+**Watch mode:**
+```bash
+npm run test:watch
+```
+
+---
+
+## 🎯 Advanced Usage
+
+### Custom Search Strategy
+
+```typescript
+import { SearchStrategy, ToolMetadata } from '@fractalizer/mcp-search';
+
+class CustomSearchStrategy implements SearchStrategy {
+  search(query: string, tools: ToolMetadata[]) {
+    return tools
+      .filter((tool) => /* custom logic */)
+      .map((tool) => ({
+        tool,
+        score: /* custom scoring */,
+      }));
+  }
+}
+
+// Use custom strategy
+const engine = new ToolSearchEngine(TOOL_INDEX);
+engine.registerStrategy('custom', new CustomSearchStrategy());
+const results = engine.search('query', 'custom');
+```
+
+### Adjusting Weights
+
+```typescript
+import { STRATEGY_WEIGHTS } from '@fractalizer/mcp-search';
+
+const customWeights = {
+  ...STRATEGY_WEIGHTS,
+  name: 0.5,        // Increase name importance
+  description: 0.3,
+  category: 0.1,
+  fuzzy: 0.1,
+};
+
+const strategy = new WeightedCombinedStrategy(customWeights);
+```
+
+---
+
+## 🤝 Contributing
+
+See [../../.github/CONTRIBUTING.md](../../.github/CONTRIBUTING.md)
+
+**Architecture rules:** [../../CLAUDE.md](../../CLAUDE.md)
+
+---
+
+## 📄 License
+
+MIT License
+
+---
+
+## 🔗 Links
+
+- **Monorepo root:** [../../README.md](../../README.md)
+- **Architecture:** [../../ARCHITECTURE.md](../../ARCHITECTURE.md)
+- **Core package:** [../core/README.md](../core/README.md)

package/dist/constants.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Константы для системы поиска tools
+ */
+/**
+ * Дефолтное количество результатов поиска
+ */
+export declare const DEFAULT_TOOL_SEARCH_LIMIT: 10;
+/**
+ * Дефолтный уровень детализации результатов
+ */
+export declare const DEFAULT_TOOL_SEARCH_DETAIL_LEVEL: "name_and_description";
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,eAAO,MAAM,yBAAyB,EAAG,EAAW,CAAC;AAErD;;GAEG;AACH,eAAO,MAAM,gCAAgC,EAAG,sBAA+B,CAAC"}

package/dist/constants.js

@@ -0,0 +1,12 @@
+/**
+ * Константы для системы поиска tools
+ */
+/**
+ * Дефолтное количество результатов поиска
+ */
+export const DEFAULT_TOOL_SEARCH_LIMIT = 10;
+/**
+ * Дефолтный уровень детализации результатов
+ */
+export const DEFAULT_TOOL_SEARCH_DETAIL_LEVEL = 'name_and_description';
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAW,CAAC;AAErD;;GAEG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,sBAA+B,CAAC"}

package/dist/engine/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Engine module exports
+ */
+export { ToolSearchEngine } from './tool-search-engine.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/engine/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/engine/index.js

@@ -0,0 +1,5 @@
+/**
+ * Engine module exports
+ */
+export { ToolSearchEngine } from './tool-search-engine.js';
+//# sourceMappingURL=index.js.map

package/dist/engine/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/engine/tool-search-engine.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Главный класс поисковой системы tools
+ *
+ * Responsibilities:
+ * - Выполнение поиска через стратегии
+ * - Фильтрация по категориям и типам
+ * - Кеширование результатов
+ * - Форматирование результатов по уровню детализации
+ * - Lazy loading полных метаданных
+ */
+import type { ISearchStrategy } from '../strategies/search-strategy.interface.js';
+import type { SearchParams, SearchResponse, StaticToolIndex } from '../types.js';
+import type { ToolRegistry } from '@fractalizer/mcp-core';
+/**
+ * Поисковый движок для tools
+ */
+export declare class ToolSearchEngine {
+    private readonly staticIndex;
+    private readonly toolRegistry;
+    private searchStrategy;
+    private cache;
+    private lazyIndex;
+    /**
+     * Максимальный размер кеша (LRU)
+     */
+    private readonly MAX_CACHE_SIZE;
+    constructor(staticIndex: readonly StaticToolIndex[] | null, toolRegistry: ToolRegistry, searchStrategy: ISearchStrategy);
+    /**
+     * Получить индекс (статический или динамический из ToolRegistry)
+     */
+    private getIndex;
+    /**
+     * Построить индекс из ToolRegistry
+     */
+    private buildIndexFromRegistry;
+    /**
+     * Выполнить поиск с кешированием
+     */
+    search(params: SearchParams): SearchResponse;
+    /**
+     * Выполнить поиск без кеширования
+     */
+    private performSearch;
+    /**
+     * Фильтровать индекс по параметрам
+     */
+    private filterIndex;
+    /**
+     * Форматировать результаты по уровню детализации
+     */
+    private formatResults;
+    /**
+     * Генерировать ключ кеша из параметров поиска
+     */
+    private getCacheKey;
+    /**
+     * Очистить кеш
+     *
+     * Полезно для тестов и при обновлении индекса
+     */
+    clearCache(): void;
+    /**
+     * Получить статистику кеша
+     */
+    getCacheStats(): {
+        size: number;
+        maxSize: number;
+    };
+}
+//# sourceMappingURL=tool-search-engine.d.ts.map

package/dist/engine/tool-search-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-search-engine.d.ts","sourceRoot":"","sources":["../../src/engine/tool-search-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAC;AAClF,OAAO,KAAK,EACV,YAAY,EACZ,cAAc,EAEd,eAAe,EAGhB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAI1D;;GAEG;AACH,qBAAa,gBAAgB;IAWzB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAX/B,OAAO,CAAC,cAAc,CAAkB;IACxC,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,SAAS,CAAkC;IAEnD;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAO;gBAGnB,WAAW,EAAE,SAAS,eAAe,EAAE,GAAG,IAAI,EAC9C,YAAY,EAAE,YAAY,EAC3C,cAAc,EAAE,eAAe;IAMjC;;OAEG;IACH,OAAO,CAAC,QAAQ;IAchB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IA+B9B;;OAEG;IACH,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,cAAc;IA2B5C;;OAEG;IACH,OAAO,CAAC,aAAa;IAiCrB;;OAEG;IACH,OAAO,CAAC,WAAW;IAgBnB;;OAEG;IACH,OAAO,CAAC,aAAa;IA6CrB;;OAEG;IACH,OAAO,CAAC,WAAW;IAUnB;;;;OAIG;IACH,UAAU,IAAI,IAAI;IAIlB;;OAEG;IACH,aAAa,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;CAMnD"}