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

Configuration

Embedding settings (EMBED_*)

Storage settings (KB_*)

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:

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.