Lancelot

Lancelot

Lancelot is an MCP server that answers search and retrieval queries against a local LanceDB database. It uses OpenAI embeddings for vector search when an API key is set, and plain text matching when it is not.

It reads the database folder and never writes to it. It speaks MCP over stdio, and over Streamable HTTP with --http (see HTTP mode).

The public read-only instance over the Ayers documentation is at https://mcp.ayers.repair/lancelot. Any MCP client that supports Streamable HTTP can use that URL. The documents are built into a table with lancelot-index.

Tools

Tool	What it does
lancedb_search	Searches a table and returns ranked hits with short snippets.
lancedb_query	Retrieves chunks for a question and returns them as one block of context, cut to a character budget.
lancedb_status	Reports the connection, the tables with row counts, and whether embeddings are available.
lancedb_version	Reports the Lancelot version, the MCP protocol version of the SDK it is built on, and what is enabled.

lancedb_search

Parameter	Type	Required	Meaning
query	string	yes	The search text.
limit	number	no	Maximum hits, 1 to 200. Default: LANCEDB_DEFAULT_LIMIT, which is 20.
searchType	vector, text or auto	no	vector embeds the query with OpenAI. text matches words in the text column. auto (the default) uses vector search when an API key is set and text search otherwise.
table	string	no	Table to search. Default: LANCEDB_TABLE.
textColumn	string	no	Column holding the text. Default: LANCEDB_TEXT_COLUMN.
vectorColumn	string	no	Column holding the vectors. Default: LANCEDB_VECTOR_COLUMN.

The reply is JSON. Its searchType field is the search that produced the hits, vector or text. When that is not the search you asked for, a note field says why: no API key, the vector search failed, or (in auto) it found nothing. For vector hits score is the distance, so lower is closer. For text hits score is the share of query words found in the hit, so higher is better.

Text search is a case-insensitive substring match on the words of the query. It does not use a full-text index and does not stem words.

lancedb_query

Parameter	Type	Required	Meaning
question	string	yes	The question to retrieve context for.
contextBudget	number	no	Maximum characters of context. Default: LANCEDB_CONTEXT_BUDGET, which is 8000.
warmStart	boolean	no	Retrieve a general project overview instead of answering question. Default: false.
table	string	no	Table to query. Default: LANCEDB_TABLE.
limit	number	no	Maximum chunks to retrieve, 1 to 200. Default: LANCEDB_DEFAULT_LIMIT.

The reply is a Markdown block: a header (mode, search type, query), then one section per chunk with its title, source and text. Chunks that would pass the budget are left out and the block says how many.

lancedb_status

Parameter	Type	Required	Meaning
verbose	boolean	no	Include the column names of each table. Default: false.

lancedb_version

No parameters.

Table layout

Lancelot reads the text from the text column (text by default). It reads title for the title, and chunkSource, docSource or path for the source, when a row has them; the first two are the layout AnythingLLM writes, and path is what lancelot-index writes. Other columns come back as metadata. Vector search needs vectors made with the same model as EMBEDDING_MODEL.

Install

Claude Code, using the stdio form from the Claude Code MCP documentation:

claude mcp add --env LANCEDB_PATH=/path/to/db --env OPENAI_API_KEY=... --transport stdio lancelot -- npx -y @ayerselectronics/lancelot

--transport stdio sits between the last --env and the server name on purpose: the CLI reads a name that follows --env directly as another variable. Everything after -- runs the server.

Leave out --env OPENAI_API_KEY=... for text search only.

Other MCP clients take the same command in their mcpServers configuration:

