onelogin-mcp copilot-instructions.md

GitHub Copilot Instructions for OneLogin MCP Server

Project Overview

This is a Model Context Protocol (MCP) server that provides comprehensive access to the OneLogin API. It enables Claude Desktop and other MCP clients to manage users, apps, roles, authentication, and security settings through comprehensive tools covering the complete OneLogin API surface.

Technology Stack:

• Runtime: Bun (Node.js compatible)
• Language: JavaScript (ES modules)
• Protocol: Model Context Protocol (MCP) SDK v1.20.1
• API: OneLogin API v1 and v2

Repository Structure

onelogin-mcp/
├── index.js                    # MCP server entry point
├── setup.js                    # Interactive credential configuration
├── lib/
│   ├── config.js               # Credential management
│   ├── onelogin-api.js         # OAuth2 client with token caching
│   └── tools/
│       ├── registry.js         # Tool registry and dispatcher
│       └── [28 tool modules]   # Individual API category handlers
├── package.json
├── CONTRIBUTING.md             # Tool description quality guidelines
├── PROGRESS.md                 # Implementation tracking
└── README.md                   # User documentation

Architecture Principles

Tool Module Pattern

Each tool module in lib/tools/ follows this structure:

export const tools = [
  {
    name: 'tool_name',
    description: '[Detailed description following CONTRIBUTING.md guidelines]',
    inputSchema: { type: 'object', properties: {...}, required: [...] }
  }
];

export const handlers = {
  tool_name: async (api, args) => {
    // Implementation using OneLogin API client
    return await api.get('/api/2/path', args);
  }
};

Tool Registration

• lib/tools/registry.js automatically discovers and registers all tools from imported modules
• Tool names use snake_case convention
• Handlers receive validated arguments and authenticated API client

Authentication Flow

• Credentials stored in ~/.config/onelogin-mcp/servers.json
• OAuth2 token caching handled by onelogin-api.js
• Multiple environment support via ONELOGIN_SERVER environment variable
• Automatic token refresh on expiration