This is page 1 of 2. Use http://codebase.md/ryanlisse/lancedb_mcp?lines=true&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:
--------------------------------------------------------------------------------
```
1 | 3.12
2 |
```
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
1 | # Python
2 | __pycache__/
3 | *.py[cod]
4 | *$py.class
5 | *.so
6 | .Python
7 | build/
8 | develop-eggs/
9 | dist/
10 | downloads/
11 | eggs/
12 | .eggs/
13 | lib/
14 | lib64/
15 | parts/
16 | sdist/
17 | var/
18 | wheels/
19 | *.egg-info/
20 | .installed.cfg
21 | *.egg
22 |
23 | # Virtual Environment
24 | .env
25 | .venv
26 | env/
27 | venv/
28 | ENV/
29 |
30 | # IDE
31 | .idea/
32 | .vscode/
33 | *.swp
34 | *.swo
35 |
36 | # Testing
37 | .coverage
38 | coverage.xml
39 | .pytest_cache/
40 | htmlcov/
41 |
42 |
43 |
44 | # Misc
45 | .DS_Store
46 | *.log
47 |
```
--------------------------------------------------------------------------------
/.pre-commit-config.yaml:
--------------------------------------------------------------------------------
```yaml
1 | repos:
2 | - repo: https://github.com/pre-commit/pre-commit-hooks
3 | rev: v4.5.0
4 | hooks:
5 | - id: trailing-whitespace
6 | - id: end-of-file-fixer
7 | - id: check-yaml
8 | - id: check-added-large-files
9 |
10 | - repo: https://github.com/psf/black
11 | rev: 23.12.0
12 | hooks:
13 | - id: black
14 | language_version: python3.12
15 |
16 | - repo: https://github.com/astral-sh/ruff-pre-commit
17 | rev: v0.1.8
18 | hooks:
19 | - id: ruff
20 | args: [--fix, --exit-non-zero-on-fix]
21 | - id: ruff-format
22 |
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # LanceDB MCP Server
2 |
3 | ## Overview
4 | 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.
5 |
6 | ## Components
7 |
8 | ### Resources
9 | The server exposes vector database tables as resources:
10 | - `table://{name}`: A vector database table that stores embeddings and metadata
11 | - Configurable vector dimensions
12 | - Text metadata support
13 | - Efficient similarity search capabilities
14 |
15 | ### API Endpoints
16 |
17 | #### Table Management
18 | - `POST /table`
19 | - Create a new vector table
20 | - Input:
21 | ```python
22 | {
23 | "name": "my_table", # Table name
24 | "dimension": 768 # Vector dimension
25 | }
26 | ```
27 |
28 | #### Vector Operations
29 | - `POST /table/{table_name}/vector`
30 | - Add vector data to a table
31 | - Input:
32 | ```python
33 | {
34 | "vector": [0.1, 0.2, ...], # Vector data
35 | "text": "associated text" # Metadata
36 | }
37 | ```
38 |
39 | - `POST /table/{table_name}/search`
40 | - Search for similar vectors
41 | - Input:
42 | ```python
43 | {
44 | "vector": [0.1, 0.2, ...], # Query vector
45 | "limit": 10 # Number of results
46 | }
47 | ```
48 |
49 | ## Installation
50 |
51 | ```bash
52 | # Clone the repository
53 | git clone https://github.com/yourusername/lancedb_mcp.git
54 | cd lancedb_mcp
55 |
56 | # Install dependencies using uv
57 | uv pip install -e .
58 | ```
59 |
60 | ## Usage with Claude Desktop
61 |
62 | ```bash
63 | # Add the server to your claude_desktop_config.json
64 | "mcpServers": {
65 | "lancedb": {
66 | "command": "uv",
67 | "args": [
68 | "run",
69 | "python",
70 | "-m",
71 | "lancedb_mcp",
72 | "--db-path",
73 | "~/.lancedb"
74 | ]
75 | }
76 | }
77 | ```
78 |
79 | ## Development
80 |
81 | ```bash
82 | # Install development dependencies
83 | uv pip install -e ".[dev]"
84 |
85 | # Run tests
86 | pytest
87 |
88 | # Format code
89 | black .
90 | ruff .
91 | ```
92 |
93 | ## Environment Variables
94 |
95 | - `LANCEDB_URI`: Path to LanceDB storage (default: ".lancedb")
96 |
97 | ## License
98 |
99 | This project is licensed under the MIT License. See the LICENSE file for details.
100 |
```
--------------------------------------------------------------------------------
/requirements-dev.txt:
--------------------------------------------------------------------------------
```
1 | pytest>=7.4.3
2 | pytest-asyncio>=0.23.2
3 | pytest-cov>=4.1.0
4 | httpx>=0.25.2
5 |
```
--------------------------------------------------------------------------------
/requirements.txt:
--------------------------------------------------------------------------------
```
1 | fastapi>=0.104.1
2 | lancedb>=0.4.0
3 | open-clip-torch>=2.20.0
4 | pillow>=10.1.0
5 | pydantic>=2.5.2
6 | uvicorn>=0.24.0
7 |
```
--------------------------------------------------------------------------------
/tests/conftest.py:
--------------------------------------------------------------------------------
```python
1 | """Test configuration."""
2 |
3 | import os
4 |
5 | # Set environment variables for testing
6 | os.environ["LANCEDB_URI"] = ".lancedb"
7 |
8 | # Configure pytest for async tests
9 | pytest_plugins = ["pytest_asyncio"]
10 |
```
--------------------------------------------------------------------------------
/src/lancedb_mcp/__init__.py:
--------------------------------------------------------------------------------
```python
1 | """LanceDB MCP Server."""
2 |
3 | from lancedb_mcp.models import SearchQuery, TableConfig, VectorData
4 | from lancedb_mcp.server import set_db_uri
5 |
6 | __version__ = "0.1.0"
7 |
8 | __all__ = [
9 | "SearchQuery",
10 | "TableConfig",
11 | "VectorData",
12 | "set_db_uri",
13 | ]
14 |
```
--------------------------------------------------------------------------------
/tests/test_init.py:
--------------------------------------------------------------------------------
```python
1 | """Tests for __init__.py functionality."""
2 |
3 |
4 | from lancedb_mcp import TableConfig, __version__
5 |
6 |
7 | def test_config():
8 | """Test TableConfig model."""
9 | config = TableConfig(name="test_table")
10 | assert config.name == "test_table"
11 | assert isinstance(config.dimension, int)
12 |
13 |
14 | def test_version():
15 | """Test version getter."""
16 | assert __version__ == "0.1.0"
17 |
```
--------------------------------------------------------------------------------
/src/lancedb_mcp/models.py:
--------------------------------------------------------------------------------
```python
1 | """Models for LanceDB MCP."""
2 |
3 | from lancedb.pydantic import LanceModel, Vector
4 | from pydantic import Field
5 |
6 |
7 | class TableConfig(LanceModel):
8 | """Configuration for creating a table."""
9 |
10 | name: str = Field(..., min_length=1, description="Name of the table")
11 | dimension: int = Field(default=512, gt=0, description="Vector dimension")
12 | metric: str = Field(default="cosine", description="Distance metric")
13 |
14 |
15 | class VectorData(LanceModel):
16 | """Vector data with text and optional URI."""
17 |
18 | vector: Vector = Field(..., dim=512, description="Vector data")
19 | text: str = Field(default="", description="Text description")
20 | uri: str | None = Field(default=None, description="Optional URI")
21 |
22 |
23 | class SearchQuery(LanceModel):
24 | """Search query for finding similar vectors."""
25 |
26 | vector: Vector = Field(..., dim=512, description="Query vector")
27 | limit: int = Field(default=10, gt=0, description="Maximum number of results")
28 |
```
--------------------------------------------------------------------------------
/pyproject.toml:
--------------------------------------------------------------------------------
```toml
1 | [project]
2 | name = "lancedb-mcp"
3 | version = "0.1.0"
4 | description = "LanceDB MCP Server for vector database operations"
5 | readme = "README.md"
6 | requires-python = ">=3.12"
7 | dependencies = [
8 | "lancedb>=0.12.0",
9 | "pydantic>=2.0",
10 | "mcp>=1.1.2",
11 | "numpy>=1.24.0",
12 | "fastapi>=0.100.0",
13 | "uvicorn>=0.22.0",
14 | "tomlkit>=0.12.0"
15 | ]
16 | authors = [
17 | { name = "RyanLisse", email = "[email protected]" }
18 | ]
19 |
20 | [project.optional-dependencies]
21 | dev = [
22 | "pytest>=7.4.0",
23 | "pytest-cov>=4.1.0",
24 | "pytest-asyncio>=0.21.0",
25 | "black>=23.12.0",
26 | "ruff>=0.1.8",
27 | ]
28 |
29 | [project.scripts]
30 | lancedb-mcp = "lancedb_mcp.__main__:main"
31 |
32 | [build-system]
33 | requires = ["hatchling"]
34 | build-backend = "hatchling.build"
35 |
36 | [tool.black]
37 | line-length = 88
38 | target-version = ["py312"]
39 |
40 | [tool.ruff]
41 | line-length = 88
42 | target-version = "py312"
43 | select = [
44 | "E", # pycodestyle errors
45 | "W", # pycodestyle warnings
46 | "F", # pyflakes
47 | "I", # isort
48 | "D", # pydocstyle
49 | "UP", # pyupgrade
50 | "N", # pep8-naming
51 | "B", # flake8-bugbear
52 | ]
53 | ignore = [
54 | "D203", # one-blank-line-before-class
55 | "D213", # multi-line-summary-second-line
56 | ]
57 |
58 | [tool.ruff.per-file-ignores]
59 | "tests/*" = ["D"] # Ignore docstring rules in tests
60 |
61 | [tool.pytest.ini_options]
62 | testpaths = ["tests"]
63 | python_files = ["test_*.py"]
64 | asyncio_mode = "auto"
65 | addopts = "--cov=src --cov-report=term-missing"
66 |
```
--------------------------------------------------------------------------------
/.github/workflows/ci.yml:
--------------------------------------------------------------------------------
```yaml
1 | name: CI/CD Pipeline
2 |
3 | on:
4 | push:
5 | branches: [ main ]
6 | paths-ignore:
7 | - '**.md'
8 | - 'docs/**'
9 | - '.gitignore'
10 | pull_request:
11 | branches: [ main ]
12 | paths-ignore:
13 | - '**.md'
14 | - 'docs/**'
15 | - '.gitignore'
16 |
17 | jobs:
18 | test:
19 | runs-on: ubuntu-latest
20 | strategy:
21 | fail-fast: false
22 | matrix:
23 | python-version: ["3.9", "3.10", "3.11", "3.12"]
24 |
25 | steps:
26 | - uses: actions/checkout@v4
27 |
28 | - name: Set up Python ${{ matrix.python-version }}
29 | uses: actions/setup-python@v4
30 | with:
31 | python-version: ${{ matrix.python-version }}
32 | cache: 'pip'
33 |
34 | - name: Cache dependencies
35 | uses: actions/cache@v3
36 | with:
37 | path: |
38 | ~/.cache/pip
39 | ~/.cache/pre-commit
40 | key: ${{ runner.os }}-py${{ matrix.python-version }}-${{ hashFiles('pyproject.toml') }}-${{ hashFiles('.pre-commit-config.yaml') }}
41 | restore-keys: |
42 | ${{ runner.os }}-py${{ matrix.python-version }}-
43 | ${{ runner.os }}-
44 |
45 | - name: Install dependencies
46 | run: |
47 | python -m pip install --upgrade pip
48 | pip install uv
49 | uv pip install -e ".[dev]"
50 | pip install pytest-cov pytest-xdist
51 |
52 | - name: Lint and format check
53 | run: |
54 | black . --check
55 | ruff check .
56 | mypy .
57 |
58 | - name: Run tests
59 | run: |
60 | pytest -n auto --cov=lancedb_mcp --cov-report=xml -v tests/
61 |
62 | - name: Upload coverage
63 | uses: codecov/codecov-action@v3
64 | with:
65 | file: ./coverage.xml
66 | fail_ci_if_error: true
67 |
68 | build:
69 | needs: test
70 | runs-on: ubuntu-latest
71 | if: github.event_name == 'push' && github.ref == 'refs/heads/main'
72 |
73 | steps:
74 | - uses: actions/checkout@v4
75 |
76 | - name: Set up Python
77 | uses: actions/setup-python@v4
78 | with:
79 | python-version: "3.12"
80 |
81 | - name: Install build dependencies
82 | run: |
83 | python -m pip install --upgrade pip
84 | pip install build twine
85 |
86 | - name: Build package
87 | run: python -m build
88 |
89 | - name: Check package
90 | run: twine check dist/*
91 |
```
--------------------------------------------------------------------------------
/tests/test_server.py:
--------------------------------------------------------------------------------
```python
1 | """Test server functionality."""
2 |
3 | import os
4 | import tempfile
5 |
6 | import numpy as np
7 | import pytest
8 | from lancedb_mcp.models import SearchQuery, TableConfig, VectorData
9 | from lancedb_mcp.server import set_db_uri
10 | from mcp import ClientSession, StdioServerParameters
11 | from mcp.client.stdio import stdio_client
12 |
13 |
14 | @pytest.fixture
15 | async def client():
16 | """Create a test client."""
17 | # Create a temporary directory for the test database
18 | temp_dir = tempfile.mkdtemp()
19 | test_db = os.path.join(temp_dir, "test.lance")
20 | set_db_uri(test_db)
21 |
22 | # Create server parameters
23 | server_params = StdioServerParameters(
24 | command="python",
25 | args=["-m", "lancedb_mcp.server"],
26 | env={"LANCEDB_URI": test_db},
27 | )
28 |
29 | # Create client session
30 | read, write = await stdio_client(server_params).__aenter__()
31 | session = await ClientSession(read, write).__aenter__()
32 | await session.initialize()
33 |
34 | yield session
35 |
36 | # Cleanup
37 | await session.__aexit__(None, None, None)
38 | await stdio_client(server_params).__aexit__(None, None, None)
39 | os.rmdir(temp_dir)
40 |
41 |
42 | @pytest.mark.asyncio
43 | async def test_create_table(client):
44 | """Test creating a table."""
45 | config = TableConfig(name="test_table", dimension=512)
46 | tools = await client.list_tools()
47 | assert len(tools) == 3
48 | result = await client.call_tool("create_table", {"config": config.model_dump()})
49 | assert "Table created successfully" in result[0].text
50 |
51 |
52 | @pytest.mark.asyncio
53 | async def test_add_vector(client):
54 | """Test adding a vector."""
55 | # Create table first
56 | config = TableConfig(name="test_table", dimension=512)
57 | await client.call_tool("create_table", {"config": config.model_dump()})
58 |
59 | # Add test vector
60 | vector = np.random.rand(512).tolist()
61 | data = VectorData(vector=vector, text="test vector")
62 | result = await client.call_tool(
63 | "add_vector", {"table_name": "test_table", "data": data.model_dump()}
64 | )
65 | assert "Added vector to table test_table" in result[0].text
66 |
67 |
68 | @pytest.mark.asyncio
69 | async def test_search_vectors(client):
70 | """Test searching vectors."""
71 | # Create table and add vector
72 | config = TableConfig(name="test_table", dimension=512)
73 | await client.call_tool("create_table", {"config": config.model_dump()})
74 |
75 | # Add test vector
76 | vector = np.random.rand(512).tolist()
77 | data = VectorData(vector=vector, text="test vector")
78 | await client.call_tool(
79 | "add_vector", {"table_name": "test_table", "data": data.model_dump()}
80 | )
81 |
82 | # Test search
83 | query = SearchQuery(vector=vector, limit=5)
84 | result = await client.call_tool(
85 | "search_vectors", {"table_name": "test_table", "query": query.model_dump()}
86 | )
87 | assert "test vector" in result[0].text
88 |
```
--------------------------------------------------------------------------------
/src/lancedb_mcp/server.py:
--------------------------------------------------------------------------------
```python
1 | """LanceDB MCP server."""
2 |
3 | import logging
4 | import os
5 | import pathlib
6 | from typing import Any
7 |
8 | import lancedb
9 | import mcp.server.stdio
10 | import mcp.types as types
11 | import pandas as pd
12 | from lancedb.pydantic import pydantic_to_schema
13 | from mcp.server import NotificationOptions, Server
14 | from mcp.server.models import InitializationOptions
15 |
16 | from lancedb_mcp.models import SearchQuery, TableConfig, VectorData
17 |
18 | # Configure logging
19 | logging.basicConfig(level=logging.INFO)
20 | logger = logging.getLogger(__name__)
21 |
22 | # Global database URI
23 | DB_URI = os.getenv("LANCEDB_URI", ".lancedb")
24 |
25 |
26 | def set_db_uri(uri: str) -> None:
27 | """Set the database URI."""
28 | global DB_URI
29 | DB_URI = uri
30 |
31 |
32 | def get_db() -> lancedb.DBConnection:
33 | """Get database connection."""
34 | logger.info(f"Connecting to database at {DB_URI}")
35 | try:
36 | pathlib.Path(DB_URI).parent.mkdir(parents=True, exist_ok=True)
37 | return lancedb.connect(DB_URI)
38 | except Exception as err:
39 | logger.error(f"Failed to connect to database: {err}")
40 | raise err
41 |
42 |
43 | # Create MCP server instance
44 | server = Server("lancedb-server")
45 |
46 |
47 | @server.list_tools()
48 | async def handle_list_tools() -> list[types.Tool]:
49 | """List available tools."""
50 | return [
51 | types.Tool(
52 | name="create_table",
53 | description="Create a new table",
54 | arguments=[
55 | types.ToolArgument(
56 | name="config",
57 | description="Table configuration",
58 | schema=TableConfig.model_json_schema(),
59 | )
60 | ],
61 | ),
62 | types.Tool(
63 | name="add_vector",
64 | description="Add a vector to a table",
65 | arguments=[
66 | types.ToolArgument(
67 | name="table_name", description="Name of the table", type="string"
68 | ),
69 | types.ToolArgument(
70 | name="data",
71 | description="Vector data",
72 | schema=VectorData.model_json_schema(),
73 | ),
74 | ],
75 | ),
76 | types.Tool(
77 | name="search_vectors",
78 | description="Search vectors in a table",
79 | arguments=[
80 | types.ToolArgument(
81 | name="table_name", description="Name of the table", type="string"
82 | ),
83 | types.ToolArgument(
84 | name="query",
85 | description="Search query",
86 | schema=SearchQuery.model_json_schema(),
87 | ),
88 | ],
89 | ),
90 | ]
91 |
92 |
93 | @server.call_tool()
94 | async def handle_call_tool(
95 | name: str, arguments: dict[str, Any]
96 | ) -> list[types.TextContent]:
97 | """Handle tool calls."""
98 | try:
99 | db = get_db()
100 |
101 | if name == "create_table":
102 | config = TableConfig.model_validate(arguments["config"])
103 | schema = pydantic_to_schema(VectorData)
104 | db.create_table(
105 | name=config.name,
106 | schema=schema,
107 | mode="overwrite",
108 | )
109 | logger.info(f"Created table {config.name}")
110 | return [types.TextContent(type="text", text="Table created successfully")]
111 |
112 | elif name == "add_vector":
113 | table_name = arguments["table_name"]
114 | data = VectorData.model_validate(arguments["data"])
115 | table = db.open_table(table_name)
116 | df = pd.DataFrame([data.model_dump()])
117 | table.add(df)
118 | logger.info(f"Added vector to table {table_name}")
119 | return [
120 | types.TextContent(
121 | type="text", text=f"Added vector to table {table_name}"
122 | )
123 | ]
124 |
125 | elif name == "search_vectors":
126 | table_name = arguments["table_name"]
127 | query = SearchQuery.model_validate(arguments["query"])
128 | table = db.open_table(table_name)
129 | results = table.search(query.vector).limit(query.limit).to_pandas()
130 | logger.info(f"Searched table {table_name}")
131 | results_dict = results.to_dict(orient="records")
132 | # Convert numpy arrays to lists for JSON serialization
133 | for result in results_dict:
134 | if "_distance" in result:
135 | result["score"] = float(result["_distance"])
136 | del result["_distance"]
137 | if "vector" in result:
138 | result["vector"] = result["vector"].tolist()
139 | return [types.TextContent(type="text", text=str(results_dict))]
140 |
141 | else:
142 | raise ValueError(f"Unknown tool: {name}")
143 |
144 | except FileNotFoundError:
145 | logger.error(f"Table {arguments.get('table_name')} not found")
146 | raise
147 | except Exception as err:
148 | logger.error(f"Failed to execute tool {name}: {err}")
149 | raise
150 |
151 |
152 | async def run():
153 | """Run the server."""
154 | async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
155 | await server.run(
156 | read_stream,
157 | write_stream,
158 | InitializationOptions(
159 | server_name="lancedb-server",
160 | server_version="0.1.0",
161 | capabilities=server.get_capabilities(
162 | notification_options=NotificationOptions(),
163 | experimental_capabilities={},
164 | ),
165 | ),
166 | )
167 |
168 |
169 | if __name__ == "__main__":
170 | import asyncio
171 |
172 | asyncio.run(run())
173 |
```
--------------------------------------------------------------------------------
/DOCS/lancedb_mcp_api.md:
--------------------------------------------------------------------------------
```markdown
1 | # LanceDB MCP Server API Reference
2 |
3 | ## Overview
4 |
5 | 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.
6 |
7 | ## Server Implementation
8 |
9 | ### Core Components
10 |
11 | #### Database Connection
12 | - Managed through LanceDB's Python client
13 | - Supports both local and cloud storage backends
14 | - Handles connection lifecycle and resource management
15 |
16 | #### Table Management
17 | - Creates and manages vector tables
18 | - Maintains table references and state
19 | - Handles table cleanup and optimization
20 |
21 | #### Vector Operations
22 | - Adds vectors with metadata
23 | - Performs similarity search with configurable metrics
24 | - Supports vector validation and dimension checking
25 |
26 | #### Resource Management
27 | - Tracks available tables and their states
28 | - Implements MCP resource isolation
29 | - Manages resource lifecycle
30 |
31 | ### MCP Protocol Implementation
32 |
33 | #### Server Features
34 | The server implements all required MCP features:
35 |
36 | 1. **Resources**
37 | - Vector tables as queryable resources
38 | - Resource isolation per connection
39 | - Resource state tracking
40 |
41 | 2. **Tools**
42 | - Table creation and management
43 | - Vector addition and search
44 | - Resource listing and status
45 |
46 | 3. **Capabilities**
47 | - Dynamic reporting of supported operations
48 | - Vector operation configurations
49 | - Resource management features
50 |
51 | ### API Reference
52 |
53 | #### Server Methods
54 |
55 | ##### Lifecycle Management
56 |
57 | ```python
58 | async def start(self):
59 | """Start the LanceDB server"""
60 | # Creates database directory
61 | # Establishes connection
62 | # Initializes state tracking
63 | ```
64 |
65 | ```python
66 | async def stop(self):
67 | """Stop the LanceDB server"""
68 | # Cleans up resources
69 | # Closes connections
70 | # Performs garbage collection
71 | ```
72 |
73 | ##### Table Operations
74 |
75 | ```python
76 | async def create_table(self, table_name: str, dimension: int) -> Dict[str, str]:
77 | """Create a new vector table"""
78 | # Creates table with specified dimension
79 | # Returns table metadata
80 | ```
81 |
82 | ```python
83 | async def add_vector(self, table_name: str, vector: List[float], metadata: Optional[Dict] = None):
84 | """Add vector to table"""
85 | # Validates vector dimensions
86 | # Adds vector with optional metadata
87 | ```
88 |
89 | ```python
90 | async def search_vectors(self, table_name: str, query_vector: List[float], limit: int = 10):
91 | """Search for similar vectors"""
92 | # Performs similarity search
93 | # Returns top-k results with scores
94 | ```
95 |
96 | ##### Resource Management
97 |
98 | ```python
99 | async def list_resources(self) -> List[Resource]:
100 | """List available tables"""
101 | # Returns list of available tables
102 | # Includes table metadata
103 | ```
104 |
105 | ```python
106 | async def get_implementation(self) -> Implementation:
107 | """Get server implementation details"""
108 | # Returns server name, version, vendor
109 | ```
110 |
111 | ```python
112 | async def get_capabilities(self) -> ServerCapabilities:
113 | """Get server capabilities"""
114 | # Returns supported operations
115 | # Includes tool configurations
116 | ```
117 |
118 | ### Error Types
119 |
120 | - `DatabaseError`: General database operation failures
121 | ```python
122 | class DatabaseError(Exception):
123 | """Raised when database operations fail"""
124 | ```
125 |
126 | - `TableError`: Table-specific operation failures
127 | ```python
128 | class TableError(Exception):
129 | """Raised for table operation failures"""
130 | ```
131 |
132 | - `VectorError`: Vector operation failures
133 | ```python
134 | class VectorError(Exception):
135 | """Raised for vector operation failures"""
136 | ```
137 |
138 | ### Configuration
139 |
140 | #### Database URI
141 | ```python
142 | server = LanceDBServer(
143 | db_uri="data/vectors", # Database location
144 | read_consistency_interval=None # Consistency check interval
145 | )
146 | ```
147 |
148 | #### Vector Operations
149 | ```python
150 | # Vector dimension validation
151 | vector_dim = 768 # Must match table dimension
152 | vector = [0.1] * vector_dim
153 |
154 | # Adding vectors with metadata
155 | metadata = {
156 | "id": "doc1",
157 | "text": "Sample document",
158 | "timestamp": "2024-01-01"
159 | }
160 |
161 | # Search configuration
162 | limit = 10 # Number of results
163 | metric = "L2" # Distance metric
164 | ```
165 |
166 | ### Best Practices
167 |
168 | 1. **Resource Management**
169 | - Clean up resources when no longer needed
170 | - Monitor table sizes and vector counts
171 | - Implement proper logging
172 |
173 | 2. **Vector Operations**
174 | - Validate vector dimensions before adding
175 | - Use appropriate metadata for tracking
176 | - Handle errors appropriately
177 |
178 | 3. **Performance Optimization**
179 | - Create indices for frequently searched tables
180 | - Use appropriate batch sizes for operations
181 | - Monitor and optimize resource usage
182 |
183 | ### Error Handling
184 |
185 | The server implements comprehensive error handling:
186 |
187 | 1. **Database Errors**
188 | - Connection failures
189 | - Resource allocation issues
190 | - Storage backend errors
191 |
192 | 2. **Table Errors**
193 | - Creation failures
194 | - Access permission issues
195 | - Resource conflicts
196 |
197 | 3. **Vector Errors**
198 | - Dimension mismatches
199 | - Invalid data types
200 | - Search operation failures
201 |
202 | ### Logging and Monitoring
203 |
204 | The server includes built-in logging for:
205 | - Operation status and errors
206 | - Resource usage and performance
207 | - Security-related events
208 |
209 | ### Security Considerations
210 |
211 | 1. **Resource Isolation**
212 | - Tables are isolated per connection
213 | - Resource access requires explicit consent
214 | - State is maintained per session
215 |
216 | 2. **Data Validation**
217 | - Input validation for all operations
218 | - Secure handling of metadata
219 | - Protection against invalid operations
220 |
221 | 3. **Error Handling**
222 | - Secure error messages
223 | - No sensitive data in logs
224 | - Proper cleanup on failures
225 |
226 | ## Testing
227 |
228 | The server includes comprehensive tests:
229 |
230 | 1. **Unit Tests**
231 | - Core functionality
232 | - Error handling
233 | - Edge cases
234 |
235 | 2. **Integration Tests**
236 | - End-to-end workflows
237 | - Resource management
238 | - Performance benchmarks
239 |
240 | 3. **Stress Tests**
241 | - Concurrent operations
242 | - Resource limits
243 | - Error recovery
244 |
245 | ## Contributing
246 |
247 | 1. **Development Setup**
248 | - Fork repository
249 | - Install dependencies
250 | - Set up development environment
251 |
252 | 2. **Making Changes**
253 | - Create feature branch
254 | - Follow coding standards
255 | - Add tests for new features
256 |
257 | 3. **Submitting Changes**
258 | - Create pull request
259 | - Pass all tests
260 | - Update documentation
261 |
262 | ## License
263 |
264 | This project is licensed under the MIT License.
265 |
```
--------------------------------------------------------------------------------
/DOCS/mcp_python_sdk.md:
--------------------------------------------------------------------------------
```markdown
1 | # MCP Python SDK
2 | [![PyPI][pypi-badge]][pypi-url]
3 | [![MIT licensed][mit-badge]][mit-url]
4 | [![Python Version][python-badge]][python-url]
5 | [![Documentation][docs-badge]][docs-url]
6 | [![Specification][spec-badge]][spec-url]
7 | [![GitHub Discussions][discussions-badge]][discussions-url]
8 |
9 | [pypi-badge]: https://img.shields.io/pypi/v/mcp.svg
10 | [pypi-url]: https://pypi.org/project/mcp/
11 | [mit-badge]: https://img.shields.io/pypi/l/mcp.svg
12 | [mit-url]: https://github.com/modelcontextprotocol/python-sdk/blob/main/LICENSE
13 | [python-badge]: https://img.shields.io/pypi/pyversions/mcp.svg
14 | [python-url]: https://www.python.org/downloads/
15 | [docs-badge]: https://img.shields.io/badge/docs-modelcontextprotocol.io-blue.svg
16 | [docs-url]: https://modelcontextprotocol.io
17 | [spec-badge]: https://img.shields.io/badge/spec-spec.modelcontextprotocol.io-blue.svg
18 | [spec-url]: https://spec.modelcontextprotocol.io
19 | [discussions-badge]: https://img.shields.io/github/discussions/modelcontextprotocol/python-sdk
20 | [discussions-url]: https://github.com/modelcontextprotocol/python-sdk/discussions
21 |
22 | Python implementation of the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), providing both client and server capabilities for integrating with LLM surfaces.
23 |
24 | ## Overview
25 |
26 | 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:
27 |
28 | - Build MCP clients that can connect to any MCP server
29 | - Create MCP servers that expose resources, prompts and tools
30 | - Use standard transports like stdio and SSE
31 | - Handle all MCP protocol messages and lifecycle events
32 |
33 | ## Installation
34 |
35 | We recommend the use of [uv](https://docs.astral.sh/uv/) to manage your Python projects:
36 |
37 | ```bash
38 | uv add mcp
39 | ```
40 |
41 | Alternatively, add mcp to your `requirements.txt`:
42 | ```
43 | pip install mcp
44 | # or add to requirements.txt
45 | pip install -r requirements.txt
46 | ```
47 |
48 | ## Overview
49 | 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.
50 |
51 | ### Key design principles
52 | - Servers are extremely easy to build with clear, simple interfaces
53 | - Multiple servers can be composed seamlessly through a shared protocol
54 | - Each server operates in isolation and cannot access conversation context
55 | - Features can be added progressively through capability negotiation
56 |
57 | ### Server provided primitives
58 | - [Prompts](https://modelcontextprotocol.io/docs/concepts/prompts): Templatable text
59 | - [Resources](https://modelcontextprotocol.io/docs/concepts/resources): File-like attachments
60 | - [Tools](https://modelcontextprotocol.io/docs/concepts/tools): Functions that models can call
61 | - Utilities:
62 | - Completion: Auto-completion provider for prompt arguments or resource URI templates
63 | - Logging: Logging to the client
64 | - Pagination*: Pagination for long results
65 |
66 | ### Client provided primitives
67 | - [Sampling](https://modelcontextprotocol.io/docs/concepts/sampling): Allow servers to sample using client models
68 | - Roots: Information about locations to operate on (e.g., directories)
69 |
70 | 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.
71 |
72 | ## Quick Start
73 |
74 | ### Creating a Server
75 |
76 | 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.
77 |
78 | **example_server.py**
79 |
80 | ```python
81 | # /// script
82 | # dependencies = [
83 | # "mcp"
84 | # ]
85 | # ///
86 | from mcp.server import Server, NotificationOptions
87 | from mcp.server.models import InitializationOptions
88 | import mcp.server.stdio
89 | import mcp.types as types
90 |
91 | # Create a server instance
92 | server = Server("example-server")
93 |
94 | # Add prompt capabilities
95 | @server.list_prompts()
96 | async def handle_list_prompts() -> list[types.Prompt]:
97 | return [
98 | types.Prompt(
99 | name="example-prompt",
100 | description="An example prompt template",
101 | arguments=[
102 | types.PromptArgument(
103 | name="arg1",
104 | description="Example argument",
105 | required=True
106 | )
107 | ]
108 | )
109 | ]
110 |
111 | @server.get_prompt()
112 | async def handle_get_prompt(
113 | name: str,
114 | arguments: dict[str, str] | None
115 | ) -> types.GetPromptResult:
116 | if name != "example-prompt":
117 | raise ValueError(f"Unknown prompt: {name}")
118 |
119 | return types.GetPromptResult(
120 | description="Example prompt",
121 | messages=[
122 | types.PromptMessage(
123 | role="user",
124 | content=types.TextContent(
125 | type="text",
126 | text="Example prompt text"
127 | )
128 | )
129 | ]
130 | )
131 |
132 | async def run():
133 | # Run the server as STDIO
134 | async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
135 | await server.run(
136 | read_stream,
137 | write_stream,
138 | InitializationOptions(
139 | server_name="example",
140 | server_version="0.1.0",
141 | capabilities=server.get_capabilities(
142 | notification_options=NotificationOptions(),
143 | experimental_capabilities={},
144 | )
145 | )
146 | )
147 |
148 | if __name__ == "__main__":
149 | import asyncio
150 | asyncio.run(run())
151 | ```
152 |
153 | ### Creating a Client
154 |
155 | **example_client.py**
156 |
157 | ```python
158 | from mcp import ClientSession, StdioServerParameters
159 | from mcp.client.stdio import stdio_client
160 |
161 | # Create server parameters for stdio connection
162 | server_params = StdioServerParameters(
163 | command="python", # Executable
164 | args=["example_server.py"], # Optional command line arguments
165 | env=None # Optional environment variables
166 | )
167 |
168 | async def run():
169 | async with stdio_client(server_params) as (read, write):
170 | async with ClientSession(read, write) as session:
171 | # Initialize the connection
172 | await session.initialize()
173 |
174 | # The example server only supports prompt primitives:
175 |
176 | # List available prompts
177 | prompts = await session.list_prompts()
178 |
179 | # Get a prompt
180 | prompt = await session.get_prompt("example-prompt", arguments={"arg1": "value"})
181 |
182 | """
183 | Other example calls include:
184 |
185 | # List available resources
186 | resources = await session.list_resources()
187 |
188 | # List available tools
189 | tools = await session.list_tools()
190 |
191 | # Read a resource
192 | resource = await session.read_resource("file://some/path")
193 |
194 | # Call a tool
195 | result = await session.call_tool("tool-name", arguments={"arg1": "value"})
196 | """
197 |
198 | if __name__ == "__main__":
199 | import asyncio
200 | asyncio.run(run())
201 | ```
202 |
203 | ## Primitives
204 |
205 | 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:
206 |
207 | | Primitive | Control | Description | Example Use |
208 | |-----------|-----------------------|-----------------------------------------------------|------------------------------|
209 | | Prompts | User-controlled | Interactive templates invoked by user choice | Slash commands, menu options |
210 | | Resources | Application-controlled| Contextual data managed by the client application | File contents, API responses |
211 | | Tools | Model-controlled | Functions exposed to the LLM to take actions | API calls, data updates |
212 |
213 | ### User-Controlled Primitives
214 |
215 | **Prompts** are designed to be explicitly selected by users for their interactions with LLMs.
216 |
217 | | Decorator | Description |
218 | |--------------------------|----------------------------------------|
219 | | `@server.list_prompts()` | List available prompt templates |
220 | | `@server.get_prompt()` | Get a specific prompt with arguments |
221 |
222 | ### Application-Controlled Primitives
223 |
224 | **Resources** are controlled by the client application, which decides how and when they should be used based on its own logic.
225 |
226 | | Decorator | Description |
227 | |--------------------------------|---------------------------------------|
228 | | `@server.list_resources()` | List available resources |
229 | | `@server.read_resource()` | Read a specific resource's content |
230 | | `@server.subscribe_resource()` | Subscribe to resource updates |
231 |
232 | ### Model-Controlled Primitives
233 |
234 | **Tools** are exposed to LLMs to enable automated actions, with user approval.
235 |
236 | | Decorator | Description |
237 | |------------------------|------------------------------------|
238 | | `@server.list_tools()` | List available tools |
239 | | `@server.call_tool()` | Execute a tool with arguments |
240 |
241 | ### Server Management
242 |
243 | Additional decorators for server functionality:
244 |
245 | | Decorator | Description |
246 | |-------------------------------|--------------------------------|
247 | | `@server.set_logging_level()` | Update server logging level |
248 |
249 | ### Capabilities
250 |
251 | MCP servers declare capabilities during initialization. These map to specific decorators:
252 |
253 | | Capability | Feature Flag | Decorators | Description |
254 | |-------------|------------------------------|-----------------------------------------------------------------|-------------------------------------|
255 | | `prompts` | `listChanged` | `@list_prompts`<br/>`@get_prompt` | Prompt template management |
256 | | `resources` | `subscribe`<br/>`listChanged`| `@list_resources`<br/>`@read_resource`<br/>`@subscribe_resource`| Resource exposure and updates |
257 | | `tools` | `listChanged` | `@list_tools`<br/>`@call_tool` | Tool discovery and execution |
258 | | `logging` | - | `@set_logging_level` | Server logging configuration |
259 | | `completion`| - | `@complete_argument` | Argument completion suggestions |
260 |
261 | Capabilities are negotiated during connection initialization. Servers only need to implement the decorators for capabilities they support.
262 |
263 | ## Client Interaction
264 |
265 | 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.
266 |
267 | ### Request Context
268 |
269 | The Request Context provides access to the current request and client session. It can be accessed through `server.request_context` and enables:
270 |
271 | - Sampling from the client's LLM
272 | - Sending progress updates
273 | - Logging messages
274 | - Accessing request metadata
275 |
276 | Example using request context for LLM sampling:
277 |
278 | ```python
279 | @server.call_tool()
280 | async def handle_call_tool(name: str, arguments: dict) -> list[types.TextContent]:
281 | # Access the current request context
282 | context = server.request_context
283 |
284 | # Use the session to sample from the client's LLM
285 | result = await context.session.create_message(
286 | messages=[
287 | types.SamplingMessage(
288 | role="user",
289 | content=types.TextContent(
290 | type="text",
291 | text="Analyze this data: " + json.dumps(arguments)
292 | )
293 | )
294 | ],
295 | max_tokens=100
296 | )
297 |
298 | return [types.TextContent(type="text", text=result.content.text)]
299 | ```
300 |
301 | Using request context for progress updates:
302 |
303 | ```python
304 | @server.call_tool()
305 | async def handle_call_tool(name: str, arguments: dict) -> list[types.TextContent]:
306 | context = server.request_context
307 |
308 | if progress_token := context.meta.progressToken:
309 | # Send progress notifications
310 | await context.session.send_progress_notification(
311 | progress_token=progress_token,
312 | progress=0.5,
313 | total=1.0
314 | )
315 |
316 | # Perform operation...
317 |
318 | if progress_token:
319 | await context.session.send_progress_notification(
320 | progress_token=progress_token,
321 | progress=1.0,
322 | total=1.0
323 | )
324 |
325 | return [types.TextContent(type="text", text="Operation complete")]
326 | ```
327 |
328 | The request context is automatically set for each request and provides a safe way to access the current client session and request metadata.
329 |
330 | ## Documentation
331 |
332 | - [Model Context Protocol documentation](https://modelcontextprotocol.io)
333 | - [Model Context Protocol specification](https://spec.modelcontextprotocol.io)
334 | - [Officially supported servers](https://github.com/modelcontextprotocol/servers)
335 |
336 | ## Contributing
337 |
338 | 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.
339 |
340 | ## License
341 |
342 | This project is licensed under the MIT License - see the LICENSE file for details.
343 |
```
--------------------------------------------------------------------------------
/DOCS/mcs_spec_docs.md:
--------------------------------------------------------------------------------
```markdown
1 | *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'
2 |
3 | # https://spec.modelcontextprotocol.io/ llms-full.txt
4 |
5 | [Specification](/specification/)
6 |
7 | [Revisions](/specification/revisions/)
8 |
9 | 2024-11-05 (Current)
10 |
11 | # 2024-11-05 (Current)
12 |
13 | This is the current version of the specification. This revision may continue to receive backwards compatible changes.[Specification](/specification/)
14 |
15 | Server Features
16 |
17 | # Server Features
18 |
19 | ℹ️
20 |
21 | **Protocol Revision**: 2024-11-05
22 |
23 | 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:
24 |
25 | - **Prompts**: Pre-defined templates or instructions that guide language model interactions
26 | - **Resources**: Structured data or content that provides additional context to the model
27 | - **Tools**: Executable functions that allow models to perform actions or retrieve information
28 |
29 | Each primitive can be summarized in the following control hierarchy:
30 |
31 | | Primitive | Control | Description | Example |
32 | | --- | --- | --- | --- |
33 | | Prompts | User-controlled | Interactive templates invoked by user choice | Slash commands, menu options |
34 | | Resources | Application-controlled | Contextual data attached and managed by the client | File contents, git history |
35 | | Tools | Model-controlled | Functions exposed to the LLM to take actions | API POST requests, file writing |
36 |
37 | Explore these key primitives in more detail below:
38 |
39 | [Prompts](prompts) [Resources](resources) [Tools](tools)[Specification](/specification/)
40 |
41 | Client Features
42 |
43 | # Client Features
44 |
45 | ℹ️
46 |
47 | **Protocol Revision**: 2024-11-05
48 |
49 | Clients can implement additional features to enrich connected MCP servers:
50 |
51 | [Roots](roots) [Sampling](sampling)# Specification
52 |
53 | ℹ️
54 |
55 | **Protocol Revision**: 2024-11-05
56 |
57 | [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.
58 |
59 | 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).
60 |
61 | For implementation guides and examples, visit [modelcontextprotocol.io](https://modelcontextprotocol.io).
62 |
63 | ## Overview [Permalink for this section](\#overview)
64 |
65 | MCP provides a standardized way for applications to:
66 |
67 | - Share contextual information with language models
68 | - Expose tools and capabilities to AI systems
69 | - Build composable integrations and workflows
70 |
71 | The protocol uses [JSON-RPC](https://www.jsonrpc.org/) 2.0 messages to establish communication between:
72 |
73 | - **Hosts**: LLM applications that initiate connections
74 | - **Clients**: Connectors within the host application
75 | - **Servers**: Services that provide context and capabilities
76 |
77 | 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.
78 |
79 | ## Key Details [Permalink for this section](\#key-details)
80 |
81 | ### Base Protocol [Permalink for this section](\#base-protocol)
82 |
83 | - [JSON-RPC](https://www.jsonrpc.org/) message format
84 | - Stateful connections
85 | - Server and client capability negotiation
86 |
87 | ### Features [Permalink for this section](\#features)
88 |
89 | Servers offer any of the following features to clients:
90 |
91 | - **Resources**: Context and data, for the user or the AI model to use
92 | - **Prompts**: Templated messages and workflows for users
93 | - **Tools**: Functions for the AI model to execute
94 |
95 | Clients may offer the following feature to servers:
96 |
97 | - **Sampling**: Server-initiated agentic behaviors and recursive LLM interactions
98 |
99 | ### Additional Utilities [Permalink for this section](\#additional-utilities)
100 |
101 | - Configuration
102 | - Progress tracking
103 | - Cancellation
104 | - Error reporting
105 | - Logging
106 |
107 | ## Security and Trust & Safety [Permalink for this section](\#security-and-trust--safety)
108 |
109 | 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.
110 |
111 | ### Key Principles [Permalink for this section](\#key-principles)
112 |
113 | 1. **User Consent and Control**
114 |
115 | - Users must explicitly consent to and understand all data access and operations
116 | - Users must retain control over what data is shared and what actions are taken
117 | - Implementors should provide clear UIs for reviewing and authorizing activities
118 | 2. **Data Privacy**
119 |
120 | - Hosts must obtain explicit user consent before exposing user data to servers
121 | - Hosts must not transmit resource data elsewhere without user consent
122 | - User data should be protected with appropriate access controls
123 | 3. **Tool Safety**
124 |
125 | - Tools represent arbitrary code execution and must be treated with appropriate caution
126 | - Hosts must obtain explicit user consent before invoking any tool
127 | - Users should understand what each tool does before authorizing its use
128 | 4. **LLM Sampling Controls**
129 |
130 | - Users must explicitly approve any LLM sampling requests
131 | - Users should control:
132 | - Whether sampling occurs at all
133 | - The actual prompt that will be sent
134 | - What results the server can see
135 | - The protocol intentionally limits server visibility into prompts
136 |
137 | ### Implementation Guidelines [Permalink for this section](\#implementation-guidelines)
138 |
139 | While MCP itself cannot enforce these security principles at the protocol level, implementors **SHOULD**:
140 |
141 | 1. Build robust consent and authorization flows into their applications
142 | 2. Provide clear documentation of security implications
143 | 3. Implement appropriate access controls and data protections
144 | 4. Follow security best practices in their integrations
145 | 5. Consider privacy implications in their feature designs
146 |
147 | ## Learn More [Permalink for this section](\#learn-more)
148 |
149 | Explore the detailed specification for each protocol component:
150 |
151 | [Architecture](architecture) [Base Protocol](basic) [Server Features](server) [Client Features](client) [Contributing](contributing)# Contributions
152 |
153 | 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.
154 |
155 | All contributors must adhere to our [Code of Conduct](https://github.com/modelcontextprotocol/specification/blob/main/CODE_OF_CONDUCT.md).
156 |
157 | For questions and discussions, please use [GitHub Discussions](https://github.com/modelcontextprotocol/specification/discussions).[Specification](/specification/)
158 |
159 | Base Protocol
160 |
161 | # Base Protocol
162 |
163 | ℹ️
164 |
165 | **Protocol Revision**: 2024-11-05
166 |
167 | 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:
168 |
169 | | Type | Description | Requirements |
170 | | --- | --- | --- |
171 | | `Requests` | Messages sent to initiate an operation | Must include unique ID and method name |
172 | | `Responses` | Messages sent in reply to requests | Must include same ID as request |
173 | | `Notifications` | One-way messages with no reply | Must not include an ID |
174 |
175 | **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.
176 |
177 | ## Protocol Layers [Permalink for this section](\#protocol-layers)
178 |
179 | The Model Context Protocol consists of several key components that work together:
180 |
181 | - **Base Protocol**: Core JSON-RPC message types
182 | - **Lifecycle Management**: Connection initialization, capability negotiation, and session control
183 | - **Server Features**: Resources, prompts, and tools exposed by servers
184 | - **Client Features**: Sampling and root directory lists provided by clients
185 | - **Utilities**: Cross-cutting concerns like logging and argument completion
186 |
187 | All implementations **MUST** support the base protocol and lifecycle management components. Other components **MAY** be implemented based on the specific needs of the application.
188 |
189 | 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.
190 |
191 | See the following pages for more details on the different components:
192 |
193 | [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)
194 |
195 | ## Auth [Permalink for this section](\#auth)
196 |
197 | 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!
198 |
199 | Clients and servers **MAY** negotiate their own custom authentication and authorization strategies.
200 |
201 | ## Schema [Permalink for this section](\#schema)
202 |
203 | 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.
204 |
205 | 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/)
206 |
207 | [Server Features](/specification/server/)
208 |
209 | Prompts
210 |
211 | # Prompts
212 |
213 | ℹ️
214 |
215 | **Protocol Revision**: 2024-11-05
216 |
217 | 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.
218 |
219 | ## User Interaction Model [Permalink for this section](\#user-interaction-model)
220 |
221 | 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.
222 |
223 | Typically, prompts would be triggered through user-initiated commands in the user interface, which allows users to naturally discover and invoke available prompts.
224 |
225 | For example, as slash commands:
226 |
227 | 
228 |
229 | 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.
230 |
231 | ## Capabilities [Permalink for this section](\#capabilities)
232 |
233 | Servers that support prompts **MUST** declare the `prompts` capability during [initialization](https://spec.modelcontextprotocol.io/specification/basic/lifecycle/#initialization):
234 |
235 | ```json
236 | {
237 | "capabilities": {
238 | "prompts": {
239 | "listChanged": true
240 | }
241 | }
242 | }
243 | ```
244 |
245 | `listChanged` indicates whether the server will emit notifications when the list of available prompts changes.
246 |
247 | ## Protocol Messages [Permalink for this section](\#protocol-messages)
248 |
249 | ### Listing Prompts [Permalink for this section](\#listing-prompts)
250 |
251 | To retrieve available prompts, clients send a `prompts/list` request. This operation supports [pagination](https://spec.modelcontextprotocol.io/specification/server/utilities/pagination/).
252 |
253 | **Request:**
254 |
255 | ```json
256 | {
257 | "jsonrpc": "2.0",
258 | "id": 1,
259 | "method": "prompts/list",
260 | "params": {
261 | "cursor": "optional-cursor-value"
262 | }
263 | }
264 | ```
265 |
266 | **Response:**
267 |
268 | ```json
269 | {
270 | "jsonrpc": "2.0",
271 | "id": 1,
272 | "result": {
273 | "prompts": [\
274 | {\
275 | "name": "code_review",\
276 | "description": "Asks the LLM to analyze code quality and suggest improvements",\
277 | "arguments": [\
278 | {\
279 | "name": "code",\
280 | "description": "The code to review",\
281 | "required": true\
282 | }\
283 | ]\
284 | }\
285 | ],
286 | "nextCursor": "next-page-cursor"
287 | }
288 | }
289 | ```
290 |
291 | ### Getting a Prompt [Permalink for this section](\#getting-a-prompt)
292 |
293 | 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/).
294 |
295 | **Request:**
296 |
297 | ```json
298 | {
299 | "jsonrpc": "2.0",
300 | "id": 2,
301 | "method": "prompts/get",
302 | "params": {
303 | "name": "code_review",
304 | "arguments": {
305 | "code": "def hello():\n print('world')"
306 | }
307 | }
308 | }
309 | ```
310 |
311 | **Response:**
312 |
313 | ```json
314 | {
315 | "jsonrpc": "2.0",
316 | "id": 2,
317 | "result": {
318 | "description": "Code review prompt",
319 | "messages": [\
320 | {\
321 | "role": "user",\
322 | "content": {\
323 | "type": "text",\
324 | "text": "Please review this Python code:\ndef hello():\n print('world')"\
325 | }\
326 | }\
327 | ]
328 | }
329 | }
330 | ```
331 |
332 | ### List Changed Notification [Permalink for this section](\#list-changed-notification)
333 |
334 | When the list of available prompts changes, servers that declared the `listChanged` capability **SHOULD** send a notification:
335 |
336 | ```json
337 | {
338 | "jsonrpc": "2.0",
339 | "method": "notifications/prompts/list_changed"
340 | }
341 | ```
342 |
343 | ## Message Flow [Permalink for this section](\#message-flow)
344 |
345 | ```
346 | ServerClientServerClientDiscoveryUsageChangesopt[listChanged]prompts/listList of promptsprompts/getPrompt contentprompts/list_changedprompts/listUpdated prompts
347 | ```
348 |
349 | ## Data Types [Permalink for this section](\#data-types)
350 |
351 | ### Prompt [Permalink for this section](\#prompt)
352 |
353 | A prompt definition includes:
354 |
355 | - `name`: Unique identifier for the prompt
356 | - `description`: Optional human-readable description
357 | - `arguments`: Optional list of arguments for customization
358 |
359 | ### PromptMessage [Permalink for this section](\#promptmessage)
360 |
361 | Messages in a prompt can contain:
362 |
363 | - `role`: Either “user” or “assistant” to indicate the speaker
364 | - `content`: One of the following content types:
365 |
366 | #### Text Content [Permalink for this section](\#text-content)
367 |
368 | Text content represents plain text messages:
369 |
370 | ```json
371 | {
372 | "type": "text",
373 | "text": "The text content of the message"
374 | }
375 | ```
376 |
377 | This is the most common content type used for natural language interactions.
378 |
379 | #### Image Content [Permalink for this section](\#image-content)
380 |
381 | Image content allows including visual information in messages:
382 |
383 | ```json
384 | {
385 | "type": "image",
386 | "data": "base64-encoded-image-data",
387 | "mimeType": "image/png"
388 | }
389 | ```
390 |
391 | The image data MUST be base64-encoded and include a valid MIME type. This enables multi-modal interactions where visual context is important.
392 |
393 | #### Embedded Resources [Permalink for this section](\#embedded-resources)
394 |
395 | Embedded resources allow referencing server-side resources directly in messages:
396 |
397 | ```json
398 | {
399 | "type": "resource",
400 | "resource": {
401 | "uri": "resource://example",
402 | "mimeType": "text/plain",
403 | "text": "Resource content"
404 | }
405 | }
406 | ```
407 |
408 | Resources can contain either text or binary (blob) data and MUST include:
409 |
410 | - A valid resource URI
411 | - The appropriate MIME type
412 | - Either text content or base64-encoded blob data
413 |
414 | Embedded resources enable prompts to seamlessly incorporate server-managed content like documentation, code samples, or other reference materials directly into the conversation flow.
415 |
416 | ## Error Handling [Permalink for this section](\#error-handling)
417 |
418 | Servers SHOULD return standard JSON-RPC errors for common failure cases:
419 |
420 | - Invalid prompt name: `-32602` (Invalid params)
421 | - Missing required arguments: `-32602` (Invalid params)
422 | - Internal errors: `-32603` (Internal error)
423 |
424 | ## Implementation Considerations [Permalink for this section](\#implementation-considerations)
425 |
426 | 1. Servers **SHOULD** validate prompt arguments before processing
427 | 2. Clients **SHOULD** handle pagination for large prompt lists
428 | 3. Both parties **SHOULD** respect capability negotiation
429 |
430 | ## Security [Permalink for this section](\#security)
431 |
432 | Implementations **MUST** carefully validate all prompt inputs and outputs to prevent injection attacks or unauthorized access to resources.
433 |
434 | [Resources](/specification/server/resources/ "Resources")[Specification](/specification/)
435 |
436 | [Base Protocol](/specification/basic/)
437 |
438 | [Utilities](/specification/basic/utilities/)
439 |
440 | Cancellation
441 |
442 | # Cancellation
443 |
444 | ℹ️
445 |
446 | **Protocol Revision**: 2024-11-05
447 |
448 | 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.
449 |
450 | ## Cancellation Flow [Permalink for this section](\#cancellation-flow)
451 |
452 | When a party wants to cancel an in-progress request, it sends a `notifications/cancelled` notification containing:
453 |
454 | - The ID of the request to cancel
455 | - An optional reason string that can be logged or displayed
456 |
457 | ```json
458 | {
459 | "jsonrpc": "2.0",
460 | "method": "notifications/cancelled",
461 | "params": {
462 | "requestId": "123",
463 | "reason": "User requested cancellation"
464 | }
465 | }
466 | ```
467 |
468 | ## Behavior Requirements [Permalink for this section](\#behavior-requirements)
469 |
470 | 1. Cancellation notifications **MUST** only reference requests that:
471 | - Were previously issued in the same direction
472 | - Are believed to still be in-progress
473 | 2. The `initialize` request **MUST NOT** be cancelled by clients
474 | 3. Receivers of cancellation notifications **SHOULD**:
475 | - Stop processing the cancelled request
476 | - Free associated resources
477 | - Not send a response for the cancelled request
478 | 4. Receivers **MAY** ignore cancellation notifications if:
479 | - The referenced request is unknown
480 | - Processing has already completed
481 | - The request cannot be cancelled
482 | 5. The sender of the cancellation notification **SHOULD** ignore any response to the request that arrives afterward
483 |
484 | ## Timing Considerations [Permalink for this section](\#timing-considerations)
485 |
486 | Due to network latency, cancellation notifications may arrive after request processing has completed, and potentially after a response has already been sent.
487 |
488 | Both parties **MUST** handle these race conditions gracefully:
489 |
490 | ```
491 | ServerClientServerClientProcessing startsProcessing may havecompleted beforecancellation arrivesStop processingalt[If notcompleted]Request (ID: 123)notifications/cancelled (ID: 123)
492 | ```
493 |
494 | ## Implementation Notes [Permalink for this section](\#implementation-notes)
495 |
496 | - Both parties **SHOULD** log cancellation reasons for debugging
497 | - Application UIs **SHOULD** indicate when cancellation is requested
498 |
499 | ## Error Handling [Permalink for this section](\#error-handling)
500 |
501 | Invalid cancellation notifications **SHOULD** be ignored:
502 |
503 | - Unknown request IDs
504 | - Already completed requests
505 | - Malformed notifications
506 |
507 | This maintains the “fire and forget” nature of notifications while allowing for race conditions in asynchronous communication.
508 |
509 | [Ping](/specification/basic/utilities/ping/ "Ping") [Progress](/specification/basic/utilities/progress/ "Progress")[Specification](/specification/)
510 |
511 | [Base Protocol](/specification/basic/)
512 |
513 | [Utilities](/specification/basic/utilities/)
514 |
515 | Ping
516 |
517 | # Ping
518 |
519 | ℹ️
520 |
521 | **Protocol Revision**: 2024-11-05
522 |
523 | 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.
524 |
525 | ## Overview [Permalink for this section](\#overview)
526 |
527 | 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.
528 |
529 | ## Message Format [Permalink for this section](\#message-format)
530 |
531 | A ping request is a standard JSON-RPC request with no parameters:
532 |
533 | ```json
534 | {
535 | "jsonrpc": "2.0",
536 | "id": "123",
537 | "method": "ping"
538 | }
539 | ```
540 |
541 | ## Behavior Requirements [Permalink for this section](\#behavior-requirements)
542 |
543 | 1. The receiver **MUST** respond promptly with an empty response:
544 |
545 | ```json
546 | {
547 | "jsonrpc": "2.0",
548 | "id": "123",
549 | "result": {}
550 | }
551 | ```
552 |
553 | 2. If no response is received within a reasonable timeout period, the sender **MAY**:
554 | - Consider the connection stale
555 | - Terminate the connection
556 | - Attempt reconnection procedures
557 |
558 | ## Usage Patterns [Permalink for this section](\#usage-patterns)
559 |
560 | ```
561 | ReceiverSenderReceiverSenderping requestempty response
562 | ```
563 |
564 | ## Implementation Considerations [Permalink for this section](\#implementation-considerations)
565 |
566 | - Implementations **SHOULD** periodically issue pings to detect connection health
567 | - The frequency of pings **SHOULD** be configurable
568 | - Timeouts **SHOULD** be appropriate for the network environment
569 | - Excessive pinging **SHOULD** be avoided to reduce network overhead
570 |
571 | ## Error Handling [Permalink for this section](\#error-handling)
572 |
573 | - Timeouts **SHOULD** be treated as connection failures
574 | - Multiple failed pings **MAY** trigger connection reset
575 | - Implementations **SHOULD** log ping failures for diagnostics
576 |
577 | [Cancellation](/specification/basic/utilities/cancellation/ "Cancellation")[Specification](/specification/)
578 |
579 | Architecture
580 |
581 | # Architecture
582 |
583 | 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.
584 |
585 | ## Core Components [Permalink for this section](\#core-components)
586 |
587 | ```
588 |
589 | Internet
590 | Local machine
591 | Application Host Process
592 |
593 | Server 3
594 | External APIs
595 | Remote
596 | Resource C
597 | Server 1
598 | Files & Git
599 | Server 2
600 | Database
601 | Local
602 | Resource A
603 | Local
604 | Resource B
605 | Host
606 | Client 1
607 | Client 2
608 | Client 3
609 | ```
610 |
611 | ### Host [Permalink for this section](\#host)
612 |
613 | The host process acts as the container and coordinator:
614 |
615 | - Creates and manages multiple client instances
616 | - Controls client connection permissions and lifecycle
617 | - Enforces security policies and consent requirements
618 | - Handles user authorization decisions
619 | - Coordinates AI/LLM integration and sampling
620 | - Manages context aggregation across clients
621 |
622 | ### Clients [Permalink for this section](\#clients)
623 |
624 | Each client is created by the host and maintains an isolated server connection:
625 |
626 | - Establishes one stateful session per server
627 | - Handles protocol negotiation and capability exchange
628 | - Routes protocol messages bidirectionally
629 | - Manages subscriptions and notifications
630 | - Maintains security boundaries between servers
631 |
632 | A host application creates and manages multiple clients, with each client having a 1:1 relationship with a particular server.
633 |
634 | ### Servers [Permalink for this section](\#servers)
635 |
636 | Servers provide specialized context and capabilities:
637 |
638 | - Expose resources, tools and prompts via MCP primitives
639 | - Operate independently with focused responsibilities
640 | - Request sampling through client interfaces
641 | - Must respect security constraints
642 | - Can be local processes or remote services
643 |
644 | ## Design Principles [Permalink for this section](\#design-principles)
645 |
646 | MCP is built on several key design principles that inform its architecture and implementation:
647 |
648 | 1. **Servers should be extremely easy to build**
649 |
650 | - Host applications handle complex orchestration responsibilities
651 | - Servers focus on specific, well-defined capabilities
652 | - Simple interfaces minimize implementation overhead
653 | - Clear separation enables maintainable code
654 | 2. **Servers should be highly composable**
655 |
656 | - Each server provides focused functionality in isolation
657 | - Multiple servers can be combined seamlessly
658 | - Shared protocol enables interoperability
659 | - Modular design supports extensibility
660 | 3. **Servers should not be able to read the whole conversation, nor “see into” other servers**
661 |
662 | - Servers receive only necessary contextual information
663 | - Full conversation history stays with the host
664 | - Each server connection maintains isolation
665 | - Cross-server interactions are controlled by the host
666 | - Host process enforces security boundaries
667 | 4. **Features can be added to servers and clients progressively**
668 |
669 | - Core protocol provides minimal required functionality
670 | - Additional capabilities can be negotiated as needed
671 | - Servers and clients evolve independently
672 | - Protocol designed for future extensibility
673 | - Backwards compatibility is maintained
674 |
675 | ## Message Types [Permalink for this section](\#message-types)
676 |
677 | MCP defines three core message types based on [JSON-RPC 2.0](https://www.jsonrpc.org/specification):
678 |
679 | - **Requests**: Bidirectional messages with method and parameters expecting a response
680 | - **Responses**: Successful results or errors matching specific request IDs
681 | - **Notifications**: One-way messages requiring no response
682 |
683 | Each message type follows the JSON-RPC 2.0 specification for structure and delivery semantics.
684 |
685 | ## Capability Negotiation [Permalink for this section](\#capability-negotiation)
686 |
687 | 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.
688 |
689 | - Servers declare capabilities like resource subscriptions, tool support, and prompt templates
690 | - Clients declare capabilities like sampling support and notification handling
691 | - Both parties must respect declared capabilities throughout the session
692 | - Additional capabilities can be negotiated through extensions to the protocol
693 |
694 | ```
695 | 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
696 | ```
697 |
698 | Each capability unlocks specific protocol features for use during the session. For example:
699 |
700 | - Implemented [server features](https://spec.modelcontextprotocol.io/specification/server/) must be advertised in the server’s capabilities
701 | - Emitting resource subscription notifications requires the server to declare subscription support
702 | - Tool invocation requires the server to declare tool capabilities
703 | - [Sampling](https://spec.modelcontextprotocol.io/specification/client/) requires the client to declare support in its capabilities
704 |
705 | This capability negotiation ensures clients and servers have a clear understanding of supported functionality while maintaining protocol extensibility.
706 |
707 | # LanceDB MCP Server Specification
708 |
709 | ## Overview
710 |
711 | 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.
712 |
713 | ## Server Implementation
714 |
715 | ### Core Components
716 |
717 | 1. **Server Class**: `LanceDBServer`
718 | - Extends the base MCP `Server` class
719 | - Manages database connections and operations
720 | - Handles vector table management
721 |
722 | 2. **Data Models**:
723 | - `VectorData`: Represents vector data with metadata
724 | - `DatabaseError`: Custom exception for database operations
725 |
726 | ### Server Capabilities
727 |
728 | The server provides the following capabilities:
729 |
730 | ```python
731 | {
732 | "tools": {
733 | "list": true,
734 | "get": true,
735 | "call": true
736 | },
737 | "resources": {
738 | "list": true,
739 | "get": true,
740 | "create": true,
741 | "update": true,
742 | "delete": true
743 | }
744 | }
745 | ```
746 |
747 | ## API Reference
748 |
749 | ### Vector Operations
750 |
751 | 1. **Create Table**
752 | ```python
753 | async def create_table(table_name: str, dimension: int) -> CallToolResult
754 | ```
755 | - Creates a new vector table
756 | - Parameters:
757 | - `table_name`: Name of the table
758 | - `dimension`: Vector dimension size
759 |
760 | 2. **Add Vector**
761 | ```python
762 | async def add_vector(table_name: str, vector: List[float], metadata: Optional[Dict] = None) -> CallToolResult
763 | ```
764 | - Adds a vector to a table
765 | - Parameters:
766 | - `table_name`: Target table name
767 | - `vector`: Vector data as float list
768 | - `metadata`: Optional metadata dictionary
769 |
770 | 3. **Search Vectors**
771 | ```python
772 | async def search_vectors(table_name: str, query_vector: List[float], limit: int = 10) -> CallToolResult
773 | ```
774 | - Searches for similar vectors
775 | - Parameters:
776 | - `table_name`: Table to search in
777 | - `query_vector`: Query vector
778 | - `limit`: Maximum results to return
779 |
780 | ### Resource Management
781 |
782 | 1. **List Resources**
783 | ```python
784 | async def list_resources() -> List[Resource]
785 | ```
786 | - Lists all available tables
787 | - Returns list of Resource objects
788 |
789 | 2. **Get Table**
790 | ```python
791 | async def _get_table(table_name: str) -> Any
792 | ```
793 | - Retrieves a table by name
794 | - Internal method for table access
795 |
796 | ## Logging and Monitoring
797 |
798 | The server implements comprehensive logging:
799 |
800 | 1. **Timestamp Generation**
801 | ```python
802 | def _get_timestamp() -> str
803 | ```
804 | - Generates UTC timestamps in ISO format
805 |
806 | 2. **Log Messages**
807 | ```python
808 | def _send_log(level: str, message: str)
809 | ```
810 | - Sends log messages to the client
811 | - Supports multiple log levels (info, error, etc.)
812 |
813 | ## Error Handling
814 |
815 | The server implements robust error handling:
816 |
817 | 1. **Database Errors**
818 | - Custom `DatabaseError` class
819 | - Proper error propagation
820 | - Detailed error messages
821 |
822 | 2. **Operation Results**
823 | - Success/failure status
824 | - Error messages in `CallToolResult`
825 | - Proper cleanup on errors
826 |
827 | ## Testing
828 |
829 | The server includes comprehensive tests:
830 |
831 | 1. **Unit Tests**
832 | - Server initialization
833 | - Vector operations
834 | - Error handling
835 |
836 | 2. **Integration Tests**
837 | - End-to-end workflows
838 | - Resource management
839 | - Vector operations
840 |
841 | ## Usage with MCP Inspector
842 |
843 | 1. **Starting the Server**
844 | ```bash
845 | python3 server.py
846 | ```
847 |
848 | 2. **Connecting Inspector**
849 | ```bash
850 | npx @modelcontextprotocol/inspector connect http://localhost:8000
851 | ```
852 |
853 | 3. **Available Operations**
854 | - View server capabilities
855 | - Create and manage tables
856 | - Add and search vectors
857 | - Monitor logs
858 |
859 | ## Best Practices
860 |
861 | 1. **Resource Management**
862 | - Always close database connections
863 | - Clean up temporary resources
864 | - Handle concurrent access
865 |
866 | 2. **Error Handling**
867 | - Validate inputs
868 | - Provide clear error messages
869 | - Implement proper rollbacks
870 |
871 | 3. **Performance**
872 | - Use appropriate vector dimensions
873 | - Implement batch operations
874 | - Monitor memory usage
875 |
876 | ## Dependencies
877 |
878 | - `mcp`: Core MCP implementation
879 | - `lancedb`: Vector database
880 | - `numpy`: Numerical operations
881 | - `pydantic`: Data validation
882 | - `pyarrow`: Table schemas
883 |
884 | ## Configuration
885 |
886 | The server can be configured through:
887 |
888 | 1. **Environment Variables**
889 | - Database URI
890 | - Log levels
891 | - Server settings
892 |
893 | 2. **Initialization Options**
894 | - Custom database path
895 | - Server name
896 | - Additional settings
897 |
```
--------------------------------------------------------------------------------
/DOCS/lancedb_docs.md:
--------------------------------------------------------------------------------
```markdown
1 | *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'
2 |
3 | # https://lancedb.github.io/lancedb/python/python/ llms-full.txt
4 |
5 | # 404
6 |
7 | **There isn't a GitHub Pages site here.**
8 |
9 | If you're trying to publish one,
10 | [read the full documentation](https://help.github.com/pages/)
11 | to learn how to set up **GitHub Pages**
12 | for your repository, organization, or user account.
13 |
14 |
15 | [GitHub Status](https://githubstatus.com) —
16 | [@githubstatus](https://twitter.com/githubstatus)
17 |
18 | [](/)[](/)- [Creating datasets](notebooks/quickstart.html)
19 | - [Versioning](notebooks/quickstart.html#versioning)
20 | - [Vectors](notebooks/quickstart.html#vectors)
21 | - [Read and Write Lance Dataset](read_and_write.html)
22 | - [Lance Formats](format.html)
23 | - [Arrays](arrays.html)
24 | - [Integrations](integrations/integrations.html)
25 | - [Performance Guide](performance.html)
26 | - [API References](api/api.html)
27 | - [Contributor Guide](contributing.html)
28 | - [Examples](examples/examples.html)
29 |
30 | [](_images/lance_logo.png)
31 |
32 | # Lance: modern columnar data format for ML [¶](\#lance-modern-columnar-data-format-for-ml "Permalink to this heading")
33 |
34 | Lance is a columnar data format that is easy and fast to version, query and train on.
35 | It’s designed to be used with images, videos, 3D point clouds, audio and of course tabular data.
36 | It supports any POSIX file systems, and cloud storage like AWS S3 and Google Cloud Storage.
37 | The key features of Lance include:
38 |
39 | - **High-performance random access:** 100x faster than Parquet.
40 |
41 | - **Vector search:** find nearest neighbors in under 1 millisecond and combine OLAP-queries with vector search.
42 |
43 | - **Zero-copy, automatic versioning:** manage versions of your data automatically, and reduce redundancy with zero-copy logic built-in.
44 |
45 | - **Ecosystem integrations:** Apache-Arrow, DuckDB and more on the way.
46 |
47 |
48 | ## Installation [¶](\#installation "Permalink to this heading")
49 |
50 | You can install Lance via pip:
51 |
52 | ```
53 | pip install pylance
54 |
55 | ```
56 |
57 | For the latest features and bug fixes, you can install the preview version:
58 |
59 | ```
60 | pip install --pre --extra-index-url https://pypi.fury.io/lancedb/ pylance
61 |
62 | ```
63 |
64 | Preview releases receive the same level of testing as regular releases.
65 |
66 | - [Creating datasets](notebooks/quickstart.html)
67 | - [Versioning](notebooks/quickstart.html#versioning)
68 | - [Vectors](notebooks/quickstart.html#vectors)
69 | - [Read and Write Lance Dataset](read_and_write.html)
70 | - [Lance Formats](format.html)
71 | - [Arrays](arrays.html)
72 | - [Integrations](integrations/integrations.html)
73 | - [Performance Guide](performance.html)
74 | - [API References](api/api.html)
75 | - [Contributor Guide](contributing.html)
76 | - [Examples](examples/examples.html)
77 |
78 | # Indices and tables [¶](\#indices-and-tables "Permalink to this heading")
79 |
80 | - [Index](genindex.html)
81 |
82 | - [Module Index](py-modindex.html)
83 |
84 | - [Search Page](search.html)
85 |
86 |
87 | <Page contents
88 |
89 | >Page contents:
90 |
91 | - Lance: modern columnar data format for ML
92 | - [Installation](#installation)
93 | - [Indices and tables](#indices-and-tables)
94 |
95 | [Creating datasets>](notebooks/quickstart.html)
96 |
97 | Styled using the [Piccolo Theme](https://github.com/piccolo-orm/piccolo_theme)
98 |
99 | [Edit this page](https://github.com/lancedb/lancedb/tree/main/docs/src/cloud/index.md "Edit this page")
100 |
101 | # About LanceDB Cloud [Permanent link](\#about-lancedb-cloud "Permanent link")
102 |
103 | 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.
104 |
105 | [Try out LanceDB Cloud](https://noteforms.com/forms/lancedb-mailing-list-cloud-kty1o5?notionforms=1&utm_source=notionforms)
106 |
107 | ## Architecture [Permanent link](\#architecture "Permanent link")
108 |
109 | 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.
110 |
111 | 
112 |
113 | ## Transitioning from the OSS to the Cloud version [Permanent link](\#transitioning-from-the-oss-to-the-cloud-version "Permanent link")
114 |
115 | 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.
116 |
117 | 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.
118 |
119 | Back to top
120 |
121 | [Ask AI](https://asklancedb.com)
122 |
123 | [Edit this page](https://github.com/lancedb/lancedb/tree/main/docs/src/sql.md "Edit this page")
124 |
125 | # Filtering [Permanent link](\#filtering "Permanent link")
126 |
127 | ## Pre and post-filtering [Permanent link](\#pre-and-post-filtering "Permanent link")
128 |
129 | LanceDB supports filtering of query results based on metadata fields. By default, post-filtering is
130 | performed on the top-k results returned by the vector search. However, pre-filtering is also an
131 | option that performs the filter prior to vector search. This can be useful to narrow down on
132 | the search space on a very large dataset to reduce query latency.
133 |
134 | 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.
135 |
136 | 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.
137 |
138 | [Python](#__tabbed_1_1)[TypeScript](#__tabbed_1_2)
139 |
140 | ```
141 | result = (
142 | tbl.search([0.5, 0.2])
143 | .where("id = 10", prefilter=True)
144 | .limit(1)
145 | .to_arrow()
146 | )
147 |
148 | ```
149 |
150 | [@lancedb/lancedb](#__tabbed_2_1)[vectordb (deprecated)](#__tabbed_2_2)
151 |
152 | ```
153 | const _result = await tbl
154 | .search(Array(1536).fill(0.5))
155 | .limit(1)
156 | .where("id = 10")
157 | .toArray();
158 |
159 | ```
160 |
161 | ```
162 | let result = await tbl
163 | .search(Array(1536).fill(0.5))
164 | .limit(1)
165 | .filter("id = 10")
166 | .prefilter(true)
167 | .execute();
168 |
169 | ```
170 |
171 | Note
172 |
173 | Creating a [scalar index](../guides/scalar_index/) accelerates filtering
174 |
175 | ## SQL filters [Permanent link](\#sql-filters "Permanent link")
176 |
177 | Because it's built on top of [DataFusion](https://github.com/apache/arrow-datafusion), LanceDB
178 | embraces the utilization of standard SQL expressions as predicates for filtering operations.
179 | It can be used during vector search, update, and deletion operations.
180 |
181 | Currently, Lance supports a growing list of SQL expressions.
182 |
183 | - `>`, `>=`, `<`, `<=`, `=`
184 | - `AND`, `OR`, `NOT`
185 | - `IS NULL`, `IS NOT NULL`
186 | - `IS TRUE`, `IS NOT TRUE`, `IS FALSE`, `IS NOT FALSE`
187 | - `IN`
188 | - `LIKE`, `NOT LIKE`
189 | - `CAST`
190 | - `regexp_match(column, pattern)`
191 | - [DataFusion Functions](https://arrow.apache.org/datafusion/user-guide/sql/scalar_functions.html)
192 |
193 | For example, the following filter string is acceptable:
194 |
195 | [Python](#__tabbed_3_1)[TypeScript](#__tabbed_3_2)
196 |
197 | ```
198 | tbl.search([100, 102]) \
199 | .where("(item IN ('item 0', 'item 2')) AND (id > 10)") \
200 | .to_arrow()
201 |
202 | ```
203 |
204 | [@lancedb/lancedb](#__tabbed_4_1)[vectordb (deprecated)](#__tabbed_4_2)
205 |
206 | ```
207 | const result = await (
208 | tbl.search(Array(1536).fill(0)) as lancedb.VectorQuery
209 | )
210 | .where("(item IN ('item 0', 'item 2')) AND (id > 10)")
211 | .postfilter()
212 | .toArray();
213 |
214 | ```
215 |
216 | ```
217 | await tbl
218 | .search(Array(1536).fill(0))
219 | .where("(item IN ('item 0', 'item 2')) AND (id > 10)")
220 | .execute();
221 |
222 | ```
223 |
224 | If your column name contains special characters or is a [SQL Keyword](https://docs.rs/sqlparser/latest/sqlparser/keywords/index.html),
225 | you can use backtick ( `` ` ``) to escape it. For nested fields, each segment of the
226 | path must be wrapped in backticks.
227 |
228 | [SQL](#__tabbed_5_1)
229 |
230 | ```
231 | `CUBE` = 10 AND `column name with space` IS NOT NULL
232 | AND `nested with space`.`inner with space` < 2
233 |
234 | ```
235 |
236 | Field names containing periods ( `.`) are not supported.
237 |
238 | Literals for dates, timestamps, and decimals can be written by writing the string
239 | value after the type name. For example
240 |
241 | [SQL](#__tabbed_6_1)
242 |
243 | ```
244 | date_col = date '2021-01-01'
245 | and timestamp_col = timestamp '2021-01-01 00:00:00'
246 | and decimal_col = decimal(8,3) '1.000'
247 |
248 | ```
249 |
250 | For timestamp columns, the precision can be specified as a number in the type
251 | parameter. Microsecond precision (6) is the default.
252 |
253 | | SQL | Time unit |
254 | | --- | --- |
255 | | `timestamp(0)` | Seconds |
256 | | `timestamp(3)` | Milliseconds |
257 | | `timestamp(6)` | Microseconds |
258 | | `timestamp(9)` | Nanoseconds |
259 |
260 | LanceDB internally stores data in [Apache Arrow](https://arrow.apache.org/) format.
261 | The mapping from SQL types to Arrow types is:
262 |
263 | | SQL type | Arrow type |
264 | | --- | --- |
265 | | `boolean` | `Boolean` |
266 | | `tinyint` / `tinyint unsigned` | `Int8` / `UInt8` |
267 | | `smallint` / `smallint unsigned` | `Int16` / `UInt16` |
268 | | `int` or `integer` / `int unsigned` or `integer unsigned` | `Int32` / `UInt32` |
269 | | `bigint` / `bigint unsigned` | `Int64` / `UInt64` |
270 | | `float` | `Float32` |
271 | | `double` | `Float64` |
272 | | `decimal(precision, scale)` | `Decimal128` |
273 | | `date` | `Date32` |
274 | | `timestamp` | `Timestamp` [1](#fn:1) |
275 | | `string` | `Utf8` |
276 | | `binary` | `Binary` |
277 |
278 | ## Filtering without Vector Search [Permanent link](\#filtering-without-vector-search "Permanent link")
279 |
280 | You can also filter your data without search.
281 |
282 | [Python](#__tabbed_7_1)[TypeScript](#__tabbed_7_2)
283 |
284 | ```
285 | tbl.search().where("id = 10").limit(10).to_arrow()
286 |
287 | ```
288 |
289 | [@lancedb/lancedb](#__tabbed_8_1)[vectordb (deprecated)](#__tabbed_8_2)
290 |
291 | ```
292 | await tbl.query().where("id = 10").limit(10).toArray();
293 |
294 | ```
295 |
296 | ```
297 | await tbl.filter("id = 10").limit(10).execute();
298 |
299 | ```
300 |
301 | 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.
302 |
303 | * * *
304 |
305 | 1. See precision mapping in previous table. [↩](#fnref:1 "Jump back to footnote 1 in the text")
306 |
307 |
308 | Back to top
309 |
310 | [Ask AI](https://asklancedb.com)
311 |
312 | [Edit this page](https://github.com/lancedb/lancedb/tree/main/docs/src/reranking/index.md "Edit this page")
313 |
314 | # Quickstart
315 |
316 | 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.
317 |
318 | LanceDB comes with some built-in rerankers. Some of the rerankers that are available in LanceDB are:
319 |
320 | | Reranker | Description | Supported Query Types |
321 | | --- | --- | --- |
322 | | `LinearCombinationReranker` | Reranks search results based on a linear combination of FTS and vector search scores | Hybrid |
323 | | `CohereReranker` | Uses cohere Reranker API to rerank results | Vector, FTS, Hybrid |
324 | | `CrossEncoderReranker` | Uses a cross-encoder model to rerank search results | Vector, FTS, Hybrid |
325 | | `ColbertReranker` | Uses a colbert model to rerank search results | Vector, FTS, Hybrid |
326 | | `OpenaiReranker`(Experimental) | Uses OpenAI's chat model to rerank search results | Vector, FTS, Hybrid |
327 | | `VoyageAIReranker` | Uses voyageai Reranker API to rerank results | Vector, FTS, Hybrid |
328 |
329 | ## Using a Reranker [Permanent link](\#using-a-reranker "Permanent link")
330 |
331 | 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.
332 |
333 | ```
334 | import lancedb
335 | from lancedb.embeddings import get_registry
336 | from lancedb.pydantic import LanceModel, Vector
337 | from lancedb.rerankers import CohereReranker
338 |
339 | embedder = get_registry().get("sentence-transformers").create()
340 | db = lancedb.connect("~/.lancedb")
341 |
342 | class Schema(LanceModel):
343 | text: str = embedder.SourceField()
344 | vector: Vector(embedder.ndims()) = embedder.VectorField()
345 |
346 | data = [\
347 | {"text": "hello world"},\
348 | {"text": "goodbye world"}\
349 | ]
350 | tbl = db.create_table("test", data)
351 | reranker = CohereReranker(api_key="your_api_key")
352 |
353 | # Run vector search with a reranker
354 | result = tbl.query("hello").rerank(reranker).to_list()
355 |
356 | # Run FTS search with a reranker
357 | result = tbl.query("hello", query_type="fts").rerank(reranker).to_list()
358 |
359 | # Run hybrid search with a reranker
360 | tbl.create_fts_index("text")
361 | result = tbl.query("hello", query_type="hybrid").rerank(reranker).to_list()
362 |
363 | ```
364 |
365 | ### Multi-vector reranking [Permanent link](\#multi-vector-reranking "Permanent link")
366 |
367 | 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`:
368 |
369 | ```
370 | from lancedb.rerankers import CrossEncoderReranker
371 |
372 | reranker = CrossEncoderReranker()
373 |
374 | query = "hello"
375 |
376 | res1 = table.search(query, vector_column_name="vector").limit(3)
377 | res2 = table.search(query, vector_column_name="text_vector").limit(3)
378 | res3 = table.search(query, vector_column_name="meta_vector").limit(3)
379 |
380 | reranked = reranker.rerank_multivector([res1, res2, res3], deduplicate=True)
381 |
382 | ```
383 |
384 | ## Available Rerankers [Permanent link](\#available-rerankers "Permanent link")
385 |
386 | LanceDB comes with some built-in rerankers. Here are some of the rerankers that are available in LanceDB:
387 |
388 | - [Cohere Reranker](cohere/)
389 | - [Cross Encoder Reranker](cross_encoder/)
390 | - [ColBERT Reranker](colbert/)
391 | - [OpenAI Reranker](openai/)
392 | - [Linear Combination Reranker](linear_combination/)
393 | - [Jina Reranker](jina/)
394 | - [AnswerDotAI Rerankers](answerdotai/)
395 | - [Reciprocal Rank Fusion Reranker](rrf/)
396 | - [VoyageAI Reranker](voyageai/)
397 |
398 | ## Creating Custom Rerankers [Permanent link](\#creating-custom-rerankers "Permanent link")
399 |
400 | 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.
401 |
402 | Back to top
403 |
404 | [Ask AI](https://asklancedb.com)
405 |
406 | [Edit this page](https://github.com/lancedb/lancedb/tree/main/docs/src/faq.md "Edit this page")
407 |
408 | # 💭 FAQs
409 |
410 | This section covers some common questions and issues that you may encounter when using LanceDB.
411 |
412 | ### Is LanceDB open source? [Permanent link](\#is-lancedb-open-source "Permanent link")
413 |
414 | 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.
415 |
416 | ### What is the difference between Lance and LanceDB? [Permanent link](\#what-is-the-difference-between-lance-and-lancedb "Permanent link")
417 |
418 | [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.
419 |
420 | 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.
421 |
422 | ### Why invent another data format instead of using Parquet? [Permanent link](\#why-invent-another-data-format-instead-of-using-parquet "Permanent link")
423 |
424 | 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.
425 |
426 | ### Why build in Rust? 🦀 [Permanent link](\#why-build-in-rust "Permanent link")
427 |
428 | 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.
429 |
430 | ### What is the difference between LanceDB OSS and LanceDB Cloud? [Permanent link](\#what-is-the-difference-between-lancedb-oss-and-lancedb-cloud "Permanent link")
431 |
432 | 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.
433 |
434 | 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.
435 |
436 | Both flavors of LanceDB benefit from the blazing fast Lance data format and are built on the same open source foundations.
437 |
438 | ### What makes LanceDB different? [Permanent link](\#what-makes-lancedb-different "Permanent link")
439 |
440 | 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.
441 |
442 | 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.
443 |
444 | ### How large of a dataset can LanceDB handle? [Permanent link](\#how-large-of-a-dataset-can-lancedb-handle "Permanent link")
445 |
446 | 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.
447 |
448 | ### 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")
449 |
450 | 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.
451 |
452 | 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.
453 |
454 | ### Does LanceDB support full-text search? [Permanent link](\#does-lancedb-support-full-text-search "Permanent link")
455 |
456 | 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)
457 |
458 | ### How can I speed up data inserts? [Permanent link](\#how-can-i-speed-up-data-inserts "Permanent link")
459 |
460 | 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.
461 |
462 | ### 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")
463 |
464 | 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.
465 |
466 | 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.
467 |
468 | ### 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")
469 |
470 | 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).
471 |
472 | 
473 |
474 | ### How do I connect to MinIO? [Permanent link](\#how-do-i-connect-to-minio "Permanent link")
475 |
476 | MinIO supports an S3 compatible API. In order to connect to a MinIO instance, you need to:
477 |
478 | - Set the envvar `AWS_ENDPOINT` to the URL of your MinIO API
479 | - Set the envvars `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` with your MinIO credential
480 | - Call `lancedb.connect("s3://minio_bucket_name")`
481 |
482 | ### Where can I find benchmarks for LanceDB? [Permanent link](\#where-can-i-find-benchmarks-for-lancedb "Permanent link")
483 |
484 | Refer to this [post](https://blog.lancedb.com/benchmarking-lancedb-92b01032874a) for recent benchmarks.
485 |
486 | ### How much data can LanceDB practically manage without effecting performance? [Permanent link](\#how-much-data-can-lancedb-practically-manage-without-effecting-performance "Permanent link")
487 |
488 | We target good performance on ~10-50 billion rows and ~10-30 TB of data.
489 |
490 | ### Does LanceDB support concurrent operations? [Permanent link](\#does-lancedb-support-concurrent-operations "Permanent link")
491 |
492 | 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
493 |
494 | Multiprocessing with LanceDB
495 |
496 | 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)
497 |
498 | Back to top
499 |
500 | [Ask AI](https://asklancedb.com)
501 |
502 | [Edit this page](https://github.com/lancedb/lancedb/tree/main/docs/src/embeddings/index.md "Edit this page")
503 |
504 | # Get Started
505 |
506 | Due to the nature of vector embeddings, they can be used to represent any kind of data, from text to images to audio.
507 | This makes them a very powerful tool for machine learning practitioners.
508 | However, there's no one-size-fits-all solution for generating embeddings - there are many different libraries and APIs
509 | (both commercial and open source) that can be used to generate embeddings from structured/unstructured data.
510 |
511 | LanceDB supports 3 methods of working with embeddings.
512 |
513 | 1. You can manually generate embeddings for the data and queries. This is done outside of LanceDB.
514 | 2. You can use the built-in [embedding functions](embedding_functions/) to embed the data and queries in the background.
515 | 3. You can define your own [custom embedding function](custom_embedding_function/)
516 | that extends the default embedding functions.
517 |
518 | For python users, there is also a legacy [with\_embeddings API](legacy/).
519 | It is retained for compatibility and will be removed in a future version.
520 |
521 | ## Quickstart [Permanent link](\#quickstart "Permanent link")
522 |
523 | To get started with embeddings, you can use the built-in embedding functions.
524 |
525 | ### OpenAI Embedding function [Permanent link](\#openai-embedding-function "Permanent link")
526 |
527 | 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"`.
528 |
529 | [Python](#__tabbed_1_1)[TypeScript](#__tabbed_1_2)[Rust](#__tabbed_1_3)
530 |
531 | ```
532 | import lancedb
533 | from lancedb.pydantic import LanceModel, Vector
534 | from lancedb.embeddings import get_registry
535 |
536 | db = lancedb.connect("/tmp/db")
537 | func = get_registry().get("openai").create(name="text-embedding-ada-002")
538 |
539 | class Words(LanceModel):
540 | text: str = func.SourceField()
541 | vector: Vector(func.ndims()) = func.VectorField()
542 |
543 | table = db.create_table("words", schema=Words, mode="overwrite")
544 | table.add(
545 | [\
546 | {"text": "hello world"},\
547 | {"text": "goodbye world"}\
548 | ]
549 | )
550 |
551 | query = "greetings"
552 | actual = table.search(query).limit(1).to_pydantic(Words)[0]
553 | print(actual.text)
554 |
555 | ```
556 |
557 | ```
558 | import * as lancedb from "@lancedb/lancedb";
559 | import "@lancedb/lancedb/embedding/openai";
560 | import { LanceSchema, getRegistry, register } from "@lancedb/lancedb/embedding";
561 | import { EmbeddingFunction } from "@lancedb/lancedb/embedding";
562 | import { type Float, Float32, Utf8 } from "apache-arrow";
563 | const db = await lancedb.connect(databaseDir);
564 | const func = getRegistry()
565 | .get("openai")
566 | ?.create({ model: "text-embedding-ada-002" }) as EmbeddingFunction;
567 |
568 | const wordsSchema = LanceSchema({
569 | text: func.sourceField(new Utf8()),
570 | vector: func.vectorField(),
571 | });
572 | const tbl = await db.createEmptyTable("words", wordsSchema, {
573 | mode: "overwrite",
574 | });
575 | await tbl.add([{ text: "hello world" }, { text: "goodbye world" }]);
576 |
577 | const query = "greetings";
578 | const actual = (await tbl.search(query).limit(1).toArray())[0];
579 |
580 | ```
581 |
582 | ```
583 | use std::{iter::once, sync::Arc};
584 |
585 | use arrow_array::{Float64Array, Int32Array, RecordBatch, RecordBatchIterator, StringArray};
586 | use arrow_schema::{DataType, Field, Schema};
587 | use futures::StreamExt;
588 | use lancedb::{
589 | arrow::IntoArrow,
590 | connect,
591 | embeddings::{openai::OpenAIEmbeddingFunction, EmbeddingDefinition, EmbeddingFunction},
592 | query::{ExecutableQuery, QueryBase},
593 | Result,
594 | };
595 |
596 | #[tokio::main]
597 | async fn main() -> Result<()> {
598 | let tempdir = tempfile::tempdir().unwrap();
599 | let tempdir = tempdir.path().to_str().unwrap();
600 | let api_key = std::env::var("OPENAI_API_KEY").expect("OPENAI_API_KEY is not set");
601 | let embedding = Arc::new(OpenAIEmbeddingFunction::new_with_model(
602 | api_key,
603 | "text-embedding-3-large",
604 | )?);
605 |
606 | let db = connect(tempdir).execute().await?;
607 | db.embedding_registry()
608 | .register("openai", embedding.clone())?;
609 |
610 | let table = db
611 | .create_table("vectors", make_data())
612 | .add_embedding(EmbeddingDefinition::new(
613 | "text",
614 | "openai",
615 | Some("embeddings"),
616 | ))?
617 | .execute()
618 | .await?;
619 |
620 | let query = Arc::new(StringArray::from_iter_values(once("something warm")));
621 | let query_vector = embedding.compute_query_embeddings(query)?;
622 | let mut results = table
623 | .vector_search(query_vector)?
624 | .limit(1)
625 | .execute()
626 | .await?;
627 |
628 | let rb = results.next().await.unwrap()?;
629 | let out = rb
630 | .column_by_name("text")
631 | .unwrap()
632 | .as_any()
633 | .downcast_ref::<StringArray>()
634 | .unwrap();
635 | let text = out.iter().next().unwrap().unwrap();
636 | println!("Closest match: {}", text);
637 | Ok(())
638 | }
639 |
640 | ```
641 |
642 | ### Sentence Transformers Embedding function [Permanent link](\#sentence-transformers-embedding-function "Permanent link")
643 |
644 | 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"`.
645 |
646 | [Python](#__tabbed_2_1)[TypeScript](#__tabbed_2_2)[Rust](#__tabbed_2_3)
647 |
648 | ```
649 | import lancedb
650 | from lancedb.pydantic import LanceModel, Vector
651 | from lancedb.embeddings import get_registry
652 |
653 | db = lancedb.connect("/tmp/db")
654 | model = get_registry().get("sentence-transformers").create(name="BAAI/bge-small-en-v1.5", device="cpu")
655 |
656 | class Words(LanceModel):
657 | text: str = model.SourceField()
658 | vector: Vector(model.ndims()) = model.VectorField()
659 |
660 | table = db.create_table("words", schema=Words)
661 | table.add(
662 | [\
663 | {"text": "hello world"},\
664 | {"text": "goodbye world"}\
665 | ]
666 | )
667 |
668 | query = "greetings"
669 | actual = table.search(query).limit(1).to_pydantic(Words)[0]
670 | print(actual.text)
671 |
672 | ```
673 |
674 | Coming Soon!
675 |
676 | Coming Soon!
677 |
678 | ### Embedding function with LanceDB cloud [Permanent link](\#embedding-function-with-lancedb-cloud "Permanent link")
679 |
680 | 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:
681 |
682 | ```
683 | import os
684 | import lancedb
685 | from lancedb.pydantic import LanceModel, Vector
686 | from lancedb.embeddings import get_registry
687 | os.environ['OPENAI_API_KEY'] = "..."
688 |
689 | db = lancedb.connect(
690 | uri="db://....",
691 | api_key="sk_...",
692 | region="us-east-1"
693 | )
694 | func = get_registry().get("openai").create()
695 |
696 | class Words(LanceModel):
697 | text: str = func.SourceField()
698 | vector: Vector(func.ndims()) = func.VectorField()
699 |
700 | table = db.create_table("words", schema=Words)
701 | table.add([\
702 | {"text": "hello world"},\
703 | {"text": "goodbye world"}\
704 | ])
705 |
706 | query = "greetings"
707 | actual = table.search(query).limit(1).to_pydantic(Words)[0]
708 | print(actual.text)
709 |
710 | ```
711 |
712 | Back to top
713 |
714 | [Ask AI](https://asklancedb.com)
715 |
716 | [Edit this page](https://github.com/lancedb/lancedb/tree/main/docs/src/fts.md "Edit this page")
717 |
718 | # Full-text search (Native FTS) [Permanent link](\#full-text-search-native-fts "Permanent link")
719 |
720 | LanceDB provides support for full-text search via Lance, allowing you to incorporate keyword-based search (based on BM25) in your retrieval solutions.
721 |
722 | Note
723 |
724 | The Python SDK uses tantivy-based FTS by default, need to pass `use_tantivy=False` to use native FTS.
725 |
726 | ## Example [Permanent link](\#example "Permanent link")
727 |
728 | 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.
729 |
730 | [Python](#__tabbed_1_1)[TypeScript](#__tabbed_1_2)[Rust](#__tabbed_1_3)
731 |
732 | ```
733 | import lancedb
734 |
735 | uri = "data/sample-lancedb"
736 | db = lancedb.connect(uri)
737 |
738 | table = db.create_table(
739 | "my_table",
740 | data=[\
741 | {"vector": [3.1, 4.1], "text": "Frodo was a happy puppy"},\
742 | {"vector": [5.9, 26.5], "text": "There are several kittens playing"},\
743 | ],
744 | )
745 |
746 | # passing `use_tantivy=False` to use lance FTS index
747 | # `use_tantivy=True` by default
748 | table.create_fts_index("text", use_tantivy=False)
749 | table.search("puppy").limit(10).select(["text"]).to_list()
750 | # [{'text': 'Frodo was a happy puppy', '_score': 0.6931471824645996}]
751 | # ...
752 |
753 | ```
754 |
755 | ```
756 | import * as lancedb from "@lancedb/lancedb";
757 | const uri = "data/sample-lancedb"
758 | const db = await lancedb.connect(uri);
759 |
760 | const data = [\
761 | { vector: [3.1, 4.1], text: "Frodo was a happy puppy" },\
762 | { vector: [5.9, 26.5], text: "There are several kittens playing" },\
763 | ];
764 | const tbl = await db.createTable("my_table", data, { mode: "overwrite" });
765 | await tbl.createIndex("text", {
766 | config: lancedb.Index.fts(),
767 | });
768 |
769 | await tbl
770 | .search("puppy", queryType="fts")
771 | .select(["text"])
772 | .limit(10)
773 | .toArray();
774 |
775 | ```
776 |
777 | ```
778 | let uri = "data/sample-lancedb";
779 | let db = connect(uri).execute().await?;
780 | let initial_data: Box<dyn RecordBatchReader + Send> = create_some_records()?;
781 | let tbl = db
782 | .create_table("my_table", initial_data)
783 | .execute()
784 | .await?;
785 | tbl
786 | .create_index(&["text"], Index::FTS(FtsIndexBuilder::default()))
787 | .execute()
788 | .await?;
789 |
790 | tbl
791 | .query()
792 | .full_text_search(FullTextSearchQuery::new("puppy".to_owned()))
793 | .select(lancedb::query::Select::Columns(vec!["text".to_owned()]))
794 | .limit(10)
795 | .execute()
796 | .await?;
797 |
798 | ```
799 |
800 | It would search on all indexed columns by default, so it's useful when there are multiple indexed columns.
801 |
802 | Passing `fts_columns="text"` if you want to specify the columns to search.
803 |
804 | Note
805 |
806 | 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.
807 |
808 | ## Tokenization [Permanent link](\#tokenization "Permanent link")
809 |
810 | 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.
811 |
812 | 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.
813 |
814 | For example, to enable stemming for English:
815 |
816 | ```
817 | table.create_fts_index("text", use_tantivy=True, tokenizer_name="en_stem")
818 |
819 | ```
820 |
821 | the following [languages](https://docs.rs/tantivy/latest/tantivy/tokenizer/enum.Language.html) are currently supported.
822 |
823 | The tokenizer is customizable, you can specify how the tokenizer splits the text, and how it filters out words, etc.
824 |
825 | For example, for language with accents, you can specify the tokenizer to use `ascii_folding` to remove accents, e.g. 'é' to 'e':
826 |
827 | ```
828 | table.create_fts_index("text",
829 | use_tantivy=False,
830 | language="French",
831 | stem=True,
832 | ascii_folding=True)
833 |
834 | ```
835 |
836 | ## Filtering [Permanent link](\#filtering "Permanent link")
837 |
838 | LanceDB full text search supports to filter the search results by a condition, both pre-filtering and post-filtering are supported.
839 |
840 | This can be invoked via the familiar `where` syntax.
841 |
842 | With pre-filtering:
843 |
844 | [Python](#__tabbed_2_1)[TypeScript](#__tabbed_2_2)[Rust](#__tabbed_2_3)
845 |
846 | ```
847 | table.search("puppy").limit(10).where("meta='foo'", prefilte=True).to_list()
848 |
849 | ```
850 |
851 | ```
852 | await tbl
853 | .search("puppy")
854 | .select(["id", "doc"])
855 | .limit(10)
856 | .where("meta='foo'")
857 | .prefilter(true)
858 | .toArray();
859 |
860 | ```
861 |
862 | ```
863 | table
864 | .query()
865 | .full_text_search(FullTextSearchQuery::new("puppy".to_owned()))
866 | .select(lancedb::query::Select::Columns(vec!["doc".to_owned()]))
867 | .limit(10)
868 | .only_if("meta='foo'")
869 | .execute()
870 | .await?;
871 |
872 | ```
873 |
874 | With post-filtering:
875 |
876 | [Python](#__tabbed_3_1)[TypeScript](#__tabbed_3_2)[Rust](#__tabbed_3_3)
877 |
878 | ```
879 | table.search("puppy").limit(10).where("meta='foo'", prefilte=False).to_list()
880 |
881 | ```
882 |
883 | ```
884 | await tbl
885 | .search("apple")
886 | .select(["id", "doc"])
887 | .limit(10)
888 | .where("meta='foo'")
889 | .prefilter(false)
890 | .toArray();
891 |
892 | ```
893 |
894 | ```
895 | table
896 | .query()
897 | .full_text_search(FullTextSearchQuery::new(words[0].to_owned()))
898 | .select(lancedb::query::Select::Columns(vec!["doc".to_owned()]))
899 | .postfilter()
900 | .limit(10)
901 | .only_if("meta='foo'")
902 | .execute()
903 | .await?;
904 |
905 | ```
906 |
907 | ## Phrase queries vs. terms queries [Permanent link](\#phrase-queries-vs-terms-queries "Permanent link")
908 |
909 | Warn
910 |
911 | Lance-based FTS doesn't support queries using boolean operators `OR`, `AND`.
912 |
913 | For full-text search you can specify either a **phrase** query like `"the old man and the sea"`,
914 | or a **terms** search query like `old man sea`. For more details on the terms
915 | query syntax, see Tantivy's [query parser rules](https://docs.rs/tantivy/latest/tantivy/query/struct.QueryParser.html).
916 |
917 | To search for a phrase, the index must be created with `with_position=True`:
918 |
919 | ```
920 | table.create_fts_index("text", use_tantivy=False, with_position=True)
921 |
922 | ```
923 |
924 | This will allow you to search for phrases, but it will also significantly increase the index size and indexing time.
925 |
926 | ## Incremental indexing [Permanent link](\#incremental-indexing "Permanent link")
927 |
928 | LanceDB supports incremental indexing, which means you can add new records to the table without reindexing the entire table.
929 |
930 | This can make the query more efficient, especially when the table is large and the new records are relatively small.
931 |
932 | [Python](#__tabbed_4_1)[TypeScript](#__tabbed_4_2)[Rust](#__tabbed_4_3)
933 |
934 | ```
935 | table.add([{"vector": [3.1, 4.1], "text": "Frodo was a happy puppy"}])
936 | table.optimize()
937 |
938 | ```
939 |
940 | ```
941 | await tbl.add([{ vector: [3.1, 4.1], text: "Frodo was a happy puppy" }]);
942 | await tbl.optimize();
943 |
944 | ```
945 |
946 | ```
947 | let more_data: Box<dyn RecordBatchReader + Send> = create_some_records()?;
948 | tbl.add(more_data).execute().await?;
949 | tbl.optimize(OptimizeAction::All).execute().await?;
950 |
951 | ```
952 |
953 | Note
954 |
955 | 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.
956 |
957 | Back to top
958 |
959 | [Ask AI](https://asklancedb.com)
960 |
961 | [Edit this page](https://github.com/lancedb/lancedb/tree/main/docs/src/integrations/index.md "Edit this page")
962 |
963 | # Integrations [Permanent link](\#integrations "Permanent link")
964 |
965 | LanceDB supports ingesting from and exporting to your favorite data formats across the Python and JavaScript ecosystems.
966 |
967 | 
968 |
969 | ## Tools [Permanent link](\#tools "Permanent link")
970 |
971 | LanceDB is integrated with a lot of popular AI tools, with more coming soon.
972 | Get started using these examples and quick links.
973 |
974 | | Integrations | |
975 | | --- | --- |
976 | | ### 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) |  |
977 | | ### Langchain<br>Langchain allows building applications with LLMs through composability <br>### [Lean More](https://lancedb.github.io/lancedb/integrations/langchain/) |  |
978 | | ### 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) |  |
979 | | ### 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/) |  |
980 | | ### 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/) |  |
981 |
982 | Back to top
983 |
984 | [Ask AI](https://asklancedb.com)
985 |
986 | [Edit this page](https://github.com/lancedb/lancedb/tree/main/docs/src/index.md "Edit this page")
987 |
988 | # LanceDB [Permanent link](\#lancedb "Permanent link")
989 |
990 | 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.
991 |
992 | Both the database and the underlying data format are designed from the ground up to be **easy-to-use**, **scalable** and **cost-effective**.
993 |
994 | 
995 |
996 | ## Truly multi-modal [Permanent link](\#truly-multi-modal "Permanent link")
997 |
998 | 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.
999 |
1000 | 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.
1001 |
1002 | ## Open-source and cloud solutions [Permanent link](\#open-source-and-cloud-solutions "Permanent link")
1003 |
1004 | LanceDB is available in two flavors: **OSS** and **Cloud**.
1005 |
1006 | 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.
1007 |
1008 | 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.
1009 |
1010 | [Try out LanceDB Cloud](https://noteforms.com/forms/lancedb-mailing-list-cloud-kty1o5?notionforms=1&utm_source=notionforms)
1011 |
1012 | ## Why use LanceDB? [Permanent link](\#why-use-lancedb "Permanent link")
1013 |
1014 | - Embedded (OSS) and serverless (Cloud) - no need to manage servers
1015 |
1016 | - Fast production-scale vector similarity, full-text & hybrid search and a SQL query interface (via [DataFusion](https://github.com/apache/arrow-datafusion))
1017 |
1018 | - Python, Javascript/Typescript, and Rust support
1019 |
1020 | - Store, query & manage multi-modal data (text, images, videos, point clouds, etc.), not just the embeddings and metadata
1021 |
1022 | - 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
1023 |
1024 | - Automatic data versioning to manage versions of your data without needing extra infrastructure
1025 |
1026 | - Disk-based index & storage, allowing for massive scalability without breaking the bank
1027 |
1028 | - Ingest your favorite data formats directly, like pandas DataFrames, Pydantic objects, Polars (coming soon), and more
1029 |
1030 |
1031 | ## Documentation guide [Permanent link](\#documentation-guide "Permanent link")
1032 |
1033 | The following pages go deeper into the internal of LanceDB and how to use it.
1034 |
1035 | - [Quick start](basic/): Get started with LanceDB and vector DB concepts
1036 | - [Vector search concepts](concepts/vector_search/): Understand the basics of vector search
1037 | - [Working with tables](guides/tables/): Learn how to work with tables and their associated functions
1038 | - [Indexing](ann_indexes/): Understand how to create indexes
1039 | - [Vector search](search/): Learn how to perform vector similarity search
1040 | - [Full-text search (native)](fts/): Learn how to perform full-text search
1041 | - [Full-text search (tantivy-based)](fts_tantivy/): Learn how to perform full-text search using Tantivy
1042 | - [Managing embeddings](embeddings/): Managing embeddings and the embedding functions API in LanceDB
1043 | - [Ecosystem Integrations](integrations/): Integrate LanceDB with other tools in the data ecosystem
1044 | - [Python API Reference](python/python/): Python OSS and Cloud API references
1045 | - [JavaScript API Reference](javascript/modules/): JavaScript OSS and Cloud API references
1046 | - [Rust API Reference](https://docs.rs/lancedb/latest/lancedb/index.html): Rust API reference
1047 |
1048 | Back to top
1049 |
1050 | [Ask AI](https://asklancedb.com)
1051 |
1052 | # LanceDB MCP Server Documentation
1053 |
1054 | ## Overview
1055 | 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.
1056 |
1057 | ## Key Features
1058 | - Embedded vector database server
1059 | - Efficient resource management
1060 | - Concurrent read support
1061 | - Automatic cleanup and garbage collection
1062 | - Error handling for common edge cases
1063 |
1064 | ## Server Operations
1065 |
1066 | ### Initialization
1067 | ```python
1068 | from lancedb_mcp.server import LanceDBServer
1069 |
1070 | # Initialize with default URI
1071 | server = LanceDBServer()
1072 |
1073 | # Initialize with custom URI
1074 | server = LanceDBServer(uri="custom/data/path")
1075 | ```
1076 |
1077 | ### Resource Management
1078 | The server implements efficient resource management:
1079 | - Tables are automatically cleaned up when no longer needed
1080 | - No explicit `close()` calls required
1081 | - Python's garbage collector handles resource cleanup
1082 | - References are cleared during server shutdown
1083 |
1084 | ### Error Handling
1085 | The server includes comprehensive error handling for:
1086 | - Non-existent tables
1087 | - Invalid vector dimensions
1088 | - Concurrent access issues
1089 | - Resource allocation failures
1090 |
1091 | ## Best Practices
1092 |
1093 | ### Server Usage
1094 | 1. Initialize server with appropriate URI
1095 | 2. Use batch operations for better performance
1096 | 3. Handle errors appropriately
1097 | 4. Allow proper cleanup during shutdown
1098 |
1099 | ### Performance Optimization
1100 | 1. Use batch operations when possible
1101 | 2. Clear unused references
1102 | 3. Monitor memory usage
1103 | 4. Handle cleanup properly
1104 |
1105 | ## Testing
1106 | The server includes comprehensive test coverage for:
1107 | - Server initialization
1108 | - Table operations
1109 | - Error handling
1110 | - Concurrent access
1111 | - Resource cleanup
1112 |
1113 | For detailed test examples, see `tests/test_server.py` and `tests/test_initialization.py`.
1114 |
```