mcp server

mddb

A minimal, lightweight structured data store designed for small applications, scripts and automation workflows. Built for simplicity, portability and low overhead.

tradik/mddbcommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

This project does not publish an install method we can turn into a config. Follow the README instead.

README

synced Oct 21, 2026

MDDB: AI-Native Document Database

AI-native document database with built-in MCP server, file upload (PDF/DOCX/HTML/ODT/RTF/TEX/YAML/Wikipedia XML to Markdown), vector search, RAG pipelines, and 81 MCP tools. Plugs directly into Claude, ChatGPT, Cursor, Windsurf, and any MCP-compatible agent.

MDDB is a document database purpose-built for AI agents and LLM workflows. Upload files (PDF, DOCX, HTML, ODT, RTF, TEX, YAML, TXT). They are auto-converted to Markdown and embedded for semantic search. Expose everything to AI agents via 81 built-in MCP tools. Integrates with Docling, Langflow, OpenSearch, SSG, wpexporter, Airbyte, WordPress Sync, a GitHub Action, a Grafana datasource, and a Chrome browser extension for production pipelines. Single ~26MB binary, zero configuration, BoltDB embedded storage, triple-protocol APIs (HTTP + gRPC + GraphQL).

🎯 What is MDDB?

MDDB gives your AI agents a persistent, searchable knowledge base:

File Upload - Upload PDF, DOCX, HTML, ODT, RTF, TEX, YAML, TXT files, auto-converted to Markdown and indexed
Wikipedia Import - Stream and import MediaWiki XML dumps (.xml.bz2). Wikitext is auto-converted to Markdown, with namespace filtering, and multi-GB files are handled
Built-in MCP Server - 81 tools for Claude Desktop, Cursor, Windsurf, or any MCP client
Vector Search - Auto-embed documents, semantic similarity with 7 index algorithms (Flat, HNSW, IVF, PQ, OPQ, SQ, BQ) + per-collection quantization (int8/int4) + disk-only low-memory mode + ARM NEON/SME hardware acceleration + goroutine parallel search
Embedding Providers - Pluggable: OpenAI, Ollama, Voyage, Cohere, configured per server or per collection (guide)
Geo Search - R-tree and geohash indexes for radius/bounding-box queries, composable with FTS/vector via hybrid-search, optional postcode lookup
RAG-Ready - Hybrid search (BM25 keyword + vector, fused with RRF or alpha blending), parent/chunk/window retrieval modes for precise LLM context, MMR result diversification, and per-query metadata boosting (freshness/recency ranking)
Native Multi-Tenancy - Namespace isolation per tenant across HTTP/gRPC/GraphQL/MCP, ready for SaaS backends
Zero-Maintenance Storage - Single-file embedded database with automatic space management: no vacuum, compaction jobs, or index maintenance windows
Memory RAG - Conversational memory system: store, recall, and summarize chat sessions with semantic search
Integrations - Docling, Langflow, OpenSearch, SSG, wpexporter, Airbyte, WordPress Sync, GitHub Action, Grafana datasource, Chrome extension for production pipelines
Zero-Shot Classification - Classify documents against candidate labels using embeddings, no training data
Custom AI Tools - Define YAML-based MCP tools for domain-specific workflows
Code Documents - Store HTML/CSS/JS alongside prose; a kind: ["code"] convention on the existing flat meta switches to a source-aware tokeniser that keeps .hero-banner and checkoutHandler findable whole and in parts (API.md)
Code Symbols - Each code document records what it defines, uses and imports in its meta, so meta.defines=.hero-banner returns the stylesheet that declares the selector instead of the twelve templates that apply it (API.md)
Code Connection Graph - What breaks if this selector changes, which pages load this script, what does nothing reference any more. Edges are derived from the symbol meta, never stored, so a reindex reproduces the graph exactly (API.md)
Per-Collection Retrieval Profiles - Search type, topK, granularity, hybrid strategy and a context token budget stored with the collection instead of repeated by every client; an explicit request parameter always wins (API.md)
Embedding Cache - Repeated queries never reach the provider twice, and a reindex reuses the vectors of chunks whose text is unchanged. Editing one paragraph of a 50-chunk document embeds one chunk, not fifty (config.md)
Answer Formatting per Collection - A responsePrompt stored with the collection tells every consumer how its answers should be shaped; MCP agents receive it with their search results, in the same round trip (API.md)
fast Ingest Profile - One named trade-off instead of a combination of flags to reverse-engineer: text-only parsing, no revisions, no webhooks, and 43x faster on HTML. Embeddings and full-text stay on, because fast should not mean unsearchable (API.md)
oversample Knob - Recall/latency dial per query or per collection, where the topK * 3 constant used to be. At 1x a chunked collection returns half the documents you asked for; at 10x it returns all of them, for about 1% more time on a flat index (SEARCH.md)
Agent Instructions - Ready-made guidance for Claude Code, Cursor and Windsurf on which tool fits a question and how to ask for chunks instead of whole documents (integrations/agent-instructions/), measured at 60x fewer tokens for the same search
Full-Text Search - Built-in inverted index with TF-IDF, BM25, BM25F, PMISparse, 8 search modes (simple, boolean, phrase, wildcard, proximity, expression, range, fuzzy), typo tolerance, multi-language stemming (18 languages), synonyms, per-query metadata boost/demote, prefix autocomplete, search-result highlighting with fragments
Geosearch - R-tree + geohash radius/bbox queries, GeoJSON polygon and multi-polygon containment, postcode lookup, distance-sorted hybrid search combining proximity with keyword/vector relevance
Async Bulk Ingest - Queue long-running document imports with job tracking, progress polling, and optional webhook callback
Full Revision History - Every update creates a new revision with complete snapshots
Multi-Protocol APIs - HTTP/JSON (easy), gRPC (fast), GraphQL (flexible), and WebSocket streaming via mddb-chat for LLM chat pipelines
Automation - Triggers, crons, webhooks with template variables and sentiment analysis
Real-Time Events - Server-Sent Events (SSE) for live document change notifications
MCP Transports - Streamable HTTP (/mcp, 2026-07-28 + 2025-11-25), legacy SSE (/sse), and stdio
Built-in TLS - Native HTTPS support, connection pooling, pprof profiling
Zero Configuration - Single ~26MB binary, embedded database, no dependencies

