npm package: @seokaka/mcp-search
Description: Enhanced MCP Server for intelligent search with real-time data extraction, AI integration, and Vietnamese financial content support
Author: Seokaka
Latest version: 1.0.5

# MCP Search Server - Máy chủ Tìm kiếm Thông minh cho AI Agents

🤖 **MCP Search Server** - Máy chủ tìm kiếm thông minh theo chuẩn Model Context Protocol (MCP), cung cấp khả năng tìm kiếm real-time cho Claude Desktop và các AI agents khác.

## 🌟 Tính năng

- 🔍 **Tìm kiếm Real-time**: Nhiều công cụ tìm kiếm (DuckDuckGo, Brave, Tavily)
- 📰 **Tìm kiếm Tin tức**: Tin tức mới nhất theo thời gian thực
- 🕐 **Thông tin Thời gian**: Lấy thời gian chính xác theo múi giờ
- 🧠 **Memory Search**: Tìm kiếm trong lịch sử các cuộc tìm kiếm trước đó
- 🔌 **MCP Protocol**: Hoàn toàn tương thích với Claude Desktop
- 🌍 **Hỗ trợ Việt Nam**: Tìm kiếm và hiển thị kết quả tiếng Việt

## 📦 Cài đặt

### Cài đặt Global
```bash
npm install -g @seokaka/mcp-search
```

### Cài đặt Local
```bash
npm install @seokaka/mcp-search
```

## 🚀 Sử dụng với Claude Desktop

### 1. Cấu hình Claude Desktop

Thêm vào file `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mcp-search-server": {
      "command": "npx",
      "args": ["@seokaka/mcp-search"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}
```

Hoặc nếu cài đặt global:

```json
{
  "mcpServers": {
    "mcp-search-server": {
      "command": "mcp-search",
      "args": [],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}
```

### 2. Khởi động lại Claude Desktop

Sau khi cấu hình, khởi động lại Claude Desktop để tải MCP server.

### 3. Sử dụng trong Claude

Claude sẽ tự động nhận diện các tools sau:

- `search_web` - Tìm kiếm web thông thường
- `search_news` - Tìm kiếm tin tức mới nhất
- `get_time` - Lấy thời gian hiện tại
- `search_memory` - Tìm kiếm trong lịch sử

## 🛠️ MCP Tools

### `search_web`
Tìm kiếm thông tin trên web với nhiều công cụ tìm kiếm.

```json
{
  "query": "tin tức bitcoin hôm nay",
  "engine": "auto",
  "max_results": 5
}
```

**Parameters:**
- `query` (required): Câu truy vấn tìm kiếm
- `engine` (optional): Công cụ tìm kiếm (`auto`, `duckduckgo`, `brave`, `tavily`)
- `max_results` (optional): Số kết quả tối đa (1-10)

### `search_news`
Tìm kiếm tin tức mới nhất theo thời gian.

```json
{
  "query": "công nghệ AI",
  "timeframe": "24h",
  "region": "VN"
}
```

**Parameters:**
- `query` (required): Từ khóa tìm tin tức
- `timeframe` (optional): Khung thời gian (`1h`, `24h`, `7d`, `30d`)
- `region` (optional): Khu vực (`VN`, `US`, `global`)

### `get_time`
Lấy thời gian hiện tại theo múi giờ cụ thể.

```json
{
  "timezone": "UTC+7",
  "format": "both"
}
```

**Parameters:**
- `timezone` (optional): Múi giờ (`UTC+7`, `America/New_York`, `Asia/Ho_Chi_Minh`)
- `format` (optional): Định dạng (`iso`, `readable`, `both`)

### `search_memory`
Tìm kiếm trong lịch sử các tìm kiếm trước đó.

```json
{
  "query": "bitcoin",
  "limit": 5
}
```

**Parameters:**
- `query` (required): Từ khóa tìm kiếm trong memory
- `limit` (optional): Số kết quả tối đa (1-20)

