qdrant-mcp-server: Instructions file for Codex

AGENTS.md

This file guides AI agents (Claude Code, OpenCode, Cursor) working in this repository.

What this repository is

A fork of mhalder/qdrant-mcp-server, upstream MIT (c) 2025 Martin Halder and contributors. All upstream code belongs to upstream. This fork adds exactly one change on top of upstream main:

• recency scoring for semantic_search and hybrid_search. Fresh documents surface ahead of older near-duplicates via Qdrant's exp_decay formula.

See README.md -> "Fork Changes" for the full description.

Stack

• Node.js 22.x or 24.x, TypeScript, compiled with tsc to build/.
• Native module tree-sitter builds against system C++ headers.
• Backend: Qdrant (vector DB), embedding via OpenCode-compatible provider (Ollama/OpenAI/etc.).

Build

npm install

# Node 22.x
npm run build

# Node 24.x: native module needs C++20
CXXFLAGS='-std=c++20' npm install
npm run build

Output goes to build/index.js. build/ and node_modules/ are gitignored.

Run

stdio transport is the default:

node build/index.js

Environment variables are documented in README.md -> Advanced Configuration. The two most important: QDRANT_URL (your Qdrant server) and EMBEDDING_PROVIDER (default ollama).

Registering the MCP server with OpenCode

Add this to opencode.json (project-scope or ~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "qdrant": {
      "type": "local",
      "command": ["node", "/path/to/qdrant-mcp-server/build/index.js"],
      "enabled": true,
      "environment": {
        "QDRANT_URL": "http://localhost:6333",
        "EMBEDDING_PROVIDER": "ollama"
      }
    }
  }
}

• command is an array of strings, never a single string.
• type is required.
• Point QDRANT_URL at your Qdrant server; set EMBEDDING_PROVIDER and, if needed, EMBEDDING_BASE_URL / EMBEDDING_MODEL to match your embedding setup.
• Save + restart OpenCode after any config change; config is loaded at startup.
• See README.md -> OpenCode Setup for the full example, including a permission block that auto-approves the search tools.