Perfect for: AI agent memory, RAG pipelines, knowledge bases for LLMs, documentation chatbots, semantic search APIs, document processing (PDF/DOCX to Markdown), static site generation, WordPress migration

🚀 Quick Start

Docker Compose (Recommended) - Full Stack

Start all services with one command:

git clone https://github.com/tradik/mddb.git
cd mddb

# Production mode (all services). Set the secrets first, see below
cp .env.example .env && $EDITOR .env
docker compose up -d

# Development mode (with hot reload)
make dev-start

# Development + Ollama for embeddings
make dev-start-with-ollama

The production compose refuses to start without credentials. The image defaults to MDDB_AUTH_ENABLED=false, which suits a throwaway docker run but not docker-compose.yml, which runs the server read-write and publishes HTTP, gRPC and MCP. So the compose file turns authentication on and reads MDDB_AUTH_JWT_SECRET and MDDB_AUTH_ADMIN_PASSWORD from .env with no fallback: leave either unset and compose stops with an error naming the variable, rather than quietly starting an open database.

Every port is published on 127.0.0.1 by default. A reverse proxy or cloudflared reaches the containers over mddb-network and needs no published port at all; to expose the stack on the host's interfaces, set MDDB_BIND_ADDR=0.0.0.0, deliberately, and only with authentication on.

Importing existing content: MDDB does not automatically index bind-mounted directories. Use scripts/load-md-folder.sh or the ingest API to load existing Markdown files.

Services started:

Service	Port	Image	Description
mddbd	11023 (HTTP), 11024 (gRPC), 9000 (MCP), 11443 (HTTP/3)	`tradik/mddb:latest`	Database server with MCP built-in
mddb-panel	3000	`tradik/mddb:panel`	React web admin UI

Connect to Claude / Cursor / Windsurf (MCP)

MDDB has a built-in MCP server, so no extra service is needed. Add to your MCP config:

{
  "mcpServers": {
    "mddb": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--network", "host",
        "-v", "mddb-data:/app/data",
        "-e", "MDDB_MCP_STDIO=true",
        "tradik/mddb:latest"
      ]
    }
  }
}

That is it. Your AI agent now has full access to your knowledge base with 81 built-in tools (add, search, vector search, classify, and more).

Full MCP setup guide | MCP server config | Custom MCP tools

Docker - Individual Services

