# larksuite/lark-openapi-mcp architecture

> Architecture diagram of the GitHub repository larksuite/lark-openapi-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/larksuite/lark-openapi-mcp
- Repository: https://github.com/larksuite/lark-openapi-mcp

## Overview

Feishu/Lark OpenAPI MCP exposes platform APIs as MCP tools for AI clients. The principal workflow is an MCP client request reaching the server, selecting an enabled tool, invoking the Lark SDK/API, and returning a tool result. The repository also provides CLI-based user OAuth login and token management, generated API tools in English and Chinese, built-in document/IM tools, and a developer-document recall tool. README capabilities guide the map; unsampled server and registry wiring is shown only at the documented level.

Main entry points: [`src/mcp-server/index.ts`](https://github.com/larksuite/lark-openapi-mcp/blob/main/src/mcp-server/index.ts) (MCP Server), [`src/mcp-tool/tools/index.ts`](https://github.com/larksuite/lark-openapi-mcp/blob/main/src/mcp-tool/tools/index.ts) (Tool Registry), [`src/auth/store.ts`](https://github.com/larksuite/lark-openapi-mcp/blob/main/src/auth/store.ts) (Token Store), [`src/mcp-tool/utils/handler.ts`](https://github.com/larksuite/lark-openapi-mcp/blob/main/src/mcp-tool/utils/handler.ts) (API Tool Handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client Access"]
  node_cli["CLI Commands<br/>[index.ts]"]
  node_login_cli["Login Handler<br/>[login-handler.ts]"]
end

subgraph group_runtime["MCP Runtime"]
  node_mcp_server["MCP Server<br/>[index.ts]"]
  node_transports["MCP Transports<br/>[index.ts]"]
  node_shared_init["Server Initialization<br/>[init.ts]"]
  node_tool_handler["API Tool Handler<br/>[handler.ts]"]
end

subgraph group_catalog["Tool Catalog"]
  node_tool_registry["Tool Registry<br/>[index.ts]"]
  node_generated_tools["Generated API Tools<br/>[index.ts]"]
  node_builtin_tools["Built-in Tools<br/>[index.ts]"]
  node_document_tools["Document Tools<br/>[index.ts]"]
  node_recall["Document Recall<br/>[index.ts]"]
end

subgraph group_auth["Authentication"]
  node_login_handler["OAuth Login Handler<br/>[handler-local.ts]"]
  node_auth_handler["OAuth Provider Handler<br/>[handler.ts]"]
  node_oauth_provider["OAuth Providers<br/>[index.ts]"]
  node_auth_store[("Token Store<br/>[store.ts]")]
  node_storage[("Encrypted Storage<br/>[storage-manager.ts]")]
end

subgraph group_platform["Lark Platform"]
  node_lark_sdk["Lark SDK"]
  node_lark_api["Feishu/Lark API"]
end

node_ai_client(("AI MCP Client"))

node_ai_client -->|"MCP requests"| node_transports
node_transports -->|"delivers requests"| node_mcp_server
node_mcp_server -->|"initializes"| node_shared_init
node_mcp_server -->|"dispatches tools"| node_tool_registry
node_tool_registry -->|"selects APIs"| node_generated_tools
node_tool_registry -->|"selects built-ins"| node_builtin_tools
node_tool_registry -->|"selects documents"| node_document_tools
node_document_tools -->|"offers recall"| node_recall
node_mcp_server -->|"invokes handler"| node_tool_handler
node_tool_handler -->|"calls SDK"| node_lark_sdk
node_lark_sdk -->|"sends API requests"| node_lark_api
node_lark_api -->|"returns API data"| node_lark_sdk
node_cli -->|"runs login"| node_login_cli
node_login_cli -->|"starts OAuth"| node_login_handler
node_login_handler -->|"uses local flow"| node_auth_handler
node_auth_handler -->|"delegates OAuth"| node_oauth_provider
node_oauth_provider -->|"exchanges tokens"| node_lark_api
node_login_handler -->|"stores access token"| node_auth_store
node_oauth_provider -->|"persists tokens"| node_auth_store
node_auth_store -->|"loads and saves"| node_storage
node_mcp_server -.->|"enables OAuth"| node_auth_handler
node_tool_handler -.->|"uses user token"| node_auth_store

click node_cli "https://github.com/larksuite/lark-openapi-mcp/blob/main/src/cli/index.ts"
click node_login_cli "https://github.com/larksuite/lark-openapi-mcp/blob/main/src/cli/login-handler.ts"
click node_mcp_server "https://github.com/larksuite/lark-openapi-mcp/blob/main/src/mcp-server/index.ts"
click node_transports "https://github.com/larksuite/lark-openapi-mcp/blob/main/src/mcp-server/transport/index.ts"
click node_shared_init "https://github.com/larksuite/lark-openapi-mcp/blob/main/src/mcp-server/shared/init.ts"
click node_tool_registry "https://github.com/larksuite/lark-openapi-mcp/blob/main/src/mcp-tool/tools/index.ts"
click node_generated_tools "https://github.com/larksuite/lark-openapi-mcp/blob/main/src/mcp-tool/tools/en/gen-tools/index.ts"
click node_builtin_tools "https://github.com/larksuite/lark-openapi-mcp/blob/main/src/mcp-tool/tools/en/builtin-tools/index.ts"
click node_document_tools "https://github.com/larksuite/lark-openapi-mcp/blob/main/src/mcp-tool/document-tool/index.ts"
click node_recall "https://github.com/larksuite/lark-openapi-mcp/blob/main/src/mcp-tool/document-tool/recall/index.ts"
click node_tool_handler "https://github.com/larksuite/lark-openapi-mcp/blob/main/src/mcp-tool/utils/handler.ts"
click node_login_handler "https://github.com/larksuite/lark-openapi-mcp/blob/main/src/auth/handler/handler-local.ts"
click node_auth_handler "https://github.com/larksuite/lark-openapi-mcp/blob/main/src/auth/handler/handler.ts"
click node_oauth_provider "https://github.com/larksuite/lark-openapi-mcp/blob/main/src/auth/provider/index.ts"
click node_auth_store "https://github.com/larksuite/lark-openapi-mcp/blob/main/src/auth/store.ts"
click node_storage "https://github.com/larksuite/lark-openapi-mcp/blob/main/src/auth/utils/storage-manager.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_cli,node_login_cli,node_ai_client toneBlue
class node_mcp_server,node_transports,node_shared_init,node_tool_handler toneAmber
class node_tool_registry,node_generated_tools,node_builtin_tools,node_document_tools,node_recall toneMint
class node_login_handler,node_auth_handler,node_oauth_provider,node_auth_store,node_storage toneRose
class node_lark_sdk,node_lark_api toneIndigo
```

## Components

### Client Access

- [CLI Commands](https://github.com/larksuite/lark-openapi-mcp/blob/main/src/cli/index.ts): `src/cli/index.ts`
- [Login Handler](https://github.com/larksuite/lark-openapi-mcp/blob/main/src/cli/login-handler.ts): `src/cli/login-handler.ts`

### MCP Runtime

- [MCP Server](https://github.com/larksuite/lark-openapi-mcp/blob/main/src/mcp-server/index.ts): `src/mcp-server/index.ts`
- [MCP Transports](https://github.com/larksuite/lark-openapi-mcp/blob/main/src/mcp-server/transport/index.ts): `src/mcp-server/transport/index.ts`
- [Server Initialization](https://github.com/larksuite/lark-openapi-mcp/blob/main/src/mcp-server/shared/init.ts): `src/mcp-server/shared/init.ts`
- [API Tool Handler](https://github.com/larksuite/lark-openapi-mcp/blob/main/src/mcp-tool/utils/handler.ts): `src/mcp-tool/utils/handler.ts`

### Tool Catalog

- [Tool Registry](https://github.com/larksuite/lark-openapi-mcp/blob/main/src/mcp-tool/tools/index.ts): `src/mcp-tool/tools/index.ts`
- [Generated API Tools](https://github.com/larksuite/lark-openapi-mcp/blob/main/src/mcp-tool/tools/en/gen-tools/index.ts): `src/mcp-tool/tools/en/gen-tools/index.ts`
- [Built-in Tools](https://github.com/larksuite/lark-openapi-mcp/blob/main/src/mcp-tool/tools/en/builtin-tools/index.ts): `src/mcp-tool/tools/en/builtin-tools/index.ts`
- [Document Tools](https://github.com/larksuite/lark-openapi-mcp/blob/main/src/mcp-tool/document-tool/index.ts): `src/mcp-tool/document-tool/index.ts`
- [Document Recall](https://github.com/larksuite/lark-openapi-mcp/blob/main/src/mcp-tool/document-tool/recall/index.ts): `src/mcp-tool/document-tool/recall/index.ts`

### Authentication

- [OAuth Login Handler](https://github.com/larksuite/lark-openapi-mcp/blob/main/src/auth/handler/handler-local.ts): `src/auth/handler/handler-local.ts`
- [OAuth Provider Handler](https://github.com/larksuite/lark-openapi-mcp/blob/main/src/auth/handler/handler.ts): `src/auth/handler/handler.ts`
- [OAuth Providers](https://github.com/larksuite/lark-openapi-mcp/blob/main/src/auth/provider/index.ts): `src/auth/provider/index.ts`
- [Token Store](https://github.com/larksuite/lark-openapi-mcp/blob/main/src/auth/store.ts): `src/auth/store.ts`
- [Encrypted Storage](https://github.com/larksuite/lark-openapi-mcp/blob/main/src/auth/utils/storage-manager.ts): `src/auth/utils/storage-manager.ts`

### Lark Platform

- **Lark SDK**
- **Feishu/Lark API**

### Other components

- **AI MCP Client**

## Connections

- AI MCP Client → MCP Transports: MCP requests
- MCP Transports → MCP Server: delivers requests
- MCP Server → Server Initialization: initializes
- MCP Server → Tool Registry: dispatches tools
- Tool Registry → Generated API Tools: selects APIs
- Tool Registry → Built-in Tools: selects built-ins
- Tool Registry → Document Tools: selects documents
- Document Tools → Document Recall: offers recall
- MCP Server → API Tool Handler: invokes handler
- API Tool Handler → Lark SDK: calls SDK
- Lark SDK → Feishu/Lark API: sends API requests
- Feishu/Lark API → Lark SDK: returns API data
- CLI Commands → Login Handler: runs login
- Login Handler → OAuth Login Handler: starts OAuth
- OAuth Login Handler → OAuth Provider Handler: uses local flow
- OAuth Provider Handler → OAuth Providers: delegates OAuth
- OAuth Providers → Feishu/Lark API: exchanges tokens
- OAuth Login Handler → Token Store: stores access token
- OAuth Providers → Token Store: persists tokens
- Token Store → Encrypted Storage: loads and saves
- MCP Server → OAuth Provider Handler: enables OAuth
- API Tool Handler → Token Store: uses user token