mdya — Busca Local em Markdown
yoshihirosuzuki/mdya
Busca rápida e híbrida para Markdown local — BM25 + vetores on-device
Ver no GitHubMCP server para busca híbrida em coleções Markdown locais, combinando full-text search (BM25) com busca vetorial on-device. Totalmente local-first, sem dependência de APIs cloud, com suporte a análise morfológica de japonês e chunking inteligente.
Instalação
npx convez-ai yoshihirosuzuki/mdya1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Indexar e pesquisar bases de conhecimento em Markdown
- Integrar busca semanticamente inteligente a aplicações Claude
- Recuperação de documentos em pipelines de RAG local
- Busca por conteúdo em repositórios de notas e wiki pessoal
Veredito

Ferramenta sólida e minimalista para busca local em Markdown, bem-integrada ao ecossistema MCP. Excelente para quem precisa de recuperação de documentos robusto sem sair da máquina local, embora requeira configuração prévia de índices.
README
A tradução para o português deste README ainda está na fila.
mdya
English / 日本語
A small, fast search primitive for your local Markdown collections. BM25 full-text search, on-device vector search, and a hybrid that fuses both — exposed through two entry points: a CLI and an MCP server.
Overview
mdya is a search primitive. It indexes local Markdown, and returns search results over a CLI and an MCP server. That is all it does.
mdya is not a search agent and not an LLM query-rewriting front-end. It has no query expansion, no reranker, and no multi-stage agent pipeline. Workflows that want those things are expected to layer a separate tool on top of mdya via its CLI or MCP interface.
It is local-first by construction. There is no path to any cloud LLM API; inference runs entirely on-device; distribution is a single binary.
What it can do:
- BM25 full-text search — full-text search with Japanese morphological analysis support.
- Vector search — cosine similarity over on-device embeddings (default
cl-nagoya/ruri-v3-30m, 256 dimensions). - Hybrid search — fuses BM25 and vector results via Reciprocal Rank Fusion (RRF).
- Markdown chunking — splits along heading and code-fence boundaries.
- MCP server —
mdya mcp(stdio / HTTP) exposes the search tools to MCP clients.
.pdf files go through the same ingest path as .md. They are converted to plain text at ingest time and then chunked and embedded with the same pipeline as Markdown.
Supported platforms
- macOS (arm64 / x86_64)
- Linux (amd64 / arm64)
- Windows (x86_64)
Install
# Linux / macOS
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/yoshihirosuzuki/mdya/releases/latest/download/mdya-installer.sh | sh
# Windows
powershell -ExecutionPolicy Bypass -c "irm https://github.com/yoshihirosuzuki/mdya/releases/latest/download/mdya-installer.ps1 | iex"
Or grab an archive from the releases page and put the mdya binary on your PATH.
Rust users can install from crates.io instead. This builds from source, so it needs the build-from-source prerequisites below (notably protoc):
cargo install mdya
Build from source
Prerequisites:
- Rust 1.95+ (pinned automatically by
rust-toolchain.tomlat the repo root) just(cargo install just)protoc(Protocol Buffers compiler, a build dependency of thelancestorage library). On macOSbrew install protobuf; on Linuxapt install -y protobuf-compiler; on Windowschoco install protoc.
git clone https://github.com/yoshihirosuzuki/mdya.git
cd mdya
cargo build --release # produces ./target/release/mdya
# or install onto your PATH:
cargo install --path . # installs mdya into ~/.cargo/bin
Getting started
The shortest path is init → collection add → update-all → search.
mdya init # create ~/.mdya/ (config.yml + data directories for the index)
mdya collection add ~/notes # register a directory as a collection (name = basename, here: notes)
mdya update-all # walk every registered collection, ingest .md / .pdf, build the index
mdya search fts "release plan" # BM25 full-text search
mdya search vector "release plan" # vector search
mdya search hybrid "release plan" # hybrid (RRF)
The first
mdya update-all(and vector / hybrid searches) automatically downloads the embedding model (cl-nagoya/ruri-v3-30m, about 140 MB) into~/.mdya-models/, and reuses that cache afterwards.
Search results are printed to stdout in a human-readable format.
notes/release.md score=0.812
> The release procedure is as follows
> 1. Update the version number
---
notes/checklist.md score=0.751
> Pre-release checklist
---
2 doc hits (showing 20 max)
Common flags:
-c, --collections <NAMES...>— restrict to specific collections (default: all)-n, --limit <N>— top N hits (default 20)--format <FORMAT>— output format (defaulthuman).json(machine-friendly envelope),md(Markdown, suitable for pasting or LLM input), andxml(structurally equivalent to JSON, also for LLM input) are also available.
MCP server
mdya can run as an MCP (Model Context Protocol) server, so clients like Claude Code or Claude Desktop can call its search tools.
mdya mcp # start the MCP server over stdio
Registering with Claude Code:
claude mcp add mdya -- mdya mcp
Further reading
For configuration, individual subcommands, and MCP details, see the user manual.
Configuration
Configuration lives in a single file at ~/.mdya/config.yml (a template is generated by mdya init). Minimal example:
collections:
notes:
path: ~/notes
embedding:
model: cl-nagoya/ruri-v3-30m
runtime:
memory_limit_mb: 8192 # upper bound on this process's RSS, in MB. 0 to disable.
embed_parallelism: 8 # number of files embedded in parallel during update-all. 0 for sequential.
mdya collection add <path> rewrites the collections section, so you usually do not need to edit it by hand. The configuration directory can be moved with --config-dir <path>, and the embedding model cache with --model-cache-dir <path> (default $HOME/.mdya-models/).
Development
just check # fmt-check + clippy (-D warnings) + cargo test (full workspace)
just smoke # smoke tests only
just # list available recipes
Contributing
Contributions are welcome on a best-effort basis (one-person maintainer; no formal SLA). Please read the following before opening an issue or PR:
- CONTRIBUTING.md — issue / PR workflow, build and test setup.
- CODE_OF_CONDUCT.md — Contributor Covenant.
- SECURITY.md — private channels for security vulnerabilities.
- SUPPORT.md — where to ask questions.
License
Dual-licensed under MIT OR Apache-2.0. See LICENSE-MIT and LICENSE-APACHE.