{"id":45916997,"url":"https://github.com/tradik/mddb","last_synced_at":"2026-04-06T09:02:51.954Z","repository":{"id":323355958,"uuid":"1091360723","full_name":"tradik/mddb","owner":"tradik","description":"A minimal, lightweight structured data store designed for small applications, scripts and automation workflows. Built for simplicity, portability and low overhead.","archived":false,"fork":false,"pushed_at":"2026-03-26T09:10:21.000Z","size":47826,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-26T19:11:12.674Z","etag":null,"topics":["automation","database","embedded-systems","go","golang","key-value-store","lightweight-database","markdown","rag-pipeline","search-algorithm","structured-data","vector-database"],"latest_commit_sha":null,"homepage":"http://mddb.tradik.com/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tradik.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-06T23:06:58.000Z","updated_at":"2026-03-26T09:10:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tradik/mddb","commit_stats":null,"previous_names":["tradik/mddb"],"tags_count":30,"template":false,"template_full_name":null,"purl":"pkg:github/tradik/mddb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tradik%2Fmddb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tradik%2Fmddb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tradik%2Fmddb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tradik%2Fmddb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tradik","download_url":"https://codeload.github.com/tradik/mddb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tradik%2Fmddb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31466228,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T08:36:52.050Z","status":"ssl_error","status_checked_at":"2026-04-06T08:36:51.267Z","response_time":112,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","database","embedded-systems","go","golang","key-value-store","lightweight-database","markdown","rag-pipeline","search-algorithm","structured-data","vector-database"],"created_at":"2026-02-28T07:54:03.057Z","updated_at":"2026-04-06T09:02:51.948Z","avatar_url":"https://github.com/tradik.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MDDB — AI-Native Document Database\n\n[![Go Version](https://img.shields.io/badge/Go-1.26-blue.svg)](https://golang.org)\n[![License](https://img.shields.io/badge/license-BSD--3--Clause-green.svg)](LICENSE)\n[![Release](https://img.shields.io/github/v/release/tradik/mddb)](https://github.com/tradik/mddb/releases)\n[![Docker](https://img.shields.io/docker/v/tradik/mddb?label=docker)](https://hub.docker.com/r/tradik/mddb)\n[![Docker Pulls](https://img.shields.io/docker/pulls/tradik/mddb)](https://hub.docker.com/r/tradik/mddb)\n[![Tests](https://github.com/tradik/mddb/workflows/Tests/badge.svg)](https://github.com/tradik/mddb/actions)\n\n**AI-native document database with built-in MCP server, file upload (PDF/DOCX/HTML/ODT/RTF/TEX/YAML→Markdown), vector search, RAG pipelines, and 54 MCP tools. Plugs directly into Claude, ChatGPT, Cursor, Windsurf, and any MCP-compatible agent.**\n\nMDDB is a document database purpose-built for AI agents and LLM workflows. Upload files (PDF, DOCX, HTML, ODT, RTF, TEX, YAML, TXT) — they're auto-converted to Markdown and embedded for semantic search. Expose everything to AI agents via 54 built-in MCP tools. Integrates with [Docling](docs/INTEGRATIONS.md#1-docling--mddb-document-ingestion), [Langflow](docs/INTEGRATIONS.md#2-langflow--mddb-visual-rag-orchestration), [OpenSearch](docs/INTEGRATIONS.md#3-opensearch--mddb-scalable-search), [SSG](docs/INTEGRATIONS.md#4-ssg--static-site-generator-from-mddb), and [wpexporter](docs/INTEGRATIONS.md#5-wpexporter--wordpress-to-mddb-migration) for production pipelines. Single ~29MB binary, zero configuration, BoltDB embedded storage, triple-protocol APIs (HTTP + gRPC + GraphQL).\n\n## 🎯 What is MDDB?\n\nMDDB gives your AI agents a persistent, searchable knowledge base:\n\n- **File Upload** - Upload PDF, DOCX, HTML, ODT, RTF, TEX, YAML, TXT files — auto-converted to Markdown and indexed\n- **Built-in MCP Server** - 54 tools for Claude Desktop, Cursor, Windsurf, or any MCP client\n- **Vector Search** - Auto-embed documents, semantic similarity with 6 index algorithms (Flat, HNSW, IVF, PQ, SQ, BQ) + per-collection quantization (int8/int4)\n- **RAG-Ready** - Hybrid search (BM25 + vector) for retrieval-augmented generation\n- **Memory RAG** - Conversational memory system: store, recall, and summarize chat sessions with semantic search\n- **Integrations** - [Docling](docs/INTEGRATIONS.md), [Langflow](docs/INTEGRATIONS.md), [OpenSearch](docs/INTEGRATIONS.md), [SSG](docs/INTEGRATIONS.md), [wpexporter](docs/INTEGRATIONS.md) for production pipelines\n- **Zero-Shot Classification** — Classify documents against candidate labels using embeddings, no training data\n- **Custom AI Tools** - Define YAML-based MCP tools for domain-specific workflows\n- **Full-Text Search** - Built-in inverted index with TF-IDF, BM25, BM25F, PMISparse, 7 search modes (simple, boolean, phrase, wildcard, proximity, range, fuzzy), typo tolerance, multi-language stemming (18 languages), synonyms\n- **Full Revision History** - Every update creates a new revision with complete snapshots\n- **Triple Protocol APIs** - HTTP/JSON (easy), gRPC (fast), or GraphQL (flexible)\n- **Automation** - Triggers, crons, webhooks with template variables and sentiment analysis\n- **Real-Time Events** - Server-Sent Events (SSE) for live document change notifications\n- **MCP Transports** - Streamable HTTP (`/mcp`, 2025-11-25), legacy SSE (`/sse`), and stdio\n- **Built-in TLS** - Native HTTPS support, connection pooling, pprof profiling\n- **Zero Configuration** - Single ~29MB binary, embedded database, no dependencies\n\n**Perfect for:** AI agent memory, RAG pipelines, knowledge bases for LLMs, documentation chatbots, semantic search APIs, document processing (PDF/DOCX→Markdown), static site generation, WordPress migration\n\n## 🚀 Quick Start\n\n### Docker Compose (Recommended) - Full Stack\n\nStart all services with one command:\n\n```bash\ngit clone https://github.com/tradik/mddb.git\ncd mddb\n\n# Production mode (all services)\ndocker compose up -d\n\n# Development mode (with hot reload)\nmake dev-start\n\n# Development + Ollama for embeddings\nmake dev-start-with-ollama\n```\n\n**Services started:**\n\n| Service | Port | Image | Description |\n|---------|------|-------|-------------|\n| **mddbd** | 11023 (HTTP), 11024 (gRPC), 9000 (MCP), 11443 (HTTP/3) | `tradik/mddb:latest` | Database server with MCP built-in |\n| **mddb-panel** | 3000 | `tradik/mddb:panel` | React web admin UI |\n\n### Connect to Claude / Cursor / Windsurf (MCP)\n\nMDDB has a built-in MCP server — no extra service needed. Add to your MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"mddb\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"-i\", \"--rm\", \"--network\", \"host\",\n        \"-v\", \"mddb-data:/app/data\",\n        \"-e\", \"MDDB_MCP_STDIO=true\",\n        \"tradik/mddb:latest\"\n      ]\n    }\n  }\n}\n```\n\nThat's it — your AI agent now has full access to your knowledge base with 54 built-in tools (add, search, vector search, classify, and more).\n\n**[→ Full MCP setup guide](docs/LLM_CONNECTIONS.md)** | **[→ MCP server config](docs/MCP.md)** | **[→ Custom MCP tools](docs/CUSTOM-TOOLS.md)**\n\n### Docker - Individual Services\n\n```bash\n# MDDB Server only\ndocker run -d --name mddb \\\n  -p 11023:11023 -p 11024:11024 -p 9000:9000 \\\n  -v mddb-data:/data \\\n  tradik/mddb:latest\n\n# Web Panel (connect to existing server)\ndocker run -d --name mddb-panel \\\n  -p 3000:3000 \\\n  -e VITE_MDDB_SERVER=host.docker.internal:11023 \\\n  tradik/mddb:panel\n\n# MCP stdio mode (for Claude Desktop, Windsurf, etc.)\ndocker run -i --rm --network host \\\n  -v mddb-data:/app/data \\\n  -e MDDB_MCP_STDIO=true \\\n  tradik/mddb:latest\n\n# Test it\ncurl http://localhost:11023/health\n```\n\n**Docker Hub:** https://hub.docker.com/r/tradik/mddb\n\n### Install Binary\n\n**Linux (Debian/Ubuntu):**\n```bash\nwget https://github.com/tradik/mddb/releases/latest/download/mddbd-latest-linux-amd64.deb\nsudo dpkg -i mddbd-latest-linux-amd64.deb\nsudo systemctl start mddbd\n```\n\n**macOS (Apple Silicon):**\n```bash\nwget https://github.com/tradik/mddb/releases/latest/download/mddbd-latest-darwin-arm64.tar.gz\ntar xzf mddbd-latest-darwin-arm64.tar.gz\nsudo mv mddbd-latest-darwin-arm64/mddbd /usr/local/bin/\nmddbd\n```\n\n**CLI Client:**\n```bash\n# Linux\nwget https://github.com/tradik/mddb/releases/latest/download/mddb-cli-latest-linux-amd64.deb\nsudo dpkg -i mddb-cli-latest-linux-amd64.deb\n\n# Usage\nmddb-cli stats\nmddb-cli add blog hello en_US -f post.md\nmddb-cli search blog -f \"tags=tutorial\"\nmddb-cli fts blog --query=\"getting started\" --algorithm=bm25\n```\n\n**Other platforms:** See [Installation Guide](docs/INSTALLATION.md)\n\n### Build from Source\n\n```bash\ngit clone https://github.com/tradik/mddb.git\ncd mddb\nmake build\n./services/mddbd/mddbd\n```\n\n## 📦 Packages \u0026 Client Libraries\n\nMDDB ships as a monorepo with multiple packages:\n\n### Server \u0026 Tools\n\n| Package | Language | Location | Description |\n|---------|----------|----------|-------------|\n| **mddbd** | Go | `services/mddbd/` | Database server (HTTP + gRPC + GraphQL + MCP) |\n| **mddb-panel** | React/JS | `services/mddb-panel/` | Web admin panel |\n| **mddb-cli** | Go | `services/mddb-cli/` | Command-line client with GraphQL support |\n| **mddb-chat** | Rust | `services/mddb-chat/` | WebSocket chat server with LLM integration |\n| **mddb-chat-widget** | JS/TS | `services/mddb-chat-widget/` | Embeddable JS chat widget |\n\n### Client Libraries (REST)\n\nZero-dependency HTTP clients - copy a single file into your project:\n\n| Library | Language | Location | Install |\n|---------|----------|----------|---------|\n| **PHP Extension** | PHP 8.0+ | `services/php-extension/mddb.php` | Copy `mddb.php` into your project |\n| **Python Extension** | Python 3.8+ | `services/python-extension/mddb.py` | Copy `mddb.py` into your project |\n\n**PHP:**\n```php\nrequire_once 'mddb.php';\n$db = mddb::connect('localhost:11023', 'write');\n$db-\u003ecollection('blog')-\u003eadd('hello', 'en_US', ['author' =\u003e ['John']], '# Hello');\n$results = $db-\u003ecollection('blog')-\u003evectorSearch('cancel subscription', 5, 0.7);\n```\n\n**Python:**\n```python\nfrom mddb import MDDB\ndb = MDDB.connect('localhost:11023', 'write').collection('blog')\ndb.add('hello', 'en_US', {'author': ['John']}, '# Hello')\nresults = db.vector_search('cancel subscription', top_k=5)\n```\n\n### Client Libraries (gRPC)\n\nHigh-performance clients generated from Protocol Buffers:\n\n| Library | Language | Location | Description |\n|---------|----------|----------|-------------|\n| **Go Client** | Go | `services/mddbd/proto/` | Native Go gRPC stubs |\n| **Python gRPC** | Python | `clients/python/` | Generated Python gRPC client |\n| **Node.js gRPC** | Node.js | `clients/nodejs/` | Uses `@grpc/grpc-js` |\n\nProto definitions at `proto/mddb.proto` - generate clients for any language supported by protobuf.\n\n### Docker Images ([Docker Hub](https://hub.docker.com/r/tradik/mddb))\n\n| Image | Size | Description |\n|-------|------|-------------|\n| `tradik/mddb:latest` | ~29MB | Database server with MCP built-in (Alpine) |\n| `tradik/mddb:panel` | ~88MB | Web admin panel (Node Alpine) |\n| `tradik/mddb:cli` | ~8MB | CLI client (Alpine) |\n\n### System Packages\n\n| Format | Platform | Contents |\n|--------|----------|----------|\n| `.deb` | Debian/Ubuntu | mddbd + systemd unit + man page |\n| `.rpm` | RHEL/CentOS/Fedora | mddbd + systemd unit + man page |\n| `.tar.gz` | Any (Linux, macOS, FreeBSD) | Standalone binary |\n\n## 💡 Key Features\n\n### AI \u0026 Search\n- ✅ **MCP Server** - 54 built-in tools via Model Context Protocol 2025-11-25 (stdio + Streamable HTTP + SSE) with tool annotations, prompts, completion, and structured output\n- ✅ **File Upload** - Upload PDF, DOCX, HTML, ODT, RTF, TEX, YAML, TXT — auto-converted to Markdown (single and batch, configurable size limit)\n- ✅ **Vector Search** - Semantic similarity with auto-embeddings (OpenAI, Ollama, Cohere, Voyage)\n- ✅ **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)\n- ✅ **Hybrid Search** - Sparse (BM25) + dense (vector) fusion with alpha blending or RRF\n- ✅ **Aggregations** - Metadata facets (value counts) and date histograms with optional pre-filtering\n- ✅ **Zero-Shot Classification** - Classify documents against candidate labels using embedding similarity\n- ✅ **Custom MCP Tools** - Define YAML-based AI tools for domain-specific workflows\n- ✅ **RAG Pipeline** - Built-in support for retrieval-augmented generation workflows\n- ✅ **Integrations** - Docling, Langflow, OpenSearch, SSG, wpexporter ([guide](docs/INTEGRATIONS.md))\n\n### Core Functionality\n- ✅ **Document Management** - Full CRUD with metadata and collections\n- ✅ **Revision History** - Complete version control with snapshots\n- ✅ **Metadata Search** - Fast indexed queries with multi-value tags\n- ✅ **Collection Checksum** - Lightweight CRC32 checksum per collection for cache invalidation\n- ✅ **Partial Document Update** - Update metadata and/or content independently\n- ✅ **Document TTL** - Time-to-live with automatic cleanup\n- ✅ **Automation** - Triggers, crons, webhooks with template variables, sentiment analysis, execution logs\n- ✅ **Multi-language** - Same key, multiple languages\n- ✅ **Schema Validation** - JSON Schema validation per collection\n- ✅ **Per-Collection Storage Backends** - Choose BoltDB (default), in-memory (ephemeral), or S3/MinIO per collection\n\n### APIs \u0026 Protocols\n- ✅ **HTTP/JSON REST** - Easy debugging, extensive docs\n- ✅ **gRPC/Protobuf** - 16x faster, 70% smaller payload\n- ✅ **GraphQL** - Flexible queries, schema introspection, Playground\n- ✅ **CLI Client** - Full-featured command-line with GraphQL support\n- ✅ **Web Panel** - React UI with REST/GraphQL toggle\n\n### Security \u0026 Access\n- ✅ **Authentication** - JWT tokens and API keys\n- ✅ **Authorization** - Collection-level RBAC (Read/Write/Admin)\n- ✅ **Per-Protocol Access Modes** - `MDDB_MCP_MODE=read` (MCP read-only), `MDDB_API_MODE`, `MDDB_GRPC_MODE`, `MDDB_HTTP3_MODE`\n- ✅ **MCP Tool Control** - `MDDB_MCP_BUILTIN_TOOLS=false` to expose only custom YAML tools\n- ✅ **User Management** - Multi-user with admin roles\n- ✅ **Group Permissions** - Organize users into groups\n\n### Replication \u0026 High Availability\n- ✅ **Leader-Follower Replication** - Binlog streaming for read scaling\n- ✅ **Automatic Catch-up** - Followers pull missing transactions\n- ✅ **Zero-Downtime Snapshots** - Full sync for new followers\n- ✅ **Cluster Monitoring** - Web panel with health and lag metrics\n\n**[→ See all features](docs/FEATURES.md)** | **[→ Compare with alternatives](docs/COMPARISON.md)** | **[→ Performance benchmarks](docs/PERFORMANCE.md)**\n\n## 🔄 Replication Architecture\n\nMDDB supports leader-follower replication allowing you to scale read operations horizontally.\n\n```mermaid\ngraph LR\n    C[Clients] --\u003e|Writes/Reads| L[Leader]\n    C --\u003e|Reads| F1[Follower 1]\n    C --\u003e|Reads| F2[Follower 2]\n    L --\u003e|gRPC StreamBinlog| F1\n    L --\u003e|gRPC StreamBinlog| F2\n```\n\n- **Leader**: Handles writes, maintains changes in a binary log, and streams them via gRPC.\n- **Followers**: Read-only, pulls transactions, reconnects automatically.\n\n**[→ Read Full Replication Guide](docs/REPLICATION.md)**\n\n## 🎨 Web Admin Panel\n\nModern React-based UI for managing documents, users, and search with REST/GraphQL API toggle.\n\n![MDDB Web Panel](docs/panel.png)\n\n**Features:** Browse collections, view/edit documents, vector search, user management, API mode switching (REST ↔ GraphQL), live markdown preview.\n\n**[→ Panel documentation](docs/PANEL.md)**\n\n## 📖 Quick Examples\n\n### Upload Files (PDF, DOCX, HTML, ODT, RTF, TEX, YAML, TXT)\n\n```bash\n# Upload a PDF — auto-converted to Markdown\ncurl -X POST http://localhost:11023/v1/upload \\\n  -F \"file=@report.pdf\" \\\n  -F \"collection=docs\" \\\n  -F \"lang=en_US\"\n\n# Upload with custom key and metadata\ncurl -X POST http://localhost:11023/v1/upload \\\n  -F \"file=@manual.docx\" \\\n  -F \"collection=docs\" \\\n  -F \"key=user-manual\" \\\n  -F \"lang=en_US\" \\\n  -F 'meta={\"category\":[\"documentation\"]}'\n\n# Batch upload multiple files\ncurl -X POST http://localhost:11023/v1/upload \\\n  -F \"files[]=@doc1.pdf\" \\\n  -F \"files[]=@doc2.html\" \\\n  -F \"files[]=@doc3.txt\" \\\n  -F \"collection=docs\" \\\n  -F \"lang=en_US\"\n```\n\n### Add and Retrieve Documents\n\n```bash\n# Add a document\ncurl -X POST http://localhost:11023/v1/add \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"collection\": \"blog\",\n    \"key\": \"hello-world\",\n    \"lang\": \"en_US\",\n    \"meta\": {\"author\": [\"John\"], \"tags\": [\"tutorial\"]},\n    \"contentMd\": \"# Hello World\\n\\nWelcome to MDDB!\"\n  }'\n\n# Get document\ncurl -X POST http://localhost:11023/v1/get \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"collection\": \"blog\", \"key\": \"hello-world\", \"lang\": \"en_US\"}'\n\n# Search by metadata\ncurl -X POST http://localhost:11023/v1/search \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"collection\": \"blog\", \"filterMeta\": {\"tags\": [\"tutorial\"]}, \"limit\": 10}'\n```\n\n### Vector Search (Semantic)\n\n```bash\n# Documents auto-embedded in background\n# Search by meaning, not keywords\ncurl -X POST http://localhost:11023/v1/vector-search \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"collection\": \"kb\",\n    \"query\": \"how do I cancel my subscription?\",\n    \"topK\": 5,\n    \"threshold\": 0.7,\n    \"includeContent\": true\n  }'\n```\n\n### Hybrid Search (Sparse + Dense)\n\nCombine keyword (BM25/BM25F) and semantic (vector) search in a single query. Two merge strategies:\n- **Alpha Blending**: `combined = (1-a) * BM25_score + a * vector_score` -- configurable weight\n- **RRF (Reciprocal Rank Fusion)**: rank-based fusion that is robust to different score distributions\n\n```bash\ncurl -X POST http://localhost:11023/v1/hybrid-search \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"collection\": \"docs\",\n    \"query\": \"machine learning\",\n    \"topK\": 10,\n    \"strategy\": \"alpha\",\n    \"alpha\": 0.5\n  }'\n```\n\n### Full-Text Search (7 Modes)\n\nFTS supports simple, boolean, phrase, wildcard, proximity, range, and fuzzy modes with auto-detection:\n\n```bash\n# Simple search with metadata pre-filtering\ncurl -X POST http://localhost:11023/v1/fts \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"collection\": \"blog\",\n    \"query\": \"getting started\",\n    \"limit\": 10,\n    \"algorithm\": \"bm25\",\n    \"filterMeta\": {\"category\": [\"tutorial\"]}\n  }'\n\n# Boolean search (AND, OR, NOT, +required, -excluded)\ncurl -X POST http://localhost:11023/v1/fts \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"collection\": \"blog\",\n    \"query\": \"rust AND performance NOT garbage\",\n    \"mode\": \"boolean\"\n  }'\n\n# Phrase search (exact sequence)\ncurl -X POST http://localhost:11023/v1/fts \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"collection\": \"blog\",\n    \"query\": \"\\\"machine learning\\\"\",\n    \"mode\": \"phrase\"\n  }'\n\n# Proximity search (terms within N words)\ncurl -X POST http://localhost:11023/v1/fts \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"collection\": \"blog\",\n    \"query\": \"\\\"database performance\\\"~5\",\n    \"mode\": \"proximity\",\n    \"distance\": 5\n  }'\n```\n\n### GraphQL\n\n```bash\n# Enable GraphQL\ndocker run -e MDDB_GRAPHQL_ENABLED=true -p 11023:11023 tradik/mddb\n\n# Query\ncurl -X POST http://localhost:11023/graphql \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"query\": \"{ document(collection: \\\"blog\\\", key: \\\"hello-world\\\", lang: \\\"en\\\") { contentMd meta } }\"\n  }'\n\n# Interactive Playground\nopen http://localhost:11023/playground\n```\n\n### CLI Client\n\n```bash\n# Install CLI\nwget https://github.com/tradik/mddb/releases/latest/download/mddb-cli-latest-linux-amd64.deb\nsudo dpkg -i mddb-cli-latest-linux-amd64.deb\n\n# Use CLI\nmddb-cli add blog hello en_US -f post.md -m \"author=John,tags=tutorial\"\nmddb-cli get blog hello en_US\nmddb-cli search blog -f \"tags=tutorial\"\nmddb-cli fts blog --query=\"getting started\"\nmddb-cli stats\n```\n\n**[→ More examples](docs/API_QUICK_REFERENCE.md)** | **[→ Use case examples](docs/USE_CASES.md)** | **[→ Client libraries](docs/CLIENTS.md)**\n\n## 📚 Documentation\n\n**🌐 [Official Website](https://mddb.tradik.com/mddb/)** - Complete documentation, downloads, examples\n\n### Getting Started\n- **[Quick Start Guide](docs/QUICKSTART.md)** - 5-minute setup\n- **[Installation Guide](docs/INSTALLATION.md)** - All platforms (Linux, macOS, FreeBSD, Windows)\n- **[Use Cases](docs/USE_CASES.md)** - Real-world examples\n\n### API Documentation\n- **[HTTP/JSON API](docs/API.md)** - Complete REST API reference\n- **[gRPC API](docs/GRPC.md)** - High-performance protocol guide\n- **[GraphQL API](docs/GRAPHQL.md)** - Flexible query language\n- **[OpenAPI/Swagger](docs/openapi.yaml)** - Machine-readable spec\n- **[Swagger UI](docs/swagger.html)** - Interactive API docs\n\n### Features \u0026 Guides\n- **[Vector Search](docs/EMBEDDING_PROVIDERS.md)** - Semantic search setup (OpenAI, Cohere, Voyage, Ollama)\n- **[RAG Pipeline](docs/RAG-PIPELINE.md)** - Complete RAG implementation guide\n- **[Search Algorithms](docs/SEARCH.md)** - TF-IDF, BM25, BM25F, PMISparse, Flat, HNSW, IVF, PQ, SQ, BQ\n- **[Vector Quantization](docs/QUANTIZATION.md)** - Per-collection int8/int4 scalar quantization (4-8x compression)\n- **[Server-Sent Events](docs/SSE.md)** - Real-time document change notifications with auth and rate limiting\n- **[Full-Text Search](docs/FTS.md)** - Built-in inverted index with multi-language support\n- **[Zero-Shot Classification](docs/ZERO-SHOT-CLASSIFICATION.md)** - Classify documents against labels using embeddings\n- **[PMISparse](docs/PMISPARSE.md)** - Two-phase BM25 + PPMI query expansion (invented by Tradik Limited)\n- **[Webhooks](docs/WEBHOOKS.md)** - Event-driven integration\n- **[Automations](docs/AUTOMATIONS.md)** - Triggers, crons, webhooks, sentiment, template variables\n- **[Authentication](docs/AUTH.md)** - JWT \u0026 API keys, RBAC\n- **[Web Panel](docs/PANEL.md)** - Admin UI guide\n- **[LLM Connections](docs/LLM_CONNECTIONS.md)** - MCP for Claude, ChatGPT, Ollama, DeepSeek\n- **[Integrations](docs/INTEGRATIONS.md)** - Docling, Langflow, OpenSearch, SSG, wpexporter\n- **[Bulk Import](docs/BULK-IMPORT.md)** - Load markdown folders\n\n### Operations\n- **[Docker Guide](docs/DOCKER.md)** - Container deployment\n- **[Deployment](docs/DEPLOYMENT.md)** - Production setup\n- **[Telemetry](docs/TELEMETRY.md)** - Prometheus metrics, Grafana\n- **[Health Checks](docs/HEALTHCHECK.md)** - Docker \u0026 Kubernetes\n- **[Performance](docs/PERFORMANCE.md)** - Benchmarks \u0026 tuning\n- **[Architecture](docs/ARCHITECTURE.md)** - System design\n\n### Development\n- **[Client Libraries](docs/CLIENTS.md)** - PHP, Python, Go, Node.js\n- **[Custom MCP Tools](docs/CUSTOM-TOOLS.md)** - YAML-defined AI tools\n- **[Examples](docs/EXAMPLES.md)** - Code samples\n- **[Contributing](CONTRIBUTING.md)** - Development guide\n- **[Changelog](CHANGELOG.md)** - Version history\n\n## 🏗️ Architecture\n\n```\n┌─────────────────────────────────────────────────────┐\n│     AI Agents (Claude, ChatGPT, Cursor, Windsurf)   │\n│     ↕ MCP (stdio / HTTP :9000)                      │\n├─────────────────────────────────────────────────────┤\n│         Other Clients                               │\n├──────────┬──────────┬──────────┬────────────────────┤\n│HTTP/JSON │gRPC/Proto│ GraphQL  │ HTTP/3             │\n│  :11023  │  :11024  │ /graphql │ :11443             │\n├──────────┴──────────┴──────────┴────────────────────┤\n│           MDDB Server (Go)                          │\n│  • File Upload (PDF/DOCX/HTML/TXT → Markdown)       │\n│  • Auto-Embeddings (OpenAI, Ollama, Cohere, Voyage) │\n│  • Vector + Full-Text + Hybrid Search               │\n│  • Zero-Shot Classification                         │\n│  • Automation (triggers, crons, webhooks)            │\n│  • JWT Auth + RBAC                                  │\n├─────────────────────────────────────────────────────┤\n│      BoltDB (Embedded ACID Storage)                 │\n│  • B+Tree index • Single-file • MVCC transactions   │\n└─────────────────────────────────────────────────────┘\n```\n\n**[→ Detailed architecture](docs/ARCHITECTURE.md)**\n\n## 🗺️ Roadmap\n\n**[→ Full roadmap](docs/ROADMAP.md)**\n\n## 🤝 Contributing\n\nContributions welcome! See **[CONTRIBUTING.md](CONTRIBUTING.md)** for guidelines.\n\n**Security issues:** See **[SECURITY.md](SECURITY.md)**\n\n## 📄 License\n\nBSD 3-Clause License - see **[LICENSE](LICENSE)**\n\n## 🔗 Quick Links\n\n- **[GitHub](https://github.com/tradik/mddb)** - Source code\n- **[Docker Hub](https://hub.docker.com/r/tradik/mddb)** - Container images\n- **[Releases](https://github.com/tradik/mddb/releases)** - Download binaries\n- **[Documentation](https://mddb.tradik.com/mddb/)** - Full docs\n- **[LLM Connections](docs/LLM_CONNECTIONS.md)** - Claude, ChatGPT, Ollama, DeepSeek, Manus, Bielik.ai\n- **[Issues](https://github.com/tradik/mddb/issues)** - Bug reports\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftradik%2Fmddb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftradik%2Fmddb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftradik%2Fmddb/lists"}