@ngao/search 1.0.0-alpha.1

package/README.md

@@ -0,0 +1,232 @@
+# NGAO Search - MCP Server
+
+A Model Context Protocol (MCP) server for local code and documentation search with LLM-friendly output.
+
+## Features
+
+- 🔍 **Multi-Format Indexing**: Python, Markdown, JavaScript/TypeScript, JSON, YAML
+- 🧠 **LLM-Optimized**: Results formatted specifically for AI model consumption
+- 📊 **Smart Ranking**: Multi-factor relevance scoring
+- 🚀 **Fast Local Search**: No network dependency, instant results
+- 📚 **Context-Aware**: Includes surrounding code context in results
+- 🔄 **Incremental Indexing**: Only reindexes changed files
+- 💾 **Persistent Storage**: LanceDB integration for data persistence across restarts
+- 🤖 **Vector Search**: Semantic similarity search with embeddings support
+
+## Installation
+
+```bash
+npm install
+npm run build
+```
+
+## Usage
+
+### As a Library
+
+```typescript
+import { SearchEngine } from 'ngao-search-mcp';
+import {
+  InMemoryBlockRepository,
+  InMemoryMetadataRepository,
+} from 'ngao-search-mcp';
+
+// Create repositories
+const blockRepo = new InMemoryBlockRepository();
+const metadataRepo = new InMemoryMetadataRepository();
+
+// Create search engine
+const engine = new SearchEngine(blockRepo, metadataRepo);
+
+// Index a directory
+const stats = await engine.indexDirectory('./src');
+console.log(`Indexed ${stats.totalBlocks} blocks from ${stats.totalFiles} files`);
+
+// Search
+const results = await engine.search('authentication handler');
+console.log(`Found ${results.length} results`);
+```
+
+### As MCP Server
+
+```typescript
+import { McpServer, handleToolCall } from 'ngao-search-mcp';
+
+const server = new McpServer();
+
+// Get available tools
+const tools = server.getTools();
+
+// Handle tool calls
+const result = await handleToolCall(server, 'search', {
+  query: 'authentication',
+  maxResults: 10,
+});
+```
+
+## Architecture
+
+### Core Components
+
+- **SearchEngine**: Main facade implementing ISearchEngine interface
+- **Parsers**: File type-specific parsers (Python, Markdown, JavaScript, etc.)
+- **Repositories**: Abstract data access layer
+- **Indexing**: Block extraction and index building
+- **Search**: Query parsing, ranking, and result formatting
+- **MCP Server**: Protocol implementation for tool exposure
+
+### Design Patterns
+
+- **Repository Pattern**: Flexible storage backend (in-memory for tests, SQLite for production)
+- **Facade Pattern**: Single entry point via SearchEngine
+- **Factory Pattern**: Parser selection by file type
+- **Dependency Injection**: Explicit dependency management
+
+## Project Structure
+
+```
+src/
+├── core/              # Models, types, constants, errors
+├── parsers/           # File type parsers
+├── repositories/      # Data access interfaces & implementations
+├── indexing/          # Block extraction & index building
+├── search/            # Query, ranking, formatting
+├── api/               # SearchEngine facade
+├── mcp/               # MCP server implementation
+└── utils/             # Utility functions
+
+tests/
+├── unit/              # Unit tests
+└── integration/       # Integration tests
+```
+
+## Coding Standards
+
+All code follows strict TypeScript conventions:
+
+- ✅ **Type Safety**: No `any` types, strict mode enabled
+- ✅ **Naming**: PascalCase classes, camelCase methods, UPPER_SNAKE_CASE constants
+- ✅ **Architecture**: Clear separation of concerns
+- ✅ **Documentation**: JSDoc comments for public APIs
+- ✅ **Testing**: Unit and integration tests
+
+## Configuration
+
+Environment variables:
+
+```bash
+NODE_ENV=development|production|test
+NGAO_DATA_DIR=~/.ngao-search        # LanceDB storage directory (default: ~/.ngao-search)
+MCP_TRANSPORT=stdio|http|both       # Transport mode (default: both)
+PORT=3000                            # REST API port (default: 3000)
+NGAO_CACHE_TTL_SECONDS=3600
+NGAO_MAX_INDEX_SIZE_MB=500
+NGAO_CONTEXT_LINES=10
+NGAO_MAX_RESULTS=50
+```
+
+### Storage
+
+NGAO Search uses **LanceDB** for persistent storage:
+
+```bash
+~/.ngao-search/
+├── blocks.lance        # Indexed code blocks with embeddings
+└── metadata.lance      # File metadata and statistics
+```
+
+Data persists across restarts. To reset, simply delete the `~/.ngao-search` directory.
+
+## Development
+
+```bash
+# Build
+npm run build
+
+# Type check
+npm run type-check
+
+# Lint
+npm run lint
+npm run lint:fix
+
+# Format
+npm run format
+npm run format:check
+
+# Test
+npm test
+npm run test:watch
+npm run test:coverage
+```
+
+## Supported File Types
+
+| Format | Extensions | Features |
+|--------|-----------|----------|
+| Python | `.py`, `.pyi` | Functions, classes, methods, docstrings |
+| Markdown | `.md`, `.markdown`, `.mdx` | Headings, paragraphs, code blocks |
+| JavaScript | `.js`, `.jsx`, `.mjs` | Functions, classes, exports, hooks |
+| TypeScript | `.ts`, `.tsx` | Types, interfaces, classes, functions |
+| JSON | `.json`, `.jsonc` | Keys, nested structures |
+| YAML | `.yaml`, `.yml` | Keys, values, nested structures |
+
+## Algorithm Details
+
+### Ranking Formula
+
+```
+Score = 0.35 × KeywordMatch + 0.25 × Position + 0.20 × ScopeSpecificity
+        + 0.10 × Recency + 0.10 × Frequency
+```
+
+### Indexing
+
+- **Inverted Index**: Maps keywords to source blocks
+- **Block Registry**: Direct block access by ID
+- **Scope Hierarchy**: Quick navigation by scope path
+- **Metadata**: Change detection via file hashing
+
+## API Reference
+
+### ISearchEngine
+
+```typescript
+search(query: string, options?: SearchOptions): Promise<SearchResult[]>
+indexDirectory(dirPath: string, options?: IndexOptions): Promise<IndexStats>
+getStats(): Promise<IndexStats>
+clearIndex(): Promise<void>
+```
+
+### IBlockRepository
+
+```typescript
+findById(id: string): Promise<Block | null>
+findAll(): Promise<Block[]>
+save(entity: Block): Promise<Block>
+delete(id: string): Promise<boolean>
+findByFilePath(filePath: string): Promise<Block[]>
+searchByKeyword(keyword: string): Promise<Block[]>
+```
+
+## Performance
+
+- Indexing: ~1000 blocks/second (single-threaded)
+- Search: <100ms for typical queries
+- Memory: ~1KB per indexed block (in-memory)
+- Storage: ~500 bytes per block (SQLite)
+
+## License
+
+MIT
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## References
+
+For detailed architecture and design documentation, see:
+- `/docs/architecture-design-standards/` - Technical design
+- `/docs/reference/` - Quick reference guides
+- `/docs/tracking/` - Implementation roadmap