feat(astrolabe): add Nextcloud PHP app for MCP server management

Adds a native Nextcloud app "Astroglobe" that provides: - Personal settings: OAuth authorization for background MCP access - Admin settings: Server status and vector sync monitoring - API endpoints for MCP server communication The app uses PKCE OAuth flow to obtain tokens for the MCP server, enabling features like background vector sync per ADR-018. Includes: - PHP app structure (controllers, services, settings) - Vue.js frontend components - Docker compose mount configuration - Installation hook for development testing - ADR-018 documentation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-14 20:11:21 +01:00
parent a58a14111b
commit 21817543ad
72 changed files with 27253 additions and 0 deletions
@@ -0,0 +1,280 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\Astroglobe\Service;
+
+use OCP\Http\Client\IClientService;
+use OCP\IConfig;
+use Psr\Log\LoggerInterface;
+
+/**
+ * HTTP client for communicating with the MCP server's management API.
+ *
+ * This service wraps the MCP server's REST API endpoints defined in ADR-018.
+ * It handles authentication via OAuth bearer tokens and provides typed methods
+ * for all management operations.
+ */
+class McpServerClient {
+	private $httpClient;
+	private $config;
+	private $logger;
+	private $baseUrl;
+
+	public function __construct(
+		IClientService $clientService,
+		IConfig $config,
+		LoggerInterface $logger
+	) {
+		$this->httpClient = $clientService->newClient();
+		$this->config = $config;
+		$this->logger = $logger;
+
+		// Get MCP server configuration from Nextcloud config
+		$this->baseUrl = $this->config->getSystemValue('mcp_server_url', 'http://localhost:8000');
+	}
+
+	/**
+	 * Get server status (version, auth mode, features).
+	 *
+	 * Public endpoint - no authentication required.
+	 *
+	 * @return array{
+	 *   version?: string,
+	 *   auth_mode?: string,
+	 *   vector_sync_enabled?: bool,
+	 *   uptime_seconds?: int,
+	 *   management_api_version?: string,
+	 *   error?: string
+	 * }
+	 */
+	public function getStatus(): array {
+		try {
+			$response = $this->httpClient->get($this->baseUrl . '/api/v1/status');
+			$data = json_decode($response->getBody(), true);
+
+			if (json_last_error() !== JSON_ERROR_NONE) {
+				throw new \RuntimeException('Invalid JSON response from server');
+			}
+
+			return $data;
+		} catch (\Exception $e) {
+			$this->logger->error('Failed to get MCP server status', [
+				'error' => $e->getMessage(),
+				'server_url' => $this->baseUrl,
+			]);
+			return ['error' => $e->getMessage()];
+		}
+	}
+
+	/**
+	 * Get user session details.
+	 *
+	 * Requires authentication via OAuth bearer token.
+	 *
+	 * @param string $userId The user ID to query
+	 * @param string $token OAuth bearer token
+	 * @return array{
+	 *   session_id?: string,
+	 *   background_access_granted?: bool,
+	 *   background_access_details?: array,
+	 *   idp_profile?: array,
+	 *   error?: string
+	 * }
+	 */
+	public function getUserSession(string $userId, string $token): array {
+		try {
+			$response = $this->httpClient->get(
+				$this->baseUrl . "/api/v1/users/" . urlencode($userId) . "/session",
+				[
+					'headers' => [
+						'Authorization' => 'Bearer ' . $token
+					]
+				]
+			);
+			$data = json_decode($response->getBody(), true);
+
+			if (json_last_error() !== JSON_ERROR_NONE) {
+				throw new \RuntimeException('Invalid JSON response from server');
+			}
+
+			return $data;
+		} catch (\Exception $e) {
+			$this->logger->error("Failed to get session for user $userId", [
+				'error' => $e->getMessage(),
+				'user_id' => $userId,
+			]);
+			return ['error' => $e->getMessage()];
+		}
+	}
+
+	/**
+	 * Revoke user's background access (delete refresh token).
+	 *
+	 * Requires authentication via OAuth bearer token.
+	 *
+	 * @param string $userId The user ID whose access to revoke
+	 * @param string $token OAuth bearer token
+	 * @return array{success?: bool, message?: string, error?: string}
+	 */
+	public function revokeUserAccess(string $userId, string $token): array {
+		try {
+			$response = $this->httpClient->post(
+				$this->baseUrl . "/api/v1/users/" . urlencode($userId) . "/revoke",
+				[
+					'headers' => [
+						'Authorization' => 'Bearer ' . $token
+					]
+				]
+			);
+			$data = json_decode($response->getBody(), true);
+
+			if (json_last_error() !== JSON_ERROR_NONE) {
+				throw new \RuntimeException('Invalid JSON response from server');
+			}
+
+			return $data;
+		} catch (\Exception $e) {
+			$this->logger->error("Failed to revoke access for user $userId", [
+				'error' => $e->getMessage(),
+				'user_id' => $userId,
+			]);
+			return ['error' => $e->getMessage()];
+		}
+	}
+
+	/**
+	 * Get vector sync status (indexing metrics).
+	 *
+	 * Public endpoint - no authentication required.
+	 * Only available if VECTOR_SYNC_ENABLED=true on server.
+	 *
+	 * @return array{
+	 *   status?: string,
+	 *   indexed_documents?: int,
+	 *   pending_documents?: int,
+	 *   last_sync_time?: string,
+	 *   documents_per_second?: float,
+	 *   errors_24h?: int,
+	 *   error?: string
+	 * }
+	 */
+	public function getVectorSyncStatus(): array {
+		try {
+			$response = $this->httpClient->get($this->baseUrl . '/api/v1/vector-sync/status');
+			$data = json_decode($response->getBody(), true);
+
+			if (json_last_error() !== JSON_ERROR_NONE) {
+				throw new \RuntimeException('Invalid JSON response from server');
+			}
+
+			return $data;
+		} catch (\Exception $e) {
+			$this->logger->error('Failed to get vector sync status', [
+				'error' => $e->getMessage(),
+			]);
+			return ['error' => $e->getMessage()];
+		}
+	}
+
+	/**
+	 * Execute semantic search for vector visualization.
+	 *
+	 * Requires OAuth bearer token for user-filtered search.
+	 * Only available if VECTOR_SYNC_ENABLED=true on server.
+	 *
+	 * @param string $query Search query string
+	 * @param string $algorithm Search algorithm: "semantic", "bm25", or "hybrid"
+	 * @param int $limit Number of results (max 50)
+	 * @param bool $includePca Whether to include PCA coordinates for 2D plot
+	 * @param array|null $docTypes Document types to filter (e.g., ['note', 'file'])
+	 * @param string|null $token OAuth bearer token for authentication
+	 * @return array{
+	 *   results?: array,
+	 *   pca_coordinates?: array,
+	 *   algorithm_used?: string,
+	 *   total_documents?: int,
+	 *   error?: string
+	 * }
+	 */
+	public function search(
+		string $query,
+		string $algorithm = 'hybrid',
+		int $limit = 10,
+		bool $includePca = true,
+		?array $docTypes = null,
+		?string $token = null
+	): array {
+		try {
+			$requestBody = [
+				'query' => $query,
+				'algorithm' => $algorithm,
+				'limit' => min($limit, 50), // Enforce max limit
+				'include_pca' => $includePca,
+			];
+
+			// Add doc_types filter if specified
+			if ($docTypes !== null && count($docTypes) > 0) {
+				$requestBody['doc_types'] = $docTypes;
+			}
+
+			$options = ['json' => $requestBody];
+
+			// Add authorization header if token provided
+			if ($token !== null) {
+				$options['headers'] = [
+					'Authorization' => 'Bearer ' . $token
+				];
+			}
+
+			$response = $this->httpClient->post(
+				$this->baseUrl . '/api/v1/vector-viz/search',
+				$options
+			);
+			$data = json_decode($response->getBody(), true);
+
+			if (json_last_error() !== JSON_ERROR_NONE) {
+				throw new \RuntimeException('Invalid JSON response from server');
+			}
+
+			return $data;
+		} catch (\Exception $e) {
+			$this->logger->error('Failed to execute search', [
+				'error' => $e->getMessage(),
+				'query' => $query,
+				'algorithm' => $algorithm,
+			]);
+			return ['error' => $e->getMessage()];
+		}
+	}
+
+	/**
+	 * Check if the MCP server is reachable and API key is valid.
+	 *
+	 * @return bool True if server is reachable and healthy
+	 */
+	public function isServerReachable(): bool {
+		$status = $this->getStatus();
+		return !isset($status['error']);
+	}
+
+	/**
+	 * Get the configured MCP server internal URL (for API calls).
+	 *
+	 * @return string The internal base URL
+	 */
+	public function getServerUrl(): string {
+		return $this->baseUrl;
+	}
+
+	/**
+	 * Get the public MCP server URL (for display, OAuth audience).
+	 *
+	 * Falls back to internal URL if public URL not configured.
+	 *
+	 * @return string The public URL users/browsers see
+	 */
+	public function getPublicServerUrl(): string {
+		return $this->config->getSystemValue('mcp_server_public_url', $this->baseUrl);
+	}
+}
@@ -0,0 +1,204 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\Astroglobe\Service;
+
+use OCP\IConfig;
+use OCP\Security\ICrypto;
+use Psr\Log\LoggerInterface;
+
+/**
+ * Storage service for per-user MCP OAuth tokens.
+ *
+ * Stores encrypted access and refresh tokens in user preferences.
+ * Handles token expiration checking and refresh logic.
+ */
+class McpTokenStorage {
+	private $config;
+	private $crypto;
+	private $logger;
+
+	public function __construct(
+		IConfig $config,
+		ICrypto $crypto,
+		LoggerInterface $logger
+	) {
+		$this->config = $config;
+		$this->crypto = $crypto;
+		$this->logger = $logger;
+	}
+
+	/**
+	 * Store MCP OAuth tokens for a user.
+	 *
+	 * Tokens are encrypted before storage to protect user credentials.
+	 *
+	 * @param string $userId User ID
+	 * @param string $accessToken OAuth access token
+	 * @param string $refreshToken OAuth refresh token
+	 * @param int $expiresAt Unix timestamp when token expires
+	 */
+	public function storeUserToken(
+		string $userId,
+		string $accessToken,
+		string $refreshToken,
+		int $expiresAt
+	): void {
+		try {
+			$tokenData = [
+				'access_token' => $accessToken,
+				'refresh_token' => $refreshToken,
+				'expires_at' => $expiresAt,
+			];
+
+			// Encrypt token data before storage
+			$encrypted = $this->crypto->encrypt(json_encode($tokenData));
+
+			// Store in user preferences
+			$this->config->setUserValue(
+				$userId,
+				'astroglobe',
+				'oauth_tokens',
+				$encrypted
+			);
+
+			$this->logger->info("Stored MCP OAuth tokens for user: $userId");
+		} catch (\Exception $e) {
+			$this->logger->error("Failed to store MCP tokens for user $userId", [
+				'error' => $e->getMessage()
+			]);
+			throw $e;
+		}
+	}
+
+	/**
+	 * Get MCP OAuth tokens for a user.
+	 *
+	 * @param string $userId User ID
+	 * @return array|null Token data array with keys: access_token, refresh_token, expires_at
+	 */
+	public function getUserToken(string $userId): ?array {
+		try {
+			$encrypted = $this->config->getUserValue(
+				$userId,
+				'astroglobe',
+				'oauth_tokens',
+				''
+			);
+
+			if (empty($encrypted)) {
+				return null;
+			}
+
+			// Decrypt and parse token data
+			$decrypted = $this->crypto->decrypt($encrypted);
+			$tokenData = json_decode($decrypted, true);
+
+			if (!$tokenData || !isset($tokenData['access_token'])) {
+				$this->logger->warning("Invalid token data for user: $userId");
+				return null;
+			}
+
+			return $tokenData;
+		} catch (\Exception $e) {
+			$this->logger->error("Failed to retrieve MCP tokens for user $userId", [
+				'error' => $e->getMessage()
+			]);
+			return null;
+		}
+	}
+
+	/**
+	 * Check if a token is expired or about to expire.
+	 *
+	 * Uses a 60-second buffer to refresh tokens before they actually expire.
+	 *
+	 * @param array $token Token data array
+	 * @return bool True if expired or about to expire
+	 */
+	public function isExpired(array $token): bool {
+		if (!isset($token['expires_at'])) {
+			return true;
+		}
+
+		// Expire 60 seconds early to avoid race conditions
+		return time() >= ($token['expires_at'] - 60);
+	}
+
+	/**
+	 * Delete stored tokens for a user.
+	 *
+	 * Used when user disconnects or revokes access.
+	 *
+	 * @param string $userId User ID
+	 */
+	public function deleteUserToken(string $userId): void {
+		try {
+			$this->config->deleteUserValue(
+				$userId,
+				'astroglobe',
+				'oauth_tokens'
+			);
+
+			$this->logger->info("Deleted MCP OAuth tokens for user: $userId");
+		} catch (\Exception $e) {
+			$this->logger->error("Failed to delete MCP tokens for user $userId", [
+				'error' => $e->getMessage()
+			]);
+			throw $e;
+		}
+	}
+
+	/**
+	 * Get the access token for a user, handling expiration and refresh.
+	 *
+	 * This is a convenience method that combines token retrieval,
+	 * expiration checking, and automatic refresh if needed.
+	 *
+	 * @param string $userId User ID
+	 * @param callable|null $refreshCallback Callback to refresh token if expired
+	 *                                      Should accept (refreshToken) and return new token data
+	 * @return string|null Access token, or null if not available
+	 */
+	public function getAccessToken(string $userId, ?callable $refreshCallback = null): ?string {
+		$token = $this->getUserToken($userId);
+
+		if (!$token) {
+			return null;
+		}
+
+		// Check if token is expired
+		if ($this->isExpired($token)) {
+			// Try to refresh if callback provided
+			if ($refreshCallback && isset($token['refresh_token'])) {
+				try {
+					$newTokenData = $refreshCallback($token['refresh_token']);
+
+					if ($newTokenData && isset($newTokenData['access_token'])) {
+						// Store refreshed token
+						$this->storeUserToken(
+							$userId,
+							$newTokenData['access_token'],
+							$token['refresh_token'], // Keep same refresh token
+							time() + ($newTokenData['expires_in'] ?? 3600)
+						);
+
+						return $newTokenData['access_token'];
+					}
+				} catch (\Exception $e) {
+					$this->logger->error("Failed to refresh token for user $userId", [
+						'error' => $e->getMessage()
+					]);
+					// Fall through to return null
+				}
+			}
+
+			// Token expired and no refresh available
+			$this->logger->info("Token expired for user $userId, no refresh available");
+			return null;
+		}
+
+		return $token['access_token'];
+	}
+}