lancedb-mcp 0.1.3

MCP server providing semantic knowledge base with LanceDB storage and configurable embeddings

lancedb-mcp

MCP knowledge base server for OpenCode with LanceDB storage and OpenAI-compatible embeddings (llama.cpp, Ollama, etc.).

What it does

Provides a semantic knowledge base that your OpenCode agent can use to remember and recall facts, rules, conventions and decisions across sessions. The agent autonomously decides when to store and search — no manual tool invocation needed.

Agent: discovers that "deploy is via make deploy-prod on Wednesdays"
       → calls kb_add("Deploy on Wednesdays via make deploy-prod", source="ops")

Agent: (next session, user asks about deployment)
       → calls kb_search("how to deploy to production")
       → gets: "Deploy on Wednesdays via make deploy-prod" (score: 0.92)
       → answers user correctly

Architecture

OpenCode ──MCP stdio──> lancedb-mcp (Python)
                            ├── LanceDB (on-disk vector storage)
                            └── OpenAI-compat endpoint (llama.cpp, Ollama, etc.)

Quick start

1. Install

cd lancedb-mcp
uv venv
uv sync

2. Start an embedding backend

The server requires an OpenAI-compatible embedding endpoint. Any of these work:

# llama.cpp
llama-server -m model.gguf --embeddings --host 127.0.0.1 --port 8080

# Ollama
ollama serve

3. Configure OpenCode

Add to opencode.json:

{
  "mcp": {
    "knowledge-base": {
      "type": "local",
      "command": ["uv", "run", "lancedb-mcp"],
      "environment": {
        "EMBED_API_BASE": "http://localhost:8080/v1",
        "KB_STORAGE_PATH": ".kb_data"
      },
      "enabled": true
    }
  }
}

Restart OpenCode for changes to take effect.

Tools available to the agent

Tool	Description	Parameters
kb_add	Add text to the knowledge base	text (required), source (default: "general")
kb_search	Semantic search, returns JSON [{text, source, score}]	query (required), limit (default: 5), source (optional filter)
kb_list	List stored documents	limit (default: 20)
kb_delete	Delete a document by ID	doc_id (required)
kb_stats	Document count, returns JSON {total_documents: N}	—

Configuration

Embedding settings (EMBED_*)

Variable	Default	Description
EMBED_API_BASE	—	Required. URL of your OpenAI-compatible embedding endpoint
EMBED_MODEL	""	Model name sent to the endpoint (ignored by llama.cpp)
EMBED_API_KEY	""	API key (ignored by llama.cpp, required for cloud endpoints)
EMBED_DIM	2560	Expected embedding dimension. Validated against the model's output on every call; a mismatch raises a clear error. Default matches Qwen3-Embedding-4B (2560). Set to your model's size, e.g. 384 (MiniLM), 1024 (Qwen3-0.6B), 4096 (Qwen3-8B).

Storage settings (KB_*)

Variable	Default	Description
KB_STORAGE_PATH	.lancedb_data	Directory for LanceDB files
KB_TABLE_NAME	knowledge	Table name inside LanceDB

CLI flags

lancedb-mcp --help
  --transport {stdio,sse,streamable-http}  # MCP transport (default: stdio)
  --host 127.0.0.1                          # Host for SSE/HTTP modes
  --port 8001                               # Port for SSE/HTTP modes
  --top-k 5                                 # Max search results

Storage

Data is stored as LanceDB tables on disk. Each table:

Column	Type	Description
id	string	Auto-generated document ID
vector	float32[n]	Embedding vector
text	string	Original document text
source	string	Origin tag (agent, user, ops, dev, ...)

Use the source field to organize facts by domain and filter via kb_search(source="ops").

Running tests

Unit tests

uv run pytest tests/ -v -k "not integration"

Integration tests

Require a running OpenAI-compatible embedding endpoint (e.g. llama.cpp on localhost:8080):

uv run pytest tests/test_integration.py -v

Project layout

src/lancedb_mcp/
├── main.py           # CLI entry point: arg parsing, transport selection
├── server.py         # FastMCP factory; wires connector + embedder + tool registration
├── settings.py       # pydantic-settings config (KB_*, EMBED_*), reads .env
├── connector.py      # LanceDB wrapper: table lifecycle, CRUD, search, filter escaping
├── embeddings.py     # Embedder ABC, OpenAICompatEmbedder, create_embedder factory
└── tools/
    ├── knowledge.py  # registers kb_add, kb_list, kb_delete
    └── search.py     # registers kb_search, kb_stats

• Requires Python ≥ 3.10.
• Dependencies (see pyproject.toml): mcp[cli], lancedb, pyarrow, openai, pydantic-settings.
• Config comes from environment variables (KB_*, EMBED_*) or a local .env file.
• License: GPL-3.0-or-later.

Conventions

Conventions for contributing to this repo:

• Comments: none unless explicitly requested. Express intent through names and structure. why/intent comments are subject to the same restriction — explaining why rather than what does not exempt a comment from it.
• Docstrings: follow existing practice in src/ — contract only (params, returns, raises, non-obvious side effects). Not affected by the comment rule.
• Regression / security tests: encode the incident in the test name (e.g. test_crafted_id_leaves_other_rows_intact), not a comment.