admin/mcp-nextcloud
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(astrolabe): rewrite README for release with pitch integration

Browse Source 
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>
This commit is contained in:
Chris Coutinho
2025-12-18 00:02:09 +01:00
co-authored by Claude Sonnet 4.5
parent d4c0da85da
commit c4b3df04a0
1 changed files with 147 additions and 174 deletions
Download Patch File Download Diff File Expand all files Collapse all files
third_party/astrolabe/README.md
Vendored
+147 -174
View File
@@ -1,250 +1,223 @@
# MCP Server UI # Astrolabe: The Intelligence Layer for Nextcloud
Nextcloud app for managing the Nextcloud MCP (Model Context Protocol) Server. 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.
## Overview **It's time to turn the lights on.**
This app provides a native Nextcloud interface for managing your MCP Server, eliminating the need for the separate `/app` endpoint. It integrates seamlessly with Nextcloud's settings interface and provides: 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.
- **Personal Settings**: Session management, background access control ---
- **Admin Settings**: Server status monitoring, vector sync metrics
- **Vector Visualization**: Interactive semantic search (coming soon)
- **Native Integration**: Uses Nextcloud sessions, design system, and UX patterns
## Architecture ## What You Can Do
Based on **ADR-018: Nextcloud PHP App for Settings UI**. ### 🔍 Search That Actually Understands
### OAuth PKCE Flow Forget clunky external tools. Astrolabe registers as a **native Nextcloud Search Provider**.
The app uses **OAuth 2.0 Authorization Code flow with PKCE** (Proof Key for Code Exchange): - **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
User → NC Settings → OAuth Authorize → IdP Login → Callback
↓
NC stores encrypted per-user tokens
↓
NC PHP App → User's OAuth Token → MCP Server validates
```
**Key Features**: 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**.
- ✅ **No client secrets** - Uses PKCE (public client model)
- ✅ **Per-user authorization** - Each user explicitly authorizes access
- ✅ **Encrypted token storage** - Tokens stored encrypted in NC database
- ✅ **Leverages existing validation** - MCP server uses UnifiedTokenVerifier
- ✅ **User-revocable** - Users can disconnect at any time
### Architecture Benefits - **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
- ✅ Preserves full MCP protocol support (sampling, elicitation, streaming) ### 🤖 Power Your AI Agents
- ✅ Provides native Nextcloud integration
- ✅ Maintains clear separation of concerns
- ✅ Avoids ExApp limitations (see ADR-011)
- ✅ No shared secrets between NC and MCP server
## Requirements 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.
1. **Nextcloud**: Version 30 or later - **Bring Your Own Brain**: Connect external AI clients (like Claude Desktop or Cursor) to your private data
2. **MCP Server**: Running in OAuth mode - **Agentic Workflows**: Enable LLMs to "sample" your files, read content, and perform complex reasoning tasks using your Nextcloud data as the source of truth
3. **Identity Provider**: OAuth provider supporting PKCE (Nextcloud OIDC or Keycloak) - **Private & Secure**: Your data never leaves your infrastructure
4. **Configuration**: Set in `config.php`:
```php ---
'mcp_server_url' => 'http://localhost:8000',
```
## Installation ## Installation
### From App Store (Recommended) ### From App Store (Recommended)
1. Open Nextcloud Apps 1. Open **Apps** in your Nextcloud
2. Search for "MCP Server UI" 2. Search for **"Astrolabe"**
3. Click "Download and enable" 3. Click **"Download and enable"**
### Manual Installation ### Manual Installation
1. Clone or download this directory to `apps/astrolabe` ```bash
2. Install dependencies: `composer install` # Clone into your Nextcloud apps directory
3. Enable the app: `occ app:enable astrolabe` cd /path/to/nextcloud/apps
git clone https://github.com/cbcoutinho/nextcloud-mcp-server.git
cd nextcloud-mcp-server/third_party/astrolabe
## Configuration # Install dependencies
composer install
### 1. Configure Nextcloud # Enable the app
php /path/to/nextcloud/occ app:enable astrolabe
```
Add to `config/config.php`: ---
## Quick Start
### 1. Configure the MCP Server URL
Add this to your Nextcloud `config/config.php`:
```php ```php
'mcp_server_url' => 'http://localhost:8000', 'mcp_server_url' => 'http://localhost:8000',
``` ```
### 2. Configure MCP Server ### 2. Start the MCP Server
Ensure MCP server is running in OAuth mode. Add to MCP server `.env`: 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 ```bash
# Enable OAuth mode docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
ENABLE_OAUTH=true ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
# OAuth provider (Nextcloud or Keycloak)
NEXTCLOUD_HOST=https://your-nextcloud.example.com
# OR
KEYCLOAK_SERVER_URL=https://keycloak.example.com
KEYCLOAK_REALM=nextcloud-mcp
# Optional: Disable legacy /app endpoint
ENABLE_BROWSER_UI=false
``` ```
### 3. User Authorization ### 3. Authorize Access
Each user must authorize the Nextcloud app to access the MCP server: 1. Go to **Settings → Personal → Astrolabe**
1. Go to **Settings → Personal → MCP Server**
2. Click **"Authorize Access"** 2. Click **"Authorize Access"**
3. Sign in to your identity provider 3. Sign in to your identity provider
4. Approve the requested permissions 4. Approve the requested permissions
5. You will be redirected back to Nextcloud
The app uses **OAuth 2.0 with PKCE** (Public Client) - no client secrets are stored. That's it! You can now use semantic search and explore your data universe.
---
## Features ## Features
### Personal Settings ### Personal Settings
Located in: **Settings → Personal → MCP Server** Located in: **Settings → Personal → Astrolabe**
- **OAuth Authorization**: Authorize Nextcloud to access MCP server on your behalf - **Semantic Search Dashboard**: Interactive 3D visualization of your document chunks
- **Session Information**: View user ID, auth mode, OAuth connection status - **OAuth Authorization**: Authorize Nextcloud to access the MCP server on your behalf
- **Background Access**: Monitor whether MCP server has offline access enabled - **Session Information**: View connection status and authentication details
- **IdP Profile**: View identity provider profile details - **Connection Management**: Revoke access or disconnect when needed
- **Connection Management**:
- Revoke background access (removes server-side refresh token)
- Disconnect from MCP server (removes local OAuth tokens)
- **Vector Visualization**: Access interactive semantic search UI (if enabled)
### Admin Settings ### Admin Settings
Located in: **Settings → Administration → MCP Server** Located in: **Settings → Administration → Astrolabe**
- Server status and version info - **Server Status**: Monitor MCP server health and version
- Configuration validation (URL, API key) - **Vector Sync Metrics**: See how many documents are indexed, processing rates, and sync status
- Vector sync metrics (if enabled): - **Configuration Validation**: Verify server URL and connectivity
- Indexed documents count - **Feature Availability**: Check which capabilities are enabled
- Pending queue size
- Processing rate (docs/sec)
- Error counts
- Uptime monitoring
- Feature availability
## Development ### Unified Search Integration
### Structure Astrolabe integrates directly with Nextcloud's **Unified Search**:
``` - Available in the top search bar across all Nextcloud pages
astrolabe/ - Returns semantic matches ranked by relevance
├── lib/ - Shows excerpts from matching documents
│ ├── Controller/ - Links directly to source files in Nextcloud
│ │ ├── ApiController.php # Form handlers (revoke, etc.)
│ │ └── PageController.php # Main page routes
│ ├── Service/
│ │ └── McpServerClient.php # HTTP client for MCP server API
│ └── Settings/
│ ├── Personal.php # User settings panel
│ ├── PersonalSection.php # Settings section
│ ├── Admin.php # Admin settings panel
│ └── AdminSection.php # Admin section
├── templates/
│ └── settings/
│ ├── personal.php # Personal settings template
│ ├── admin.php # Admin settings template
│ └── error.php # Error template
├── css/
│ └── astrolabe-settings.css # Settings styles
└── js/
├── astrolabe-personalSettings.js
└── astrolabe-adminSettings.js
```
### Testing ---
1. Start MCP server with management API enabled ## Use Cases
2. Configure Nextcloud (config.php)
3. Enable the app: `occ app:enable astrolabe`
4. Navigate to settings panels
5. Verify data loads from MCP server API
### Debugging ### For Individuals
**Check logs:** - **Research**: Find all notes related to a project, even if they use different terminology
```bash - **Organization**: Discover forgotten documents related to your current work
# Nextcloud logs - **Exploration**: Visualize how your knowledge connects and evolves over time
tail -f data/nextcloud.log
# MCP server logs ### For Teams
docker compose logs -f mcp
```
**Common issues:** - **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
1. **"Cannot connect to MCP server"** ### For Developers
- Verify `mcp_server_url` is correct in config.php
- Check MCP server is running and accessible
- Verify network connectivity
2. **"Authorization Required" shown on personal settings** - **AI Integration**: Connect Claude Desktop, Cursor, or other MCP clients to Nextcloud
- User needs to click "Authorize Access" to complete OAuth flow - **RAG Workflows**: Build retrieval-augmented generation pipelines on your private data
- Verify MCP server is running in OAuth mode (`ENABLE_OAUTH=true`) - **Custom Agents**: Use the MCP protocol to create specialized workflows
- Check identity provider is accessible
3. **OAuth callback fails** ---
- Verify redirect URI is registered with IdP
- Check MCP server OAuth configuration
- Review browser console for errors
- Check nextcloud.log for PHP errors
4. **Settings panel blank** ## Requirements
- Check browser console for errors
- Verify templates exist in `templates/settings/`
- Check PHP errors in nextcloud.log
## Migration from /app Endpoint - **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))
If you're currently using the MCP server's `/app` endpoint: ---
1. **Phase 1** (v0.53+): Both UIs available
- Install this app
- Keep using `/app` or migrate to NC app
- Test functionality in NC app
2. **Phase 2** (v0.54+): NC app recommended
- `/app` shows deprecation notice
- New features only in NC app
- Begin migration
3. **Phase 3** (v0.56+): NC app only
- `/app` endpoint removed
- All users must use NC app
See [ADR-018](https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/ADR-018-nextcloud-php-app-for-settings-ui.md) for full migration plan.
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request
## Documentation ## Documentation
- [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) ### User Guides
- [MCP Server Configuration Guide](https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/configuration.md)
- [MCP Server Installation](https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/installation.md) - [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 ## License
AGPL-3.0 AGPL-3.0
## Author ---
Chris Coutinho <chris@coutinho.io> ## 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.