# MDDB Server only
docker run -d --name mddb \
  -p 11023:11023 -p 11024:11024 -p 9000:9000 \
  -v mddb-data:/data \
  tradik/mddb:latest

# Web Panel (connect to existing server)
docker run -d --name mddb-panel \
  -p 3000:3000 \
  -e VITE_MDDB_SERVER=host.docker.internal:11023 \
  tradik/mddb:panel

# MCP stdio mode (for Claude Desktop, Windsurf, etc.)
docker run -i --rm --network host \
  -v mddb-data:/app/data \
  -e MDDB_MCP_STDIO=true \
  tradik/mddb:latest

# Test it
curl http://localhost:11023/health

Docker Hub: https://hub.docker.com/r/tradik/mddb

Install Binary

Linux (Debian/Ubuntu):

wget https://github.com/tradik/mddb/releases/latest/download/mddbd-latest-linux-amd64.deb
sudo dpkg -i mddbd-latest-linux-amd64.deb
sudo systemctl start mddbd

macOS (Apple Silicon):

wget https://github.com/tradik/mddb/releases/latest/download/mddbd-latest-darwin-arm64.tar.gz
tar xzf mddbd-latest-darwin-arm64.tar.gz
sudo mv mddbd-latest-darwin-arm64/mddbd /usr/local/bin/
mddbd

CLI Client:

# Linux
wget https://github.com/tradik/mddb/releases/latest/download/mddb-cli-latest-linux-amd64.deb
sudo dpkg -i mddb-cli-latest-linux-amd64.deb

# Usage
mddb-cli stats
mddb-cli add blog hello en_US -f post.md
mddb-cli search blog -f "tags=tutorial"
mddb-cli fts blog --query="getting started" --algorithm=bm25

Other platforms: See Installation Guide

Platform support

Platform	Release binary	Test suite runs in CI
linux/amd64, linux/arm64	✅	✅ every push
darwin/amd64, darwin/arm64	✅	compiled and vetted, not run
freebsd/amd64, freebsd/arm64	✅	compiled and vetted, not run
windows/amd64	❌ build from source	✅ every push, since 2.13
windows/arm64	❌	❌ not a target

Two things this table is precise about on purpose.

macOS and FreeBSD ship binaries that no CI job executes. They are built and type-checked on every push, including test files, which catches a platform-split that fails to compile. The FreeBSD build broke once on a Statfs_t field width and that is exactly what it catches. It does not catch a syscall that compiles and returns the wrong thing.

Windows runs the suite but ships nothing. As of 2.13 the full test suite runs on windows-latest on every push, and native windows/amd64 binaries build from source with make build-windows. There are no Windows release artifacts, and Unix domain sockets are refused there by design, because the listener's security model is owner-only mode bits, which Windows cannot express. WSL2 remains the route that runs the same binary every release is built and tested against. See the Installation Guide.

Build from Source

git clone https://github.com/tradik/mddb.git
cd mddb
make build                 # host platform
make build-windows         # cross-compile windows/amd64 into dist/
./services/mddbd/mddbd

Development with Go Workspace

MDDB is a Go monorepo with multiple modules (services/mddbd, services/mddb-cli, clients/go/mddb, tools/bench). A go.work file at the repo root enables Go workspace mode for local development:

Cross-module refactoring: renaming a symbol in services/mddbd immediately updates references in services/mddb-cli via gopls.
Unified build: go build ./services/mddbd/... ./services/mddb-cli/... ./tools/bench/... from the repo root.
IDE "goto definition" works across module boundaries without opening each module separately.

`services/mddbd` internal package structure (GO-015)

The daemon was refactored from one flat ~58k-LOC package main into importable, independently-testable internal/ packages. Server-independent leaves and dependency-inverted subsystems now live behind compilation boundaries:

Area	Packages
Storage & docs	`internal/storage` (the `Doc` type, key builders, proto conversion), `internal/binlog` (replication log), `internal/compression`, `internal/delta`
Search	`internal/fts` (full-text), `internal/vector` (ANN/embeddings/SIMD), `internal/geo`, `internal/spell`, `internal/embedding`
Subsystems	`internal/cache`, `internal/metrics` (inverted via `StatsProvider`), `internal/indexqueue` (inverted via `Store`), `internal/ttl` (inverted via `Reaper`), `internal/encryption`, `internal/webhooks`, `internal/automationlog`, `internal/schema`, `internal/temporal`, `internal/audit`
Shared utilities	`internal/envconf`, `internal/sliceutil`, `internal/httpclient` (pooled SSRF-safe client), `internal/wikitext`, `internal/sentiment`

