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>
7.8 KiB
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)
- Open Apps in your Nextcloud
- Search for "Astrolabe"
- Click "Download and enable"
Manual Installation
# 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:
'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 for details.
Quick start with Docker:
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
3. Authorize Access
- Go to Settings → Personal → Astrolabe
- Click "Authorize Access"
- Sign in to your identity provider
- 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)
Documentation
User Guides
Technical Details
Troubleshooting
Cannot connect to MCP server:
- Verify
mcp_server_urlinconfig.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.
Contributing
We welcome contributions! Here's how to get started:
- Fork the nextcloud-mcp-server repository
- Create a feature branch:
git checkout -b feature/your-feature - Make your changes in
third_party/astrolabe/ - Test thoroughly with a local Nextcloud instance
- Submit a pull request
See CONTRIBUTING.md for detailed guidelines.
License
AGPL-3.0
About
Astrolabe is developed as part of the 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.