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!

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:

• 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

Report Bug Request Feature Documentation