HTTP/gRPC/MCP/GraphQL handlers stay in package main as thin transport over these packages. The HTTP API client is a separate shared module, clients/go/mddb (mddb-client), consumed by mddb-cli and external Go integrations.

CI runs in module-isolation mode (GOWORK=off in .github/workflows/test.yml and release.yml) so each module builds and tests independently. This catches missing require entries that workspace mode would transparently resolve from sibling modules.

To use the same mode locally for debugging:

GOWORK=off go build ./...   # from inside services/mddbd

Regenerating protos (buf generate) and Docker builds are unaffected by go.work. They operate on individual modules.

📦 Packages & Client Libraries

MDDB ships as a monorepo with multiple packages:

Server & Tools

Package	Language	Location	Description
mddbd	Go	`services/mddbd/`	Database server (HTTP + gRPC + GraphQL + MCP)
mddb-panel	React/JS	`services/mddb-panel/`	Web admin panel
mddb-cli	Go	`services/mddb-cli/`	Command-line client with GraphQL support
mddb-chat	Rust	`services/mddb-chat/`	WebSocket chat server with LLM integration
mddb-chat-widget	JS/TS	`services/mddb-chat-widget/`	Embeddable JS chat widget

Client Libraries (REST)

Zero-dependency HTTP clients - copy a single file into your project:

Library	Language	Location	Install
PHP Extension	PHP 8.0+	`services/php-extension/mddb.php`	Copy `mddb.php` into your project
Python Extension	Python 3.8+	`services/python-extension/mddb.py`	Copy `mddb.py` into your project

PHP:

require_once 'mddb.php';
$db = mddb::connect('localhost:11023', 'write');
$db->collection('blog')->add('hello', 'en_US', ['author' => ['John']], '# Hello');
$results = $db->collection('blog')->vectorSearch('cancel subscription', 5, 0.7);

Python:

from mddb import MDDB
db = MDDB.connect('localhost:11023', 'write').collection('blog')
db.add('hello', 'en_US', {'author': ['John']}, '# Hello')
results = db.vector_search('cancel subscription', top_k=5)

Client Libraries (gRPC)

High-performance clients generated from Protocol Buffers:

Library	Language	Location	Description
Go HTTP client	Go	`clients/go/mddb/`	Official HTTP/JSON SDK, shared by `mddb-cli` and external Go integrations
Go gRPC stubs	Go	`services/mddbd/proto/`	Native Go gRPC stubs
Python gRPC	Python	`clients/python/`	Generated Python gRPC client
Node.js gRPC	Node.js	`clients/nodejs/`	Uses `@grpc/grpc-js`

Proto definitions at proto/mddb.proto - generate clients for any language supported by protobuf.

The Go HTTP SDK is a standalone module (mddb-client); import it directly:

import mddb "mddb-client" // replace => ./clients/go/mddb in the monorepo

c := mddb.New("http://localhost:11023", mddb.WithAPIKey(os.Getenv("MDDB_API_KEY")))
doc, err := c.Add(ctx, mddb.AddRequest{Collection: "blog", Key: "hello", Lang: "en", ContentMD: "# Hi"})

Docker Images (Docker Hub)

Image	Size	Description
`tradik/mddb:latest`	~26MB	Database server with MCP built-in (Alpine)
`tradik/mddb:panel`	~88MB	Web admin panel (Node Alpine)
`tradik/mddb:cli`	~8MB	CLI client (Alpine)

System Packages

Format	Platform	Contents
`.deb`	Debian/Ubuntu	mddbd + systemd unit + man page
`.rpm`	RHEL/CentOS/Fedora	mddbd + systemd unit + man page
`.tar.gz`	Any (Linux, macOS, FreeBSD)	Standalone binary

💡 Key Features

AI & Search

