🔍 MCPower
Semantic Knowledge Search, Simplified
Transform your documents into searchable knowledge bases with FAISS vector embeddings
🚀 Quick Start • 📚 Documentation • 🐛 Report Bug • 💡 Request Feature
⭐ Spread the Word
If you find MCPower useful, help us grow the community!
⭐ Star this repo to show your support!
📊 Project Status
- ✅ Phase 1-5: Complete (All user stories implemented)
- 🚧 Phase 6: Polish & documentation (in progress)
✨ What is MCPower?
MCPower is a Model Context Protocol (MCP) server that provides powerful semantic search over your document collections. Drop in any folder of .txt or .md files, and get instant AI-powered search capabilities through a beautiful web interface or programmatic API.
Perfect for:
- 📚 Documentation sites
- 🗂️ Knowledge bases
- 💬 Chatbot context
- 🔍 Research papers
- 📝 Note collections
🎯 Features at a Glance
🖱️ Drag & Drop InterfaceJust drop folders into the web console to create searchable datasets. No CLI commands needed! ⚡ Lightning FastFAISS-powered vector search with <500ms response times. Search thousands of documents instantly. 🧠 Semantic UnderstandingUses sentence transformers for intelligent matching beyond keyword search. |
🔌 MCP CompatibleWorks with Claude Desktop, VS Code, Cherry Studio, and any MCP client. 📦 Zero ConfigOne-click launcher automatically sets up everything. Just run 🎨 Beautiful UIModern, responsive web console with real-time stats and visual feedback. |
🚀 Quick Start
🐧 Linux / 🍎 macOS
# Clone the repository
git clone https://github.com/wspotter/mcpower.git
cd mcpower
# Run the launcher - it does everything!
./launch.sh
The web console opens automatically at http://127.0.0.1:4173 🎉
🪟 Windows
# Clone the repository
git clone https://github.com/wspotter/mcpower.git
cd mcpower
# Double-click launch.bat or run:
launch.bat
Your browser opens automatically to http://127.0.0.1:4173 🎉
📸 What You'll See
Drag & drop folders, browse for directories, or type paths manually
✨ Features
- Semantic Search: Search knowledge datasets using natural language queries
- Interactive Web Console: Manage datasets with drag-and-drop interface
- Multiple Datasets: Manage and search across multiple knowledge bases
- MCP Compatible: Works with any MCP client (VS Code, Cherry Studio, etc.)
- Fast & Reliable: FAISS-powered vector search with <500ms p95 latency
- Graceful Degradation: Continues working even with invalid datasets
- Comprehensive Logging: Structured JSON logs with detailed diagnostics
🏗️ How It Works
graph TD
A[📄 Your Documents] -->|Python Indexer| B[🧮 Embeddings]
B -->|FAISS| C[💾 Vector Database]
C -->|TypeScript MCP Server| D[🔌 MCP Protocol]
D --> E1[VS Code Copilot]
D --> E2[Cherry Studio]
D --> E3[Any MCP Client]
style A fill:#e3f2fd
style B fill:#fff3e0
style C fill:#f3e5f5
style D fill:#e8f5e9
style E1 fill:#fce4ec
style E2 fill:#fce4ec
style E3 fill:#fce4ec
The Magic Behind MCPower
-
📚 Document Processing
- Python reads your documents (txt, md, pdf)
- Splits them into semantic chunks
- Generates embeddings using
sentence-transformers
-
⚡ Fast Vector Search
- FAISS indexes embeddings for lightning-fast similarity search
- Sub-500ms query latency even on large datasets
- Efficient memory usage with optimized index structures
-
🔌 MCP Integration
- TypeScript server exposes MCP tools
- Clients send queries via stdio protocol
- Python bridge handles FAISS operations
- Results returned as JSON with relevance scores
⚙️ Installation
Prerequisites
- Node.js 18+ and npm
- Python 3.10+
- Git
Automatic Setup (Recommended)
git clone https://github.com/wspotter/mcpower.git
cd mcpower
./launch.sh # Does everything automatically!
The launcher will:
- ✅ Create virtual environment
- ✅ Install Python dependencies
- ✅ Install Node.js dependencies
- ✅ Configure environment variables
- ✅ Start the web console
- ✅ Open your browser
Manual Setup
Click to expand manual installation steps
1. Clone the repository
git clone https://github.com/wspotter/mcpower.git
cd mcpower
2. Install Node.js dependencies
npm install
3. Create Python virtual environment
python3 -m venv .venv
4. Install Python dependencies
.venv/bin/pip install typer faiss-cpu sentence-transformers
5. Configure environment
cat > .env << EOF
MCPOWER_PYTHON=$(pwd)/.venv/bin/python
EOF
6. Build and run
npm run build
npm run dev -- --datasets ./datasets
⚙️ Configuration
Command Line Options
npm run dev -- [options]
Options:
--datasets <path>: Path to datasets directory (default:./datasets)--log-level <level>: Log level: debug, info, warn, error (default:info)--version: Show version information
Environment Variables
Create a .env file in the project root:
# Datasets directory path
DATASETS_PATH=./datasets
# Log level (debug, info, warn, error)
LOG_LEVEL=info
📚 Dataset Management
Using the Web Console
The easiest way to create datasets is through the web console:
- Start the console:
./launch.sh - Add a dataset:
- Click Browse to open directory picker
- Or drag & drop a folder into the input field
- Or type the path manually
- Submit: Click "Create Dataset"
- Monitor: Watch real-time indexing progress
Dataset Structure
Each dataset has three components stored in datasets/<name>/:
datasets/
└── my-docs/
├── config.json # Dataset configuration
├── index.faiss # FAISS vector index
└── metadata.json # Chunk metadata and text
Manual Dataset Creation
Advanced: Create datasets via Python CLI
# Index a directory of documents
.venv/bin/python python/src/index.py index \
--source-path ./my-documents \
--dataset-name my-docs \
--output-dir ./datasets/my-docs
# Supported file types: .txt, .md, .pdf
Configuration options:
--chunk-size 512 # Characters per chunk
--chunk-overlap 50 # Overlap between chunks
--model sentence-transformers/all-MiniLM-L6-v2
Dataset Operations
# List all datasets
GET /api/datasets
# Get dataset details
GET /api/datasets/:name
# Delete dataset
DELETE /api/datasets/:name
# Create dataset (via web console or API)
POST /api/datasets
{
"name": "my-docs",
"sourcePath": "/absolute/path/to/documents"
}
🔌 MCP Integration
MCPower works with any MCP-compatible client. Here's how to connect it:
VS Code Copilot
Add to your VS Code settings.json:
{
"github.copilot.chat.codeGeneration.instructions": [
{
"text": "Use the mcpower MCP server for knowledge search"
}
],
"mcp.servers": {
"mcpower": {
"command": "node",
"args": ["/absolute/path/to/mcpower/dist/cli.js", "--datasets", "./datasets"],
"env": {
"MCPOWER_PYTHON": "/absolute/path/to/mcpower/.venv/bin/python"
}
}
}
}
Cherry Studio
Add to Cherry Studio's MCP configuration:
{
"mcpServers": {
"mcpower": {
"command": "node",
"args": ["/absolute/path/to/mcpower/dist/cli.js", "--datasets", "./datasets"]
}
}
}
Available Tools
🔍 knowledge.search
Search your knowledge bases using natural language.
{
dataset: string; // Dataset name (required)
query: string; // Your search query (required)
topK?: number; // Number of results (default: 5)
}
Example:
{
"tool": "knowledge.search",
"arguments": {
"dataset": "my-docs",
"query": "How do I configure authentication?",
"topK": 3
}
}
Response:
{
"results": [
{
"score": 0.89,
"title": "Authentication Guide",
"path": "docs/auth.md",
"snippet": "To configure authentication, set the AUTH_ENABLED=true..."
}
]
}
📋 knowledge.listDatasets
List all available datasets.
{} // No parameters
Response:
{
"datasets": [
{
"id": "my-docs",
"name": "My Documentation",
"description": "Internal docs",
"chunkCount": 1264,
"defaultTopK": 5
}
],
"metadata": {
"total": 1,
"ready": 1,
"errors": 0
}
}
🛠️ Development
Project Structure
mcpower/
├── src/ # TypeScript MCP server
│ ├── cli.ts # Entry point
│ ├── server.ts # MCP protocol handler
│ ├── bridge/ # Python FAISS bridge
│ ├── config/ # Dataset registry
│ ├── store/ # Knowledge store cache
│ └── tools/ # MCP tool implementations
├── python/src/ # Python indexer & search
│ ├── index.py # CLI for indexing
│ └── search.py # FAISS search operations
├── webapp/ # Web console
│ ├── index.html # SPA interface
│ ├── app.js # Frontend logic
│ └── styles.css # Styling
├── tests/ # Test suites
│ ├── unit/ # Unit tests
│ └── integration/ # Integration tests
└── datasets/ # Your knowledge bases
└── sample-docs/ # Example dataset
Development Scripts
# Development mode (auto-reload)
npm run dev -- --datasets ./datasets
# Build TypeScript
npm run build
# Start web console
npm run web
# Run tests
npm test
# Run with coverage
npm run test:coverage
# Type checking & linting
npm run lint
Creating a New Tool
- Define the tool in
src/tools/yourTool.ts:
export const yourTool: Tool = {
name: "knowledge.yourTool",
description: "What your tool does",
inputSchema: {
type: "object",
properties: {
param: { type: "string", description: "Parameter description" }
},
required: ["param"]
}
};
-
Implement the handler in
src/tools/handlers/yourTool.ts -
Register it in
src/server.ts -
Add tests in
tests/unit/tools/yourTool.test.ts
🧪 Testing
Quick Test
# Run all 86 tests
npm test
# Run with coverage report
npm run test:coverage
Test Coverage
✅ 86 tests passing across:
- 🔍 18 search edge cases (empty queries, special chars, large results)
- 🛠️ 15 search tool validations
- 📚 11 dataset registry operations
- 📋 9 listDatasets tool tests
- 🚀 9 startup integration tests
- 💾 8 knowledge store caching
- ⚡ 6 performance benchmarks (<500ms p95)
- 🔗 5+5 integration tests (search + listDatasets)
Integration Testing
# Test with real datasets
./test-search.sh
# Test web console API
./test-web.sh
🐛 Troubleshooting
❌ Dataset Not Found
Error: Dataset not found: your-dataset
Solutions:
- ✅ Verify dataset exists in
datasets/directory - ✅ Check
config.jsonhas correct name field - ✅ Restart server to reload dataset registry
- ✅ Use web console to verify dataset list
🐍 Python Bridge Failures
Error: Python bridge command failed
Solutions:
- ✅ Verify Python 3.10+ is installed:
python3 --version - ✅ Check virtual environment:
.venv/bin/python --version - ✅ Reinstall dependencies:
.venv/bin/pip install -r python/requirements.txt - ✅ Test FAISS:
.venv/bin/python -c "import faiss; print('OK')" - ✅ Check .env file has correct
MCPOWER_PYTHONpath
🐌 Slow Search Performance
Issue: Queries taking >500ms
Solutions:
- ✅ Check dataset size (>10k chunks may need optimization)
- ✅ Verify FAISS index is properly trained
- ✅ Reduce
topKparameter (try 3-5 instead of 10+) - ✅ Consider using faster embedding model
- ✅ Use GPU-accelerated FAISS for large datasets
🌐 Web Console Connection Issues
Error: ERR_CONNECTION_REFUSED
Solutions:
- ✅ Ensure web server is running:
npm run web - ✅ Check port 4173 isn't blocked by firewall
- ✅ Try accessing
http://127.0.0.1:4173directly - ✅ Check console logs for startup errors
📝 Enable Debug Logging
Get detailed diagnostics:
npm run dev -- --log-level=debug --datasets ./datasets
This shows:
- Dataset loading details
- Python bridge communication
- FAISS index operations
- Search query execution
- Error stack traces
🤝 Contributing
🚨 We're actively looking for contributors! Check out our good first issues and help wanted labels.
We welcome contributions! Here's how to get started:
Quick Start
# Fork and clone
git clone https://github.com/YOUR_USERNAME/mcpower.git
cd mcpower
# Create feature branch
git checkout -b feature/amazing-feature
# Install dependencies
npm install
.venv/bin/pip install -r python/requirements.txt
# Make changes and test
npm run build
npm test
# Commit with clear message
git commit -m "feat: add amazing feature"
# Push and create PR
git push origin feature/amazing-feature
🔥 Areas We Need Help
We're especially looking for contributors in these areas:
- 🎨 UI/UX: Improve web console design
- 📚 Documentation: Tutorials, examples, guides
- 🧪 Testing: More test coverage, edge cases
- 🚀 Performance: Optimization, caching strategies
- 🔌 Integrations: New MCP clients, data sources
- 🐛 Bug Fixes: See issues
Code Guidelines
- Write tests for new features
- Follow TypeScript/Python best practices
- Update documentation for API changes
- Use conventional commit messages
- Keep PRs focused and atomic
📄 License
MIT License - see LICENSE for details
🙏 Acknowledgments
Built with amazing open-source tools:
- FAISS - Vector similarity search by Facebook Research
- sentence-transformers - State-of-the-art text embeddings
- MCP - Model Context Protocol by Anthropic
- TypeScript - Type-safe JavaScript
- Express - Fast web framework
❓ Getting Help
Need assistance? We're here to help!
- 🐛 Bug Reports: Open an issue
- 💡 Feature Requests: Request a feature
- ❓ Questions: Search existing issues or open a new one
- 📚 Documentation: Check our Quick Start Guide
⭐ Star this repo if you find it useful!
Made with ❤️ by the MCPower team