Skip to main content
Glama

MCP Power - Knowledge Search Server

by wspotter
OverviewInspectSchemaRelated ServersScoreDiscussions
TypeScript
Local
MIT License
1

🔍 MCPower

Semantic Knowledge Search, Simplified

Transform your documents into searchable knowledge bases with FAISS vector embeddings

TypeScript Node.js Python Tests License

🚀 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!

Share MCPower: Twitter/X • LinkedIn • Reddit

📊 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 Interface

Just drop folders into the web console to create searchable datasets. No CLI commands needed!

⚡ Lightning Fast

FAISS-powered vector search with <500ms response times. Search thousands of documents instantly.

🧠 Semantic Understanding

Uses sentence transformers for intelligent matching beyond keyword search.

🔌 MCP Compatible

Works with Claude Desktop, VS Code, Cherry Studio, and any MCP client.

📦 Zero Config

One-click launcher automatically sets up everything. Just run ./launch.sh.

🎨 Beautiful UI

Modern, responsive web console with real-time stats and visual feedback.

🚀 Quick Start

# 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 🎉

# 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

✨ 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

  1. 📚 Document Processing

    • Python reads your documents (txt, md, pdf)

    • Splits them into semantic chunks

    • Generates embeddings using sentence-transformers

  2. ⚡ 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

  3. 🔌 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

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:

  1. Start the console: ./launch.sh

  2. Add a dataset:

    • Click Browse to open directory picker

    • Or drag & drop a folder into the input field

    • Or type the path manually

  3. Submit: Click "Create Dataset"

  4. 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

# 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

  1. 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"] } };

  1. Implement the handler in src/tools/handlers/yourTool.ts

  2. Register it in src/server.ts

  3. 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

Error: Dataset not found: your-dataset

Solutions:

  • ✅ Verify dataset exists in datasets/ directory

  • ✅ Check config.json has correct name field

  • ✅ Restart server to reload dataset registry

  • ✅ Use web console to verify dataset list

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_PYTHON path

Issue: Queries taking >500ms

Solutions:

  • ✅ Check dataset size (>10k chunks may need optimization)

  • ✅ Verify FAISS index is properly trained

  • ✅ Reduce topK parameter (try 3-5 instead of 10+)

  • ✅ Consider using faster embedding model

  • ✅ Use GPU-accelerated FAISS for large datasets

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:4173 directly

  • ✅ Check console logs for startup errors

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:

❓ Getting Help

Need assistance? We're here to help!

⭐ Star this repo if you find it useful!

Made with ❤️ by the MCPower team

🐛 Report Bug • ✨ Request Feature • 📖 Documentation

One-click Deploy
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

Resources

Tools

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/wspotter/mcpower'

If you have feedback or need assistance with the MCP directory API, please join our Discord server