✅ MCP Server - 81 built-in tools via Model Context Protocol 2026-07-28 and 2025-11-25, served side by side (stdio + Streamable HTTP + SSE) with server/discover, tool annotations, prompts, completion, and structured output
✅ WordPress Publishing - wordpress_publish / wordpress_set_status MCP tools create, update and (un)publish posts & pages on sites running the mddb-sync plugin, including tags, categories, meta fields and Polylang/WPML translations included (docs)
✅ File Upload - Upload PDF, DOCX, HTML, ODT, RTF, TEX, YAML, TXT, auto-converted to Markdown (single and batch, configurable size limit)
✅ Wikipedia Import - Stream MediaWiki XML dumps (.xml.bz2) with wikitext to Markdown conversion, namespace filtering, batch processing
✅ Vector Search - Semantic similarity with auto-embeddings (OpenAI, Ollama, Cohere, Voyage), ARM NEON/SME SIMD acceleration
✅ Full-Text Search - Built-in inverted index with TF-IDF, BM25, BM25F, PMISparse scoring, 7 search modes (simple, boolean, phrase, wildcard, proximity, range, fuzzy), typo tolerance, metadata pre-filtering, multi-language stemming and stop words (18 languages)
✅ Hybrid Search - Sparse (BM25) + dense (vector) fusion with alpha blending or RRF
✅ Aggregations - Metadata facets (value counts) and date histograms with optional pre-filtering
✅ Inline Facets on Search (v2.9.14+) - Pass facetBy to /v1/fts or /v1/hybrid-search and get per-key value counts alongside results, with no separate aggregate call
✅ Curation Rules (v2.9.14+) - Pin or hide documents for specific queries via /v1/curation (CRUD); applied in FTS + Hybrid pipelines
✅ Zero-Shot Classification - Classify documents against candidate labels using embedding similarity
✅ Custom MCP Tools - Define YAML-based AI tools for domain-specific workflows
✅ RAG Pipeline - Built-in support for retrieval-augmented generation workflows
✅ Integrations - Docling, Langflow, OpenSearch, SSG, wpexporter, Airbyte, WordPress Sync, GitHub Action, Grafana datasource, Chrome browser extension (guide)

Core Functionality

✅ Document Management - Full CRUD with metadata and collections
✅ Revision History - Complete version control with snapshots, per-collection retention cap (maxRevisions, v2.9.14+) trimmed synchronously on every write
✅ Metadata Search - Fast indexed queries with multi-value tags
✅ Collection Checksum - Lightweight CRC32 checksum per collection for cache invalidation
✅ Partial Document Update - Update metadata and/or content independently
✅ Document TTL - Time-to-live with automatic cleanup
✅ Temporal Tracking - Document event history (create/update/access), hot-docs leaderboard, activity histograms (env MDDB_TEMPORAL=true)
✅ Spell Correction - SymSpell-based FTS spell suggestions, text cleanup, per-collection custom dictionaries (env MDDB_SPELL=true)
✅ Automation - Triggers, crons, webhooks with template variables, sentiment analysis, execution logs
✅ Multi-language - Same key, multiple languages
✅ Schema Validation - JSON Schema validation per collection
✅ Per-Collection Storage Backends - Choose BoltDB (default), in-memory (ephemeral), or S3/MinIO per collection

APIs & Protocols

✅ HTTP/JSON REST - Easy debugging, extensive docs
✅ gRPC/Protobuf - 16x faster, 70% smaller payload
✅ GraphQL - Flexible queries, schema introspection, Playground
✅ CLI Client - Full-featured command-line with GraphQL support
✅ Web Panel - React UI with REST/GraphQL toggle

Security & Access

