Metadata-Version: 2.4
Name: seekdb-mcp-server
Version: 0.0.4
Summary: A Model Context Protocol (MCP) server that enables interaction with seekdb database. This server allows AI assistants to perform vector operations, manage collections, execute SQL queries and leverage AI functions through a controlled interface, making database exploration and analysis safer and more structured.
License:                                  Apache License
                                   Version 2.0, January 2004
                                http://www.apache.org/licenses/
        
           TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
        
           1. Definitions.
        
              "License" shall mean the terms and conditions for use, reproduction,
              and distribution as defined by Sections 1 through 9 of this document.
        
              "Licensor" shall mean the copyright owner or entity authorized by
              the copyright owner that is granting the License.
        
              "Legal Entity" shall mean the union of the acting entity and all
              other entities that control, are controlled by, or are under common
              control with that entity. For the purposes of this definition,
              "control" means (i) the power, direct or indirect, to cause the
              direction or management of such entity, whether by contract or
              otherwise, or (ii) ownership of fifty percent (50%) or more of the
              outstanding shares, or (iii) beneficial ownership of such entity.
        
              "You" (or "Your") shall mean an individual or Legal Entity
              exercising permissions granted by this License.
        
              "Source" form shall mean the preferred form for making modifications,
              including but not limited to software source code, documentation
              source, and configuration files.
        
              "Object" form shall mean any form resulting from mechanical
              transformation or translation of a Source form, including but
              not limited to compiled object code, generated documentation,
              and conversions to other media types.
        
              "Work" shall mean the work of authorship, whether in Source or
              Object form, made available under the License, as indicated by a
              copyright notice that is included in or attached to the work
              (an example is provided in the Appendix below).
        
              "Derivative Works" shall mean any work, whether in Source or Object
              form, that is based on (or derived from) the Work and for which the
              editorial revisions, annotations, elaborations, or other modifications
              represent, as a whole, an original work of authorship. For the purposes
              of this License, Derivative Works shall not include works that remain
              separable from, or merely link (or bind by name) to the interfaces of,
              the Work and Derivative Works thereof.
        
              "Contribution" shall mean any work of authorship, including
              the original version of the Work and any modifications or additions
              to that Work or Derivative Works thereof, that is intentionally
              submitted to Licensor for inclusion in the Work by the copyright owner
              or by an individual or Legal Entity authorized to submit on behalf of
              the copyright owner. For the purposes of this definition, "submitted"
              means any form of electronic, verbal, or written communication sent
              to the Licensor or its representatives, including but not limited to
              communication on electronic mailing lists, source code control systems,
              and issue tracking systems that are managed by, or on behalf of, the
              Licensor for the purpose of discussing and improving the Work, but
              excluding communication that is conspicuously marked or otherwise
              designated in writing by the copyright owner as "Not a Contribution."
        
              "Contributor" shall mean Licensor and any individual or Legal Entity
              on behalf of whom a Contribution has been received by Licensor and
              subsequently incorporated within the Work.
        
           2. Grant of Copyright License. Subject to the terms and conditions of
              this License, each Contributor hereby grants to You a perpetual,
              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
              copyright license to reproduce, prepare Derivative Works of,
              publicly display, publicly perform, sublicense, and distribute the
              Work and such Derivative Works in Source or Object form.
        
           3. Grant of Patent License. Subject to the terms and conditions of
              this License, each Contributor hereby grants to You a perpetual,
              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
              (except as stated in this section) patent license to make, have made,
              use, offer to sell, sell, import, and otherwise transfer the Work,
              where such license applies only to those patent claims licensable
              by such Contributor that are necessarily infringed by their
              Contribution(s) alone or by combination of their Contribution(s)
              with the Work to which such Contribution(s) was submitted. If You
              institute patent litigation against any entity (including a
              cross-claim or counterclaim in a lawsuit) alleging that the Work
              or a Contribution incorporated within the Work constitutes direct
              or contributory patent infringement, then any patent licenses
              granted to You under this License for that Work shall terminate
              as of the date such litigation is filed.
        
           4. Redistribution. You may reproduce and distribute copies of the
              Work or Derivative Works thereof in any medium, with or without
              modifications, and in Source or Object form, provided that You
              meet the following conditions:
        
              (a) You must give any other recipients of the Work or
                  Derivative Works a copy of this License; and
        
              (b) You must cause any modified files to carry prominent notices
                  stating that You changed the files; and
        
              (c) You must retain, in the Source form of any Derivative Works
                  that You distribute, all copyright, patent, trademark, and
                  attribution notices from the Source form of the Work,
                  excluding those notices that do not pertain to any part of
                  the Derivative Works; and
        
              (d) If the Work includes a "NOTICE" text file as part of its
                  distribution, then any Derivative Works that You distribute must
                  include a readable copy of the attribution notices contained
                  within such NOTICE file, excluding those notices that do not
                  pertain to any part of the Derivative Works, in at least one
                  of the following places: within a NOTICE text file distributed
                  as part of the Derivative Works; within the Source form or
                  documentation, if provided along with the Derivative Works; or,
                  within a display generated by the Derivative Works, if and
                  wherever such third-party notices normally appear. The contents
                  of the NOTICE file are for informational purposes only and
                  do not modify the License. You may add Your own attribution
                  notices within Derivative Works that You distribute, alongside
                  or as an addendum to the NOTICE text from the Work, provided
                  that such additional attribution notices cannot be construed
                  as modifying the License.
        
              You may add Your own copyright statement to Your modifications and
              may provide additional or different license terms and conditions
              for use, reproduction, or distribution of Your modifications, or
              for any such Derivative Works as a whole, provided Your use,
              reproduction, and distribution of the Work otherwise complies with
              the conditions stated in this License.
        
           5. Submission of Contributions. Unless You explicitly state otherwise,
              any Contribution intentionally submitted for inclusion in the Work
              by You to the Licensor shall be under the terms and conditions of
              this License, without any additional terms or conditions.
              Notwithstanding the above, nothing herein shall supersede or modify
              the terms of any separate license agreement you may have executed
              with Licensor regarding such Contributions.
        
           6. Trademarks. This License does not grant permission to use the trade
              names, trademarks, service marks, or product names of the Licensor,
              except as required for reasonable and customary use in describing the
              origin of the Work and reproducing the content of the NOTICE file.
        
           7. Disclaimer of Warranty. Unless required by applicable law or
              agreed to in writing, Licensor provides the Work (and each
              Contributor provides its Contributions) on an "AS IS" BASIS,
              WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
              implied, including, without limitation, any warranties or conditions
              of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
              PARTICULAR PURPOSE. You are solely responsible for determining the
              appropriateness of using or redistributing the Work and assume any
              risks associated with Your exercise of permissions under this License.
        
           8. Limitation of Liability. In no event and under no legal theory,
              whether in tort (including negligence), contract, or otherwise,
              unless required by applicable law (such as deliberate and grossly
              negligent acts) or agreed to in writing, shall any Contributor be
              liable to You for damages, including any direct, indirect, special,
              incidental, or consequential damages of any character arising as a
              result of this License or out of the use or inability to use the
              Work (including but not limited to damages for loss of goodwill,
              work stoppage, computer failure or malfunction, or any and all
              other commercial damages or losses), even if such Contributor
              has been advised of the possibility of such damages.
        
           9. Accepting Warranty or Additional Liability. While redistributing
              the Work or Derivative Works thereof, You may choose to offer,
              and charge a fee for, acceptance of support, warranty, indemnity,
              or other liability obligations and/or rights consistent with this
              License. However, in accepting such obligations, You may act only
              on Your own behalf and on Your sole responsibility, not on behalf
              of any other Contributor, and only if You agree to indemnify,
              defend, and hold each Contributor harmless for any liability
              incurred by, or claims asserted against, such Contributor by reason
              of your accepting any such warranty or additional liability.
        
           END OF TERMS AND CONDITIONS
        
           APPENDIX: How to apply the Apache License to your work.
        
              To apply the Apache License to your work, attach the following
              boilerplate notice, with the fields enclosed by brackets "[]"
              replaced with your own identifying information. (Don't include
              the brackets!)  The text should be enclosed in the appropriate
              comment syntax for the file format. We also recommend that a
              file or class name and description of purpose be included on the
              same "printed page" as the copyright notice for easier
              identification within third-party archives.
        
           Copyright [yyyy] [name of copyright owner]
        
           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.
        
