# merill/lokka architecture

> Architecture diagram of the GitHub repository merill/lokka, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/merill/lokka
- Repository: https://github.com/merill/lokka

## Overview

Lokka is an MCP server that lets an AI client query and manage Microsoft Graph and Azure Resource Manager through natural-language tool calls. The main runtime registers and handles tools, selects an API path, and performs requests; authentication is provided by a separate auth manager supporting interactive, certificate, client-secret, and client-supplied-token modes. Token management, permission requests, Graph-version selection, and paginated responses are part of this runtime. Source excerpts show the main request and auth wiring; some tool-registration details are only documented in the README.

Main entry points: [`src/mcp/src/main.ts`](https://github.com/merill/lokka/blob/main/src/mcp/src/main.ts) (MCP server runtime), [`src/mcp/src/auth.ts`](https://github.com/merill/lokka/blob/main/src/mcp/src/auth.ts) (Auth manager), [`src/mcp/src/logger.ts`](https://github.com/merill/lokka/blob/main/src/mcp/src/logger.ts) (Logger), [`src/mcp/src/constants.ts`](https://github.com/merill/lokka/blob/main/src/mcp/src/constants.ts) (Auth configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["MCP runtime"]
  node_server["MCP server runtime<br/>[main.ts]"]
  node_stdio["stdio transport<br/>[main.ts]"]
  node_tool["API request tool<br/>[main.ts]"]
  node_token_tools["Token management tools<br/>[main.ts]"]
  node_permission_tool["Permission request tool<br/>[main.ts]"]
  node_logger["Logger<br/>[logger.ts]"]
end

subgraph group_identity["Authentication"]
  node_auth["Auth manager<br/>[auth.ts]"]
  node_auth_config["Auth configuration<br/>[constants.ts]"]
end

subgraph group_requests["API requests"]
  node_graph_request["Graph requests<br/>[main.ts]"]
  node_azure_request["Azure RM requests<br/>[main.ts]"]
end

subgraph group_integrations["External systems"]
  node_graph_api{{"Microsoft Graph API"}}
  node_azure_api{{"Azure Resource Manager API"}}
  node_identity_sdk{{"Azure Identity SDK"}}
  node_mcp_sdk{{"MCP SDK"}}
end

node_client(("AI MCP client"))

node_client -->|"connects over"| node_stdio
node_stdio -->|"starts runtime"| node_server
node_server -->|"registers tools"| node_tool
node_server -->|"registers tools"| node_token_tools
node_server -->|"registers tools"| node_permission_tool
node_tool -->|"dispatches Graph"| node_graph_request
node_tool -->|"dispatches Azure"| node_azure_request
node_graph_request -->|"sends requests"| node_graph_api
node_azure_request -->|"fetches requests"| node_azure_api
node_server -->|"initializes"| node_auth
node_auth -->|"creates credentials"| node_identity_sdk
node_server -->|"initializes Graph client"| node_graph_api
node_token_tools -->|"updates token"| node_auth
node_permission_tool -->|"refreshes credentials"| node_auth
node_auth -->|"uses defaults"| node_auth_config
node_server -->|"creates server"| node_mcp_sdk
node_server -->|"logs runtime"| node_logger

click node_server "https://github.com/merill/lokka/blob/main/src/mcp/src/main.ts"
click node_stdio "https://github.com/merill/lokka/blob/main/src/mcp/src/main.ts"
click node_tool "https://github.com/merill/lokka/blob/main/src/mcp/src/main.ts"
click node_token_tools "https://github.com/merill/lokka/blob/main/src/mcp/src/main.ts"
click node_permission_tool "https://github.com/merill/lokka/blob/main/src/mcp/src/main.ts"
click node_auth "https://github.com/merill/lokka/blob/main/src/mcp/src/auth.ts"
click node_auth_config "https://github.com/merill/lokka/blob/main/src/mcp/src/constants.ts"
click node_logger "https://github.com/merill/lokka/blob/main/src/mcp/src/logger.ts"
click node_graph_request "https://github.com/merill/lokka/blob/main/src/mcp/src/main.ts"
click node_azure_request "https://github.com/merill/lokka/blob/main/src/mcp/src/main.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_stdio,node_tool,node_token_tools,node_permission_tool,node_logger,node_client toneBlue
class node_auth,node_auth_config toneAmber
class node_graph_request,node_azure_request toneMint
class node_graph_api,node_azure_api,node_identity_sdk,node_mcp_sdk toneRose
```

## Components

### MCP runtime

- [MCP server runtime](https://github.com/merill/lokka/blob/main/src/mcp/src/main.ts): `src/mcp/src/main.ts`
- [stdio transport](https://github.com/merill/lokka/blob/main/src/mcp/src/main.ts): `src/mcp/src/main.ts`
- [API request tool](https://github.com/merill/lokka/blob/main/src/mcp/src/main.ts): `src/mcp/src/main.ts`
- [Token management tools](https://github.com/merill/lokka/blob/main/src/mcp/src/main.ts): `src/mcp/src/main.ts`
- [Permission request tool](https://github.com/merill/lokka/blob/main/src/mcp/src/main.ts): `src/mcp/src/main.ts`
- [Logger](https://github.com/merill/lokka/blob/main/src/mcp/src/logger.ts): `src/mcp/src/logger.ts`

### Authentication

- [Auth manager](https://github.com/merill/lokka/blob/main/src/mcp/src/auth.ts): `src/mcp/src/auth.ts`
- [Auth configuration](https://github.com/merill/lokka/blob/main/src/mcp/src/constants.ts): `src/mcp/src/constants.ts`

### API requests

- [Graph requests](https://github.com/merill/lokka/blob/main/src/mcp/src/main.ts): `src/mcp/src/main.ts`
- [Azure RM requests](https://github.com/merill/lokka/blob/main/src/mcp/src/main.ts): `src/mcp/src/main.ts`

### External systems

- **Microsoft Graph API**
- **Azure Resource Manager API**
- **Azure Identity SDK**
- **MCP SDK**

### Other components

- **AI MCP client**

## Connections

- AI MCP client → stdio transport: connects over (evidence: `README.md`)
- stdio transport → MCP server runtime: starts runtime (evidence: `src/mcp/src/main.ts`)
- MCP server runtime → API request tool: registers tools (evidence: `README.md`)
- MCP server runtime → Token management tools: registers tools (evidence: `README.md`)
- MCP server runtime → Permission request tool: registers tools (evidence: `README.md`)
- API request tool → Graph requests: dispatches Graph (evidence: `src/mcp/src/main.ts`)
- API request tool → Azure RM requests: dispatches Azure (evidence: `src/mcp/src/main.ts`)
- Graph requests → Microsoft Graph API: sends requests (evidence: `src/mcp/src/main.ts`)
- Azure RM requests → Azure Resource Manager API: fetches requests (evidence: `src/mcp/src/main.ts`)
- MCP server runtime → Auth manager: initializes (evidence: `src/mcp/src/main.ts`)
- Auth manager → Azure Identity SDK: creates credentials (evidence: `src/mcp/src/auth.ts`)
- MCP server runtime → Microsoft Graph API: initializes Graph client (evidence: `src/mcp/src/main.ts`)
- Token management tools → Auth manager: updates token (evidence: `src/mcp/src/main.ts`)
- Permission request tool → Auth manager: refreshes credentials (evidence: `src/mcp/src/main.ts`)
- Auth manager → Auth configuration: uses defaults (evidence: `src/mcp/src/auth.ts`)
- MCP server runtime → MCP SDK: creates server (evidence: `src/mcp/src/main.ts`)
- MCP server runtime → Logger: logs runtime (evidence: `src/mcp/src/main.ts`)