✅ Authentication - JWT tokens and API keys
✅ Authorization - Collection-level RBAC (Read/Write/Admin)
✅ Per-Protocol Access Modes - MDDB_MCP_MODE=read (MCP read-only), MDDB_API_MODE, MDDB_GRPC_MODE, MDDB_HTTP3_MODE
✅ MCP Tool Control - MDDB_MCP_BUILTIN_TOOLS=false to expose only custom YAML tools
✅ User Management - Multi-user with admin roles
✅ Native Multi-Tenancy - Namespace isolation per tenant, enforced centrally across HTTP/gRPC/GraphQL/MCP; zero config for single-tenant deployments
✅ Group Permissions - Organize users into groups
✅ TLS / HTTPS - MDDB_TLS_ENABLED=true, MDDB_TLS_CERT, MDDB_TLS_KEY, taking a user-supplied PEM cert and key, TLS 1.2 minimum
✅ Mutual TLS (mTLS) - MDDB_TLS_CLIENT_CA points to a PEM bundle of trusted client CAs; MDDB_TLS_CLIENT_AUTH=require (default) or request. Rejects unauthenticated clients when require
✅ Unix Domain Socket transport - MDDB_HTTP_ADDR=unix:/tmp/mddb-http.sock and MDDB_GRPC_ADDR=unix:/tmp/mddb-grpc.sock, a zero-network local transport with 0600 filesystem perms. Clients in Python (MDDB.connect('unix:/tmp/mddb-http.sock')), PHP (mddb::connect('unix:/tmp/mddb-http.sock')), Node/Python gRPC (unix:/tmp/mddb-grpc.sock channel target)
✅ Audit log (ISO 27001 / SOC 2) - MDDB_AUDIT_ENABLED=true persists structured JSON events (auth attempts, writes, deletes) to a dedicated BoltDB bucket. Admin-only GET /v1/audit query with actor / action / result / time-window filters. Retention configurable via MDDB_AUDIT_RETENTION_DAYS (default 90)
✅ Incident webhook events - subscribe on /v1/webhooks to security.auth_failure_burst, security.rate_limit_exceeded, ops.replication_lag_high, ops.panic_recovered, ops.disk_usage_high. Panic-recovery middleware turns handler crashes into structured 500 + event instead of process kill
✅ At-rest encryption (opt-in per collection) - AES-256-GCM on document values. Enable globally with MDDB_ENCRYPTION_KEY (32 B base64) and flip CollectionConfig.encrypted=true per collection. Legacy plaintext stays readable after flip. FTS / vector indexes remain plaintext (queryable). Losing the key is terminal, so store it in an HSM with escrow
✅ Encryption key rotation (2.9.16) - V2 ciphertext format prefixes the keyID byte so the encryptor can hold a primary plus any number of read-only previous keys. Rotate by setting a fresh MDDB_ENCRYPTION_KEY + MDDB_ENCRYPTION_KEY_ID and listing every superseded key in MDDB_ENCRYPTION_KEYS_PREVIOUS (JSON [{"id":1,"key":"..."}]). Old documents stay readable; the admin endpoint POST /v1/encryption/rotate (or panel "Encryption", then "Start rotation") rewrites every encrypted entry under the new primary in the background. V1 (2.9.15) ciphertexts continue to decrypt, so the change is non-breaking
✅ Audit log export to SIEM / syslog (2.9.16) - MDDB_AUDIT_EXPORT_WEBHOOK_URL mirrors every audit event as JSON to a SIEM (Splunk HEC, Datadog Logs, ELK) with custom auth headers from MDDB_AUDIT_EXPORT_WEBHOOK_HEADER. MDDB_AUDIT_EXPORT_SYSLOG_ADDR=host:port (or tcp://host:port) sends RFC 5424 framed messages to a syslog collector. Both can run together. Per-sink delivered/failed/dropped counters at GET /v1/audit/exporters and in the Security panel
✅ HTTP + gRPC rate limiting - MDDB_RATE_LIMIT_ENABLED=true enforces a single sliding-window budget across both transports (per-IP by default, MDDB_RATE_LIMIT_BY=user keys on authenticated username). Emits X-RateLimit-* headers + 429 Retry-After on HTTP; ResourceExhausted on gRPC. Health / metrics endpoints are always exempt
✅ Production hardening switch - MDDB_PRODUCTION=true fails startup unless every compliance guardrail is satisfied (auth on, JWT secret of 32 bytes or more, TLS on, CORS explicit, audit + rate limit enabled). Unset = silent warning; no breaking change for existing deployments. Details

Full compliance map, threat model, operational checklist

Replication & High Availability

✅ Leader-Follower Replication - Binlog streaming for read scaling
✅ Automatic Catch-up - Followers pull missing transactions
✅ Zero-Downtime Snapshots - Full sync for new followers
✅ Cluster Monitoring - Web panel with health and lag metrics

See all features | Compare with alternatives | Measured benchmarks

🔄 Replication Architecture

MDDB supports leader-follower replication allowing you to scale read operations horizontally.

graph LR
    C[Clients] -->|Writes/Reads| L[Leader]
    C -->|Reads| F1[Follower 1]
    C -->|Reads| F2[Follower 2]
    L -->|gRPC StreamBinlog| F1
    L -->|gRPC StreamBinlog| F2

Leader: Handles writes, maintains changes in a binary log, and streams them via gRPC.
Followers: Read-only, pulls transactions, reconnects automatically.

Read Full Replication Guide

🎨 Web Admin Panel

Modern React-based UI for managing documents, users, and search with REST/GraphQL API toggle.

Features: Browse collections, view/edit documents, vector search, user management, API mode switching (REST and GraphQL), live markdown preview.

Panel documentation

📖 Quick Examples

Upload Files (PDF, DOCX, HTML, ODT, RTF, TEX, YAML, TXT)

# Upload a PDF, auto-converted to Markdown
curl -X POST http://localhost:11023/v1/upload \
  -F "file=@report.pdf" \
  -F "collection=docs" \
  -F "lang=en_US"

# Upload with custom key and metadata
curl -X POST http://localhost:11023/v1/upload \
  -F "file=@manual.docx" \
  -F "collection=docs" \
  -F "key=user-manual" \
  -F "lang=en_US" \
  -F 'meta={"category":["documentation"]}'

# Batch upload multiple files
curl -X POST http://localhost:11023/v1/upload \
  -F "files[]=@doc1.pdf" \
  -F "files[]=@doc2.html" \
  -F "files[]=@doc3.txt" \
  -F "collection=docs" \
  -F "lang=en_US"

Add and Retrieve Documents

# Add a document
curl -X POST http://localhost:11023/v1/add \
  -H 'Content-Type: application/json' \
  -d '{
    "collection": "blog",
    "key": "hello-world",
    "lang": "en_US",
    "meta": {"author": ["John"], "tags": ["tutorial"]},
    "contentMd": "# Hello World\n\nWelcome to MDDB!"
  }'

