A high-performance local MCP server for semantic code search, summarization, and RAG.
npm install @sevenseconds/vibescoutA high-performance Model Context Protocol (MCP) server and Web Dashboard for local semantic code search and AI-powered assistance. VibeScout transforms your codebase into a searchable, chat-ready knowledge base using local or cloud-based AI providers.
/src/plugins/// for built-in plugins.| Provider | Type | Description |
| :--- | :--- | :--- |
| Local | Built-in | Transformers.js (BGE, MiniLM). High-speed, zero config. |
| Ollama | Local API | Full support for local models like Llama 3, Mistral, and Nomic. |
| Z.AI | Cloud | BigModel.cn integration. Supports GLM-4 and dedicated Coding Plans. |
| Bedrock | Cloud | AWS Bedrock (Claude 3, Titan). Supports AWS Profiles. |
| Gemini | Cloud | Google Generative AI (1.5 Flash/Pro) and specialized embeddings. |
| OpenAI | Cloud | Standard OpenAI API or compatible (DeepSeek, Groq, etc). |
| Cloudflare | Cloud | Workers AI & Vectorize integration for cloud-native indexing. |
| LM Studio | Local API | OpenAI-compatible local server preset. |
VibeScout features a powerful plugin system for extending functionality:
/src/plugins/// )vibescout plugin install ~/.vibescout/plugins/bash
List plugins
vibescout plugin listInstall from npm
vibescout plugin install vibescout-plugin-nextjsInstall specific version
vibescout plugin install vibescout-plugin-nextjs@betaUninstall
vibescout plugin uninstall vibescout-plugin-nextjsEnable/Disable (via Web UI or config.json)
Plugins are stored in ~/.vibescout/config.json
`$3
See /docs/ directory for:
- plugin-guide.md - Getting started
- plugin-api.md - API reference
- plugin-architecture.md - Design patterns
- plugin-example.md - Complete example
- two-phase-search.md - Two-phase search with token count preview
- profiling-guide.md - Performance profiling and optimization🛠Installation
$3
`bash
npm install -g @sevenseconds/vibescout
`💻 CLI Usage
$3
Launch the interactive dashboard:
`bash
vibescout ui
`$3
Control terminal output verbosity:
`bash
Default is INFO (concise)
vibescout ui --log-level warnFull debug output (alias for --log-level debug)
vibescout ui --verbose
`$3
`bash
Index a project manually
vibescout index ./my-app "My Project"Semantic search via terminal
vibescout search "how does the auth flow work?"Reset the database (clear all data)
vibescout reset
Or via npm
npm run reset-db
`$3
When using VibeScout with Claude Desktop, Cursor, or other MCP clients, you can preview search results before consuming tokens:
Phase 1: Preview Token Count
`json
{
"name": "search_code",
"arguments": {
"query": "authentication flow",
"limit": 20,
"previewOnly": true
}
}
`This returns metadata without actual code:
- Result count
- Total tokens (from stored counts during indexing)
- Average relevance score
- Recommendation on whether to proceed
Phase 2: Fetch Results (if tokens are acceptable)
`json
{
"name": "search_code",
"arguments": {
"query": "authentication flow",
"limit": 10,
"previewOnly": false
}
}
`Benefits:
- Avoid unexpected token consumption
- Adjust
limit parameter based on preview
- Use more specific filters if token count is high
- Backward compatible: omit previewOnly for existing behavior$3
`bash
Profile with 100% sampling (most detailed)
vibescout --profile index ./my-app "My Project"Profile with 10% sampling (lower overhead)
vibescout --profile --profile-sampling 0.1 search "authentication"Dedicated profiling command
vibescout profile index --folder ./my-app --sampling 1.0View traces in chrome://tracing
Traces saved to ~/.vibescout/profiles/
`Profiling Features:
- Zero overhead when disabled (default)
- Chrome DevTools-compatible flame graphs
- Configurable sampling rates (0.0-1.0) to reduce overhead
- Category-based sampling (indexing, search, embedding, database)
- Web UI dashboard at http://localhost:3000/performance
docs/profiling-guide.md for detailed documentation.🔒 Offline Mode
To use VibeScout in a restricted environment without internet access:
1. Download Models: In an online environment, let VibeScout download the models first, or download them manually from Hugging Face.
2. Enable Offline Mode: Toggle Offline Mode in Settings or run with the
--offline flag.
3. Local Path: Use --models-path if your models are stored in a non-standard directory.When enabled, VibeScout sets
allowRemoteModels: false and disables all attempts to connect to the Hugging Face Hub.🔌 Client Integration
$3
Add VibeScout to your configuration:`json
{
"mcpServers": {
"vibescout": {
"command": "vibescout",
"args": ["--mcp", "stdio"]
}
}
}
``