Keywords: seekdb,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.13.1
Requires-Dist: fastmcp>=2.12.0
Requires-Dist: mysql-connector-python>=9.1.0
Requires-Dist: SQLAlchemy>=2.0.32
Requires-Dist: beautifulsoup4>=4.13.5
Requires-Dist: pydantic>=2.11.7
Requires-Dist: python-dotenv>=1.1.1
Requires-Dist: certifi>=2022.12.7
Requires-Dist: pyseekdb>=1.0.0b2
Provides-Extra: dev
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Dynamic: license-file

English | [简体中文](README_CN.md)

# seekdb mcp server

A Model Context Protocol (MCP) server that enables interaction with seekdb database. This server allows AI assistants to perform vector operations, manage collections, execute SQL queries and leverage AI functions through a controlled interface, making database exploration and analysis safer and more structured.

## 📋 Table of Contents

- [Features](#-features)
- [Available Tools](#%EF%B8%8F-available-tools)
- [Prerequisites](#-prerequisites)
- [Installation](#-installation)
  - [Install uv](#install-uv-recommended)
  - [Install seekdb mcp server](#install-seekdb-mcp-server)
- [Configuration](#%EF%B8%8F-configuration)
- [Quickstart](#-quickstart)
  - [Stdio Mode](#stdio-mode)
  - [SSE Mode](#sse-mode)
  - [Streamable HTTP](#streamable-http)
- [Advanced Features](#-advanced-features)
  - [AI Memory System](#-ai-memory-system)
- [Examples](#-examples)
- [Security](#-security)
- [License](#-license)
- [Contributing](#-contributing)

## ✨ Features

- **Vector Collection Management**: Create, list, query, and manage vector collections
- **Advanced Search**: Full-text search, vector similarity search, and hybrid search
- **AI Functions**: Integrate with AI models for embedding, completion, and reranking
- **AI Memory System**: Persistent vector-based memory for AI assistants
- **Data Import/Export**: Import CSV files to seekdb and export data to CSV
- **SQL Operations**: Execute SQL queries on seekdb
- **Multi-Transport**: Support for stdio, SSE, and Streamable HTTP modes

## 🛠️ Available Tools

### Vector Collection Tools

| Tool | Description |
|------|-------------|
| `create_collection` | Create a new vector collection with configurable dimension and distance metric |
| `list_collections` | List all collections in seekdb |
| `has_collection` | Check if a collection exists |
| `peek_collection` | Preview documents in a collection |
| `add_data_to_collection` | Add documents with auto-generated embeddings |
| `update_collection` | Update existing documents in a collection |
| `delete_documents` | Delete documents by ID or filter conditions |
| `query_collection` | Query documents using vector similarity search |
| `delete_collection` | Delete a collection and all its data |

### Search Tools

| Tool | Description |
|------|-------------|
| `full_text_search` | Perform full-text search using MATCH...AGAINST syntax |
| `hybrid_search` | Combine full-text search and vector search with RRF ranking |

### AI Model Tools

| Tool | Description |
|------|-------------|
| `create_ai_model` | Register an AI model (embedding, completion, or rerank) |
| `create_ai_model_endpoint` | Create an endpoint connecting a model to an API service |
| `drop_ai_model` | Remove a registered AI model |
| `drop_ai_model_endpoint` | Remove an AI model endpoint |
| `ai_complete` | Call an LLM for text generation |
| `ai_rerank` | Rerank documents by relevance using an AI model |
| `get_registered_ai_models` | List all registered AI models |
| `get_ai_model_endpoints` | List all AI model endpoints |

### Memory Tools

| Tool | Description |
|------|-------------|
| `seekdb_memory_query` | Semantic search for stored memories |
| `seekdb_memory_insert` | Store new memories with metadata |
| `seekdb_memory_delete` | Delete memories by ID |
| `seekdb_memory_update` | Update existing memories |

### Data Import/Export Tools

| Tool | Description |
|------|-------------|
| `import_csv_file_to_seekdb` | Import CSV data as a table or vector collection |
| `export_csv_file_from_seekdb` | Export table or collection data to CSV |

### Database Tools

| Tool | Description |
|------|-------------|
| `execute_sql` | Execute SQL queries on seekdb |
| `get_current_time` | Get current time from seekdb database |


## 📋 Prerequisites

### seekdb Requirements

seekdb supports two deployment modes:

- **Embedded Mode**: seekdb runs as a library inside your application
  - Supported OS: Linux (glibc >= 2.28)
  - Supported Python: 3.11 to 3.13 (pyseekdb), CPython 3.8 to 3.14 (pylibseekdb)
  - Supported Architecture: x86_64, aarch64
  - Deployment: Deploy using the `pyseekdb` SDK

- **Client/Server Mode**: Connect to a deployed seekdb
  - Deploy using `yum install`
  - Deploy in a container environment
  - Deploy using [OceanBase Desktop](https://www.oceanbase.ai/docs/deploy-overview/) (GUI application)

For detailed deployment instructions, see the [seekdb Deployment Overview](https://www.oceanbase.ai/docs/deploy-overview/).

## 🚀 Installation

### Install uv (recommended)

[uv](https://docs.astral.sh/uv/) is an extremely fast Python package installer and resolver. The `uvx` command (included with uv) is used to run Python tools.

```bash
# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or install via pip
pip install uv
```

After installation, restart your terminal or run `source ~/.bashrc` (or equivalent) to ensure `uvx` is available.

### Install seekdb mcp server

Install from PyPI:

```bash
pip install seekdb-mcp-server
```

Or install from source:

```bash
git clone https://github.com/oceanbase/awesome-oceanbase-mcp.git
cd awesome-oceanbase-mcp/src/seekdb_mcp_server
pip install .
```

## ⚙️ Configuration

seekdb MCP Server supports two deployment modes:

### Embedded Mode (Default)

No configuration required. The server automatically initializes an embedded seekdb database when started. This mode is recommended for local development and personal use.

> **Note**: Embedded mode currently only supports Linux (glibc >= 2.28).

### Server Mode

To connect to a deployed seekdb server, configure the following environment variables:

**Method 1: Environment Variables**

```bash
SEEKDB_HOST=localhost      # Database host
SEEKDB_PORT=2881           # Database port (default: 2881)
SEEKDB_USER=your_username
SEEKDB_PASSWORD=your_password
SEEKDB_DATABASE=your_database
```

**Method 2: .env File**

Copy `.env.template` to `.env` and fill in the values:

```bash
cp .env.template .env
# Edit .env with your seekdb connection details
```

> **Note**: If `SEEKDB_USER` is not set, the server will automatically use embedded mode.

## 🚀 Quickstart

The seekdb MCP Server supports three transport modes:

### Stdio Mode

Add the following content to your MCP client configuration file:

**Embedded Mode (Using uvx):**

```json
{
  "mcpServers": {
    "seekdb": {
      "command": "uvx",
      "args": [
        "seekdb-mcp-server"
      ]
    }
  }
}
```

**Server Mode (Using uvx with env):**

```json
{
  "mcpServers": {
    "seekdb": {
      "command": "uvx",
      "args": [
        "seekdb-mcp-server"
      ],
      "env": {
        "SEEKDB_HOST": "your_host",
        "SEEKDB_PORT": "2881",
        "SEEKDB_USER": "your_username",
        "SEEKDB_PASSWORD": "your_password",
        "SEEKDB_DATABASE": "your_database"
      }
    }
  }
}
```

**Running from source:**

```json
{
  "mcpServers": {
    "seekdb": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/awesome-oceanbase-mcp/src/seekdb_mcp_server",
        "run",
        "seekdb-mcp-server"
      ]
    }
  }
}
```

### SSE Mode

Start the server in SSE mode:

**Step 1: Configure .env file in current directory**
```bash
# Create .env file with your seekdb connection details
cat > .env << EOF
SEEKDB_HOST=your_host
SEEKDB_PORT=2881
SEEKDB_USER=your_username
SEEKDB_PASSWORD=your_password
SEEKDB_DATABASE=your_database
EOF
```

**Step 2: Load environment variables**
```bash
source .env
```

**Step 3: Start the server**
```bash
uvx seekdb-mcp-server --transport sse --port 6000
```

**Parameters:**
- `--transport`: MCP server transport type (default: stdio)
- `--host`: Host to bind to (default: 127.0.0.1, use 0.0.0.0 for remote access)
- `--port`: Port to listen on (default: 6000)

**Alternative startup (from source):**
```bash
uv --directory path/to/seekdb_mcp_server run seekdb-mcp-server --transport sse --port 6000
```

**Configuration URL:** `http://ip:port/sse`

#### Client Configuration Examples

**VSCode Extension Cline:**
```json
"sse-seekdb": {
  "autoApprove": [],
  "disabled": false,
  "timeout": 60,
  "type": "sse",
  "url": "http://127.0.0.1:6000/sse"
}
```

**Cursor:**
```json
"sse-seekdb": {
  "autoApprove": [],
  "disabled": false,
  "timeout": 60,
  "type": "sse",
  "url": "http://127.0.0.1:6000/sse"
}
```

**Cherry Studio:**
- MCP → General → Type: Select "Server-Sent Events (sse)" from dropdown
- URL: `http://127.0.0.1:6000/sse`

### Streamable HTTP

Start the server in Streamable HTTP mode:

**Step 1: Configure .env file in current directory**
```bash
# Create .env file with your seekdb connection details
cat > .env << EOF
SEEKDB_HOST=your_host
SEEKDB_PORT=2881
SEEKDB_USER=your_username
SEEKDB_PASSWORD=your_password
SEEKDB_DATABASE=your_database
EOF
```

**Step 2: Load environment variables**
```bash
source .env
```

**Step 3: Start the server**
```bash
uvx seekdb-mcp-server --transport streamable-http --port 6000
```

**Parameters:**
- `--transport`: MCP server transport type (default: stdio)
- `--host`: Host to bind to (default: 127.0.0.1, use 0.0.0.0 for remote access)
- `--port`: Port to listen on (default: 6000)

**Alternative startup (from source):**
```bash
uv --directory path/to/seekdb_mcp_server run seekdb-mcp-server --transport streamable-http --port 6000
```

**Configuration URL:** `http://ip:port/mcp`

#### Client Configuration Examples

**VSCode Extension Cline:**
```json
"streamable-seekdb": {
  "autoApprove": [],
  "disabled": false,
  "timeout": 60,
  "type": "streamableHttp",
  "url": "http://127.0.0.1:6000/mcp"
}
```

**Cursor:**
```json
"streamable-seekdb": {
  "autoApprove": [],
  "disabled": false,
  "timeout": 60,
  "type": "streamableHttp",
  "url": "http://127.0.0.1:6000/mcp"
}
```

**Cherry Studio:**
- MCP → General → Type: Select "Streamable HTTP (streamableHttp)" from dropdown
- URL: `http://127.0.0.1:6000/mcp`

## 🔧 Advanced Features

### 🧠 AI Memory System

The AI Memory System enables your AI assistant to maintain persistent vector-based memory powered by seekdb's vector capabilities.

The memory system allows your AI to maintain continuous context across conversations, eliminating the need to repeat personal preferences and information. Four intelligent tools work together to create a seamless memory experience:

- **`seekdb_memory_query`** - Semantically search and retrieve contextual memories
- **`seekdb_memory_insert`** - Automatically capture and store important conversations
- **`seekdb_memory_delete`** - Remove outdated or unwanted memories
- **`seekdb_memory_update`** - Evolve memories with new information over time

#### Memory System Features

- ✅ **Cross-Session Continuity** - No need to reintroduce yourself
- ✅ **Intelligent Semantic Search** - Understands related concepts and context
- ✅ **Personalized Experience** - AI truly "knows" your preferences
- ✅ **Automatic Capture** - Important information saved without manual effort
- ✅ **Multilingual Support** - Store and query memories in any language

#### Memory Categories

The memory system intelligently organizes information by category:

- **Sports/Fitness**: football, basketball, swimming, gym, yoga, running, etc.
- **Food/Drinks**: coffee, tea, pizza, sushi, vegan preferences, etc.
- **Work/Career**: job, position, company, skills, projects, etc.
- **Personal**: birthday, hometown, family, languages, hobbies, etc.
- **Technology**: programming languages, frameworks, databases, tools, etc.
- **Entertainment**: movies, music, books, games, genres, etc.

## 📚 Examples

### Collection Operations

**User:** Create a Collection named "document"

**AI:** I've successfully created a collection named **"document"** in seekdb with the following default settings:
- **Dimension**: 384 (vector size)
- **Distance metric**: L2 (Euclidean distance)

---

**User:** Insert two sentences into the document: Machine learning is a subset of artificial intelligence, and vector databases enable semantic search

**AI:** Done! I've inserted two sentences into the **"document"** collection:

| ID | Document |
|------|----------|
| doc1 | Machine learning is a subset of artificial intelligence |
| doc2 | vector databases enable semantic search |

---

**User:** Query documents related to machine learning

**AI:** Here are the documents related to **"machine learning"**, ranked by relevance:

| Rank | ID | Document | Distance |
|------|------|----------|----------|
| 1 | doc1 | Machine learning is a subset of artificial intelligence | 5.44 |
| 2 | doc2 | vector databases enable semantic search | 7.83 |

---

**User:** Update the document about machine learning to "Python is a popular programming language."

**AI:** Done! I've updated the document:

| ID | Before | After |
|------|--------|-------|
| doc1 | Machine learning is a subset of artificial intelligence | Python is a popular programming language. |

---

**User:** Delete the document about vector database

**AI:** Done! I've deleted the document about vector databases:

| ID | Deleted Document |
|------|------------------|
| doc2 | vector databases enable semantic search |

---

**User:** Query all documents in the document

**AI:** Here are all the documents in the **"document"** collection:

| ID | Document | Metadata |
|------|----------|----------|
| doc1 | Python is a popular programming language. | {} |

The collection currently contains **1 document**.

---

**User:** Delete the collection document

**AI:** Done! The collection **"document"** has been permanently deleted along with all its data.

### Search Tools

**User:** Create a collection, hybrid_search_test

**AI:** Done! The collection `hybrid_search_test` has been created successfully with:
- **Dimension**: 384
- **Distance metric**: L2

---

**User:** Insert the following documents:
- "The weather forecast predicts sunny skies for the weekend."
- "Mount Everest is the highest mountain peak in the world."
- "Ocean waves crash against the rocky shoreline at sunset."
- "Apple is a delicious red fruit that grows on trees in orchards."
- "The new iPhone 17 Pro features an advanced camera system and titanium design."

**AI:** Done! Successfully added 5 documents to the `hybrid_search_test` collection:

| ID | Document |
|------|----------|
| doc1 | The weather forecast predicts sunny skies for the weekend. |
| doc2 | Mount Everest is the highest mountain peak in the world. |
| doc3 | Ocean waves crash against the rocky shoreline at sunset. |
| doc4 | Apple is a delicious red fruit that grows on trees in orchards. |
| doc5 | The new iPhone 17 Pro features an advanced camera system and titanium design. |

---

**User:** Perform a hybrid_search, full-text keyword "apple", semantic search "apple smartphone technology"

**AI:** Here are the hybrid search results combining full-text keyword **"apple"** and semantic query **"apple smartphone technology"**:

| Rank | ID | Document |
|------|------|----------|
| 1 | doc4 | Apple is a delicious red fruit that grows on trees in orchards. |
| 2 | doc5 | The new iPhone 17 Pro features an advanced camera system and titanium design. |
| 3 | doc2 | Mount Everest is the highest mountain peak in the world. |
| 4 | doc1 | The weather forecast predicts sunny skies for the weekend. |
| 5 | doc3 | Ocean waves crash against the rocky shoreline at sunset. |

**Analysis:**
- **doc4** ranks first due to the strong full-text match with the literal word "Apple"
- **doc5** ranks second because it matches semantically with "smartphone technology" (iPhone is an Apple smartphone), even though it doesn't contain the word "apple" explicitly
- The remaining documents have lower relevance scores as they don't match either search criterion well

The hybrid search successfully combined keyword matching (BM25) with semantic similarity (vector search) using Reciprocal Rank Fusion (RRF) to produce these ranked results.

---

## 🔒 Security

This MCP server uses embedded seekdb by default, which runs locally within your application.

### Security Best Practices

1. **Local Data Storage**: Embedded seekdb stores data locally, ensuring data privacy
2. **Network Security**: When using SSE or Streamable HTTP modes, ensure proper network security measures
3. **File Permissions**: Ensure proper file permissions for the data directory

### Security Checklist

- ✅ Data stays local with embedded mode
- ✅ No credentials required for embedded mode
- ✅ Stdio mode: No network ports exposed
- ✅ SSE/HTTP modes: Use `--host 127.0.0.1` to restrict access to localhost only
- ✅ Standard file system security applies

## 📄 License

Apache License - see [LICENSE](LICENSE) file for details.

## 🤝 Contributing

We welcome contributions! Please follow these steps:

1. **Fork the repository**
2. **Create your feature branch**
   ```bash
   git checkout -b feature/amazing-feature
   ```
3. **Commit your changes**
   ```bash
   git commit -m 'Add some amazing feature'
   ```
4. **Push to the branch**
   ```bash
   git push origin feature/amazing-feature
   ```
5. **Open a Pull Request**
