@ngao/search 0.1.0 → 0.1.2

package/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(find:*)",
+      "Bash(xargs:*)",
+      "Bash(npm run build:*)",
+      "Bash(npm test:*)"
+    ]
+  }
+}

package/.env.example

@@ -0,0 +1,7 @@
+# ngao search Configuration
+# Copy this to .env and customize for your environment
+
+# Port for REST API (optional)
+# Leave unset or set to 0 for random available port
+# Set to specific port number (e.g., 3000) to use that port
+PORT=

package/.eslintrc.json

@@ -0,0 +1,20 @@
+{
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": 2020,
+    "sourceType": "module"
+  },
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "rules": {
+    "@typescript-eslint/no-explicit-any": "warn",
+    "@typescript-eslint/explicit-module-boundary-types": "off",
+    "no-console": "off"
+  },
+  "env": {
+    "node": true,
+    "es6": true
+  }
+}

package/.github/workflows/build.yml

@@ -0,0 +1,39 @@
+name: Build
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        node-version: [20.x]
+    
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Build application
+        run: npm run build
+      
+      - name: Build CLI binary
+        run: npm run build:cli
+      
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v3
+        with:
+          name: ngao-search-${{ matrix.os }}
+          path: bin/

package/.github/workflows/release.yml

@@ -0,0 +1,34 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    runs-on: ${{ matrix.os }}
+    
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    
+    steps:
+      - uses: actions/checkout@v3
+      
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Build CLI binary
+        run: npm run build:cli
+      
+      - name: Create Release
+        uses: softprops/action-gh-release@v1
+        with:
+          files: bin/ngao-search*
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/test.yml

@@ -0,0 +1,35 @@
+name: Test
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x]
+    
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Type check
+        run: npx tsc --noEmit
+      
+      - name: Run tests
+        run: npm test
+      
+      - name: Run linter
+        run: npm run lint

package/.mcp-config.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "ngao-search": {
+      "command": "node",
+      "args": [
+        "dist/main.js"
+      ],
+      "env": {
+        "MCP_TRANSPORT": "stdio"
+      },
+      "cwd": "/Users/tuanva/Desktop/ngao-search"
+    }
+  }
+}

package/.prettierrc.json

@@ -0,0 +1,10 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "arrowParens": "always",
+  "endOfLine": "lf"
+}

package/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2026 Ngao Search Contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/Makefile

@@ -0,0 +1,26 @@
+.PHONY: all build build-js build-cli clean test dev install
+
+all: clean build
+
+build: build-js
+
+build-js:
+	npm run build
+
+build-cli:
+	npm run build:cli
+
+clean:
+	rm -rf dist/ bin/
+
+test:
+	npm test
+
+dev:
+	npm run dev
+
+install:
+	npm install
+
+start:
+	npm start

package/README.md

@@ -1,219 +1,104 @@
-# ngao search
+# Ngao Search - MCP Server
 
-A Model Context Protocol (MCP) server for local code and document search with LLM-friendly output.
+Claude Desktop MCP Server for code search with file watching, REST API, and Model Context Protocol integration.
+
+> **Note:** This is the MCP server package for Claude Desktop integration. If you're looking for the core search library to embed in your own applications, see [`@ngao/search-core`](https://www.npmjs.com/package/@ngao/search-core).
 
 ## 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
+- 🔍 Full-text and semantic code search
+- 👁️ Automatic file watching and reindexing
+- 🌐 REST API server
+- 🔌 Model Context Protocol (MCP) integration
+- 🖥️ Interactive CLI
+- 📊 Session and search history management
 
 ## 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`);
+npm install -g @ngao/search
 ```
 
-### As MCP Server
-
-```typescript
-import { McpServer, handleToolCall } from 'ngao-search-mcp';
+Or use directly:
 
-const server = new McpServer();
-
-// Get available tools
-const tools = server.getTools();
-
-// Handle tool calls
-const result = await handleToolCall(server, 'search', {
-  query: 'authentication',
-  maxResults: 10,
-});
+```bash
+npx @ngao/search
 ```
 
-## Architecture
+### Pre-downloaded Models
 
-### Core Components
+Embedding models are **included with @ngao/search-core** dependency.
 
-- **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
+The core library contains pre-downloaded models - no additional downloads needed!
 
-### Design Patterns
+See the [Installation Guide](./docs/INSTALLATION.md) for details.
 
-- **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
+## Quick Start
 
-## Project Structure
+### Setup
 
+```bash
+npx @ngao/search --setup
 ```
-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
+This will guide you through setting up a search index for your project.
 
-Environment variables:
+### Search via CLI
 
 ```bash
-PORT=3000                            # REST API port (optional, defaults to random available port)
+npx @ngao/search search "function name"
 ```
 
-### Storage
-
-ngao search uses **LanceDB** for persistent storage:
+### Start REST API Server
 
 ```bash
-~/.ngao-search/
-├── blocks.lance        # Indexed code blocks with embeddings
-└── metadata.lance      # File metadata and statistics
+npx @ngao/search --server --port 3000
 ```
 
-Data persists across restarts. To reset, simply delete the `~/.ngao-search` directory.
-
-## Development
+Then use the API:
 
 ```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
+curl http://localhost:3000/api/search?q=useState
 ```
 
