Skip to content

docs: Revamp README for clarity, onboarding, and community growth #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
wspotter merged 2 commits into from
Nov 30, 2025
Merged

docs: Revamp README for clarity, onboarding, and community growth #2

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
57620a4
Initial plan
Copilot Nov 30, 2025
c6b4b38
docs: Revamp README for clarity, onboarding, and community growth
Copilot Nov 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
172 changes: 41 additions & 131 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,31 @@

[🚀 Quick Start](#-quick-start) • [📚 Documentation](QUICKSTART.md) • [🐛 Report Bug](https://github.com/wspotter/mcpower/issues) • [💡 Request Feature](https://github.com/wspotter/mcpower/issues)

---

</div>

---

## ⭐ Spread the Word

If you find MCPower useful, help us grow the community!

<div align="center">

**[⭐ Star this repo](https://github.com/wspotter/mcpower)** to show your support!

Share MCPower: [Twitter/X](https://twitter.com/intent/tweet?text=Check%20out%20MCPower%20-%20Semantic%20Knowledge%20Search%20with%20FAISS%20%26%20MCP!&url=https://github.com/wspotter/mcpower) • [LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https://github.com/wspotter/mcpower) • [Reddit](https://reddit.com/submit?url=https://github.com/wspotter/mcpower&title=MCPower%20-%20Semantic%20Knowledge%20Search%20with%20FAISS%20%26%20MCP)

</div>

---

## 📊 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.
Expand Down Expand Up @@ -65,8 +86,6 @@ Modern, responsive web console with real-time stats and visual feedback.

---

---

## 🚀 Quick Start

<details open>
Expand Down Expand Up @@ -104,6 +123,7 @@ Your browser opens automatically to **http://127.0.0.1:4173** 🎉
### 📸 What You'll See

<div align="center">
<!-- TODO: Replace with actual screenshot once UI is finalized -->
<img src="assets/screenshot-placeholder.png" alt="MCPower Web Console" width="800">
<p><i>Drag & drop folders, browse for directories, or type paths manually</i></p>
</div>
Expand Down Expand Up @@ -232,58 +252,6 @@ npm run dev -- --datasets ./datasets
</details>

---
│ └─────┬─────┘ │
└────────┼────────┘
│ execa (JSON over stdio)
│
┌────────┴────────┐
│ Python Bridge │
│ (Python) │
│ │
│ ┌───────────┐ │
│ │ FAISS │ │ Vector search
│ │ Index │ │
│ └───────────┘ │
│ │
│ ┌───────────┐ │
│ │ Sentence │ │ Query encoding
│ │Transformers│ │
│ └───────────┘ │
└─────────────────┘
```

## 📦 Installation

### Prerequisites

- **Node.js**: 18.x or higher
- **Python**: 3.10 or higher
- **npm**: 9.x or higher

### From Source

```bash
# Clone the repository
git clone https://github.com/yourusername/mcpower.git
cd mcpower

# Install dependencies
npm install
cd python && pip install -r requirements.txt && cd ..

# Build
npm run build

# Optional: Link globally
npm link
```

### Verify Installation

```bash
npm run dev -- --version
# Output: Starting MCP Knowledge Server v0.1.0...
```

## ⚙️ Configuration

Expand Down Expand Up @@ -381,52 +349,8 @@ POST /api/datasets
```

---
└── your-dataset/
├── manifest.json # Configuration
├── metadata.json # Document metadata
└── index/ # FAISS index directory
└── docs.index # FAISS index file
```

### Manifest Format

`manifest.json`:
```json
{
"id": "your-dataset",
"name": "Your Dataset Name",
"description": "Description of your dataset",
"index": "index",
"metadata": "metadata.json",
"defaultTopK": 5
}
```

### Metadata Format

`metadata.json`:
```json
[
{
"id": "doc-1",
"title": "Document Title",
"path": "path/to/document.md",
"content": "Full document content...",
"snippet": "Short excerpt..."
}
]
```

### Creating a Dataset

See the [sample dataset](datasets/sample-docs/) for a complete example.

To create embeddings from your documents, use a tool like:
- [sentence-transformers](https://www.sbert.net/)
- FAISS for indexing
- Custom embedding pipeline

## � MCP Integration
## 🔌 MCP Integration

MCPower works with any MCP-compatible client. Here's how to connect it:

Expand Down Expand Up @@ -726,6 +650,8 @@ This shows:

## 🤝 Contributing

**🚨 We're actively looking for contributors!** Check out our [good first issues](https://github.com/wspotter/mcpower/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) and [help wanted](https://github.com/wspotter/mcpower/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) labels.

We welcome contributions! Here's how to get started:

### Quick Start
Expand Down Expand Up @@ -753,7 +679,9 @@ git commit -m "feat: add amazing feature"
git push origin feature/amazing-feature
```

### Areas We Need Help
### 🔥 Areas We Need Help

We're especially looking for contributors in these areas:

- 🎨 **UI/UX**: Improve web console design
- 📚 **Documentation**: Tutorials, examples, guides
Expand Down Expand Up @@ -790,6 +718,17 @@ Built with amazing open-source tools:

---

## ❓ Getting Help

Need assistance? We're here to help!

- **🐛 Bug Reports**: [Open an issue](https://github.com/wspotter/mcpower/issues/new?labels=bug)
- **💡 Feature Requests**: [Request a feature](https://github.com/wspotter/mcpower/issues/new?labels=enhancement)
- **❓ Questions**: [Search existing issues](https://github.com/wspotter/mcpower/issues) or open a new one
- **📚 Documentation**: Check our [Quick Start Guide](QUICKSTART.md)

---

<div align="center">

**[⭐ Star this repo](https://github.com/wspotter/mcpower)** if you find it useful!
Expand All @@ -799,32 +738,3 @@ Made with ❤️ by the MCPower team
[🐛 Report Bug](https://github.com/wspotter/mcpower/issues) • [✨ Request Feature](https://github.com/wspotter/mcpower/issues) • [📖 Documentation](QUICKSTART.md)

</div>

Look for error logs with:
- `manifestPath`: Location of problematic manifest
- `errorType`: Type of error (json_parse_error, file_not_found, validation_error)
- `error`: Detailed error message

## 📝 License

ISC

## 🤝 Contributing

Contributions welcome! Please read our contributing guidelines before submitting PRs.

## 🔗 Links

- [MCP Protocol Documentation](https://modelcontextprotocol.io)
- [Quick Start Guide](specs/001-mcp-server-core/quickstart.md)
- [API Documentation](specs/001-mcp-server-core/contracts/)
- [Design Documents](specs/001-mcp-server-core/)

## 📊 Project Status

- ✅ Phase 1-5: Complete (All user stories implemented)
- 🚧 Phase 6: Polish & documentation (in progress)

---

**Made with ❤️ for the MCP community**