Chris Coutinho
c4b3df04a0
Rewrote Astrolabe README to be user-friendly and release-ready by incorporating pitch.md content and moving technical details to linked documentation. Key changes: - Incorporated compelling pitch narrative as opening - Restructured around "What You Can Do" rather than architecture - Added clear use cases for individuals, teams, and developers - Simplified installation to 3 steps - Moved OAuth flow and architecture details to ADR links - Added emoji sections for visual appeal - Focused on benefits over implementation Sections: - What You Can Do (search, visualization, AI agents) - Installation (app store + manual) - Quick Start (3-step setup) - Features (personal, admin, unified search) - Use Cases (research, collaboration, RAG workflows) - Requirements (Nextcloud 30+, MCP server, OAuth) - Documentation (links to installation, configuration, ADRs) - Troubleshooting (quick fixes with links to detailed guides) This README is now suitable for Nextcloud App Store submission. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
224 lines
7.8 KiB
Markdown
224 lines
7.8 KiB
Markdown
# Astrolabe: The Intelligence Layer for Nextcloud
|
|
|
|
Your Nextcloud instance is more than just a bucket for files—it is a galaxy of ideas, projects, and knowledge. But until now, you've been navigating it in the dark, relying on exact filenames and rigid keywords.
|
|
|
|
**It's time to turn the lights on.**
|
|
|
|
Astrolabe is a fully integrated Nextcloud application that transforms your server into a semantic intelligence engine. It doesn't just store your data; it **maps it, understands it, and connects it** to the AI future.
|
|
|
|
---
|
|
|
|
## What You Can Do
|
|
|
|
### 🔍 Search That Actually Understands
|
|
|
|
Forget clunky external tools. Astrolabe registers as a **native Nextcloud Search Provider**.
|
|
|
|
- **Seamless**: Lives right in the standard Nextcloud search bar you already use
|
|
- **Semantic**: Type "marketing strategy for the winter launch" and Astrolabe finds the relevant PDFs, chat logs, and text files—even if those exact words never appear in the document
|
|
- **Intelligent**: It finds the **concept**, not just the string
|
|
|
|
### 🌌 Visualize Your Data Universe
|
|
|
|
Data shouldn't just be a list; it should be a landscape. Astrolabe includes a dedicated dashboard that visualizes your document chunks as a **3D PCA Vector Plot**.
|
|
|
|
- **See the Connections**: View your data as a constellation of points in 3D space
|
|
- **Explore Clusters**: Visually identify how your documents relate to one another
|
|
- **True "Astroglobe" Experience**: Rotate, zoom, and fly through your semantic universe just like navigators once studied the stars
|
|
|
|
### 🤖 Power Your AI Agents
|
|
|
|
Astrolabe isn't just for humans; it's for your AI agents, too. It acts as a bridge, running a **Model Context Protocol (MCP) Server** directly from your Nextcloud.
|
|
|
|
- **Bring Your Own Brain**: Connect external AI clients (like Claude Desktop or Cursor) to your private data
|
|
- **Agentic Workflows**: Enable LLMs to "sample" your files, read content, and perform complex reasoning tasks using your Nextcloud data as the source of truth
|
|
- **Private & Secure**: Your data never leaves your infrastructure
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
### From App Store (Recommended)
|
|
|
|
1. Open **Apps** in your Nextcloud
|
|
2. Search for **"Astrolabe"**
|
|
3. Click **"Download and enable"**
|
|
|
|
### Manual Installation
|
|
|
|
```bash
|
|
# Clone into your Nextcloud apps directory
|
|
cd /path/to/nextcloud/apps
|
|
git clone https://github.com/cbcoutinho/nextcloud-mcp-server.git
|
|
cd nextcloud-mcp-server/third_party/astrolabe
|
|
|
|
# Install dependencies
|
|
composer install
|
|
|
|
# Enable the app
|
|
php /path/to/nextcloud/occ app:enable astrolabe
|
|
```
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
### 1. Configure the MCP Server URL
|
|
|
|
Add this to your Nextcloud `config/config.php`:
|
|
|
|
```php
|
|
'mcp_server_url' => 'http://localhost:8000',
|
|
```
|
|
|
|
### 2. Start the MCP Server
|
|
|
|
The MCP server handles semantic search and AI agent connections. See the [MCP Server Installation Guide](https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/installation.md) for details.
|
|
|
|
Quick start with Docker:
|
|
|
|
```bash
|
|
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
|
|
ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
|
|
```
|
|
|
|
### 3. Authorize Access
|
|
|
|
1. Go to **Settings → Personal → Astrolabe**
|
|
2. Click **"Authorize Access"**
|
|
3. Sign in to your identity provider
|
|
4. Approve the requested permissions
|
|
|
|
That's it! You can now use semantic search and explore your data universe.
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
### Personal Settings
|
|
|
|
Located in: **Settings → Personal → Astrolabe**
|
|
|
|
- **Semantic Search Dashboard**: Interactive 3D visualization of your document chunks
|
|
- **OAuth Authorization**: Authorize Nextcloud to access the MCP server on your behalf
|
|
- **Session Information**: View connection status and authentication details
|
|
- **Connection Management**: Revoke access or disconnect when needed
|
|
|
|
### Admin Settings
|
|
|
|
Located in: **Settings → Administration → Astrolabe**
|
|
|
|
- **Server Status**: Monitor MCP server health and version
|
|
- **Vector Sync Metrics**: See how many documents are indexed, processing rates, and sync status
|
|
- **Configuration Validation**: Verify server URL and connectivity
|
|
- **Feature Availability**: Check which capabilities are enabled
|
|
|
|
### Unified Search Integration
|
|
|
|
Astrolabe integrates directly with Nextcloud's **Unified Search**:
|
|
|
|
- Available in the top search bar across all Nextcloud pages
|
|
- Returns semantic matches ranked by relevance
|
|
- Shows excerpts from matching documents
|
|
- Links directly to source files in Nextcloud
|
|
|
|
---
|
|
|
|
## Use Cases
|
|
|
|
### For Individuals
|
|
|
|
- **Research**: Find all notes related to a project, even if they use different terminology
|
|
- **Organization**: Discover forgotten documents related to your current work
|
|
- **Exploration**: Visualize how your knowledge connects and evolves over time
|
|
|
|
### For Teams
|
|
|
|
- **Knowledge Discovery**: Surface institutional knowledge that would otherwise stay buried
|
|
- **Collaboration**: Find team members working on similar problems
|
|
- **Documentation**: Locate relevant documentation without knowing exact titles
|
|
|
|
### For Developers
|
|
|
|
- **AI Integration**: Connect Claude Desktop, Cursor, or other MCP clients to Nextcloud
|
|
- **RAG Workflows**: Build retrieval-augmented generation pipelines on your private data
|
|
- **Custom Agents**: Use the MCP protocol to create specialized workflows
|
|
|
|
---
|
|
|
|
## Requirements
|
|
|
|
- **Nextcloud**: Version 30 or later
|
|
- **MCP Server**: Running instance (Docker recommended)
|
|
- **Identity Provider**: OAuth provider supporting PKCE (Nextcloud OIDC Login or Keycloak)
|
|
- **Vector Sync**: Optional but recommended for semantic search (see [configuration guide](https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/configuration.md))
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
### User Guides
|
|
|
|
- [MCP Server Installation](https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/installation.md)
|
|
- [Configuration Guide](https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/configuration.md)
|
|
- [OAuth Setup](https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/oauth-setup.md)
|
|
|
|
### Technical Details
|
|
|
|
- [ADR-018: Nextcloud PHP App Architecture](https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/ADR-018-nextcloud-php-app-for-settings-ui.md)
|
|
- [OAuth PKCE Flow Details](https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/ADR-004-progressive-consent.md)
|
|
- [Vector Sync Architecture](https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/ADR-002-vector-sync-authentication.md)
|
|
|
|
### Troubleshooting
|
|
|
|
**Cannot connect to MCP server:**
|
|
- Verify `mcp_server_url` in `config.php`
|
|
- Check MCP server is running: `curl http://localhost:8000/health`
|
|
- Review logs: `tail -f data/nextcloud.log`
|
|
|
|
**Authorization fails:**
|
|
- Ensure MCP server is in OAuth mode
|
|
- Verify identity provider is accessible
|
|
- Check browser console for errors
|
|
|
|
**Semantic search returns no results:**
|
|
- Verify vector sync is enabled and running
|
|
- Check indexing status in Admin settings
|
|
- Allow time for initial indexing to complete
|
|
|
|
For more help, see the [Troubleshooting Guide](https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/troubleshooting.md).
|
|
|
|
---
|
|
|
|
## Contributing
|
|
|
|
We welcome contributions! Here's how to get started:
|
|
|
|
1. Fork the [nextcloud-mcp-server repository](https://github.com/cbcoutinho/nextcloud-mcp-server)
|
|
2. Create a feature branch: `git checkout -b feature/your-feature`
|
|
3. Make your changes in `third_party/astrolabe/`
|
|
4. Test thoroughly with a local Nextcloud instance
|
|
5. Submit a pull request
|
|
|
|
See [CONTRIBUTING.md](https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/CONTRIBUTING.md) for detailed guidelines.
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
AGPL-3.0
|
|
|
|
---
|
|
|
|
## About
|
|
|
|
**Astrolabe** is developed as part of the [Nextcloud MCP Server](https://github.com/cbcoutinho/nextcloud-mcp-server) project, bringing the power of semantic search and AI integration to Nextcloud.
|
|
|
|
**Author**: Chris Coutinho <chris@coutinho.io>
|
|
|
|
---
|
|
|
|
**Your Data. Mapped. Visualized. Connected.**
|
|
|
|
Install Astrolabe for Nextcloud.
|