This is page 1 of 2. Use http://codebase.md/ryanlisse/lancedb_mcp?page={x} to view the full context.
# Directory Structure
```
├── .github
│ └── workflows
│ └── ci.yml
├── .gitignore
├── .lancedb
│ ├── dim_test.lance
│ │ ├── _latest.manifest
│ │ ├── _transactions
│ │ │ ├── 0-f3508686-181e-45aa-b39d-000929d849c5.txn
│ │ │ ├── 1-aface4fb-500d-40c3-9496-6a3ff1a8ac1d.txn
│ │ │ └── 2-a1f2063a-db31-4501-ae90-56991c9d7506.txn
│ │ └── _versions
│ │ ├── 1.manifest
│ │ ├── 2.manifest
│ │ └── 3.manifest
│ ├── search_test.lance
│ │ ├── _latest.manifest
│ │ ├── _transactions
│ │ │ ├── 0-698ac5c4-92e7-43b0-8fc4-6a5e8e1006b2.txn
│ │ │ ├── 1-8fb28042-5699-422f-9beb-269e6a8e6f3e.txn
│ │ │ ├── 2-3dec6144-c710-49eb-bf2e-7d3472e4c3db.txn
│ │ │ ├── 3-e5b08f50-ad75-46bb-bf0f-af10dafde959.txn
│ │ │ └── 4-599bd20d-672b-4f69-97cc-cef1236d6493.txn
│ │ ├── _versions
│ │ │ ├── 1.manifest
│ │ │ ├── 2.manifest
│ │ │ ├── 3.manifest
│ │ │ ├── 4.manifest
│ │ │ └── 5.manifest
│ │ └── data
│ │ ├── 71245ad6-85fc-4640-9d9d-38214632f03c.lance
│ │ └── f2e8d034-8ca4-403e-a671-1bf7de45b45e.lance
│ ├── test_table.lance
│ │ ├── _latest.manifest
│ │ ├── _transactions
│ │ │ ├── 0-91e1cdeb-cba2-40a8-a013-61e515342975.txn
│ │ │ ├── 1-db0889c2-1d58-47fc-a416-84e4a042454b.txn
│ │ │ └── 2-b1b74a44-533c-49f1-974c-48e0e1c1bbe3.txn
│ │ └── _versions
│ │ ├── 1.manifest
│ │ ├── 2.manifest
│ │ └── 3.manifest
│ └── vector_test.lance
│ ├── _latest.manifest
│ ├── _transactions
│ │ ├── 0-b210021a-3d03-4f2a-8e88-6ebf232e6709.txn
│ │ ├── 1-d48e6418-0b57-417f-b35e-04eabc06b369.txn
│ │ ├── 2-a9e1023e-bc4c-4da5-a13d-3527de361c69.txn
│ │ ├── 3-062d3713-270d-496b-86a4-5e37b63005c9.txn
│ │ └── 4-194c662a-ef52-4fd0-8ad2-60d66ed0cd8c.txn
│ ├── _versions
│ │ ├── 1.manifest
│ │ ├── 2.manifest
│ │ ├── 3.manifest
│ │ ├── 4.manifest
│ │ └── 5.manifest
│ └── data
│ ├── 92356c76-e316-46e6-845e-37d31473249c.lance
│ └── 97d8fb8c-42f5-4b58-b6d2-1f5dd3a4d7bd.lance
├── .pre-commit-config.yaml
├── .python-version
├── data
│ └── vectors
│ └── _init.lance
│ ├── _latest.manifest
│ ├── _transactions
│ │ ├── 0-5257a8a5-ed96-4110-9783-dda859af0d5b.txn
│ │ ├── 1-5eaa29c5-2a59-48d1-b5b5-e889ae94869f.txn
│ │ ├── 2-5c8a729e-bb61-4848-968d-506da61525b8.txn
│ │ └── 3-9cdffa49-59b3-4b10-b95c-d602b61f5cd3.txn
│ ├── _versions
│ │ ├── 1.manifest
│ │ ├── 2.manifest
│ │ ├── 3.manifest
│ │ └── 4.manifest
│ └── data
│ ├── 0bab45fe-c66d-46a2-a4de-3cddff00acc0.lance
│ └── 5c28a99d-55d3-4919-9396-d2623e506098.lance
├── DOCS
│ ├── lancedb_docs.md
│ ├── lancedb_mcp_api.md
│ ├── mcp_docs.md
│ ├── mcp_python_sdk.md
│ └── mcs_spec_docs.md
├── pyproject.toml
├── README.md
├── requirements-dev.txt
├── requirements.txt
├── src
│ └── lancedb_mcp
│ ├── __init__.py
│ ├── models.py
│ └── server.py
├── tests
│ ├── conftest.py
│ ├── test_init.py
│ └── test_server.py
└── uv.lock
```
# Files
--------------------------------------------------------------------------------
/.python-version:
--------------------------------------------------------------------------------
```
3.12
```
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
*.egg-info/
.installed.cfg
*.egg
# Virtual Environment
.env
.venv
env/
venv/
ENV/
# IDE
.idea/
.vscode/
*.swp
*.swo
# Testing
.coverage
coverage.xml
.pytest_cache/
htmlcov/
# Misc
.DS_Store
*.log
```
--------------------------------------------------------------------------------
/.pre-commit-config.yaml:
--------------------------------------------------------------------------------
```yaml
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.5.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-yaml
- id: check-added-large-files
- repo: https://github.com/psf/black
rev: 23.12.0
hooks:
- id: black
language_version: python3.12
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.1.8
hooks:
- id: ruff
args: [--fix, --exit-non-zero-on-fix]
- id: ruff-format
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
# LanceDB MCP Server
## Overview
A Model Context Protocol (MCP) server implementation for LanceDB vector database operations. This server enables efficient vector storage, similarity search, and management of vector embeddings with associated metadata.
## Components
### Resources
The server exposes vector database tables as resources:
- `table://{name}`: A vector database table that stores embeddings and metadata
- Configurable vector dimensions
- Text metadata support
- Efficient similarity search capabilities
### API Endpoints
#### Table Management
- `POST /table`
- Create a new vector table
- Input:
```python
{
"name": "my_table", # Table name
"dimension": 768 # Vector dimension
}
```
#### Vector Operations
- `POST /table/{table_name}/vector`
- Add vector data to a table
- Input:
```python
{
"vector": [0.1, 0.2, ...], # Vector data
"text": "associated text" # Metadata
}
```
- `POST /table/{table_name}/search`
- Search for similar vectors
- Input:
```python
{
"vector": [0.1, 0.2, ...], # Query vector
"limit": 10 # Number of results
}
```
## Installation
```bash
# Clone the repository
git clone https://github.com/yourusername/lancedb_mcp.git
cd lancedb_mcp
# Install dependencies using uv
uv pip install -e .
```
## Usage with Claude Desktop
```bash
# Add the server to your claude_desktop_config.json
"mcpServers": {
"lancedb": {
"command": "uv",
"args": [
"run",
"python",
"-m",
"lancedb_mcp",
"--db-path",
"~/.lancedb"
]
}
}
```
## Development
```bash
# Install development dependencies
uv pip install -e ".[dev]"
# Run tests
pytest
# Format code
black .
ruff .
```
## Environment Variables
- `LANCEDB_URI`: Path to LanceDB storage (default: ".lancedb")
## License
This project is licensed under the MIT License. See the LICENSE file for details.
```
--------------------------------------------------------------------------------
/requirements-dev.txt:
--------------------------------------------------------------------------------
```
pytest>=7.4.3
pytest-asyncio>=0.23.2
pytest-cov>=4.1.0
httpx>=0.25.2
```
--------------------------------------------------------------------------------
/requirements.txt:
--------------------------------------------------------------------------------
```
fastapi>=0.104.1
lancedb>=0.4.0
open-clip-torch>=2.20.0
pillow>=10.1.0
pydantic>=2.5.2
uvicorn>=0.24.0
```
--------------------------------------------------------------------------------
/tests/conftest.py:
--------------------------------------------------------------------------------
```python
"""Test configuration."""
import os
# Set environment variables for testing
os.environ["LANCEDB_URI"] = ".lancedb"
# Configure pytest for async tests
pytest_plugins = ["pytest_asyncio"]
```
--------------------------------------------------------------------------------
/src/lancedb_mcp/__init__.py:
--------------------------------------------------------------------------------
```python
"""LanceDB MCP Server."""
from lancedb_mcp.models import SearchQuery, TableConfig, VectorData
from lancedb_mcp.server import set_db_uri
__version__ = "0.1.0"
__all__ = [
"SearchQuery",
"TableConfig",
"VectorData",
"set_db_uri",
]
```
--------------------------------------------------------------------------------
/tests/test_init.py:
--------------------------------------------------------------------------------
```python
"""Tests for __init__.py functionality."""
from lancedb_mcp import TableConfig, __version__
def test_config():
"""Test TableConfig model."""
config = TableConfig(name="test_table")
assert config.name == "test_table"
assert isinstance(config.dimension, int)
def test_version():
"""Test version getter."""
assert __version__ == "0.1.0"
```
--------------------------------------------------------------------------------
/src/lancedb_mcp/models.py:
--------------------------------------------------------------------------------
```python
"""Models for LanceDB MCP."""
from lancedb.pydantic import LanceModel, Vector
from pydantic import Field
class TableConfig(LanceModel):
"""Configuration for creating a table."""
name: str = Field(..., min_length=1, description="Name of the table")
dimension: int = Field(default=512, gt=0, description="Vector dimension")
metric: str = Field(default="cosine", description="Distance metric")
class VectorData(LanceModel):
"""Vector data with text and optional URI."""
vector: Vector = Field(..., dim=512, description="Vector data")
text: str = Field(default="", description="Text description")
uri: str | None = Field(default=None, description="Optional URI")
class SearchQuery(LanceModel):
"""Search query for finding similar vectors."""
vector: Vector = Field(..., dim=512, description="Query vector")
limit: int = Field(default=10, gt=0, description="Maximum number of results")
```
--------------------------------------------------------------------------------
/pyproject.toml:
--------------------------------------------------------------------------------
```toml
[project]
name = "lancedb-mcp"
version = "0.1.0"
description = "LanceDB MCP Server for vector database operations"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
"lancedb>=0.12.0",
"pydantic>=2.0",
"mcp>=1.1.2",
"numpy>=1.24.0",
"fastapi>=0.100.0",
"uvicorn>=0.22.0",
"tomlkit>=0.12.0"
]
authors = [
{ name = "RyanLisse", email = "[email protected]" }
]
[project.optional-dependencies]
dev = [
"pytest>=7.4.0",
"pytest-cov>=4.1.0",
"pytest-asyncio>=0.21.0",
"black>=23.12.0",
"ruff>=0.1.8",
]
[project.scripts]
lancedb-mcp = "lancedb_mcp.__main__:main"
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[tool.black]
line-length = 88
target-version = ["py312"]
[tool.ruff]
line-length = 88
target-version = "py312"
select = [
"E", # pycodestyle errors
"W", # pycodestyle warnings
"F", # pyflakes
"I", # isort
"D", # pydocstyle
"UP", # pyupgrade
"N", # pep8-naming
"B", # flake8-bugbear
]
ignore = [
"D203", # one-blank-line-before-class
"D213", # multi-line-summary-second-line
]
[tool.ruff.per-file-ignores]
"tests/*" = ["D"] # Ignore docstring rules in tests
[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
asyncio_mode = "auto"
addopts = "--cov=src --cov-report=term-missing"
```
--------------------------------------------------------------------------------
/.github/workflows/ci.yml:
--------------------------------------------------------------------------------
```yaml
name: CI/CD Pipeline
on:
push:
branches: [ main ]
paths-ignore:
- '**.md'
- 'docs/**'
- '.gitignore'
pull_request:
branches: [ main ]
paths-ignore:
- '**.md'
- 'docs/**'
- '.gitignore'
jobs:
test:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
python-version: ["3.9", "3.10", "3.11", "3.12"]
steps:
- uses: actions/checkout@v4
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v4
with:
python-version: ${{ matrix.python-version }}
cache: 'pip'
- name: Cache dependencies
uses: actions/cache@v3
with:
path: |
~/.cache/pip
~/.cache/pre-commit
key: ${{ runner.os }}-py${{ matrix.python-version }}-${{ hashFiles('pyproject.toml') }}-${{ hashFiles('.pre-commit-config.yaml') }}
restore-keys: |
${{ runner.os }}-py${{ matrix.python-version }}-
${{ runner.os }}-
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install uv
uv pip install -e ".[dev]"
pip install pytest-cov pytest-xdist
- name: Lint and format check
run: |
black . --check
ruff check .
mypy .
- name: Run tests
run: |
pytest -n auto --cov=lancedb_mcp --cov-report=xml -v tests/
- name: Upload coverage
uses: codecov/codecov-action@v3
with:
file: ./coverage.xml
fail_ci_if_error: true
build:
needs: test
runs-on: ubuntu-latest
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: "3.12"
- name: Install build dependencies
run: |
python -m pip install --upgrade pip
pip install build twine
- name: Build package
run: python -m build
- name: Check package
run: twine check dist/*
```
--------------------------------------------------------------------------------
/tests/test_server.py:
--------------------------------------------------------------------------------
```python
"""Test server functionality."""
import os
import tempfile
import numpy as np
import pytest
from lancedb_mcp.models import SearchQuery, TableConfig, VectorData
from lancedb_mcp.server import set_db_uri
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
@pytest.fixture
async def client():
"""Create a test client."""
# Create a temporary directory for the test database
temp_dir = tempfile.mkdtemp()
test_db = os.path.join(temp_dir, "test.lance")
set_db_uri(test_db)
# Create server parameters
server_params = StdioServerParameters(
command="python",
args=["-m", "lancedb_mcp.server"],
env={"LANCEDB_URI": test_db},
)
# Create client session
read, write = await stdio_client(server_params).__aenter__()
session = await ClientSession(read, write).__aenter__()
await session.initialize()
yield session
# Cleanup
await session.__aexit__(None, None, None)
await stdio_client(server_params).__aexit__(None, None, None)
os.rmdir(temp_dir)
@pytest.mark.asyncio
async def test_create_table(client):
"""Test creating a table."""
config = TableConfig(name="test_table", dimension=512)
tools = await client.list_tools()
assert len(tools) == 3
result = await client.call_tool("create_table", {"config": config.model_dump()})
assert "Table created successfully" in result[0].text
@pytest.mark.asyncio
async def test_add_vector(client):
"""Test adding a vector."""
# Create table first
config = TableConfig(name="test_table", dimension=512)
await client.call_tool("create_table", {"config": config.model_dump()})
# Add test vector
vector = np.random.rand(512).tolist()
data = VectorData(vector=vector, text="test vector")
result = await client.call_tool(
"add_vector", {"table_name": "test_table", "data": data.model_dump()}
)
assert "Added vector to table test_table" in result[0].text
@pytest.mark.asyncio
async def test_search_vectors(client):
"""Test searching vectors."""
# Create table and add vector
config = TableConfig(name="test_table", dimension=512)
await client.call_tool("create_table", {"config": config.model_dump()})
# Add test vector
vector = np.random.rand(512).tolist()
data = VectorData(vector=vector, text="test vector")
await client.call_tool(
"add_vector", {"table_name": "test_table", "data": data.model_dump()}
)
# Test search
query = SearchQuery(vector=vector, limit=5)
result = await client.call_tool(
"search_vectors", {"table_name": "test_table", "query": query.model_dump()}
)
assert "test vector" in result[0].text
```
--------------------------------------------------------------------------------
/src/lancedb_mcp/server.py:
--------------------------------------------------------------------------------
```python
"""LanceDB MCP server."""
import logging
import os
import pathlib
from typing import Any
import lancedb
import mcp.server.stdio
import mcp.types as types
import pandas as pd
from lancedb.pydantic import pydantic_to_schema
from mcp.server import NotificationOptions, Server
from mcp.server.models import InitializationOptions
from lancedb_mcp.models import SearchQuery, TableConfig, VectorData
# Configure logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
# Global database URI
DB_URI = os.getenv("LANCEDB_URI", ".lancedb")
def set_db_uri(uri: str) -> None:
"""Set the database URI."""
global DB_URI
DB_URI = uri
def get_db() -> lancedb.DBConnection:
"""Get database connection."""
logger.info(f"Connecting to database at {DB_URI}")
try:
pathlib.Path(DB_URI).parent.mkdir(parents=True, exist_ok=True)
return lancedb.connect(DB_URI)
except Exception as err:
logger.error(f"Failed to connect to database: {err}")
raise err
# Create MCP server instance
server = Server("lancedb-server")
@server.list_tools()
async def handle_list_tools() -> list[types.Tool]:
"""List available tools."""
return [
types.Tool(
name="create_table",
description="Create a new table",
arguments=[
types.ToolArgument(
name="config",
description="Table configuration",
schema=TableConfig.model_json_schema(),
)
],
),
types.Tool(
name="add_vector",
description="Add a vector to a table",
arguments=[
types.ToolArgument(
name="table_name", description="Name of the table", type="string"
),
types.ToolArgument(
name="data",
description="Vector data",
schema=VectorData.model_json_schema(),
),
],
),
types.Tool(
name="search_vectors",
description="Search vectors in a table",
arguments=[
types.ToolArgument(
name="table_name", description="Name of the table", type="string"
),
types.ToolArgument(
name="query",
description="Search query",
schema=SearchQuery.model_json_schema(),
),
],
),
]
@server.call_tool()
async def handle_call_tool(
name: str, arguments: dict[str, Any]
) -> list[types.TextContent]:
"""Handle tool calls."""
try:
db = get_db()
if name == "create_table":
config = TableConfig.model_validate(arguments["config"])
schema = pydantic_to_schema(VectorData)
db.create_table(
name=config.name,
schema=schema,
mode="overwrite",
)
logger.info(f"Created table {config.name}")
return [types.TextContent(type="text", text="Table created successfully")]
elif name == "add_vector":
table_name = arguments["table_name"]
data = VectorData.model_validate(arguments["data"])
table = db.open_table(table_name)
df = pd.DataFrame([data.model_dump()])
table.add(df)
logger.info(f"Added vector to table {table_name}")
return [
types.TextContent(
type="text", text=f"Added vector to table {table_name}"
)
]
elif name == "search_vectors":
table_name = arguments["table_name"]
query = SearchQuery.model_validate(arguments["query"])
table = db.open_table(table_name)
results = table.search(query.vector).limit(query.limit).to_pandas()
logger.info(f"Searched table {table_name}")
results_dict = results.to_dict(orient="records")
# Convert numpy arrays to lists for JSON serialization
for result in results_dict:
if "_distance" in result:
result["score"] = float(result["_distance"])
del result["_distance"]
if "vector" in result:
result["vector"] = result["vector"].tolist()
return [types.TextContent(type="text", text=str(results_dict))]
else:
raise ValueError(f"Unknown tool: {name}")
except FileNotFoundError:
logger.error(f"Table {arguments.get('table_name')} not found")
raise
except Exception as err:
logger.error(f"Failed to execute tool {name}: {err}")
raise
async def run():
"""Run the server."""
async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
await server.run(
read_stream,
write_stream,
InitializationOptions(
server_name="lancedb-server",
server_version="0.1.0",
capabilities=server.get_capabilities(
notification_options=NotificationOptions(),
experimental_capabilities={},
),
),
)
if __name__ == "__main__":
import asyncio
asyncio.run(run())
```
--------------------------------------------------------------------------------
/DOCS/lancedb_mcp_api.md:
--------------------------------------------------------------------------------
```markdown
# LanceDB MCP Server API Reference
## Overview
The LanceDB MCP Server implements the Model Control Protocol (MCP) specification, providing a standardized interface for vector database operations through LanceDB. This server enables vector operations including table creation, vector addition, and similarity search while adhering to MCP's principles of user consent, resource isolation, and secure data handling.
## Server Implementation
### Core Components
#### Database Connection
- Managed through LanceDB's Python client
- Supports both local and cloud storage backends
- Handles connection lifecycle and resource management
#### Table Management
- Creates and manages vector tables
- Maintains table references and state
- Handles table cleanup and optimization
#### Vector Operations
- Adds vectors with metadata
- Performs similarity search with configurable metrics
- Supports vector validation and dimension checking
#### Resource Management
- Tracks available tables and their states
- Implements MCP resource isolation
- Manages resource lifecycle
### MCP Protocol Implementation
#### Server Features
The server implements all required MCP features:
1. **Resources**
- Vector tables as queryable resources
- Resource isolation per connection
- Resource state tracking
2. **Tools**
- Table creation and management
- Vector addition and search
- Resource listing and status
3. **Capabilities**
- Dynamic reporting of supported operations
- Vector operation configurations
- Resource management features
### API Reference
#### Server Methods
##### Lifecycle Management
```python
async def start(self):
"""Start the LanceDB server"""
# Creates database directory
# Establishes connection
# Initializes state tracking
```
```python
async def stop(self):
"""Stop the LanceDB server"""
# Cleans up resources
# Closes connections
# Performs garbage collection
```
##### Table Operations
```python
async def create_table(self, table_name: str, dimension: int) -> Dict[str, str]:
"""Create a new vector table"""
# Creates table with specified dimension
# Returns table metadata
```
```python
async def add_vector(self, table_name: str, vector: List[float], metadata: Optional[Dict] = None):
"""Add vector to table"""
# Validates vector dimensions
# Adds vector with optional metadata
```
```python
async def search_vectors(self, table_name: str, query_vector: List[float], limit: int = 10):
"""Search for similar vectors"""
# Performs similarity search
# Returns top-k results with scores
```
##### Resource Management
```python
async def list_resources(self) -> List[Resource]:
"""List available tables"""
# Returns list of available tables
# Includes table metadata
```
```python
async def get_implementation(self) -> Implementation:
"""Get server implementation details"""
# Returns server name, version, vendor
```
```python
async def get_capabilities(self) -> ServerCapabilities:
"""Get server capabilities"""
# Returns supported operations
# Includes tool configurations
```
### Error Types
- `DatabaseError`: General database operation failures
```python
class DatabaseError(Exception):
"""Raised when database operations fail"""
```
- `TableError`: Table-specific operation failures
```python
class TableError(Exception):
"""Raised for table operation failures"""
```
- `VectorError`: Vector operation failures
```python
class VectorError(Exception):
"""Raised for vector operation failures"""
```
### Configuration
#### Database URI
```python
server = LanceDBServer(
db_uri="data/vectors", # Database location
read_consistency_interval=None # Consistency check interval
)
```
#### Vector Operations
```python
# Vector dimension validation
vector_dim = 768 # Must match table dimension
vector = [0.1] * vector_dim
# Adding vectors with metadata
metadata = {
"id": "doc1",
"text": "Sample document",
"timestamp": "2024-01-01"
}
# Search configuration
limit = 10 # Number of results
metric = "L2" # Distance metric
```
### Best Practices
1. **Resource Management**
- Clean up resources when no longer needed
- Monitor table sizes and vector counts
- Implement proper logging
2. **Vector Operations**
- Validate vector dimensions before adding
- Use appropriate metadata for tracking
- Handle errors appropriately
3. **Performance Optimization**
- Create indices for frequently searched tables
- Use appropriate batch sizes for operations
- Monitor and optimize resource usage
### Error Handling
The server implements comprehensive error handling:
1. **Database Errors**
- Connection failures
- Resource allocation issues
- Storage backend errors
2. **Table Errors**
- Creation failures
- Access permission issues
- Resource conflicts
3. **Vector Errors**
- Dimension mismatches
- Invalid data types
- Search operation failures
### Logging and Monitoring
The server includes built-in logging for:
- Operation status and errors
- Resource usage and performance
- Security-related events
### Security Considerations
1. **Resource Isolation**
- Tables are isolated per connection
- Resource access requires explicit consent
- State is maintained per session
2. **Data Validation**
- Input validation for all operations
- Secure handling of metadata
- Protection against invalid operations
3. **Error Handling**
- Secure error messages
- No sensitive data in logs
- Proper cleanup on failures
## Testing
The server includes comprehensive tests:
1. **Unit Tests**
- Core functionality
- Error handling
- Edge cases
2. **Integration Tests**
- End-to-end workflows
- Resource management
- Performance benchmarks
3. **Stress Tests**
- Concurrent operations
- Resource limits
- Error recovery
## Contributing
1. **Development Setup**
- Fork repository
- Install dependencies
- Set up development environment
2. **Making Changes**
- Create feature branch
- Follow coding standards
- Add tests for new features
3. **Submitting Changes**
- Create pull request
- Pass all tests
- Update documentation
## License
This project is licensed under the MIT License.
```
--------------------------------------------------------------------------------
/DOCS/mcp_python_sdk.md:
--------------------------------------------------------------------------------
```markdown
# MCP Python SDK
[![PyPI][pypi-badge]][pypi-url]
[![MIT licensed][mit-badge]][mit-url]
[![Python Version][python-badge]][python-url]
[![Documentation][docs-badge]][docs-url]
[![Specification][spec-badge]][spec-url]
[![GitHub Discussions][discussions-badge]][discussions-url]
[pypi-badge]: https://img.shields.io/pypi/v/mcp.svg
[pypi-url]: https://pypi.org/project/mcp/
[mit-badge]: https://img.shields.io/pypi/l/mcp.svg
[mit-url]: https://github.com/modelcontextprotocol/python-sdk/blob/main/LICENSE
[python-badge]: https://img.shields.io/pypi/pyversions/mcp.svg
[python-url]: https://www.python.org/downloads/
[docs-badge]: https://img.shields.io/badge/docs-modelcontextprotocol.io-blue.svg
[docs-url]: https://modelcontextprotocol.io
[spec-badge]: https://img.shields.io/badge/spec-spec.modelcontextprotocol.io-blue.svg
[spec-url]: https://spec.modelcontextprotocol.io
[discussions-badge]: https://img.shields.io/github/discussions/modelcontextprotocol/python-sdk
[discussions-url]: https://github.com/modelcontextprotocol/python-sdk/discussions
Python implementation of the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), providing both client and server capabilities for integrating with LLM surfaces.
## Overview
The Model Context Protocol allows applications to provide context for LLMs in a standardized way, separating the concerns of providing context from the actual LLM interaction. This Python SDK implements the full MCP specification, making it easy to:
- Build MCP clients that can connect to any MCP server
- Create MCP servers that expose resources, prompts and tools
- Use standard transports like stdio and SSE
- Handle all MCP protocol messages and lifecycle events
## Installation
We recommend the use of [uv](https://docs.astral.sh/uv/) to manage your Python projects:
```bash
uv add mcp
```
Alternatively, add mcp to your `requirements.txt`:
```
pip install mcp
# or add to requirements.txt
pip install -r requirements.txt
```
## Overview
MCP servers provide focused functionality like resources, tools, prompts, and other capabilities that can be reused across many client applications. These servers are designed to be easy to build, highly composable, and modular.
### Key design principles
- Servers are extremely easy to build with clear, simple interfaces
- Multiple servers can be composed seamlessly through a shared protocol
- Each server operates in isolation and cannot access conversation context
- Features can be added progressively through capability negotiation
### Server provided primitives
- [Prompts](https://modelcontextprotocol.io/docs/concepts/prompts): Templatable text
- [Resources](https://modelcontextprotocol.io/docs/concepts/resources): File-like attachments
- [Tools](https://modelcontextprotocol.io/docs/concepts/tools): Functions that models can call
- Utilities:
- Completion: Auto-completion provider for prompt arguments or resource URI templates
- Logging: Logging to the client
- Pagination*: Pagination for long results
### Client provided primitives
- [Sampling](https://modelcontextprotocol.io/docs/concepts/sampling): Allow servers to sample using client models
- Roots: Information about locations to operate on (e.g., directories)
Connections between clients and servers are established through transports like **stdio** or **SSE** (Note that most clients support stdio, but not SSE at the moment). The transport layer handles message framing, delivery, and error handling.
## Quick Start
### Creating a Server
MCP servers follow a decorator approach to register handlers for MCP primitives like resources, prompts, and tools. The goal is to provide a simple interface for exposing capabilities to LLM clients.
**example_server.py**
```python
# /// script
# dependencies = [
# "mcp"
# ]
# ///
from mcp.server import Server, NotificationOptions
from mcp.server.models import InitializationOptions
import mcp.server.stdio
import mcp.types as types
# Create a server instance
server = Server("example-server")
# Add prompt capabilities
@server.list_prompts()
async def handle_list_prompts() -> list[types.Prompt]:
return [
types.Prompt(
name="example-prompt",
description="An example prompt template",
arguments=[
types.PromptArgument(
name="arg1",
description="Example argument",
required=True
)
]
)
]
@server.get_prompt()
async def handle_get_prompt(
name: str,
arguments: dict[str, str] | None
) -> types.GetPromptResult:
if name != "example-prompt":
raise ValueError(f"Unknown prompt: {name}")
return types.GetPromptResult(
description="Example prompt",
messages=[
types.PromptMessage(
role="user",
content=types.TextContent(
type="text",
text="Example prompt text"
)
)
]
)
async def run():
# Run the server as STDIO
async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
await server.run(
read_stream,
write_stream,
InitializationOptions(
server_name="example",
server_version="0.1.0",
capabilities=server.get_capabilities(
notification_options=NotificationOptions(),
experimental_capabilities={},
)
)
)
if __name__ == "__main__":
import asyncio
asyncio.run(run())
```
### Creating a Client
**example_client.py**
```python
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
# Create server parameters for stdio connection
server_params = StdioServerParameters(
command="python", # Executable
args=["example_server.py"], # Optional command line arguments
env=None # Optional environment variables
)
async def run():
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
# Initialize the connection
await session.initialize()
# The example server only supports prompt primitives:
# List available prompts
prompts = await session.list_prompts()
# Get a prompt
prompt = await session.get_prompt("example-prompt", arguments={"arg1": "value"})
"""
Other example calls include:
# List available resources
resources = await session.list_resources()
# List available tools
tools = await session.list_tools()
# Read a resource
resource = await session.read_resource("file://some/path")
# Call a tool
result = await session.call_tool("tool-name", arguments={"arg1": "value"})
"""
if __name__ == "__main__":
import asyncio
asyncio.run(run())
```
## Primitives
The MCP Python SDK provides decorators that map to the core protocol primitives. Each primitive follows a different interaction pattern based on how it is controlled and used:
| Primitive | Control | Description | Example Use |
|-----------|-----------------------|-----------------------------------------------------|------------------------------|
| Prompts | User-controlled | Interactive templates invoked by user choice | Slash commands, menu options |
| Resources | Application-controlled| Contextual data managed by the client application | File contents, API responses |
| Tools | Model-controlled | Functions exposed to the LLM to take actions | API calls, data updates |
### User-Controlled Primitives
**Prompts** are designed to be explicitly selected by users for their interactions with LLMs.
| Decorator | Description |
|--------------------------|----------------------------------------|
| `@server.list_prompts()` | List available prompt templates |
| `@server.get_prompt()` | Get a specific prompt with arguments |
### Application-Controlled Primitives
**Resources** are controlled by the client application, which decides how and when they should be used based on its own logic.
| Decorator | Description |
|--------------------------------|---------------------------------------|
| `@server.list_resources()` | List available resources |
| `@server.read_resource()` | Read a specific resource's content |
| `@server.subscribe_resource()` | Subscribe to resource updates |
### Model-Controlled Primitives
**Tools** are exposed to LLMs to enable automated actions, with user approval.
| Decorator | Description |
|------------------------|------------------------------------|
| `@server.list_tools()` | List available tools |
| `@server.call_tool()` | Execute a tool with arguments |
### Server Management
Additional decorators for server functionality:
| Decorator | Description |
|-------------------------------|--------------------------------|
| `@server.set_logging_level()` | Update server logging level |
### Capabilities
MCP servers declare capabilities during initialization. These map to specific decorators:
| Capability | Feature Flag | Decorators | Description |
|-------------|------------------------------|-----------------------------------------------------------------|-------------------------------------|
| `prompts` | `listChanged` | `@list_prompts`<br/>`@get_prompt` | Prompt template management |
| `resources` | `subscribe`<br/>`listChanged`| `@list_resources`<br/>`@read_resource`<br/>`@subscribe_resource`| Resource exposure and updates |
| `tools` | `listChanged` | `@list_tools`<br/>`@call_tool` | Tool discovery and execution |
| `logging` | - | `@set_logging_level` | Server logging configuration |
| `completion`| - | `@complete_argument` | Argument completion suggestions |
Capabilities are negotiated during connection initialization. Servers only need to implement the decorators for capabilities they support.
## Client Interaction
The MCP Python SDK enables servers to interact with clients through request context and session management. This allows servers to perform operations like LLM sampling and progress tracking.
### Request Context
The Request Context provides access to the current request and client session. It can be accessed through `server.request_context` and enables:
- Sampling from the client's LLM
- Sending progress updates
- Logging messages
- Accessing request metadata
Example using request context for LLM sampling:
```python
@server.call_tool()
async def handle_call_tool(name: str, arguments: dict) -> list[types.TextContent]:
# Access the current request context
context = server.request_context
# Use the session to sample from the client's LLM
result = await context.session.create_message(
messages=[
types.SamplingMessage(
role="user",
content=types.TextContent(
type="text",
text="Analyze this data: " + json.dumps(arguments)
)
)
],
max_tokens=100
)
return [types.TextContent(type="text", text=result.content.text)]
```
Using request context for progress updates:
```python
@server.call_tool()
async def handle_call_tool(name: str, arguments: dict) -> list[types.TextContent]:
context = server.request_context
if progress_token := context.meta.progressToken:
# Send progress notifications
await context.session.send_progress_notification(
progress_token=progress_token,
progress=0.5,
total=1.0
)
# Perform operation...
if progress_token:
await context.session.send_progress_notification(
progress_token=progress_token,
progress=1.0,
total=1.0
)
return [types.TextContent(type="text", text="Operation complete")]
```
The request context is automatically set for each request and provides a safe way to access the current client session and request metadata.
## Documentation
- [Model Context Protocol documentation](https://modelcontextprotocol.io)
- [Model Context Protocol specification](https://spec.modelcontextprotocol.io)
- [Officially supported servers](https://github.com/modelcontextprotocol/servers)
## Contributing
We are passionate about supporting contributors of all levels of experience and would love to see you get involved in the project. See the [contributing guide](CONTRIBUTING.md) to get started.
## License
This project is licensed under the MIT License - see the LICENSE file for details.
```
--------------------------------------------------------------------------------
/DOCS/mcs_spec_docs.md:
--------------------------------------------------------------------------------
```markdown
*Note: This is llms-full.txt is not complete, please enter a Firecrawl API key to get the entire llms-full.txt at llmstxt.firecrawl.dev or you can access llms.txt via API with curl -X GET 'http://llmstxt.firecrawl.dev/https://spec.modelcontextprotocol.io/?FIRECRAWL_API_KEY=YOUR_API_KEY' or llms-full.txt via API with curl -X GET 'http://llmstxt.firecrawl.dev/https://spec.modelcontextprotocol.io//full?FIRECRAWL_API_KEY=YOUR_API_KEY'
# https://spec.modelcontextprotocol.io/ llms-full.txt
[Specification](/specification/)
[Revisions](/specification/revisions/)
2024-11-05 (Current)
# 2024-11-05 (Current)
This is the current version of the specification. This revision may continue to receive backwards compatible changes.[Specification](/specification/)
Server Features
# Server Features
ℹ️
**Protocol Revision**: 2024-11-05
Servers provide the fundamental building blocks for adding context to language models via MCP. These primitives enable rich interactions between clients, servers, and language models:
- **Prompts**: Pre-defined templates or instructions that guide language model interactions
- **Resources**: Structured data or content that provides additional context to the model
- **Tools**: Executable functions that allow models to perform actions or retrieve information
Each primitive can be summarized in the following control hierarchy:
| Primitive | Control | Description | Example |
| --- | --- | --- | --- |
| Prompts | User-controlled | Interactive templates invoked by user choice | Slash commands, menu options |
| Resources | Application-controlled | Contextual data attached and managed by the client | File contents, git history |
| Tools | Model-controlled | Functions exposed to the LLM to take actions | API POST requests, file writing |
Explore these key primitives in more detail below:
[Prompts](prompts) [Resources](resources) [Tools](tools)[Specification](/specification/)
Client Features
# Client Features
ℹ️
**Protocol Revision**: 2024-11-05
Clients can implement additional features to enrich connected MCP servers:
[Roots](roots) [Sampling](sampling)# Specification
ℹ️
**Protocol Revision**: 2024-11-05
[Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. Whether you’re building an AI-powered IDE, enhancing a chat interface, or creating custom AI workflows, MCP provides a standardized way to connect LLMs with the context they need.
This specification defines the authoritative protocol requirements, based on the TypeScript schema in [schema.ts](https://github.com/modelcontextprotocol/specification/blob/main/schema/schema.ts).
For implementation guides and examples, visit [modelcontextprotocol.io](https://modelcontextprotocol.io).
## Overview [Permalink for this section](\#overview)
MCP provides a standardized way for applications to:
- Share contextual information with language models
- Expose tools and capabilities to AI systems
- Build composable integrations and workflows
The protocol uses [JSON-RPC](https://www.jsonrpc.org/) 2.0 messages to establish communication between:
- **Hosts**: LLM applications that initiate connections
- **Clients**: Connectors within the host application
- **Servers**: Services that provide context and capabilities
MCP takes some inspiration from the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/), which standardizes how to add support for programming languages across a whole ecosystem of development tools. In a similar way, MCP standardizes how to integrate additional context and tools into the ecosystem of AI applications.
## Key Details [Permalink for this section](\#key-details)
### Base Protocol [Permalink for this section](\#base-protocol)
- [JSON-RPC](https://www.jsonrpc.org/) message format
- Stateful connections
- Server and client capability negotiation
### Features [Permalink for this section](\#features)
Servers offer any of the following features to clients:
- **Resources**: Context and data, for the user or the AI model to use
- **Prompts**: Templated messages and workflows for users
- **Tools**: Functions for the AI model to execute
Clients may offer the following feature to servers:
- **Sampling**: Server-initiated agentic behaviors and recursive LLM interactions
### Additional Utilities [Permalink for this section](\#additional-utilities)
- Configuration
- Progress tracking
- Cancellation
- Error reporting
- Logging
## Security and Trust & Safety [Permalink for this section](\#security-and-trust--safety)
The Model Context Protocol enables powerful capabilities through arbitrary data access and code execution paths. With this power comes important security and trust considerations that all implementors must carefully address.
### Key Principles [Permalink for this section](\#key-principles)
1. **User Consent and Control**
- Users must explicitly consent to and understand all data access and operations
- Users must retain control over what data is shared and what actions are taken
- Implementors should provide clear UIs for reviewing and authorizing activities
2. **Data Privacy**
- Hosts must obtain explicit user consent before exposing user data to servers
- Hosts must not transmit resource data elsewhere without user consent
- User data should be protected with appropriate access controls
3. **Tool Safety**
- Tools represent arbitrary code execution and must be treated with appropriate caution
- Hosts must obtain explicit user consent before invoking any tool
- Users should understand what each tool does before authorizing its use
4. **LLM Sampling Controls**
- Users must explicitly approve any LLM sampling requests
- Users should control:
- Whether sampling occurs at all
- The actual prompt that will be sent
- What results the server can see
- The protocol intentionally limits server visibility into prompts
### Implementation Guidelines [Permalink for this section](\#implementation-guidelines)
While MCP itself cannot enforce these security principles at the protocol level, implementors **SHOULD**:
1. Build robust consent and authorization flows into their applications
2. Provide clear documentation of security implications
3. Implement appropriate access controls and data protections
4. Follow security best practices in their integrations
5. Consider privacy implications in their feature designs
## Learn More [Permalink for this section](\#learn-more)
Explore the detailed specification for each protocol component:
[Architecture](architecture) [Base Protocol](basic) [Server Features](server) [Client Features](client) [Contributing](contributing)# Contributions
We welcome contributions from the community! Please review our [contributing guidelines](https://github.com/modelcontextprotocol/specification/blob/main/CONTRIBUTING.md) for details on how to submit changes.
All contributors must adhere to our [Code of Conduct](https://github.com/modelcontextprotocol/specification/blob/main/CODE_OF_CONDUCT.md).
For questions and discussions, please use [GitHub Discussions](https://github.com/modelcontextprotocol/specification/discussions).[Specification](/specification/)
Base Protocol
# Base Protocol
ℹ️
**Protocol Revision**: 2024-11-05
All messages between MCP clients and servers **MUST** follow the [JSON-RPC 2.0](https://www.jsonrpc.org/specification) specification. The protocol defines three fundamental types of messages:
| Type | Description | Requirements |
| --- | --- | --- |
| `Requests` | Messages sent to initiate an operation | Must include unique ID and method name |
| `Responses` | Messages sent in reply to requests | Must include same ID as request |
| `Notifications` | One-way messages with no reply | Must not include an ID |
**Responses** are further sub-categorized as either **successful results** or **errors**. Results can follow any JSON object structure, while errors must include an error code and message at minimum.
## Protocol Layers [Permalink for this section](\#protocol-layers)
The Model Context Protocol consists of several key components that work together:
- **Base Protocol**: Core JSON-RPC message types
- **Lifecycle Management**: Connection initialization, capability negotiation, and session control
- **Server Features**: Resources, prompts, and tools exposed by servers
- **Client Features**: Sampling and root directory lists provided by clients
- **Utilities**: Cross-cutting concerns like logging and argument completion
All implementations **MUST** support the base protocol and lifecycle management components. Other components **MAY** be implemented based on the specific needs of the application.
These protocol layers establish clear separation of concerns while enabling rich interactions between clients and servers. The modular design allows implementations to support exactly the features they need.
See the following pages for more details on the different components:
[Lifecycle](/specification/basic/lifecycle) [Resources](/specification/server/resources) [Prompts](/specification/server/prompts) [Tools](/specification/server/tools) [Logging](/specification/server/utilities/logging) [Sampling](/specification/client/sampling)
## Auth [Permalink for this section](\#auth)
Authentication and authorization are not currently part of the core MCP specification, but we are considering ways to introduce them in future. Join us in [GitHub Discussions](https://github.com/modelcontextprotocol/specification/discussions) to help shape the future of the protocol!
Clients and servers **MAY** negotiate their own custom authentication and authorization strategies.
## Schema [Permalink for this section](\#schema)
The full specification of the protocol is defined as a [TypeScript schema](http://github.com/modelcontextprotocol/specification/tree/main/schema/schema.ts). This is the source of truth for all protocol messages and structures.
There is also a [JSON Schema](http://github.com/modelcontextprotocol/specification/tree/main/schema/schema.json), which is automatically generated from the TypeScript source of truth, for use with various automated tooling.[Specification](/specification/)
[Server Features](/specification/server/)
Prompts
# Prompts
ℹ️
**Protocol Revision**: 2024-11-05
The Model Context Protocol (MCP) provides a standardized way for servers to expose prompt templates to clients. Prompts allow servers to provide structured messages and instructions for interacting with language models. Clients can discover available prompts, retrieve their contents, and provide arguments to customize them.
## User Interaction Model [Permalink for this section](\#user-interaction-model)
Prompts are designed to be **user-controlled**, meaning they are exposed from servers to clients with the intention of the user being able to explicitly select them for use.
Typically, prompts would be triggered through user-initiated commands in the user interface, which allows users to naturally discover and invoke available prompts.
For example, as slash commands:
However, implementors are free to expose prompts through any interface pattern that suits their needs—the protocol itself does not mandate any specific user interaction model.
## Capabilities [Permalink for this section](\#capabilities)
Servers that support prompts **MUST** declare the `prompts` capability during [initialization](https://spec.modelcontextprotocol.io/specification/basic/lifecycle/#initialization):
```json
{
"capabilities": {
"prompts": {
"listChanged": true
}
}
}
```
`listChanged` indicates whether the server will emit notifications when the list of available prompts changes.
## Protocol Messages [Permalink for this section](\#protocol-messages)
### Listing Prompts [Permalink for this section](\#listing-prompts)
To retrieve available prompts, clients send a `prompts/list` request. This operation supports [pagination](https://spec.modelcontextprotocol.io/specification/server/utilities/pagination/).
**Request:**
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "prompts/list",
"params": {
"cursor": "optional-cursor-value"
}
}
```
**Response:**
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"prompts": [\
{\
"name": "code_review",\
"description": "Asks the LLM to analyze code quality and suggest improvements",\
"arguments": [\
{\
"name": "code",\
"description": "The code to review",\
"required": true\
}\
]\
}\
],
"nextCursor": "next-page-cursor"
}
}
```
### Getting a Prompt [Permalink for this section](\#getting-a-prompt)
To retrieve a specific prompt, clients send a `prompts/get` request. Arguments may be auto-completed through [the completion API](https://spec.modelcontextprotocol.io/specification/server/utilities/completion/).
**Request:**
```json
{
"jsonrpc": "2.0",
"id": 2,
"method": "prompts/get",
"params": {
"name": "code_review",
"arguments": {
"code": "def hello():\n print('world')"
}
}
}
```
**Response:**
```json
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"description": "Code review prompt",
"messages": [\
{\
"role": "user",\
"content": {\
"type": "text",\
"text": "Please review this Python code:\ndef hello():\n print('world')"\
}\
}\
]
}
}
```
### List Changed Notification [Permalink for this section](\#list-changed-notification)
When the list of available prompts changes, servers that declared the `listChanged` capability **SHOULD** send a notification:
```json
{
"jsonrpc": "2.0",
"method": "notifications/prompts/list_changed"
}
```
## Message Flow [Permalink for this section](\#message-flow)
```
ServerClientServerClientDiscoveryUsageChangesopt[listChanged]prompts/listList of promptsprompts/getPrompt contentprompts/list_changedprompts/listUpdated prompts
```
## Data Types [Permalink for this section](\#data-types)
### Prompt [Permalink for this section](\#prompt)
A prompt definition includes:
- `name`: Unique identifier for the prompt
- `description`: Optional human-readable description
- `arguments`: Optional list of arguments for customization
### PromptMessage [Permalink for this section](\#promptmessage)
Messages in a prompt can contain:
- `role`: Either “user” or “assistant” to indicate the speaker
- `content`: One of the following content types:
#### Text Content [Permalink for this section](\#text-content)
Text content represents plain text messages:
```json
{
"type": "text",
"text": "The text content of the message"
}
```
This is the most common content type used for natural language interactions.
#### Image Content [Permalink for this section](\#image-content)
Image content allows including visual information in messages:
```json
{
"type": "image",
"data": "base64-encoded-image-data",
"mimeType": "image/png"
}
```
The image data MUST be base64-encoded and include a valid MIME type. This enables multi-modal interactions where visual context is important.
#### Embedded Resources [Permalink for this section](\#embedded-resources)
Embedded resources allow referencing server-side resources directly in messages:
```json
{
"type": "resource",
"resource": {
"uri": "resource://example",
"mimeType": "text/plain",
"text": "Resource content"
}
}
```
Resources can contain either text or binary (blob) data and MUST include:
- A valid resource URI
- The appropriate MIME type
- Either text content or base64-encoded blob data
Embedded resources enable prompts to seamlessly incorporate server-managed content like documentation, code samples, or other reference materials directly into the conversation flow.
## Error Handling [Permalink for this section](\#error-handling)
Servers SHOULD return standard JSON-RPC errors for common failure cases:
- Invalid prompt name: `-32602` (Invalid params)
- Missing required arguments: `-32602` (Invalid params)
- Internal errors: `-32603` (Internal error)
## Implementation Considerations [Permalink for this section](\#implementation-considerations)
1. Servers **SHOULD** validate prompt arguments before processing
2. Clients **SHOULD** handle pagination for large prompt lists
3. Both parties **SHOULD** respect capability negotiation
## Security [Permalink for this section](\#security)
Implementations **MUST** carefully validate all prompt inputs and outputs to prevent injection attacks or unauthorized access to resources.
[Resources](/specification/server/resources/ "Resources")[Specification](/specification/)
[Base Protocol](/specification/basic/)
[Utilities](/specification/basic/utilities/)
Cancellation
# Cancellation
ℹ️
**Protocol Revision**: 2024-11-05
The Model Context Protocol (MCP) supports optional cancellation of in-progress requests through notification messages. Either side can send a cancellation notification to indicate that a previously-issued request should be terminated.
## Cancellation Flow [Permalink for this section](\#cancellation-flow)
When a party wants to cancel an in-progress request, it sends a `notifications/cancelled` notification containing:
- The ID of the request to cancel
- An optional reason string that can be logged or displayed
```json
{
"jsonrpc": "2.0",
"method": "notifications/cancelled",
"params": {
"requestId": "123",
"reason": "User requested cancellation"
}
}
```
## Behavior Requirements [Permalink for this section](\#behavior-requirements)
1. Cancellation notifications **MUST** only reference requests that:
- Were previously issued in the same direction
- Are believed to still be in-progress
2. The `initialize` request **MUST NOT** be cancelled by clients
3. Receivers of cancellation notifications **SHOULD**:
- Stop processing the cancelled request
- Free associated resources
- Not send a response for the cancelled request
4. Receivers **MAY** ignore cancellation notifications if:
- The referenced request is unknown
- Processing has already completed
- The request cannot be cancelled
5. The sender of the cancellation notification **SHOULD** ignore any response to the request that arrives afterward
## Timing Considerations [Permalink for this section](\#timing-considerations)
Due to network latency, cancellation notifications may arrive after request processing has completed, and potentially after a response has already been sent.
Both parties **MUST** handle these race conditions gracefully:
```
ServerClientServerClientProcessing startsProcessing may havecompleted beforecancellation arrivesStop processingalt[If notcompleted]Request (ID: 123)notifications/cancelled (ID: 123)
```
## Implementation Notes [Permalink for this section](\#implementation-notes)
- Both parties **SHOULD** log cancellation reasons for debugging
- Application UIs **SHOULD** indicate when cancellation is requested
## Error Handling [Permalink for this section](\#error-handling)
Invalid cancellation notifications **SHOULD** be ignored:
- Unknown request IDs
- Already completed requests
- Malformed notifications
This maintains the “fire and forget” nature of notifications while allowing for race conditions in asynchronous communication.
[Ping](/specification/basic/utilities/ping/ "Ping") [Progress](/specification/basic/utilities/progress/ "Progress")[Specification](/specification/)
[Base Protocol](/specification/basic/)
[Utilities](/specification/basic/utilities/)
Ping
# Ping
ℹ️
**Protocol Revision**: 2024-11-05
The Model Context Protocol includes an optional ping mechanism that allows either party to verify that their counterpart is still responsive and the connection is alive.
## Overview [Permalink for this section](\#overview)
The ping functionality is implemented through a simple request/response pattern. Either the client or server can initiate a ping by sending a `ping` request.
## Message Format [Permalink for this section](\#message-format)
A ping request is a standard JSON-RPC request with no parameters:
```json
{
"jsonrpc": "2.0",
"id": "123",
"method": "ping"
}
```
## Behavior Requirements [Permalink for this section](\#behavior-requirements)
1. The receiver **MUST** respond promptly with an empty response:
```json
{
"jsonrpc": "2.0",
"id": "123",
"result": {}
}
```
2. If no response is received within a reasonable timeout period, the sender **MAY**:
- Consider the connection stale
- Terminate the connection
- Attempt reconnection procedures
## Usage Patterns [Permalink for this section](\#usage-patterns)
```
ReceiverSenderReceiverSenderping requestempty response
```
## Implementation Considerations [Permalink for this section](\#implementation-considerations)
- Implementations **SHOULD** periodically issue pings to detect connection health
- The frequency of pings **SHOULD** be configurable
- Timeouts **SHOULD** be appropriate for the network environment
- Excessive pinging **SHOULD** be avoided to reduce network overhead
## Error Handling [Permalink for this section](\#error-handling)
- Timeouts **SHOULD** be treated as connection failures
- Multiple failed pings **MAY** trigger connection reset
- Implementations **SHOULD** log ping failures for diagnostics
[Cancellation](/specification/basic/utilities/cancellation/ "Cancellation")[Specification](/specification/)
Architecture
# Architecture
The Model Context Protocol (MCP) follows a client-host-server architecture where each host can run multiple client instances. This architecture enables users to integrate AI capabilities across applications while maintaining clear security boundaries and isolating concerns. Built on JSON-RPC, MCP provides a stateful session protocol focused on context exchange and sampling coordination between clients and servers.
## Core Components [Permalink for this section](\#core-components)
```
Internet
Local machine
Application Host Process
Server 3
External APIs
Remote
Resource C
Server 1
Files & Git
Server 2
Database
Local
Resource A
Local
Resource B
Host
Client 1
Client 2
Client 3
```
### Host [Permalink for this section](\#host)
The host process acts as the container and coordinator:
- Creates and manages multiple client instances
- Controls client connection permissions and lifecycle
- Enforces security policies and consent requirements
- Handles user authorization decisions
- Coordinates AI/LLM integration and sampling
- Manages context aggregation across clients
### Clients [Permalink for this section](\#clients)
Each client is created by the host and maintains an isolated server connection:
- Establishes one stateful session per server
- Handles protocol negotiation and capability exchange
- Routes protocol messages bidirectionally
- Manages subscriptions and notifications
- Maintains security boundaries between servers
A host application creates and manages multiple clients, with each client having a 1:1 relationship with a particular server.
### Servers [Permalink for this section](\#servers)
Servers provide specialized context and capabilities:
- Expose resources, tools and prompts via MCP primitives
- Operate independently with focused responsibilities
- Request sampling through client interfaces
- Must respect security constraints
- Can be local processes or remote services
## Design Principles [Permalink for this section](\#design-principles)
MCP is built on several key design principles that inform its architecture and implementation:
1. **Servers should be extremely easy to build**
- Host applications handle complex orchestration responsibilities
- Servers focus on specific, well-defined capabilities
- Simple interfaces minimize implementation overhead
- Clear separation enables maintainable code
2. **Servers should be highly composable**
- Each server provides focused functionality in isolation
- Multiple servers can be combined seamlessly
- Shared protocol enables interoperability
- Modular design supports extensibility
3. **Servers should not be able to read the whole conversation, nor “see into” other servers**
- Servers receive only necessary contextual information
- Full conversation history stays with the host
- Each server connection maintains isolation
- Cross-server interactions are controlled by the host
- Host process enforces security boundaries
4. **Features can be added to servers and clients progressively**
- Core protocol provides minimal required functionality
- Additional capabilities can be negotiated as needed
- Servers and clients evolve independently
- Protocol designed for future extensibility
- Backwards compatibility is maintained
## Message Types [Permalink for this section](\#message-types)
MCP defines three core message types based on [JSON-RPC 2.0](https://www.jsonrpc.org/specification):
- **Requests**: Bidirectional messages with method and parameters expecting a response
- **Responses**: Successful results or errors matching specific request IDs
- **Notifications**: One-way messages requiring no response
Each message type follows the JSON-RPC 2.0 specification for structure and delivery semantics.
## Capability Negotiation [Permalink for this section](\#capability-negotiation)
The Model Context Protocol uses a capability-based negotiation system where clients and servers explicitly declare their supported features during initialization. Capabilities determine which protocol features and primitives are available during a session.
- Servers declare capabilities like resource subscriptions, tool support, and prompt templates
- Clients declare capabilities like sampling support and notification handling
- Both parties must respect declared capabilities throughout the session
- Additional capabilities can be negotiated through extensions to the protocol
```
ServerClientHostServerClientHostActive Session with Negotiated Featuresloop[Client Requests]loop[Server Requests]loop[Notifications]Initialize clientInitialize session with capabilitiesRespond with supported capabilitiesUser- or model-initiated actionRequest (tools/resources)ResponseUpdate UI or respond to modelRequest (sampling)Forward to AIAI responseResponseResource updatesStatus changesTerminateEnd session
```
Each capability unlocks specific protocol features for use during the session. For example:
- Implemented [server features](https://spec.modelcontextprotocol.io/specification/server/) must be advertised in the server’s capabilities
- Emitting resource subscription notifications requires the server to declare subscription support
- Tool invocation requires the server to declare tool capabilities
- [Sampling](https://spec.modelcontextprotocol.io/specification/client/) requires the client to declare support in its capabilities
This capability negotiation ensures clients and servers have a clear understanding of supported functionality while maintaining protocol extensibility.
# LanceDB MCP Server Specification
## Overview
The LanceDB MCP Server implements the Model Context Protocol (MCP) for vector database operations. It provides a standardized interface for managing and querying vector embeddings using LanceDB.
## Server Implementation
### Core Components
1. **Server Class**: `LanceDBServer`
- Extends the base MCP `Server` class
- Manages database connections and operations
- Handles vector table management
2. **Data Models**:
- `VectorData`: Represents vector data with metadata
- `DatabaseError`: Custom exception for database operations
### Server Capabilities
The server provides the following capabilities:
```python
{
"tools": {
"list": true,
"get": true,
"call": true
},
"resources": {
"list": true,
"get": true,
"create": true,
"update": true,
"delete": true
}
}
```
## API Reference
### Vector Operations
1. **Create Table**
```python
async def create_table(table_name: str, dimension: int) -> CallToolResult
```
- Creates a new vector table
- Parameters:
- `table_name`: Name of the table
- `dimension`: Vector dimension size
2. **Add Vector**
```python
async def add_vector(table_name: str, vector: List[float], metadata: Optional[Dict] = None) -> CallToolResult
```
- Adds a vector to a table
- Parameters:
- `table_name`: Target table name
- `vector`: Vector data as float list
- `metadata`: Optional metadata dictionary
3. **Search Vectors**
```python
async def search_vectors(table_name: str, query_vector: List[float], limit: int = 10) -> CallToolResult
```
- Searches for similar vectors
- Parameters:
- `table_name`: Table to search in
- `query_vector`: Query vector
- `limit`: Maximum results to return
### Resource Management
1. **List Resources**
```python
async def list_resources() -> List[Resource]
```
- Lists all available tables
- Returns list of Resource objects
2. **Get Table**
```python
async def _get_table(table_name: str) -> Any
```
- Retrieves a table by name
- Internal method for table access
## Logging and Monitoring
The server implements comprehensive logging:
1. **Timestamp Generation**
```python
def _get_timestamp() -> str
```
- Generates UTC timestamps in ISO format
2. **Log Messages**
```python
def _send_log(level: str, message: str)
```
- Sends log messages to the client
- Supports multiple log levels (info, error, etc.)
## Error Handling
The server implements robust error handling:
1. **Database Errors**
- Custom `DatabaseError` class
- Proper error propagation
- Detailed error messages
2. **Operation Results**
- Success/failure status
- Error messages in `CallToolResult`
- Proper cleanup on errors
## Testing
The server includes comprehensive tests:
1. **Unit Tests**
- Server initialization
- Vector operations
- Error handling
2. **Integration Tests**
- End-to-end workflows
- Resource management
- Vector operations
## Usage with MCP Inspector
1. **Starting the Server**
```bash
python3 server.py
```
2. **Connecting Inspector**
```bash
npx @modelcontextprotocol/inspector connect http://localhost:8000
```
3. **Available Operations**
- View server capabilities
- Create and manage tables
- Add and search vectors
- Monitor logs
## Best Practices
1. **Resource Management**
- Always close database connections
- Clean up temporary resources
- Handle concurrent access
2. **Error Handling**
- Validate inputs
- Provide clear error messages
- Implement proper rollbacks
3. **Performance**
- Use appropriate vector dimensions
- Implement batch operations
- Monitor memory usage
## Dependencies
- `mcp`: Core MCP implementation
- `lancedb`: Vector database
- `numpy`: Numerical operations
- `pydantic`: Data validation
- `pyarrow`: Table schemas
## Configuration
The server can be configured through:
1. **Environment Variables**
- Database URI
- Log levels
- Server settings
2. **Initialization Options**
- Custom database path
- Server name
- Additional settings
```
--------------------------------------------------------------------------------
/DOCS/lancedb_docs.md:
--------------------------------------------------------------------------------
```markdown
*Note: This is llms-full.txt is not complete, please enter a Firecrawl API key to get the entire llms-full.txt at llmstxt.firecrawl.dev or you can access llms.txt via API with curl -X GET 'http://llmstxt.firecrawl.dev/https://lancedb.github.io/lancedb/python/python/?FIRECRAWL_API_KEY=fc-8b492ef4411549e894cd4b923a82e5fc' or llms-full.txt via API with curl -X GET 'http://llmstxt.firecrawl.dev/https://lancedb.github.io/lancedb/python/python//full?FIRECRAWL_API_KEY=fc-8b492ef4411549e894cd4b923a82e5fc'
# https://lancedb.github.io/lancedb/python/python/ llms-full.txt
# 404
**There isn't a GitHub Pages site here.**
If you're trying to publish one,
[read the full documentation](https://help.github.com/pages/)
to learn how to set up **GitHub Pages**
for your repository, organization, or user account.
[GitHub Status](https://githubstatus.com) —
[@githubstatus](https://twitter.com/githubstatus)
[](/)[](/)- [Creating datasets](notebooks/quickstart.html)
- [Versioning](notebooks/quickstart.html#versioning)
- [Vectors](notebooks/quickstart.html#vectors)
- [Read and Write Lance Dataset](read_and_write.html)
- [Lance Formats](format.html)
- [Arrays](arrays.html)
- [Integrations](integrations/integrations.html)
- [Performance Guide](performance.html)
- [API References](api/api.html)
- [Contributor Guide](contributing.html)
- [Examples](examples/examples.html)
[](_images/lance_logo.png)
# Lance: modern columnar data format for ML [¶](\#lance-modern-columnar-data-format-for-ml "Permalink to this heading")
Lance is a columnar data format that is easy and fast to version, query and train on.
It’s designed to be used with images, videos, 3D point clouds, audio and of course tabular data.
It supports any POSIX file systems, and cloud storage like AWS S3 and Google Cloud Storage.
The key features of Lance include:
- **High-performance random access:** 100x faster than Parquet.
- **Vector search:** find nearest neighbors in under 1 millisecond and combine OLAP-queries with vector search.
- **Zero-copy, automatic versioning:** manage versions of your data automatically, and reduce redundancy with zero-copy logic built-in.
- **Ecosystem integrations:** Apache-Arrow, DuckDB and more on the way.
## Installation [¶](\#installation "Permalink to this heading")
You can install Lance via pip:
```
pip install pylance
```
For the latest features and bug fixes, you can install the preview version:
```
pip install --pre --extra-index-url https://pypi.fury.io/lancedb/ pylance
```
Preview releases receive the same level of testing as regular releases.
- [Creating datasets](notebooks/quickstart.html)
- [Versioning](notebooks/quickstart.html#versioning)
- [Vectors](notebooks/quickstart.html#vectors)
- [Read and Write Lance Dataset](read_and_write.html)
- [Lance Formats](format.html)
- [Arrays](arrays.html)
- [Integrations](integrations/integrations.html)
- [Performance Guide](performance.html)
- [API References](api/api.html)
- [Contributor Guide](contributing.html)
- [Examples](examples/examples.html)
# Indices and tables [¶](\#indices-and-tables "Permalink to this heading")
- [Index](genindex.html)
- [Module Index](py-modindex.html)
- [Search Page](search.html)
<Page contents
>Page contents:
- Lance: modern columnar data format for ML
- [Installation](#installation)
- [Indices and tables](#indices-and-tables)
[Creating datasets>](notebooks/quickstart.html)
Styled using the [Piccolo Theme](https://github.com/piccolo-orm/piccolo_theme)
[Edit this page](https://github.com/lancedb/lancedb/tree/main/docs/src/cloud/index.md "Edit this page")
# About LanceDB Cloud [Permanent link](\#about-lancedb-cloud "Permanent link")
LanceDB Cloud is a SaaS (software-as-a-service) solution that runs serverless in the cloud, clearly separating storage from compute. It's designed to be highly scalable without breaking the bank. LanceDB Cloud is currently in private beta with general availability coming soon, but you can apply for early access with the private beta release by signing up below.
[Try out LanceDB Cloud](https://noteforms.com/forms/lancedb-mailing-list-cloud-kty1o5?notionforms=1&utm_source=notionforms)
## Architecture [Permanent link](\#architecture "Permanent link")
LanceDB Cloud provides the same underlying fast vector store that powers the OSS version, but without the need to maintain your own infrastructure. Because it's serverless, you only pay for the storage you use, and you can scale compute up and down as needed depending on the size of your data and its associated index.
## Transitioning from the OSS to the Cloud version [Permanent link](\#transitioning-from-the-oss-to-the-cloud-version "Permanent link")
The OSS version of LanceDB is designed to be embedded in your application, and it runs in-process. This makes it incredibly simple to self-host your own AI retrieval workflows for RAG and more and build and test out your concepts on your own infrastructure. The OSS version is forever free, and you can continue to build and integrate LanceDB into your existing backend applications without any added costs.
Should you decide that you need a managed deployment in production, it's possible to seamlessly transition from the OSS to the cloud version by changing the connection string to point to a remote database instead of a local one. With LanceDB Cloud, you can take your AI application from development to production without major code changes or infrastructure burden.
Back to top
[Ask AI](https://asklancedb.com)
[Edit this page](https://github.com/lancedb/lancedb/tree/main/docs/src/sql.md "Edit this page")
# Filtering [Permanent link](\#filtering "Permanent link")
## Pre and post-filtering [Permanent link](\#pre-and-post-filtering "Permanent link")
LanceDB supports filtering of query results based on metadata fields. By default, post-filtering is
performed on the top-k results returned by the vector search. However, pre-filtering is also an
option that performs the filter prior to vector search. This can be useful to narrow down on
the search space on a very large dataset to reduce query latency.
Note that both pre-filtering and post-filtering can yield false positives. For pre-filtering, if the filter is too selective, it might eliminate relevant items that the vector search would have otherwise identified as a good match. In this case, increasing `nprobes` parameter will help reduce such false positives. It is recommended to set `use_index=false` if you know that the filter is highly selective.
Similarly, a highly selective post-filter can lead to false positives. Increasing both `nprobes` and `refine_factor` can mitigate this issue. When deciding between pre-filtering and post-filtering, pre-filtering is generally the safer choice if you're uncertain.
[Python](#__tabbed_1_1)[TypeScript](#__tabbed_1_2)
```
result = (
tbl.search([0.5, 0.2])
.where("id = 10", prefilter=True)
.limit(1)
.to_arrow()
)
```
[@lancedb/lancedb](#__tabbed_2_1)[vectordb (deprecated)](#__tabbed_2_2)
```
const _result = await tbl
.search(Array(1536).fill(0.5))
.limit(1)
.where("id = 10")
.toArray();
```
```
let result = await tbl
.search(Array(1536).fill(0.5))
.limit(1)
.filter("id = 10")
.prefilter(true)
.execute();
```
Note
Creating a [scalar index](../guides/scalar_index/) accelerates filtering
## SQL filters [Permanent link](\#sql-filters "Permanent link")
Because it's built on top of [DataFusion](https://github.com/apache/arrow-datafusion), LanceDB
embraces the utilization of standard SQL expressions as predicates for filtering operations.
It can be used during vector search, update, and deletion operations.
Currently, Lance supports a growing list of SQL expressions.
- `>`, `>=`, `<`, `<=`, `=`
- `AND`, `OR`, `NOT`
- `IS NULL`, `IS NOT NULL`
- `IS TRUE`, `IS NOT TRUE`, `IS FALSE`, `IS NOT FALSE`
- `IN`
- `LIKE`, `NOT LIKE`
- `CAST`
- `regexp_match(column, pattern)`
- [DataFusion Functions](https://arrow.apache.org/datafusion/user-guide/sql/scalar_functions.html)
For example, the following filter string is acceptable:
[Python](#__tabbed_3_1)[TypeScript](#__tabbed_3_2)
```
tbl.search([100, 102]) \
.where("(item IN ('item 0', 'item 2')) AND (id > 10)") \
.to_arrow()
```
[@lancedb/lancedb](#__tabbed_4_1)[vectordb (deprecated)](#__tabbed_4_2)
```
const result = await (
tbl.search(Array(1536).fill(0)) as lancedb.VectorQuery
)
.where("(item IN ('item 0', 'item 2')) AND (id > 10)")
.postfilter()
.toArray();
```
```
await tbl
.search(Array(1536).fill(0))
.where("(item IN ('item 0', 'item 2')) AND (id > 10)")
.execute();
```
If your column name contains special characters or is a [SQL Keyword](https://docs.rs/sqlparser/latest/sqlparser/keywords/index.html),
you can use backtick ( `` ` ``) to escape it. For nested fields, each segment of the
path must be wrapped in backticks.
[SQL](#__tabbed_5_1)
```
`CUBE` = 10 AND `column name with space` IS NOT NULL
AND `nested with space`.`inner with space` < 2
```
Field names containing periods ( `.`) are not supported.
Literals for dates, timestamps, and decimals can be written by writing the string
value after the type name. For example
[SQL](#__tabbed_6_1)
```
date_col = date '2021-01-01'
and timestamp_col = timestamp '2021-01-01 00:00:00'
and decimal_col = decimal(8,3) '1.000'
```
For timestamp columns, the precision can be specified as a number in the type
parameter. Microsecond precision (6) is the default.
| SQL | Time unit |
| --- | --- |
| `timestamp(0)` | Seconds |
| `timestamp(3)` | Milliseconds |
| `timestamp(6)` | Microseconds |
| `timestamp(9)` | Nanoseconds |
LanceDB internally stores data in [Apache Arrow](https://arrow.apache.org/) format.
The mapping from SQL types to Arrow types is:
| SQL type | Arrow type |
| --- | --- |
| `boolean` | `Boolean` |
| `tinyint` / `tinyint unsigned` | `Int8` / `UInt8` |
| `smallint` / `smallint unsigned` | `Int16` / `UInt16` |
| `int` or `integer` / `int unsigned` or `integer unsigned` | `Int32` / `UInt32` |
| `bigint` / `bigint unsigned` | `Int64` / `UInt64` |
| `float` | `Float32` |
| `double` | `Float64` |
| `decimal(precision, scale)` | `Decimal128` |
| `date` | `Date32` |
| `timestamp` | `Timestamp` [1](#fn:1) |
| `string` | `Utf8` |
| `binary` | `Binary` |
## Filtering without Vector Search [Permanent link](\#filtering-without-vector-search "Permanent link")
You can also filter your data without search.
[Python](#__tabbed_7_1)[TypeScript](#__tabbed_7_2)
```
tbl.search().where("id = 10").limit(10).to_arrow()
```
[@lancedb/lancedb](#__tabbed_8_1)[vectordb (deprecated)](#__tabbed_8_2)
```
await tbl.query().where("id = 10").limit(10).toArray();
```
```
await tbl.filter("id = 10").limit(10).execute();
```
If your table is large, this could potentially return a very large amount of data. Please be sure to use a `limit` clause unless you're sure you want to return the whole result set.
* * *
1. See precision mapping in previous table. [↩](#fnref:1 "Jump back to footnote 1 in the text")
Back to top
[Ask AI](https://asklancedb.com)
[Edit this page](https://github.com/lancedb/lancedb/tree/main/docs/src/reranking/index.md "Edit this page")
# Quickstart
Reranking is the process of reordering a list of items based on some criteria. In the context of search, reranking is used to reorder the search results returned by a search engine based on some criteria. This can be useful when the initial ranking of the search results is not satisfactory or when the user has provided additional information that can be used to improve the ranking of the search results.
LanceDB comes with some built-in rerankers. Some of the rerankers that are available in LanceDB are:
| Reranker | Description | Supported Query Types |
| --- | --- | --- |
| `LinearCombinationReranker` | Reranks search results based on a linear combination of FTS and vector search scores | Hybrid |
| `CohereReranker` | Uses cohere Reranker API to rerank results | Vector, FTS, Hybrid |
| `CrossEncoderReranker` | Uses a cross-encoder model to rerank search results | Vector, FTS, Hybrid |
| `ColbertReranker` | Uses a colbert model to rerank search results | Vector, FTS, Hybrid |
| `OpenaiReranker`(Experimental) | Uses OpenAI's chat model to rerank search results | Vector, FTS, Hybrid |
| `VoyageAIReranker` | Uses voyageai Reranker API to rerank results | Vector, FTS, Hybrid |
## Using a Reranker [Permanent link](\#using-a-reranker "Permanent link")
Using rerankers is optional for vector and FTS. However, for hybrid search, rerankers are required. To use a reranker, you need to create an instance of the reranker and pass it to the `rerank` method of the query builder.
```
import lancedb
from lancedb.embeddings import get_registry
from lancedb.pydantic import LanceModel, Vector
from lancedb.rerankers import CohereReranker
embedder = get_registry().get("sentence-transformers").create()
db = lancedb.connect("~/.lancedb")
class Schema(LanceModel):
text: str = embedder.SourceField()
vector: Vector(embedder.ndims()) = embedder.VectorField()
data = [\
{"text": "hello world"},\
{"text": "goodbye world"}\
]
tbl = db.create_table("test", data)
reranker = CohereReranker(api_key="your_api_key")
# Run vector search with a reranker
result = tbl.query("hello").rerank(reranker).to_list()
# Run FTS search with a reranker
result = tbl.query("hello", query_type="fts").rerank(reranker).to_list()
# Run hybrid search with a reranker
tbl.create_fts_index("text")
result = tbl.query("hello", query_type="hybrid").rerank(reranker).to_list()
```
### Multi-vector reranking [Permanent link](\#multi-vector-reranking "Permanent link")
Most rerankers support reranking based on multiple vectors. To rerank based on multiple vectors, you can pass a list of vectors to the `rerank` method. Here's an example of how to rerank based on multiple vector columns using the `CrossEncoderReranker`:
```
from lancedb.rerankers import CrossEncoderReranker
reranker = CrossEncoderReranker()
query = "hello"
res1 = table.search(query, vector_column_name="vector").limit(3)
res2 = table.search(query, vector_column_name="text_vector").limit(3)
res3 = table.search(query, vector_column_name="meta_vector").limit(3)
reranked = reranker.rerank_multivector([res1, res2, res3], deduplicate=True)
```
## Available Rerankers [Permanent link](\#available-rerankers "Permanent link")
LanceDB comes with some built-in rerankers. Here are some of the rerankers that are available in LanceDB:
- [Cohere Reranker](cohere/)
- [Cross Encoder Reranker](cross_encoder/)
- [ColBERT Reranker](colbert/)
- [OpenAI Reranker](openai/)
- [Linear Combination Reranker](linear_combination/)
- [Jina Reranker](jina/)
- [AnswerDotAI Rerankers](answerdotai/)
- [Reciprocal Rank Fusion Reranker](rrf/)
- [VoyageAI Reranker](voyageai/)
## Creating Custom Rerankers [Permanent link](\#creating-custom-rerankers "Permanent link")
LanceDB also you to create custom rerankers by extending the base `Reranker` class. The custom reranker should implement the `rerank` method that takes a list of search results and returns a reranked list of search results. This is covered in more detail in the [Creating Custom Rerankers](custom_reranker/) section.
Back to top
[Ask AI](https://asklancedb.com)
[Edit this page](https://github.com/lancedb/lancedb/tree/main/docs/src/faq.md "Edit this page")
# 💭 FAQs
This section covers some common questions and issues that you may encounter when using LanceDB.
### Is LanceDB open source? [Permanent link](\#is-lancedb-open-source "Permanent link")
Yes, LanceDB is an open source vector database available under an Apache 2.0 license. We also have a serverless SaaS solution, LanceDB Cloud, available under a commercial license.
### What is the difference between Lance and LanceDB? [Permanent link](\#what-is-the-difference-between-lance-and-lancedb "Permanent link")
[Lance](https://github.com/lancedb/lance) is a modern columnar data format for AI, written in Rust 🦀. It’s perfect for building search engines, feature stores and being the foundation of large-scale ML training jobs requiring high performance IO and shuffles. It also has native support for storing, querying, and inspecting deeply nested data for robotics or large blobs like images, point clouds, and more.
LanceDB is the vector database that’s built on top of Lance, and utilizes the underlying optimized storage format to build efficient disk-based indexes that power semantic search & retrieval applications, from RAGs to QA Bots to recommender systems.
### Why invent another data format instead of using Parquet? [Permanent link](\#why-invent-another-data-format-instead-of-using-parquet "Permanent link")
As we mention in our talk titled “ [Lance, a modern columnar data format](https://www.youtube.com/watch?v=ixpbVyrsuL8)”, Parquet and other tabular formats that derive from it are rather dated (Parquet is over 10 years old), especially when it comes to random access on vectors. We needed a format that’s able to handle the complex trade-offs involved in shuffling, scanning, OLAP and filtering large datasets involving vectors, and our extensive experiments with Parquet didn't yield sufficient levels of performance for modern ML. [Our benchmarks](https://blog.lancedb.com/benchmarking-random-access-in-lance-ed690757a826) show that Lance is up to 1000x faster than Parquet for random access, which we believe justifies our decision to create a new data format for AI.
### Why build in Rust? 🦀 [Permanent link](\#why-build-in-rust "Permanent link")
We believe that the Rust ecosystem has attained mainstream maturity and that Rust will form the underpinnings of large parts of the data and ML landscape in a few years. Performance, latency and reliability are paramount to a vector DB, and building in Rust allows us to iterate and release updates more rapidly due to Rust’s safety guarantees. Both Lance (the data format) and LanceDB (the database) are written entirely in Rust. We also provide Python, JavaScript, and Rust client libraries to interact with the database.
### What is the difference between LanceDB OSS and LanceDB Cloud? [Permanent link](\#what-is-the-difference-between-lancedb-oss-and-lancedb-cloud "Permanent link")
LanceDB OSS is an **embedded** (in-process) solution that can be used as the vector store of choice for your LLM and RAG applications. It can be embedded inside an existing application backend, or used in-process alongside existing ML and data engineering pipelines.
LanceDB Cloud is a **serverless** solution — the database and data sit on the cloud and we manage the scalability of the application side via a remote client, without the need to manage any infrastructure.
Both flavors of LanceDB benefit from the blazing fast Lance data format and are built on the same open source foundations.
### What makes LanceDB different? [Permanent link](\#what-makes-lancedb-different "Permanent link")
LanceDB is among the few embedded vector DBs out there that we believe can unlock a whole new class of LLM-powered applications in the browser or via edge functions. Lance’s multi-modal nature allows you to store the raw data, metadata and the embeddings all at once, unlike other solutions that typically store just the embeddings and metadata.
The Lance data format that powers our storage system also provides true zero-copy access and seamless interoperability with numerous other data formats (like Pandas, Polars, Pydantic) via Apache Arrow, as well as automatic data versioning and data management without needing extra infrastructure.
### How large of a dataset can LanceDB handle? [Permanent link](\#how-large-of-a-dataset-can-lancedb-handle "Permanent link")
LanceDB and its underlying data format, Lance, are built to scale to really large amounts of data (hundreds of terabytes). We are currently working with customers who regularly perform operations on 200M+ vectors, and we’re fast approaching billion scale and beyond, which are well-handled by our disk-based indexes, without you having to break the bank.
### Do I need to build an ANN index to run vector search? [Permanent link](\#do-i-need-to-build-an-ann-index-to-run-vector-search "Permanent link")
No. LanceDB is blazing fast (due to its disk-based index) for even brute force kNN search, within reason. In our benchmarks, computing 100K pairs of 1000-dimension vectors takes less than 20ms. For small datasets of ~100K records or applications that can accept ~100ms latency, an ANN index is usually not necessary.
For large-scale (>1M) or higher dimension vectors, it is beneficial to create an ANN index. See the [ANN indexes](../ann_indexes/) section for more details.
### Does LanceDB support full-text search? [Permanent link](\#does-lancedb-support-full-text-search "Permanent link")
Yes, LanceDB supports full-text search (FTS) via [Tantivy](https://github.com/quickwit-oss/tantivy). Our current FTS integration is Python-only, and our goal is to push it down to the Rust level in future versions to enable much more powerful search capabilities available to our Python, JavaScript and Rust clients. Follow along in the [Github issue](https://github.com/lancedb/lance/issues/1195)
### How can I speed up data inserts? [Permanent link](\#how-can-i-speed-up-data-inserts "Permanent link")
It's highly recommend to perform bulk inserts via batches (for e.g., Pandas DataFrames or lists of dicts in Python) to speed up inserts for large datasets. Inserting records one at a time is slow and can result in suboptimal performance because each insert creates a new data fragment on disk. Batching inserts allows LanceDB to create larger fragments (and their associated manifests), which are more efficient to read and write.
### Do I need to set a refine factor when using an index? [Permanent link](\#do-i-need-to-set-a-refine-factor-when-using-an-index "Permanent link")
Yes. LanceDB uses PQ, or Product Quantization, to compress vectors and speed up search when using an ANN index. However, because PQ is a lossy compression algorithm, it tends to reduce recall while also reducing the index size. To address this trade-off, we introduce a process called **refinement**. The normal process computes distances by operating on the compressed PQ vectors. The refinement factor ( _rf_) is a multiplier that takes the top-k similar PQ vectors to a given query, fetches `rf * k` _full_ vectors and computes the raw vector distances between them and the query vector, reordering the top-k results based on these scores instead.
For example, if you're retrieving the top 10 results and set `refine_factor` to 25, LanceDB will fetch the 250 most similar vectors (according to PQ), compute the distances again based on the full vectors for those 250 and then re-rank based on their scores. This can significantly improve recall, with a small added latency cost (typically a few milliseconds), so it's recommended you set a `refine_factor` of anywhere between 5-50 and measure its impact on latency prior to deploying your solution.
### How can I improve IVF-PQ recall while keeping latency low? [Permanent link](\#how-can-i-improve-ivf-pq-recall-while-keeping-latency-low "Permanent link")
When using an IVF-PQ index, there's a trade-off between recall and latency at query time. You can improve recall by increasing the number of probes and the `refine_factor`. In our benchmark on the GIST-1M dataset, we show that it's possible to achieve >0.95 recall with a latency of under 10 ms on most systems, using ~50 probes and a `refine_factor` of 50. This is, of course, subject to the dataset at hand and a quick sensitivity study can be performed on your own data. You can find more details on the benchmark in our [blog post](https://blog.lancedb.com/benchmarking-lancedb-92b01032874a).
### How do I connect to MinIO? [Permanent link](\#how-do-i-connect-to-minio "Permanent link")
MinIO supports an S3 compatible API. In order to connect to a MinIO instance, you need to:
- Set the envvar `AWS_ENDPOINT` to the URL of your MinIO API
- Set the envvars `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` with your MinIO credential
- Call `lancedb.connect("s3://minio_bucket_name")`
### Where can I find benchmarks for LanceDB? [Permanent link](\#where-can-i-find-benchmarks-for-lancedb "Permanent link")
Refer to this [post](https://blog.lancedb.com/benchmarking-lancedb-92b01032874a) for recent benchmarks.
### How much data can LanceDB practically manage without effecting performance? [Permanent link](\#how-much-data-can-lancedb-practically-manage-without-effecting-performance "Permanent link")
We target good performance on ~10-50 billion rows and ~10-30 TB of data.
### Does LanceDB support concurrent operations? [Permanent link](\#does-lancedb-support-concurrent-operations "Permanent link")
LanceDB can handle concurrent reads very well, and can scale horizontally. The main constraint is how well the [storage layer](https://lancedb.github.io/lancedb/concepts/storage/) you've chosen scales. For writes, we support concurrent writing, though too many concurrent writers can lead to failing writes as there is a limited number of times a writer retries a commit
Multiprocessing with LanceDB
For multiprocessing you should probably not use `fork` as lance is multi-threaded internally and `fork` and multi-thread do not work well. [Refer to this discussion](https://discuss.python.org/t/concerns-regarding-deprecation-of-fork-with-alive-threads/33555)
Back to top
[Ask AI](https://asklancedb.com)
[Edit this page](https://github.com/lancedb/lancedb/tree/main/docs/src/embeddings/index.md "Edit this page")
# Get Started
Due to the nature of vector embeddings, they can be used to represent any kind of data, from text to images to audio.
This makes them a very powerful tool for machine learning practitioners.
However, there's no one-size-fits-all solution for generating embeddings - there are many different libraries and APIs
(both commercial and open source) that can be used to generate embeddings from structured/unstructured data.
LanceDB supports 3 methods of working with embeddings.
1. You can manually generate embeddings for the data and queries. This is done outside of LanceDB.
2. You can use the built-in [embedding functions](embedding_functions/) to embed the data and queries in the background.
3. You can define your own [custom embedding function](custom_embedding_function/)
that extends the default embedding functions.
For python users, there is also a legacy [with\_embeddings API](legacy/).
It is retained for compatibility and will be removed in a future version.
## Quickstart [Permanent link](\#quickstart "Permanent link")
To get started with embeddings, you can use the built-in embedding functions.
### OpenAI Embedding function [Permanent link](\#openai-embedding-function "Permanent link")
LanceDB registers the OpenAI embeddings function in the registry as `openai`. You can pass any supported model name to the `create`. By default it uses `"text-embedding-ada-002"`.
[Python](#__tabbed_1_1)[TypeScript](#__tabbed_1_2)[Rust](#__tabbed_1_3)
```
import lancedb
from lancedb.pydantic import LanceModel, Vector
from lancedb.embeddings import get_registry
db = lancedb.connect("/tmp/db")
func = get_registry().get("openai").create(name="text-embedding-ada-002")
class Words(LanceModel):
text: str = func.SourceField()
vector: Vector(func.ndims()) = func.VectorField()
table = db.create_table("words", schema=Words, mode="overwrite")
table.add(
[\
{"text": "hello world"},\
{"text": "goodbye world"}\
]
)
query = "greetings"
actual = table.search(query).limit(1).to_pydantic(Words)[0]
print(actual.text)
```
```
import * as lancedb from "@lancedb/lancedb";
import "@lancedb/lancedb/embedding/openai";
import { LanceSchema, getRegistry, register } from "@lancedb/lancedb/embedding";
import { EmbeddingFunction } from "@lancedb/lancedb/embedding";
import { type Float, Float32, Utf8 } from "apache-arrow";
const db = await lancedb.connect(databaseDir);
const func = getRegistry()
.get("openai")
?.create({ model: "text-embedding-ada-002" }) as EmbeddingFunction;
const wordsSchema = LanceSchema({
text: func.sourceField(new Utf8()),
vector: func.vectorField(),
});
const tbl = await db.createEmptyTable("words", wordsSchema, {
mode: "overwrite",
});
await tbl.add([{ text: "hello world" }, { text: "goodbye world" }]);
const query = "greetings";
const actual = (await tbl.search(query).limit(1).toArray())[0];
```
```
use std::{iter::once, sync::Arc};
use arrow_array::{Float64Array, Int32Array, RecordBatch, RecordBatchIterator, StringArray};
use arrow_schema::{DataType, Field, Schema};
use futures::StreamExt;
use lancedb::{
arrow::IntoArrow,
connect,
embeddings::{openai::OpenAIEmbeddingFunction, EmbeddingDefinition, EmbeddingFunction},
query::{ExecutableQuery, QueryBase},
Result,
};
#[tokio::main]
async fn main() -> Result<()> {
let tempdir = tempfile::tempdir().unwrap();
let tempdir = tempdir.path().to_str().unwrap();
let api_key = std::env::var("OPENAI_API_KEY").expect("OPENAI_API_KEY is not set");
let embedding = Arc::new(OpenAIEmbeddingFunction::new_with_model(
api_key,
"text-embedding-3-large",
)?);
let db = connect(tempdir).execute().await?;
db.embedding_registry()
.register("openai", embedding.clone())?;
let table = db
.create_table("vectors", make_data())
.add_embedding(EmbeddingDefinition::new(
"text",
"openai",
Some("embeddings"),
))?
.execute()
.await?;
let query = Arc::new(StringArray::from_iter_values(once("something warm")));
let query_vector = embedding.compute_query_embeddings(query)?;
let mut results = table
.vector_search(query_vector)?
.limit(1)
.execute()
.await?;
let rb = results.next().await.unwrap()?;
let out = rb
.column_by_name("text")
.unwrap()
.as_any()
.downcast_ref::<StringArray>()
.unwrap();
let text = out.iter().next().unwrap().unwrap();
println!("Closest match: {}", text);
Ok(())
}
```
### Sentence Transformers Embedding function [Permanent link](\#sentence-transformers-embedding-function "Permanent link")
LanceDB registers the Sentence Transformers embeddings function in the registry as `sentence-transformers`. You can pass any supported model name to the `create`. By default it uses `"sentence-transformers/paraphrase-MiniLM-L6-v2"`.
[Python](#__tabbed_2_1)[TypeScript](#__tabbed_2_2)[Rust](#__tabbed_2_3)
```
import lancedb
from lancedb.pydantic import LanceModel, Vector
from lancedb.embeddings import get_registry
db = lancedb.connect("/tmp/db")
model = get_registry().get("sentence-transformers").create(name="BAAI/bge-small-en-v1.5", device="cpu")
class Words(LanceModel):
text: str = model.SourceField()
vector: Vector(model.ndims()) = model.VectorField()
table = db.create_table("words", schema=Words)
table.add(
[\
{"text": "hello world"},\
{"text": "goodbye world"}\
]
)
query = "greetings"
actual = table.search(query).limit(1).to_pydantic(Words)[0]
print(actual.text)
```
Coming Soon!
Coming Soon!
### Embedding function with LanceDB cloud [Permanent link](\#embedding-function-with-lancedb-cloud "Permanent link")
Embedding functions are now supported on LanceDB cloud. The embeddings will be generated on the source device and sent to the cloud. This means that the source device must have the necessary resources to generate the embeddings. Here's an example using the OpenAI embedding function:
```
import os
import lancedb
from lancedb.pydantic import LanceModel, Vector
from lancedb.embeddings import get_registry
os.environ['OPENAI_API_KEY'] = "..."
db = lancedb.connect(
uri="db://....",
api_key="sk_...",
region="us-east-1"
)
func = get_registry().get("openai").create()
class Words(LanceModel):
text: str = func.SourceField()
vector: Vector(func.ndims()) = func.VectorField()
table = db.create_table("words", schema=Words)
table.add([\
{"text": "hello world"},\
{"text": "goodbye world"}\
])
query = "greetings"
actual = table.search(query).limit(1).to_pydantic(Words)[0]
print(actual.text)
```
Back to top
[Ask AI](https://asklancedb.com)
[Edit this page](https://github.com/lancedb/lancedb/tree/main/docs/src/fts.md "Edit this page")
# Full-text search (Native FTS) [Permanent link](\#full-text-search-native-fts "Permanent link")
LanceDB provides support for full-text search via Lance, allowing you to incorporate keyword-based search (based on BM25) in your retrieval solutions.
Note
The Python SDK uses tantivy-based FTS by default, need to pass `use_tantivy=False` to use native FTS.
## Example [Permanent link](\#example "Permanent link")
Consider that we have a LanceDB table named `my_table`, whose string column `text` we want to index and query via keyword search, the FTS index must be created before you can search via keywords.
[Python](#__tabbed_1_1)[TypeScript](#__tabbed_1_2)[Rust](#__tabbed_1_3)
```
import lancedb
uri = "data/sample-lancedb"
db = lancedb.connect(uri)
table = db.create_table(
"my_table",
data=[\
{"vector": [3.1, 4.1], "text": "Frodo was a happy puppy"},\
{"vector": [5.9, 26.5], "text": "There are several kittens playing"},\
],
)
# passing `use_tantivy=False` to use lance FTS index
# `use_tantivy=True` by default
table.create_fts_index("text", use_tantivy=False)
table.search("puppy").limit(10).select(["text"]).to_list()
# [{'text': 'Frodo was a happy puppy', '_score': 0.6931471824645996}]
# ...
```
```
import * as lancedb from "@lancedb/lancedb";
const uri = "data/sample-lancedb"
const db = await lancedb.connect(uri);
const data = [\
{ vector: [3.1, 4.1], text: "Frodo was a happy puppy" },\
{ vector: [5.9, 26.5], text: "There are several kittens playing" },\
];
const tbl = await db.createTable("my_table", data, { mode: "overwrite" });
await tbl.createIndex("text", {
config: lancedb.Index.fts(),
});
await tbl
.search("puppy", queryType="fts")
.select(["text"])
.limit(10)
.toArray();
```
```
let uri = "data/sample-lancedb";
let db = connect(uri).execute().await?;
let initial_data: Box<dyn RecordBatchReader + Send> = create_some_records()?;
let tbl = db
.create_table("my_table", initial_data)
.execute()
.await?;
tbl
.create_index(&["text"], Index::FTS(FtsIndexBuilder::default()))
.execute()
.await?;
tbl
.query()
.full_text_search(FullTextSearchQuery::new("puppy".to_owned()))
.select(lancedb::query::Select::Columns(vec!["text".to_owned()]))
.limit(10)
.execute()
.await?;
```
It would search on all indexed columns by default, so it's useful when there are multiple indexed columns.
Passing `fts_columns="text"` if you want to specify the columns to search.
Note
LanceDB automatically searches on the existing FTS index if the input to the search is of type `str`. If you provide a vector as input, LanceDB will search the ANN index instead.
## Tokenization [Permanent link](\#tokenization "Permanent link")
By default the text is tokenized by splitting on punctuation and whitespaces, and would filter out words that are with length greater than 40, and lowercase all words.
Stemming is useful for improving search results by reducing words to their root form, e.g. "running" to "run". LanceDB supports stemming for multiple languages, you can specify the tokenizer name to enable stemming by the pattern `tokenizer_name="{language_code}_stem"`, e.g. `en_stem` for English.
For example, to enable stemming for English:
```
table.create_fts_index("text", use_tantivy=True, tokenizer_name="en_stem")
```
the following [languages](https://docs.rs/tantivy/latest/tantivy/tokenizer/enum.Language.html) are currently supported.
The tokenizer is customizable, you can specify how the tokenizer splits the text, and how it filters out words, etc.
For example, for language with accents, you can specify the tokenizer to use `ascii_folding` to remove accents, e.g. 'é' to 'e':
```
table.create_fts_index("text",
use_tantivy=False,
language="French",
stem=True,
ascii_folding=True)
```
## Filtering [Permanent link](\#filtering "Permanent link")
LanceDB full text search supports to filter the search results by a condition, both pre-filtering and post-filtering are supported.
This can be invoked via the familiar `where` syntax.
With pre-filtering:
[Python](#__tabbed_2_1)[TypeScript](#__tabbed_2_2)[Rust](#__tabbed_2_3)
```
table.search("puppy").limit(10).where("meta='foo'", prefilte=True).to_list()
```
```
await tbl
.search("puppy")
.select(["id", "doc"])
.limit(10)
.where("meta='foo'")
.prefilter(true)
.toArray();
```
```
table
.query()
.full_text_search(FullTextSearchQuery::new("puppy".to_owned()))
.select(lancedb::query::Select::Columns(vec!["doc".to_owned()]))
.limit(10)
.only_if("meta='foo'")
.execute()
.await?;
```
With post-filtering:
[Python](#__tabbed_3_1)[TypeScript](#__tabbed_3_2)[Rust](#__tabbed_3_3)
```
table.search("puppy").limit(10).where("meta='foo'", prefilte=False).to_list()
```
```
await tbl
.search("apple")
.select(["id", "doc"])
.limit(10)
.where("meta='foo'")
.prefilter(false)
.toArray();
```
```
table
.query()
.full_text_search(FullTextSearchQuery::new(words[0].to_owned()))
.select(lancedb::query::Select::Columns(vec!["doc".to_owned()]))
.postfilter()
.limit(10)
.only_if("meta='foo'")
.execute()
.await?;
```
## Phrase queries vs. terms queries [Permanent link](\#phrase-queries-vs-terms-queries "Permanent link")
Warn
Lance-based FTS doesn't support queries using boolean operators `OR`, `AND`.
For full-text search you can specify either a **phrase** query like `"the old man and the sea"`,
or a **terms** search query like `old man sea`. For more details on the terms
query syntax, see Tantivy's [query parser rules](https://docs.rs/tantivy/latest/tantivy/query/struct.QueryParser.html).
To search for a phrase, the index must be created with `with_position=True`:
```
table.create_fts_index("text", use_tantivy=False, with_position=True)
```
This will allow you to search for phrases, but it will also significantly increase the index size and indexing time.
## Incremental indexing [Permanent link](\#incremental-indexing "Permanent link")
LanceDB supports incremental indexing, which means you can add new records to the table without reindexing the entire table.
This can make the query more efficient, especially when the table is large and the new records are relatively small.
[Python](#__tabbed_4_1)[TypeScript](#__tabbed_4_2)[Rust](#__tabbed_4_3)
```
table.add([{"vector": [3.1, 4.1], "text": "Frodo was a happy puppy"}])
table.optimize()
```
```
await tbl.add([{ vector: [3.1, 4.1], text: "Frodo was a happy puppy" }]);
await tbl.optimize();
```
```
let more_data: Box<dyn RecordBatchReader + Send> = create_some_records()?;
tbl.add(more_data).execute().await?;
tbl.optimize(OptimizeAction::All).execute().await?;
```
Note
New data added after creating the FTS index will appear in search results while incremental index is still progress, but with increased latency due to a flat search on the unindexed portion. LanceDB Cloud automates this merging process, minimizing the impact on search speed.
Back to top
[Ask AI](https://asklancedb.com)
[Edit this page](https://github.com/lancedb/lancedb/tree/main/docs/src/integrations/index.md "Edit this page")
# Integrations [Permanent link](\#integrations "Permanent link")
LanceDB supports ingesting from and exporting to your favorite data formats across the Python and JavaScript ecosystems.
## Tools [Permanent link](\#tools "Permanent link")
LanceDB is integrated with a lot of popular AI tools, with more coming soon.
Get started using these examples and quick links.
| Integrations | |
| --- | --- |
| ### LlamaIndex<br>LlamaIndex is a simple, flexible data framework for connecting custom data sources to large language models. Llama index integrates with LanceDB as the serverless VectorDB. <br>### [Lean More](https://gpt-index.readthedocs.io/en/latest/examples/vector_stores/LanceDBIndexDemo.html) |  |
| ### Langchain<br>Langchain allows building applications with LLMs through composability <br>### [Lean More](https://lancedb.github.io/lancedb/integrations/langchain/) |  |
| ### Langchain TS<br> Javascript bindings for Langchain. It integrates with LanceDB's serverless vectordb allowing you to build powerful AI applications through composibility using only serverless functions. <br>### [Learn More](https://js.langchain.com/docs/modules/data_connection/vectorstores/integrations/lancedb) |  |
| ### Voxel51<br> It is an open source toolkit that enables you to build better computer vision workflows by improving the quality of your datasets and delivering insights about your models.<br>### [Learn More](voxel51/) |  |
| ### PromptTools<br> Offers a set of free, open-source tools for testing and experimenting with models, prompts, and configurations. The core idea is to enable developers to evaluate prompts using familiar interfaces like code and notebooks. You can use it to experiment with different configurations of LanceDB, and test how LanceDB integrates with the LLM of your choice.<br>### [Learn More](prompttools/) |  |
Back to top
[Ask AI](https://asklancedb.com)
[Edit this page](https://github.com/lancedb/lancedb/tree/main/docs/src/index.md "Edit this page")
# LanceDB [Permanent link](\#lancedb "Permanent link")
LanceDB is an open-source vector database for AI that's designed to store, manage, query and retrieve embeddings on large-scale multi-modal data. The core of LanceDB is written in Rust 🦀 and is built on top of [Lance](https://github.com/lancedb/lance), an open-source columnar data format designed for performant ML workloads and fast random access.
Both the database and the underlying data format are designed from the ground up to be **easy-to-use**, **scalable** and **cost-effective**.
## Truly multi-modal [Permanent link](\#truly-multi-modal "Permanent link")
Most existing vector databases that store and query just the embeddings and their metadata. The actual data is stored elsewhere, requiring you to manage their storage and versioning separately.
LanceDB supports storage of the _actual data itself_, alongside the embeddings and metadata. You can persist your images, videos, text documents, audio files and more in the Lance format, which provides automatic data versioning and blazing fast retrievals and filtering via LanceDB.
## Open-source and cloud solutions [Permanent link](\#open-source-and-cloud-solutions "Permanent link")
LanceDB is available in two flavors: **OSS** and **Cloud**.
LanceDB **OSS** is an **open-source**, batteries-included embedded vector database that you can run on your own infrastructure. "Embedded" means that it runs _in-process_, making it incredibly simple to self-host your own AI retrieval workflows for RAG and more. No servers, no hassle.
LanceDB **Cloud** is a SaaS (software-as-a-service) solution that runs serverless in the cloud, making the storage clearly separated from compute. It's designed to be cost-effective and highly scalable without breaking the bank. LanceDB Cloud is currently in private beta with general availability coming soon, but you can apply for early access with the private beta release by signing up below.
[Try out LanceDB Cloud](https://noteforms.com/forms/lancedb-mailing-list-cloud-kty1o5?notionforms=1&utm_source=notionforms)
## Why use LanceDB? [Permanent link](\#why-use-lancedb "Permanent link")
- Embedded (OSS) and serverless (Cloud) - no need to manage servers
- Fast production-scale vector similarity, full-text & hybrid search and a SQL query interface (via [DataFusion](https://github.com/apache/arrow-datafusion))
- Python, Javascript/Typescript, and Rust support
- Store, query & manage multi-modal data (text, images, videos, point clouds, etc.), not just the embeddings and metadata
- Tight integration with the [Arrow](https://arrow.apache.org/docs/format/Columnar.html) ecosystem, allowing true zero-copy access in shared memory with SIMD and GPU acceleration
- Automatic data versioning to manage versions of your data without needing extra infrastructure
- Disk-based index & storage, allowing for massive scalability without breaking the bank
- Ingest your favorite data formats directly, like pandas DataFrames, Pydantic objects, Polars (coming soon), and more
## Documentation guide [Permanent link](\#documentation-guide "Permanent link")
The following pages go deeper into the internal of LanceDB and how to use it.
- [Quick start](basic/): Get started with LanceDB and vector DB concepts
- [Vector search concepts](concepts/vector_search/): Understand the basics of vector search
- [Working with tables](guides/tables/): Learn how to work with tables and their associated functions
- [Indexing](ann_indexes/): Understand how to create indexes
- [Vector search](search/): Learn how to perform vector similarity search
- [Full-text search (native)](fts/): Learn how to perform full-text search
- [Full-text search (tantivy-based)](fts_tantivy/): Learn how to perform full-text search using Tantivy
- [Managing embeddings](embeddings/): Managing embeddings and the embedding functions API in LanceDB
- [Ecosystem Integrations](integrations/): Integrate LanceDB with other tools in the data ecosystem
- [Python API Reference](python/python/): Python OSS and Cloud API references
- [JavaScript API Reference](javascript/modules/): JavaScript OSS and Cloud API references
- [Rust API Reference](https://docs.rs/lancedb/latest/lancedb/index.html): Rust API reference
Back to top
[Ask AI](https://asklancedb.com)
# LanceDB MCP Server Documentation
## Overview
The LanceDB MCP (Model Control Protocol) Server provides a standardized interface for managing vector databases using LanceDB. It implements the MCP specification for vector database operations while leveraging LanceDB's efficient storage and retrieval capabilities.
## Key Features
- Embedded vector database server
- Efficient resource management
- Concurrent read support
- Automatic cleanup and garbage collection
- Error handling for common edge cases
## Server Operations
### Initialization
```python
from lancedb_mcp.server import LanceDBServer
# Initialize with default URI
server = LanceDBServer()
# Initialize with custom URI
server = LanceDBServer(uri="custom/data/path")
```
### Resource Management
The server implements efficient resource management:
- Tables are automatically cleaned up when no longer needed
- No explicit `close()` calls required
- Python's garbage collector handles resource cleanup
- References are cleared during server shutdown
### Error Handling
The server includes comprehensive error handling for:
- Non-existent tables
- Invalid vector dimensions
- Concurrent access issues
- Resource allocation failures
## Best Practices
### Server Usage
1. Initialize server with appropriate URI
2. Use batch operations for better performance
3. Handle errors appropriately
4. Allow proper cleanup during shutdown
### Performance Optimization
1. Use batch operations when possible
2. Clear unused references
3. Monitor memory usage
4. Handle cleanup properly
## Testing
The server includes comprehensive test coverage for:
- Server initialization
- Table operations
- Error handling
- Concurrent access
- Resource cleanup
For detailed test examples, see `tests/test_server.py` and `tests/test_initialization.py`.
```