Admin API & GraphQL
Relevant source files
The following files were used as context for generating this wiki page:
The Admin API & GraphQL systems in MCB provide the management and observability layer for the Model Context Protocol (MCP) server. This infrastructure encompasses a web-based Administrative UI, a set of RESTful health and configuration endpoints, and a GraphQL interface powered by the SeaQL ecosystem. These tools allow administrators to monitor system health, manage jobs, browse indexed collections, and view server configurations in real-time.
The system is built upon the Loco.rs framework and Axum, utilizing SeaORM for database interactions and Seaography for automated GraphQL schema generation. The frontend is a lightweight, zero-framework implementation using vanilla JavaScript and CSS variables to ensure high performance and minimal external dependencies.
Sources: crates/mcb-server/src/controllers/web/mod.rs, crates/mcb-server/Cargo.toml, README.md
Web Administrative Interface
The Admin UI is served via the /ui prefix and provides several functional modules for system oversight. It uses a server-side rendering (SSR) approach with shared layout components and client-side theme management.
UI Architecture and Navigation
The interface is structured as a single-page-like experience using shared layout logic and a consistent navigation bar. The frontend logic is encapsulated in shared.js, which handles theme switching and API communication.
The diagram shows the relationship between the client-side assets and the server-side controllers that generate the Admin UI.
Sources: crates/mcb-server/src/controllers/web/mod.rs:58-94, assets/admin/ui/shared.js
Core Admin Routes
| Route | Function | Description |
|---|---|---|
/ui/ | Dashboard | High-level system metrics and overview. |
/ui/config | Configuration | Displays active server settings (port, host, providers). |
/ui/health | Health Status | Real-time system health and component status. |
/ui/jobs | Job Monitor | Status of background tasks such as indexing. |
/ui/browse | Collection Browser | Interface for exploring indexed code collections. |
Sources: crates/mcb-server/src/controllers/web/mod.rs:114-122, tests/e2e/admin-ui-routes.spec.ts:25-70
GraphQL Integration
MCB leverages the SeaQL ecosystem to provide a powerful GraphQL interface for data exploration. This system integrates SeaORM entities with Seaography to expose the underlying domain model through a typed GraphQL schema.
GraphQL Stack Components
- async-graphql: The core GraphQL implementation for Rust.
- Seaography: Automatically generates GraphQL types and resolvers from SeaORM entities.
- SeaORM: The Object-Relational Mapper that handles database queries for GraphQL requests.
- Axum Integration: Exposed via
async-graphql-axumfor HTTP transport.
The flow of a GraphQL query from the client through the generated resolvers to the database.
Sources: crates/mcb-server/Cargo.toml:86-90, Cargo.toml:410-435
System Observability and Health
The Admin API provides programmatic access to system status, which the UI consumes to display real-time metrics.
API Endpoints
The following internal API endpoints are used by the functional tests and the Admin UI to retrieve system data:
- GET /health: Returns a JSON object containing the
statusof the system and individual components. - GET /config: Returns the current runtime configuration (e.g., embedding providers, vector stores).
- GET /jobs: Provides statistics on background jobs (total, running, queued).
- GET /collections: Lists the collections currently stored in the vector database.
Sources: tests/e2e/admin-functional.spec.ts:50-89
UI Components and Utilities
The frontend utilizes CSS variables for theme management, allowing for seamless switching between light and dark modes.
/* theme.css excerpt */
:root {
--color-primary: #2563eb;
--bg-primary: #ffffff;
--text-primary: #111827;
}
[data-theme='dark'] {
--bg-primary: #1f2937;
--text-primary: #f9fafb;
}
Sources: assets/admin/ui/theme.css:2-105
The shared.js utility provides a standardized apiRequest function that handles timeouts, headers, and JSON parsing for all administrative interactions.
async function apiRequest(url, options = {}) {
// Handles fetch with AbortController timeout
// Automatically injects Content-Type: application/json
// Parses JSON response or returns text
}
Sources: assets/admin/ui/shared.js:125-165
Conclusion
The Admin API & GraphQL infrastructure in MCB ensures that the server is not a "black box." By providing both a human-readable Web UI and a machine-readable GraphQL/REST API, the system enables deep inspection of the persistent memory, indexed repositories, and internal system health. The use of the SeaQL ecosystem allows the GraphQL interface to evolve automatically alongside the domain entities, reducing maintenance overhead while providing flexible data access.