Radius MCP Server

# Radius MCP Server The Radius MCP Server is a comprehensive Model Context Protocol (MCP) server that provides authentication, calendar management, and session handling capabilities for AI agents and developer tools. This server offers a complete business productivity suite, enabling AI agents to authenticate users, manage calendar events, create meetings, and maintain persistent API sessions for seamless integration with Russian business platforms. ## Project Structure The codebase is organized as follows: ``` radius-mcp-server/ ├── src/ │ ├── common/ # Shared utilities and helpers │ │ ├── event-bus.ts # Simple event bus for broadcasting events │ │ ├── request-helper.ts # HTTP request helper utilities │ │ └── version.ts # Version info │ ├── tools/ # MCP tool definitions │ │ ├── index.ts # Registers all tool modules with the MCP server │ │ ├── hello-world.ts # Hello world tool implementation │ │ ├── auth-tools.ts # Authentication and session management tools │ │ └── calendar-tools.ts # Calendar and meeting management tools │ ├── http-server.ts # Express HTTP server, MCP/SSE endpoints │ ├── server.ts # MCP server initialization and tool registration │ ├── schemas.ts # Zod schemas for data structures │ ├── declarations.d.ts # TypeScript module declarations │ └── index.ts # Entry point, loads .env and starts the HTTP server ├── .gitlab-ci.yml # GitLab CI/CD pipeline configuration ├── _common.yml # Shared GitLab CI templates ├── werf.yaml # Container build configuration ├── .helm/ # Kubernetes Helm charts │ ├── Chart.yaml # Helm chart metadata │ ├── values.yaml # Base configuration │ ├── values.dev.yaml # Development environment config │ ├── values.testing.yaml # Testing environment config │ ├── values.prod20.yaml # Production environment config │ └── templates/ # Kubernetes resource templates ├── docker-compose.yml # Docker development setup ├── Dockerfile # Container build instructions ├── README.md # Project documentation ├── package.json # Project metadata and dependencies └── ... # Other config and support files ``` ### Key Components #### Core Infrastructure - **src/common/**: Shared utilities for HTTP requests, event handling, and versioning - **src/http-server.ts**: Express server with MCP and SSE endpoints - **src/server.ts**: MCP server initialization and tool registration - **src/schemas.ts**: Zod schemas for data validation and TypeScript types - **src/index.ts**: Application entry point with environment configuration #### Business Logic Tools - **src/tools/auth-tools.ts**: Complete authentication system with session management - Sign-in with email/password and automatic API key storage - Password management (check/change) - Session lifecycle management (login/logout/info) - Connection testing and debugging - **src/tools/calendar-tools.ts**: Comprehensive calendar and meeting management - Personal and user calendar retrieval - Meeting creation, retrieval, and management - User availability checking - Meeting attention notifications - **src/tools/hello-world.ts**: Simple demonstration tool - **src/tools/index.ts**: Central tool registration hub #### DevOps & Deployment - **GitLab CI/CD Pipeline**: Automated testing, building, and deployment - **Docker Support**: Containerized development and production deployment - **Kubernetes Helm Charts**: Production-ready container orchestration - **Multi-environment Config**: Separate configurations for dev/testing/production #### Features - **Session Management**: Persistent API key storage across requests - **Multi-API Integration**: Authorization and Calendar microservice connectivity - **Error Handling**: Comprehensive error reporting and debugging - **Type Safety**: Full TypeScript implementation with Zod validation - **Scalable Architecture**: Modular tool system for easy extension --- ## Core Capabilities The Radius MCP Server provides enterprise-grade functionality for AI agents: ### 🔐 Authentication & Session Management - **Complete Sign-in Flow**: Authenticate with email/password, automatically receive and store API keys - **Session Persistence**: Maintain authentication across multiple tool calls - **Password Management**: Check and change user passwords securely - **Multi-session Support**: Handle multiple concurrent user sessions ### 📅 Calendar & Meeting Management - **Personal Calendar**: Retrieve your calendar events with date filtering - **User Calendar Access**: View any user's calendar by ID - **Meeting Creation**: Create meetings with invitations and notifications - **Availability Checking**: Check user availability before scheduling - **Meeting Management**: Get meeting details and attention-required meetings ### 🛠️ Developer Features - **Type-Safe API**: Full TypeScript implementation with Zod validation - **Error Handling**: Comprehensive error reporting and debugging tools - **Flexible Configuration**: Environment variables and parameter overrides - **Session Debugging**: Tools to inspect and manage authentication sessions - **Modular Architecture**: Easy to extend with additional business tools ### 🚀 Production Ready - **CI/CD Pipeline**: Automated testing, building, and deployment with GitLab - **Container Support**: Docker and Kubernetes deployment ready - **Multi-environment**: Separate configurations for development, testing, and production - **Monitoring**: Built-in logging and debugging capabilities --- ## Example: Configuring MCP Server (Local with npx & Remote with SSE) You can connect to your Radius MCP server either by running it locally with `npx` or by connecting to a remote server using the SSE MCP type. Below are configuration examples for both approaches in popular clients. ### VSCode MCP Server Configuration Add this to your `.vscode/settings.json` or `mcp.json`: #### Local (npx) ```json { "servers": { "radius": { "command": "npx", "args": ["-y", "radius-mcp-server"] } } } ``` #### Remote (SSE) ```json { "servers": { "radius": { "type": "sse", "url": "http://<your-server-host>:3000/sse", "capabilities": { "tools": true } } } } ``` - Replace `<your-server-host>` with your server's public IP or domain. - Use the `npx` config for local development, and the `sse` config for connecting to a remote server. ### Claude Desktop Configuration #### Local (npx) ```json { "mcpServers": { "radius": { "command": "npx", "args": ["-y", "radius-mcp-server"] } } } ``` #### Remote (SSE) ```json { "mcpServers": { "radius": { "type": "sse", "url": "http://<your-server-host>:3000/sse", "capabilities": { "tools": true } } } } ``` ### Generic MCP Client If your client supports specifying the MCP type and endpoint, use: ```json { "type": "sse", "url": "http://<your-server-host>:3000/sse" } ``` ### Notes - For local development, use the `npx` configuration to run the server on demand. - For remote access, use the `sse` configuration and ensure your server is accessible from the client (open firewall, correct port, etc.). - For production, use HTTPS and a secure domain. - The `/sse` endpoint is compatible with any MCP client that supports the SSE transport. --- ## What can you do with it? This server provides comprehensive business productivity capabilities that enable AI agents to: ### 🔐 **Complete User Authentication** - **Sign in with credentials**: Authenticate users with email/password and automatically manage API keys - **Session management**: Maintain persistent authentication across multiple operations - **Password operations**: Securely check and change user passwords - **Multi-user support**: Handle multiple concurrent user sessions with isolation ### 📅 **Advanced Calendar Management** - **Personal calendar access**: Retrieve and filter your calendar events by date range - **Cross-user calendar viewing**: Access any user's calendar for scheduling coordination - **Meeting lifecycle management**: Create, retrieve, and manage meeting details - **Smart scheduling**: Check user availability before creating meetings - **Notification handling**: Get meetings requiring attention or responses ### 🛡️ **Enterprise-Grade Session Handling** - **Automatic API key management**: Store and reuse authentication tokens seamlessly - **Session isolation**: Support multiple concurrent user sessions - **Connection testing**: Validate authentication status and API connectivity - **Graceful error handling**: Comprehensive error reporting and recovery ### 🔧 **Developer-Friendly Integration** - **Type-safe operations**: Full TypeScript implementation with Zod validation - **Flexible authentication**: Support both manual API keys and automatic sign-in flows - **Environment configuration**: Easily configure API endpoints and credentials - **Comprehensive logging**: Detailed debugging and monitoring capabilities This makes the server ideal for building AI assistants that need to interact with Russian business platforms, manage user authentication, and coordinate calendar activities in a secure, scalable manner. ## Development ### Building and Running (Local) ```bash # Install dependencies npm install # Development mode (with hot reload) npm run dev # Build the project npm run build # Start the server (production) npm start ``` ### Development Mode The `npm run dev` command provides a development server with: - **Hot reload**: Automatically restarts when you change TypeScript files - **Direct TypeScript execution**: No need to build first using `ts-node` - **File watching**: Monitors `src/` directory for changes - **Development environment**: Sets `NODE_ENV=development` ```bash # Start development server npm run dev # The server will restart automatically when you modify files in src/ ``` ### Testing ```bash # Run all tests (lint, format check, build, and startup test) npm test # Run individual commands npm run lint npm run format:check npm run build npm run test-startup ``` ## Docker The Radius MCP Server includes Docker support for easy deployment and development. ### Docker Compose (Recommended) #### Production ```bash # Build and start the server npm run docker:up # View logs npm run docker:logs # Stop the server npm run docker:down ``` #### Development ```bash # Start development environment with hot reload npm run docker:dev # Stop development environment npm run docker:dev:down ``` ### Manual Docker Commands ```bash # Build the Docker image docker build -t radius-mcp-server . # Run the container docker run -d -p 3000:3000 --name radius-mcp-server radius-mcp-server # View logs docker logs -f radius-mcp-server # Stop the container docker stop radius-mcp-server ``` ### Docker Configuration The Docker setup includes: - **Multi-stage build** for optimized production images - **Health checks** for container monitoring - **Non-root user** for security - **Development profile** with volume mounting for hot reload - **Port 3000** exposed for the MCP server #### Ports - **Production**: `http://localhost:3000` - **Development**: `http://localhost:3001` #### Environment Variables You can customize the Docker deployment by setting environment variables in a `.env` file or directly in the docker-compose.yml file. ## Available Tools ### Hello World Tool - `hello_world`: A simple tool that greets the world ### Authorization Tools The server includes authorization functionality for password management and session control: #### Authentication & Session Management - `auth_sign_in`: Sign in with email and password, automatically store API key - Parameters: `account` (required), `password` (required), `platform` (optional, default: "WEB"), `session_id` (optional) - Description: Complete sign-in flow - authenticates with email/password and automatically stores received API key in session - `auth_login`: Authenticate and store API key for session - Parameters: `api_key` (required), `session_id` (optional) - Description: Stores an existing API key in session for automatic authentication in subsequent requests - `auth_logout`: Logout and clear session - Parameters: `session_id` (optional) - Description: Clears stored API key from session - `auth_session_info`: Get current session information - Parameters: `session_id` (optional) - Description: Shows current session status and stored authentication info - `auth_test_connection`: Test authenticated connection to authorization API - Parameters: `session_id` (optional) - Description: Tests if stored credentials are working #### Password Management - `auth_check_password`: Check current password - Parameters: `password` (required), `api_key` (optional), `session_id` (optional) - Description: Verifies your current password - `auth_change_password`: Change current password - Parameters: `password` (required), `new_password` (required), `api_key` (optional), `session_id` (optional) - Description: Changes your password from current to new one ### Calendar Tools The server includes comprehensive calendar functionality for the Russian calendar microservice: #### Get Calendar Events - `calendar_get_my`: Get your calendar events - Parameters: `start`, `end` (optional dates), `api_key` (optional), `session_id` (optional) - Description: Retrieves your personal calendar events for specified date range - `calendar_get_by_user`: Get calendar events for a specific user - Parameters: `user_id` (required), `start`, `end` (optional), `api_key` (optional), `session_id` (optional) - Description: Retrieves calendar events for any user by their ID #### Meeting Management - `meeting_create`: Create a new meeting - Parameters: `title` (required), `description`, `place`, `start` (required), `end` (required), `invited` (user IDs), `notify`, `api_key` (optional), `session_id` (optional) - Description: Creates a new meeting with specified details and invites users - `meeting_get`: Get specific meeting details - Parameters: `meeting_id` (required), `api_key` (optional), `session_id` (optional) - Description: Retrieves detailed information about a specific meeting - `meeting_get_user_availability`: Check user availability for meetings - Parameters: `start` (required), `end` (required), `user_ids` (required), `meeting_id` (optional exclude), `api_key` (optional), `session_id` (optional) - Description: Checks if specified users are available during the given time period - `meeting_get_requiring_attention`: Get meetings requiring attention - Parameters: `api_key` (optional), `session_id` (optional) - Description: Retrieves list of meetings that need your attention or response ### Authentication Configuration #### Environment Variables - `AUTH_API_HOST_URL`: Authorization API base URL (default: https://api.development.myradius.ru) - `AUTH_API_KEY`: Default API key for authorization (can be overridden per request) - `CALENDAR_API_HOST_URL`: Calendar API base URL (default: http://localhost:8000) - `CALENDAR_API_KEY`: Default API key for calendar (can be overridden per request) #### Session Management The server supports persistent session management with two authentication flows: **Complete Sign-in Flow:** 1. Use `auth_sign_in` with email/password to authenticate and automatically store API key 2. All subsequent API calls will automatically use the stored key 3. No need to manually handle API keys **Manual API Key Flow:** 1. Use `auth_login` to store an existing API key in memory 2. All subsequent API calls will automatically use the stored key **Additional Features:** 3. Override stored key by passing `api_key` parameter to any tool 4. Use `session_id` to manage multiple concurrent sessions 5. Clear session with `auth_logout` 6. Check session status with `auth_session_info` This allows for convenient authentication flow where you authenticate once and then use tools without specifying credentials each time. ## License This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.