## 💡 Ví dụ sử dụng

### Tìm kiếm thông tin
```javascript
// Claude sẽ tự động gọi:
{
  "tool": "search_web",
  "arguments": {
    "query": "giá vàng hôm nay Việt Nam",
    "max_results": 3
  }
}
```

### Tin tức mới nhất
```javascript
{
  "tool": "search_news",
  "arguments": {
    "query": "thời tiết Hà Nội",
    "timeframe": "1h",
    "region": "VN"
  }
}
```

### Kiểm tra thời gian
```javascript
{
  "tool": "get_time",
  "arguments": {
    "timezone": "Asia/Ho_Chi_Minh",
    "format": "readable"
  }
}
```

## ⚙️ Cấu hình nâng cao

### Environment Variables
```bash
# Brave Search API (2000 requests/tháng miễn phí)
export BRAVE_API_KEY="your-brave-api-key"

# Tavily API (100 requests/tháng miễn phí)
export TAVILY_API_KEY="your-tavily-api-key"

# Claude API (nếu muốn AI response nâng cao)
export CLAUDE_API_KEY="your-claude-api-key"
```

### File cấu hình
Tạo file `~/.mcp-search/config.json`:

```json
{
  "braveApiKey": "your-brave-api-key",
  "tavilyApiKey": "your-tavily-api-key",
  "claudeApiKey": "your-claude-api-key",
  "defaultEngine": "auto",
  "defaultTimezone": "UTC+7",
  "maxResults": 5,
  "enableMemory": true
}
```

## 🧪 Testing

### Test MCP Server
```bash
# Test server trực tiếp
npx @seokaka/mcp-search

# Test với tools
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "search_web", "arguments": {"query": "test"}}}' | npx @seokaka/mcp-search
```

### Test CLI mode
```bash
# Sử dụng CLI mode
npx @seokaka/mcp-search search "tin tức bitcoin"
npx @seokaka/mcp-search chat
```

## 🔧 Development

### Local Development
```bash
# Clone repository
git clone https://github.com/seokaka/mcp-search.git
cd mcp-search

# Install dependencies
npm install

# Chạy development mode
npm run dev

# Test
npm test
```

### Build MCP Server
```bash
npm run build:mcp
npm run mcp:server
```

## 📋 API Response Format

MCP server trả về kết quả theo format JSON:

```json
{
  "content": [
    {
      "type": "text",
      "text": "{\"query\":\"bitcoin\",\"results\":[{\"title\":\"...\",\"url\":\"...\",\"snippet\":\"...\"}],\"timestamp\":\"2024-01-01T00:00:00.000Z\"}"
    }
  ]
}
```

## 🌐 Tương thích

- ✅ Claude Desktop (macOS, Windows)
- ✅ Claude Web Interface
- ✅ Các MCP-compatible AI agents
- ✅ Custom implementations

## 🤝 Đóng góp

1. Fork repository
2. Tạo feature branch (`git checkout -b feature/tính-năng-mới`)
3. Commit changes (`git commit -m 'Thêm tính năng mới'`)
4. Push đến branch (`git push origin feature/tính-năng-mới`)
5. Open Pull Request

## 📄 License

MIT License - xem file [LICENSE](LICENSE) để biết chi tiết.

## 🆘 Hỗ trợ

- 🐛 [Báo lỗi](https://github.com/seokaka/mcp-search/issues)
- 💡 [Yêu cầu tính năng](https://github.com/seokaka/mcp-search/discussions)
- 📧 Email: contact@seokaka.com

## 🔗 Links

- [MCP Specification](https://modelcontextprotocol.io/)
- [Claude Desktop](https://claude.ai/download)
- [Brave Search API](https://brave.com/search/api/)
- [Tavily API](https://tavily.com/)

---

**Xây dựng với ❤️ theo chuẩn Model Context Protocol (MCP)**

Made with 🇻🇳 in Vietnam