# Get document
curl -X POST http://localhost:11023/v1/get \
  -H 'Content-Type: application/json' \
  -d '{"collection": "blog", "key": "hello-world", "lang": "en_US"}'

# Search by metadata
curl -X POST http://localhost:11023/v1/search \
  -H 'Content-Type: application/json' \
  -d '{"collection": "blog", "filterMeta": {"tags": ["tutorial"]}, "limit": 10}'

Vector Search (Semantic)

# Documents auto-embedded in background
# Search by meaning, not keywords
curl -X POST http://localhost:11023/v1/vector-search \
  -H 'Content-Type: application/json' \
  -d '{
    "collection": "kb",
    "query": "how do I cancel my subscription?",
    "topK": 5,
    "threshold": 0.7,
    "includeContent": true
  }'

Hybrid Search (Sparse + Dense)

Combine keyword (BM25/BM25F) and semantic (vector) search in a single query. Two merge strategies:

Alpha Blending: combined = (1-a) * BM25_score + a * vector_score -- configurable weight
RRF (Reciprocal Rank Fusion): rank-based fusion that is robust to different score distributions

curl -X POST http://localhost:11023/v1/hybrid-search \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "docs",
    "query": "machine learning",
    "topK": 10,
    "strategy": "alpha",
    "alpha": 0.5
  }'

Full-Text Search (7 Modes)

FTS supports simple, boolean, phrase, wildcard, proximity, range, and fuzzy modes with auto-detection:

# Simple search with metadata pre-filtering
curl -X POST http://localhost:11023/v1/fts \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "blog",
    "query": "getting started",
    "limit": 10,
    "algorithm": "bm25",
    "filterMeta": {"category": ["tutorial"]}
  }'

# Boolean search (AND, OR, NOT, +required, -excluded)
curl -X POST http://localhost:11023/v1/fts \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "blog",
    "query": "rust AND performance NOT garbage",
    "mode": "boolean"
  }'

# Phrase search (exact sequence)
curl -X POST http://localhost:11023/v1/fts \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "blog",
    "query": "\"machine learning\"",
    "mode": "phrase"
  }'

# Proximity search (terms within N words)
curl -X POST http://localhost:11023/v1/fts \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "blog",
    "query": "\"database performance\"~5",
    "mode": "proximity",
    "distance": 5
  }'

GraphQL

# Enable GraphQL
docker run -e MDDB_GRAPHQL_ENABLED=true -p 11023:11023 tradik/mddb

# Query
curl -X POST http://localhost:11023/graphql \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "{ document(collection: \"blog\", key: \"hello-world\", lang: \"en\") { contentMd meta } }"
  }'

# Interactive Playground
open http://localhost:11023/playground

CLI Client

# Install CLI
wget https://github.com/tradik/mddb/releases/latest/download/mddb-cli-latest-linux-amd64.deb
sudo dpkg -i mddb-cli-latest-linux-amd64.deb

