{ "markdown": "
\n\n\"Vexor\"\n\n# Vexor\n\n[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)\n[![PyPI](https://img.shields.io/pypi/v/vexor.svg)](https://pypi.org/project/vexor/)\n[![CI](https://img.shields.io/github/actions/workflow/status/scarletkc/vexor/publish.yml?branch=main)](https://github.com/scarletkc/vexor/actions/workflows/publish.yml)\n[![Codecov](https://img.shields.io/codecov/c/github/scarletkc/vexor/main)](https://codecov.io/github/scarletkc/vexor)\n[![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/scarletkc/vexor?utm_source=oss&utm_medium=github&utm_campaign=scarletkc%2Fvexor&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)](https://coderabbit.ai)\n[![License](https://img.shields.io/github/license/scarletkc/vexor.svg)](https://github.com/scarletkc/vexor/blob/main/LICENSE)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/scarletkc/vexor)\n\n
\n\n---\n\n**Vexor** is a semantic search engine that builds reusable indexes over files and code.\nIt supports configurable embedding and reranking providers, and exposes the same core through a Python API, a CLI tool, and an MCP server.\n\n\n\n## Featured In\n\nVexor has been recognized and featured by the community:\n\n- **[Ruan Yifeng's Weekly (Issue #379)](https://github.com/ruanyf/weekly/blob/master/docs/issue-379.md#ai-%E7%9B%B8%E5%85%B3)** - A leading tech newsletter in the Chinese developer community.\n- **[Awesome Claude Skills](https://github.com/VoltAgent/awesome-claude-skills?tab=readme-ov-file#development-and-testing)** - Curated list of best-in-class skills for AI agents.\n- **[Awesome MCP Servers](https://github.com/punkpeye/awesome-mcp-servers#-developer-tools)** - Curated list of Model Context Protocol servers.\n- **[Awesome CLI Apps](https://github.com/agarrharr/awesome-cli-apps#search)** - Curated list of command-line apps.\n\n## Why Vexor?\n\nWhen you remember what a file *does* but forget its name or location, Vexor finds it instantly—no grep patterns or directory traversal needed.\n\nDesigned for both humans and AI coding assistants, enabling semantic file discovery in autonomous agent workflows.\n\n## Install\n\nDownload standalone binary from [releases](https://github.com/scarletkc/vexor/releases) (no Python required), or:\n```bash\npip install vexor # also works with pipx, uv\n```\n\n## Quick Start\n\n### 0. Guided Setup (Recommended)\n```bash\nvexor init\n```\nThe wizard also runs automatically before the first interactive operational\ncommand when no config exists. Configuration-management (`vexor config`), MCP,\nhelp, and version commands run directly.\n\n### 1. Search\n```bash\nvexor \"api client config\" # defaults to search current directory\n# or explicit path:\nvexor search \"api client config\" --path ~/projects/demo --top 5\n# in-memory search only:\nvexor search \"api client config\" --no-cache \n```\n\nVexor auto-indexes on first search. Example output:\n```\nVexor semantic file search results\n──────────────────────────────────\n# Similarity File path Lines Preview\n1 0.923 ./src/config_loader.py - config loader entrypoint\n2 0.871 ./src/utils/config_parse.py - parse config helpers\n3 0.809 ./tests/test_config_loader.py - tests for config loader\n```\n\n### 2. Explicit Index (Optional)\n```bash\nvexor index # indexes current directory\n# or explicit path:\nvexor index --path ~/projects/demo --mode code\n```\nUseful for CI warmup or when `auto_index` is disabled.\n\n## Python API\n\nVexor can also be imported and used directly from Python:\n\n```python\nfrom vexor import index, search\n\nindex(path=\".\", mode=\"head\")\nresponse = search(\"config loader\", path=\".\", mode=\"name\")\n\nfor hit in response.results:\n print(hit.path, hit.score)\n```\n\nConfiguration follows the same global and project-level resolution as the CLI.\nFor runtime overrides, cache controls, and per-call options, see\n[`docs/api/python.md`](https://github.com/scarletkc/vexor/tree/main/docs/api/python.md).\n\n## AI Agent Skill\n\nThis repo includes a skill for AI agents to use Vexor effectively:\n\n```bash\nvexor install --skills claude # Claude Code\nvexor install --skills codex # Codex\n```\n\nSkill source: [`plugins/vexor/skills/vexor-cli`](https://github.com/scarletkc/vexor/raw/refs/heads/main/plugins/vexor/skills/vexor-cli/SKILL.md)\n\n## MCP Server\n\n\n\n[![vexor MCP server](https://glama.ai/mcp/servers/scarletkc/vexor/badges/score.svg)](https://glama.ai/mcp/servers/scarletkc/vexor)\n\n> [!NOTE]\n> The Agent Skill and the MCP server provide the same core capability — pick **one** per agent.\n> The skill teaches shell-capable agents (Claude Code, Codex) to drive the full CLI and assumes `vexor` is installed on PATH; the MCP server exposes search as native tools, works in any MCP client (Cursor, Windsurf, Zed, ...), and can bootstrap without prior setup via `uvx` and environment variables.\n\nVexor ships a built-in [MCP](https://modelcontextprotocol.io) stdio server, so any MCP-capable agent can use semantic file search as a native tool:\n\n```bash\nclaude mcp add vexor -- vexor mcp # Claude Code\ncodex mcp add vexor -- vexor mcp # Codex\n```\n\nOr configure manually in any MCP client, optionally supplying the API key\nand any config overrides via `env` (no `vexor init` needed):\n\n```json\n{\n \"mcpServers\": {\n \"vexor\": {\n \"command\": \"vexor\",\n \"args\": [\"mcp\"],\n \"env\": {\n \"VEXOR_API_KEY\": \"sk-...\",\n \"VEXOR_CONFIG_JSON\": \"{\\\"provider\\\": \\\"gemini\\\", \\\"rerank\\\": \\\"bm25\\\"}\"\n }\n }\n }\n}\n```\n\nThe server exposes two tools: `vexor_search` (semantic file search, returning the matching source text so an agent rarely needs a follow-up file read) and `vexor_index` (explicit index warm-up). No extra dependencies are required. Vexor is listed on the [official MCP registry](https://registry.modelcontextprotocol.io) as `io.github.scarletkc/vexor`. See [`docs/mcp.md`](https://github.com/scarletkc/vexor/tree/main/docs/mcp.md) for tool schemas, environment variables, and client setup details.\n\n## Configuration\n\n```bash\nvexor init # guided setup (recommended)\nvexor config --set-api-key \"YOUR_KEY\" # or env: VEXOR_API_KEY / OPENAI_API_KEY / ...\nvexor config --set-provider openai # default; also gemini/voyageai/custom/local\nvexor config --rerank hybrid # optional: fuse exact keyword + semantic ranking\nvexor config --show # view effective settings and origins\n```\n\nGlobal config lives in `~/.vexor/config.json`; the nearest\n`/.vexor/config.json` can override a restricted set of behavior fields\nfor that project. Non-secret fields can also be injected via `VEXOR_CONFIG_JSON`\n(useful for MCP clients and CI), and fully offline use is supported through\nlocal embedding models.\n\nSee [`docs/configuration.md`](https://github.com/scarletkc/vexor/blob/main/docs/configuration.md) for the complete reference: project config fields and precedence, all config commands, API keys and environment variables, rerank strategies (hybrid / BM25 / FlashRank / remote), remote vs local providers, embedding dimensions, and offline local model setup.\n\n## CLI Reference\n\nEveryday usage fits in `vexor \"query\"`, `vexor search`, and `vexor index` (see Quick Start). The full command table, common flags, index modes (`--mode auto/name/head/brief/full/code/outline`), `.vexorignore` files, project-local indexes (`vexor index --local`), cache behavior, and porcelain output format are documented in [`docs/cli.md`](https://github.com/scarletkc/vexor/blob/main/docs/cli.md).\n\n## Documentation\n\n- [Configuration](https://github.com/scarletkc/vexor/blob/main/docs/configuration.md) — providers, API keys, rerank, embedding dimensions, local models\n- [CLI reference](https://github.com/scarletkc/vexor/blob/main/docs/cli.md) — commands, flags, index modes, cache behavior\n- [MCP server](https://github.com/scarletkc/vexor/blob/main/docs/mcp.md) — client setup, environment variables, tool schemas\n- [Python API](https://github.com/scarletkc/vexor/blob/main/docs/api/python.md) — programmatic usage\n- [Collections API](https://github.com/scarletkc/vexor/blob/main/docs/api/collections.md) — database-backed text records and filtered search\n\n## Contributing\n\nContributions, issues, and PRs welcome! Commit messages and PR titles follow [Conventional Commits](https://www.conventionalcommits.org) (e.g. `feat(mcp): add stdio server`). Star if you find it helpful.\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=scarletkc/vexor&type=date&legend=top-left)](https://www.star-history.com/#scarletkc/vexor&type=date&legend=top-left)\n\n## License\n\n[MIT](http://github.com/scarletkc/vexor/blob/main/LICENSE)\n", "bytes": 9127, "sha": "d3676c594352de76617809953705a6c0ebbcda178abc55a75daab93dcaf1e07b", "repo_slug": "scarletkc/vexor", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_scarletkc_vexor_1a896aaf/readme" }