Metadata-Version: 2.4
Name: lancedb-mcp
Version: 0.1.2
Summary: MCP server providing semantic knowledge base with LanceDB storage and configurable embeddings
Project-URL: Homepage, https://gitlab.com/skopciewski/lancedb-mcp
Project-URL: Repository, https://gitlab.com/skopciewski/lancedb-mcp
Project-URL: Issues, https://gitlab.com/skopciewski/lancedb-mcp/-/issues
Author-email: simonk <s.kopciewski@dlamnie.net>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: embeddings,knowledge-base,lancedb,mcp,opencode,vector-search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: lancedb>=0.17.0
Requires-Dist: mcp[cli]>=1.6.0
Requires-Dist: openai>=1.0.0
Requires-Dist: pyarrow>=17.0.0
Requires-Dist: pydantic-settings>=2.6.0
Description-Content-Type: text/markdown

# 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

```bash
cd lancedb-mcp
uv venv
uv sync
```

### 2. Start an embedding backend

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

```bash
# 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`:

```jsonc
{
  "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: "agent") |
| `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

```bash
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](https://lancedb.com) 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

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

### Integration tests

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

```bash
uv run pytest tests/test_integration.py -v
```