-## 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
+### Start MCP Server
 
-### Ranking Formula
-
-```
-Score = 0.35 × KeywordMatch + 0.25 × Position + 0.20 × ScopeSpecificity
-        + 0.10 × Recency + 0.10 × Frequency
+```bash
+npx @ngao/search --mcp
 ```
 
-### 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>
-```
+## Configuration
 
-### IBlockRepository
+Create a `config.json` file in your project root:
 
-```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[]>
+```json
+{
+  "projectRoot": "/path/to/project",
+  "language": "typescript",
+  "indexDirectory": ".ngao/index",
+  "watchMode": true,
+  "autoReindex": true
+}
 ```
 
-## Performance
+## Documentation
 
-- Indexing: ~1000 blocks/second (single-threaded)
-- Search: <100ms for typical queries
-- Memory: ~1KB per indexed block (in-memory)
-- Storage: ~500 bytes per block (SQLite)
+- [Installation Guide](./docs/INSTALLATION.md)
+- [Usage Guide](./docs/USAGE.md)
+- [API Documentation](./docs/API.md)
+- [MCP Integration](./docs/MCP_INTEGRATION.md)
+- [File Watching](./docs/FILE_WATCHING.md)
 
-## License
+## Architecture
 
-MIT
+This application is built on top of [`@ngao/search-core`](https://www.npmjs.com/package/@ngao/search-core), providing additional features:
 
-## Contributing
+- File watching (Chokidar)
+- HTTP REST API (Express)
+- MCP protocol transport
+- CLI interface
+- Session management
 
-Contributions are welcome! Please feel free to submit issues and pull requests.
+## License
 
+Apache-2.0

package/config.example.json

@@ -0,0 +1,8 @@
+{
+  "databasePath": "./data/index.db",
+  "cacheTtlSeconds": 3600,
+  "maxIndexSizeMb": 1000,
+  "maxSearchResults": 100,
+  "logLevel": "INFO",
+  "enableMetrics": false
+}

package/dist/backend/api/search-engine.d.ts

@@ -0,0 +1,40 @@
+/**
+ * SearchEngine Facade Implementation
+ * Main public API for NGAO Search
+ * Updated: LanceDB-based storage with vector embeddings
+ */
+import 'reflect-metadata';
+import { ISearchEngine, ILogger } from '../core/types';
+import { SearchResult, IndexStats, SearchOptions, IndexOptions } from '../core/models';
+import { IBlockRepository, IMetadataRepository } from '../repositories/repository.interface';
+/**
+ * SearchEngine implements ISearchEngine interface
+ * Orchestrates all components for search and indexing
+ * Storage: LanceDB (persistent, with vector embeddings)
+ */
+export declare class SearchEngine implements ISearchEngine {
+    private _blockRepository;
+    private _metadataRepository;
+    private _parserFactory;
+    private _queryParser;
+    private _blockExtractor;
+    private _searcher;
+    private _rankingEngine;
+    private _contextExtractor;
+    private _logger;
+    private _embeddingService;
+    private _quantizationService;
+    private _enableVectorSearch;
+    constructor(blockRepository: IBlockRepository, metadataRepository: IMetadataRepository, logger?: ILogger, options?: {
+        enableVectorSearch?: boolean;
+    });
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    indexDirectory(dirPath: string, options?: IndexOptions & {
+        includePaths?: string[];
+        excludePaths?: string[];
+    }): Promise<IndexStats>;
+    getStats(): Promise<IndexStats>;
+    clearIndex(): Promise<void>;
+    private _shouldReindexFile;
+}
+//# sourceMappingURL=search-engine.d.ts.map

package/dist/backend/api/search-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-engine.d.ts","sourceRoot":"","sources":["../../../src/backend/api/search-engine.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,OAAO,EAAkC,MAAM,eAAe,CAAC;AACvF,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACvF,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAc7F;;;;GAIG;AACH,qBAAa,YAAa,YAAW,aAAa;IAChD,OAAO,CAAC,gBAAgB,CAAmB;IAC3C,OAAO,CAAC,mBAAmB,CAAsB;IACjD,OAAO,CAAC,cAAc,CAAgB;IACtC,OAAO,CAAC,YAAY,CAAc;IAClC,OAAO,CAAC,eAAe,CAAiB;IACxC,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,cAAc,CAAgB;IACtC,OAAO,CAAC,iBAAiB,CAAmB;IAC5C,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,iBAAiB,CAAmB;IAC5C,OAAO,CAAC,oBAAoB,CAAsB;IAClD,OAAO,CAAC,mBAAmB,CAAU;gBAGnC,eAAe,EAAE,gBAAgB,EACjC,kBAAkB,EAAE,mBAAmB,EACvC,MAAM,CAAC,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE;QACR,kBAAkB,CAAC,EAAE,OAAO,CAAC;KAC9B;IA8BU,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IA2DvE,cAAc,CACzB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY,GAAG;QAAE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAC5E,OAAO,CAAC,UAAU,CAAC;IA2GT,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC;IAuB/B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;YAK1B,kBAAkB;CAiBjC"}