# Use CLI
mddb-cli add blog hello en_US -f post.md -m "author=John,tags=tutorial"
mddb-cli get blog hello en_US
mddb-cli search blog -f "tags=tutorial"
mddb-cli fts blog --query="getting started"
mddb-cli stats

API reference | Use case examples | Client libraries

📚 Documentation

🌐 Official Website - Complete documentation, downloads, examples

Getting Started

Quick Start Guide - 5-minute setup
Installation Guide - All platforms (Linux, macOS, FreeBSD, Windows)
Use Cases - Real-world examples

API Documentation

HTTP/JSON API - Complete REST API reference
gRPC API - High-performance protocol guide
GraphQL API - Flexible query language
OpenAPI/Swagger - Machine-readable spec
Swagger UI - Interactive API docs

Features & Guides

Vector Search - Semantic search setup (OpenAI, Cohere, Voyage, Ollama)
RAG Pipeline - Complete RAG implementation guide
Search Algorithms - TF-IDF, BM25, BM25F, PMISparse, Flat, HNSW, IVF, PQ, SQ, BQ
Vector Quantization - Per-collection int8/int4 scalar quantization (4-8x compression)
Server-Sent Events - Real-time document change notifications with auth and rate limiting
Search algorithms - Inverted index, four ranking algorithms, multi-language
Zero-Shot Classification - Classify documents against labels using embeddings
PMISparse - Two-phase BM25 + PPMI query expansion (invented by Tradik Limited)
Webhooks - Event-driven integration (API reference)
Automations - Triggers, crons, webhooks, sentiment, template variables
Temporal Tracking - Document event history, hot-docs leaderboard, activity histograms
Spell Correction - SymSpell FTS spell suggestions, text cleanup, custom dictionaries
Authentication - JWT & API keys, RBAC
Web Panel - Admin UI guide
LLM Connections - MCP for Claude, ChatGPT, Ollama, DeepSeek
Integrations - Docling, Langflow, OpenSearch, SSG, wpexporter, Airbyte, WordPress Sync, GitHub Action, Grafana datasource, Chrome browser extension
Bulk Import - Load markdown folders
Blog - Release announcements and engineering notes

Operations

Docker Guide - Container deployment
Backup, Restore & Repair - Consistent verified backups, safe restores, mddbd -verify-db / -repair-db for a damaged database file
Deployment - Production setup
Telemetry - Prometheus metrics, Grafana
Health Checks - Docker & Kubernetes
Benchmarks - FTS algorithm comparison, measured
Architecture - System design

Development

Client Libraries - PHP, Python, Go, Node.js
Custom MCP Tools - YAML-defined AI tools
Examples - Code samples
Contributing - Development guide
Versioning - What moves with a release, and what does not
Changelog - Version history

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│     AI Agents (Claude, ChatGPT, Cursor, Windsurf)   │
│     |  MCP (stdio / HTTP :9000)                     │
├─────────────────────────────────────────────────────┤
│         Other Clients                               │
├──────────┬──────────┬──────────┬────────────────────┤
│HTTP/JSON │gRPC/Proto│ GraphQL  │ HTTP/3             │
│  :11023  │  :11024  │ /graphql │ :11443             │
├──────────┴──────────┴──────────┴────────────────────┤
│           MDDB Server (Go)                          │
│  - File Upload (PDF/DOCX/HTML/TXT to Markdown)      │
│  - Auto-Embeddings (OpenAI, Ollama, Cohere, Voyage) │
│  - Vector + Full-Text + Hybrid Search               │
│  - Zero-Shot Classification                         │
│  - Automation (triggers, crons, webhooks)           │
│  - JWT Auth + RBAC                                  │
├─────────────────────────────────────────────────────┤
│      BoltDB (Embedded ACID Storage)                 │
│  - B+Tree index, single-file, MVCC transactions     │
└─────────────────────────────────────────────────────┘

Detailed architecture

🗺️ What's next

Shipped work is in CHANGELOG.md. What people are asking for is in Issues and Discussions. Both are current by construction, which a hand-written roadmap was not.

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Security issues: See SECURITY.md

📄 License

BSD 3-Clause License - see LICENSE

🔗 Quick Links

GitHub - Source code
Docker Hub - Container images
Releases - Download binaries
Documentation - Full docs
LLM Connections - Claude, ChatGPT, Ollama, DeepSeek, Manus, Bielik.ai
Issues - Bug reports