open-index/open-npm huggingface dataset:
npm package: @ngao/search
Description: Search engine CLI and API with file watching
Author: Ngao Search Contributors
Latest version: 0.1.3

# Ngao Search - MCP Server

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

- 🔍 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 -g @ngao/search
```

Or use directly:

```bash
npx @ngao/search
```

### Pre-downloaded Models

Embedding models are **included with @ngao/search-core** dependency.

The core library contains pre-downloaded models - no additional downloads needed!

See the [Installation Guide](./docs/INSTALLATION.md) for details.

## Quick Start

### Setup

```bash
npx @ngao/search --setup
```

This will guide you through setting up a search index for your project.

### Search via CLI

```bash
npx @ngao/search search "function name"
```

### Start REST API Server

```bash
npx @ngao/search --server --port 3000
```

Then use the API:

```bash
curl http://localhost:3000/api/search?q=useState
```

### Start MCP Server

```bash
npx @ngao/search --mcp
```

## Configuration

Create a `config.json` file in your project root:

```json
{
  "projectRoot": "/path/to/project",
  "language": "typescript",
  "indexDirectory": ".ngao/index",
  "watchMode": true,
  "autoReindex": true
}
```

## Documentation

- [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)

## Architecture

This application is built on top of [`@ngao/search-core`](https://www.npmjs.com/package/@ngao/search-core), providing additional features:

- File watching (Chokidar)
- HTTP REST API (Express)
- MCP protocol transport
- CLI interface
- Session management

## License

Apache-2.0
npm package: @ngao/search-core
Description: Lightweight search engine library for code and documentation
Author: Ngao Search Contributors
Latest version: 1.0.1

# @ngao/search-core

Lightweight search engine library for indexing and searching code, documentation, and text.

## Features

- 🔍 Full-text search with ranking
- 🧠 Semantic search with embeddings
- 📝 Multi-language support (Python, JavaScript, TypeScript, Markdown, JSON, YAML)
- ⚡ Fast incremental indexing
- 💾 LanceDB vector database
- 📦 Zero external service dependencies

## Installation

```bash
npm install @ngao/search-core
```

## Pre-downloaded Models (Included)

**Important:** This library uses **pre-downloaded** local embedding models, NOT npm downloads.

The embedding models are **included in the package** at `models/` directory:

```
@ngao/search-core/
├── dist/
├── models/              ← Pre-downloaded models included here
│   └── Xenova/
│       └── all-MiniLM-L6-v2/
│           ├── config.json
│           ├── tokenizer.json
│           ├── tokenizer_config.json
│           └── onnx/
│               └── model_quantized.onnx
└── package.json
```

**For Development:**
```bash
# If models are missing, download them:
cd ngao-search-core
mkdir -p models/Xenova
git clone https://huggingface.co/Xenova/all-MiniLM-L6-v2 models/Xenova/all-MiniLM-L6-v2
```

The library automatically detects and uses these pre-downloaded models. Benefits:
- ✅ No npm download overhead - models bundled with package
- ✅ Works offline after installation
- ✅ Faster initialization (~50ms vs ~5s download)
- ✅ Self-contained library with all dependencies

## Quick Start

```typescript
import { SearchEngine } from '@ngao/search-core'

const engine = new SearchEngine()
await engine.indexDirectory('./src')
const results = await engine.search('useContext')

results.forEach(result => {
  console.log(`${result.filePath}:${result.location.startLine} - ${result.name}`)
})
```

## API Overview

### SearchEngine

The main interface for indexing and searching.

```typescript
interface ISearchEngine {
  indexDirectory(dirPath: string): Promise<IndexStats>
  indexFile(filePath: string): Promise<void>
  reindexFile(filePath: string): Promise<void>
  search(query: string): Promise<SearchResult[]>
  getIndexStats(): Promise<IndexStats>
}
```

### Types

- `Block` - A searchable code/documentation block
- `SearchResult` - A search hit with relevance score
- `Query` - Parsed search query
- `IndexStats` - Index statistics

## Documentation

- [API Documentation](./docs/API.md)
- [Architecture](./docs/ARCHITECTURE.md)
- [Integration Guide](./docs/INTEGRATION.md)
- [Examples](./docs/EXAMPLES.md)

## License

Apache-2.0