nextcloud-mcp-server/third_party/astroglobe

MCP Server UI

Nextcloud app for managing the Nextcloud MCP (Model Context Protocol) Server.

Overview

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:

• 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

Based on ADR-018: Nextcloud PHP App for Settings UI.

OAuth PKCE Flow

The app uses OAuth 2.0 Authorization Code flow with PKCE (Proof Key for Code Exchange):

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:

• ✅ 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

• ✅ Preserves full MCP protocol support (sampling, elicitation, streaming)
• ✅ Provides native Nextcloud integration
• ✅ Maintains clear separation of concerns
• ✅ Avoids ExApp limitations (see ADR-011)
• ✅ No shared secrets between NC and MCP server

Requirements

1. Nextcloud: Version 30 or later
2. MCP Server: Running in OAuth mode
3. Identity Provider: OAuth provider supporting PKCE (Nextcloud OIDC or Keycloak)
4. Configuration: Set in config.php:

'mcp_server_url' => 'http://localhost:8000',

Installation

From App Store (Recommended)

1. Open Nextcloud Apps
2. Search for "MCP Server UI"
3. Click "Download and enable"

Manual Installation

1. Clone or download this directory to apps/astroglobe
2. Install dependencies: composer install
3. Enable the app: occ app:enable astroglobe

Configuration

1. Configure Nextcloud

Add to config/config.php:

'mcp_server_url' => 'http://localhost:8000',

2. Configure MCP Server

Ensure MCP server is running in OAuth mode. Add to MCP server .env:

# Enable OAuth mode
ENABLE_OAUTH=true

# 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

Each user must authorize the Nextcloud app to access the MCP server:

1. Go to Settings → Personal → MCP Server
2. Click "Authorize Access"
3. Sign in to your identity provider
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.

Features

Personal Settings

Located in: Settings → Personal → MCP Server

• OAuth Authorization: Authorize Nextcloud to access MCP server on your behalf
• Session Information: View user ID, auth mode, OAuth connection status
• Background Access: Monitor whether MCP server has offline access enabled
• IdP Profile: View identity provider profile details
• 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

Located in: Settings → Administration → MCP Server

• Server status and version info
• Configuration validation (URL, API key)
• Vector sync metrics (if enabled):
  • Indexed documents count
  • Pending queue size
  • Processing rate (docs/sec)
  • Error counts
• Uptime monitoring
• Feature availability

Development

Structure

astroglobe/
├── lib/
│   ├── Controller/
│   │   ├── 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/
│   └── astroglobe-settings.css   # Settings styles
└── js/
    ├── astroglobe-personalSettings.js
    └── astroglobe-adminSettings.js

Testing

1. Start MCP server with management API enabled
2. Configure Nextcloud (config.php)
3. Enable the app: occ app:enable astroglobe
4. Navigate to settings panels
5. Verify data loads from MCP server API

Debugging

Check logs:

# Nextcloud logs
tail -f data/nextcloud.log

# MCP server logs
docker compose logs -f mcp

Common issues:

1. "Cannot connect to MCP server"

   • 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

   • User needs to click "Authorize Access" to complete OAuth flow
   • Verify MCP server is running in OAuth mode (ENABLE_OAUTH=true)
   • 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

   • Check browser console for errors
   • Verify templates exist in templates/settings/
   • Check PHP errors in nextcloud.log

Migration from /app Endpoint

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 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

• ADR-018: Nextcloud PHP App Architecture
• MCP Server Configuration Guide
• MCP Server Installation

License

AGPL-3.0

Author

Chris Coutinho chris@coutinho.io