{
  "mcpServers": {
    "lancelot": {
      "command": "npx",
      "args": ["-y", "@ayerselectronics/lancelot"],
      "env": {
        "LANCEDB_PATH": "/path/to/db",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Install links

Open one of these in a browser or on the command line to add the server to the editor. Set LANCEDB_PATH to your database folder afterwards.

• VS Code: vscode:mcp/install?%7B%22name%22%3A%22lancelot%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40ayerselectronics%2Flancelot%400.3.1%22%5D%2C%22env%22%3A%7B%22LANCEDB_PATH%22%3A%22%2Fpath%2Fto%2Fdb%22%7D%7D
• Cursor: cursor://anysphere.cursor-deeplink/mcp/install?name=lancelot&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBheWVyc2VsZWN0cm9uaWNzL2xhbmNlbG90QDAuMy4xIl0sImVudiI6eyJMQU5DRURCX1BBVEgiOiIvcGF0aC90by9kYiJ9fQ==

The link formats are from the VS Code MCP guide and the Cursor install links documentation.

Registry

MCP Registry identity: io.github.ayers-software-repair/lancelot.

Setup command

lancelot-init asks for the database folder and an OpenAI API key, and stores them for later runs. The key goes to the operating system keychain through keytar, or to an encrypted file when keytar is not available. Run it with npx -p @ayerselectronics/lancelot lancelot-init. Environment variables override what it stored.

HTTP mode

npx -y @ayerselectronics/lancelot --http                      # http://127.0.0.1:3000/mcp
npx -y @ayerselectronics/lancelot --http 8080
npx -y @ayerselectronics/lancelot --http 8080 --host 0.0.0.0  # all interfaces

Without --http the server is stdio, exactly as before. With it, the server speaks the Streamable HTTP transport of MCP 2025-06-18, the protocol version of the SDK Lancelot is built on. --http takes an optional port (default 3000). The server binds 127.0.0.1 unless --host names another address, as the specification advises for a local server. The endpoint is /mcp; any other path is 404.

• Origin. The specification says the server must validate the Origin header. A request that carries an Origin not listed in LANCELOT_ALLOWED_ORIGINS gets 403. With the variable unset, every request that carries an Origin gets 403. A request with no Origin header is not from a browser and is let through; the SDK's own origin check refuses those, so Lancelot does the check itself.
• Host. LANCELOT_ALLOWED_HOSTS lists the Host header values that may call, for DNS rebinding protection. Left unset on a loopback bind, it defaults to 127.0.0.1:<port>, localhost:<port> and [::1]:<port>. Left unset with --host 0.0.0.0, the Host header is not checked and a warning goes to stderr. A request with a Host not listed gets 403.
• Stateless. No session id is issued. Each POST gets its own MCP server and transport, closed when the response ends, and answers with one JSON object. GET (the optional event stream) and DELETE (ending a session) answer 405 with Allow: POST, which the specification permits.
• Limits. A body over 64 KB is 413. A body that is not JSON is 400.
• Protocol version. The MCP-Protocol-Version header is checked by the SDK: a version it does not support is 400, and a missing header is taken as 2025-03-26, as the specification says.

Both variables take comma-separated lists, for example LANCELOT_ALLOWED_ORIGINS=https://app.example,https://other.example. HTTP mode has no authentication; the tools are read-only, and a server open to a network should sit behind something that has it.

AWS Lambda

dist/lambda.js exports handler(event) for an API Gateway HTTP API with payload format 2.0. It turns the event into the request the SDK's transport expects and returns { statusCode, headers, body }. It reads LANCEDB_PATH, LANCELOT_BASE_PATH (the path the endpoint is served under, such as /lancelot; unset serves every path) and the two allow-list variables. The database connection is opened on the first invocation and reused on warm ones. The function may write only to /tmp, where Lancelot keeps its own settings file.

The Dockerfile builds the container image on the AWS Node.js 24 base image for arm64, with the handler dist/lambda.handler. Build dist first:

docker buildx build --platform linux/arm64 --provenance=false -t lancelot-lambda .

Index your documents

lancelot-index builds the table the server reads from a folder of .md, .txt and .html files:

npx -p @ayerselectronics/lancelot lancelot-index ./docs ./db
npx -p @ayerselectronics/lancelot lancelot-index ./docs ./db --table documents

It walks the folder and its subfolders (skipping names that start with a dot), strips HTML to text, and splits each file into chunks of about 1,200 characters on paragraph boundaries. A paragraph longer than that is cut at a space. Each chunk becomes a row { id, path, title, text }: id is the relative path and chunk number, path is the relative path, and title is the first Markdown heading of the file, or the file name. There are no vectors, so search is text search.

--table names the table (default documents). The command replaces that table if it exists, so running it again rebuilds the table from the folder. It is the only part of the package that writes to a database; the server never does. Point LANCEDB_PATH at the database folder afterwards.

Environment variables

Settings come from, in order: the environment, the file written by lancelot-init, the defaults. A variable that is empty or only whitespace counts as not set. MCP clients that substitute a blank optional value pass an empty string, and Lancelot then behaves as if the variable were absent: no OpenAI client is created, search is text only, and nothing is logged as an error.

Variable	Default	Meaning
LANCEDB_PATH	none	The LanceDB database folder. Required for the tools to work. It must exist; Lancelot does not create it.
LANCEDB_TABLE	documents	Table used when a call names none.
LANCEDB_TEXT_COLUMN	text	Column holding the text.
LANCEDB_VECTOR_COLUMN	vector	Column holding the vectors.
LANCEDB_DEFAULT_LIMIT	20	Hits returned when a call sets no limit.
LANCEDB_CONTEXT_BUDGET	8000	Characters of context lancedb_query returns when a call sets no contextBudget.
OPENAI_API_KEY	none	Enables vector search. When unset, the credential store is checked next.
EMBEDDING_MODEL	text-embedding-ada-002	The OpenAI model used to embed queries.
EMBEDDING_DIMENSIONS	1536	Reported by lancedb_status. It is not sent to OpenAI.
LANCELOT_LOG_LEVEL	info	One of error, warn, info, http, verbose, debug, silly.
LANCELOT_ALLOWED_ORIGINS	none	HTTP mode: comma-separated Origin values that may call. See HTTP mode.
LANCELOT_ALLOWED_HOSTS	loopback names on the port	HTTP mode: comma-separated Host header values that may call.
LANCELOT_BASE_PATH	any path	Lambda only: the path the endpoint is served under, such as /lancelot.

Standard output

The MCP stdio transport says the server writes only valid MCP messages to stdout, and that it may write logs to stderr. Lancelot follows that:

• Every log level goes to stderr. The logger has one transport, a winston Console transport with all seven levels listed in stderrLevels.
• The server entry point points console.log, console.info and console.debug at stderr, so a library that prints does not corrupt the stream.
• The server reads stdin until the client closes it, then exits.

HTTP mode keeps the same rule: it writes nothing to stdout either.

lancelot-init and lancelot-index write to stdout. They talk to a person at a terminal and are never started as a server.

Read-only

The four tools open a table and query it. No code the server runs creates a table, adds, updates or deletes rows, or builds an index, and the server does not create the database folder if the path is wrong. The one exception in src is src/bin/lancelot-index.ts, a separate command that builds a table (see Index your documents); the server never imports it. tests/readonly.test.ts scans the rest of the source for those calls.

Lancelot keeps its own settings and credentials in the per-user configuration directory, never in the database folder.

Privacy

When OPENAI_API_KEY is set, query text is sent to OpenAI to compute embeddings. With no key nothing leaves the machine.

Privacy policy and terms: the full statement, including what the hosted endpoint receives.

Development

npm ci
npm run check    # typecheck, lint, test, build

Node 20 or later. See CONTRIBUTING.md.

License

Apache-2.0. See LICENSE and NOTICE.

Published by Ayers Electronics.