# aashari/mcp-server-aws-sso architecture

> Architecture diagram of the GitHub repository aashari/mcp-server-aws-sso, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aashari/mcp-server-aws-sso
- Repository: https://github.com/aashari/mcp-server-aws-sso

## Overview

##### Project Type and Purpose
- This is a Node.js/TypeScript CLI/MCP‐server library (package name `@aashari/mcp-server-aws-sso`) that implements the Model Context Protocol (MCP) over a command-based interface.
- Purpose: Expose AWS SSO flows (login, status, list accounts, execute CLI/EC2 commands) as MCP “tools” so that LLM-powered clients can securely authenticate and interact with AWS resources.

##### File Structure
Top‐level:
- src/cli – CLI entrypoints and argument parsing
- src/controllers – Controllers translate CLI/MCP requests into service calls and format responses
- src/services – Business logic for AWS SSO device flow, account listing, AWS CLI exec, EC2 SSM exec
- src/tools – MCP tool definitions (mapping MCP tool names to controller methods)
- src/utils – Cross-cutting concerns: caching, config, logging, error handling, retry, transport (stdin/stdout)
- tests are collocated with controllers, services, CLI under .test.ts files
Config and Packaging:
- package.json, scripts/, .github/workflows – CI, release, linting
- .npmrc, .prettierrc, eslint.config.mjs – style & publishing rules

##### README for Additional Insights
- Describes the four MCP tools (`aws_sso_login`, `aws_sso_status`, `aws_sso_ls_accounts`, `aws_sso_exec_command`, `aws_sso_ec2_exec_command`) and corresponding CLI commands (`login`, `status`, `ls-accounts`, `exec-command`, `ec2-exec-command`).
- Explains AWS SSO device flow, temporary credential rotation, and tool usage patterns.

a. Main Components
1. **CLI/MCP Interface**
- CLI Parsers (src/cli/index.ts & individual .cli.ts files)
- MCP Transport (stdin/stdout)
2. **Controller Layer** (src/controllers)
- Receives parsed commands or MCP payloads, orchestrates services, and applies formatters
3. **Service Layer** (src/services)
- AWS SSO Auth Core (device flow / polling)
- AWS SSO Accounts Service (list accounts & roles)
- AWS SSO Exec Service (invoke AWS CLI subprocess)
- AWS SSO EC2 Service (SSM shell exec via AWS SDK)
4. **Tool Definitions** (src/tools)
- Maps MCP tool names and parameter schemas to controller invocations
5. **Utility Modules** (src/utils)
- Config loader, caching, logging, error handling, retry, transport
6. **External Systems**
- AWS SSO Device Authorization API
- AWS IAM Identity Center (accounts & roles)
- AWS Cloud (EC2, SSM)
- AWS CLI subprocess (shell out)

b. Component Relationships and Data Flow
- User invokes `mcp-aws-sso <command>` or LLM client writes MCP JSON →
CLI Parser reads args/JSON → Controller → Service → AWS API/CLI → Service
→ Controller applies formatter → Transport (stdout/JSON) back to user.
- Controllers depend on Services and Formatter utilities.
- Services depend on Utility modules (caching, HTTP, retry).
- Tools layer injects controller methods into the MCP server registry.

c. Architectural Patterns
- Layered (CLI → Controller → Service → External)
- Dependency Injection via import boundaries
- Single Responsibility: controllers orchestrate, services implement logic, utils cross-cut
- Adapter pattern: AWS SDK & CLI calls are wrapped by service interfaces
- Plugin/Registry: tools register themselves under MCP server’s handlers

d. Key Technologies
- Node.js, TypeScript
- AWS SDK v3 (SSO, SSM) & AWS CLI subprocess
- Commander (or custom parser) for CLI
- Model Context Protocol over STDIN/STDOUT
- Jest/Mocha for tests

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI/MCP Interface
    subgraph "CLI/MCP Interface"
        CLIIndex["index.ts"]:::cli
        CLIAuthCli["aws.sso.auth.cli.ts"]:::cli
        CLIAccountsCli["aws.sso.accounts.cli.ts"]:::cli
        CLIExecCli["aws.sso.exec.cli.ts"]:::cli
        CLIEc2Cli["aws.sso.ec2.cli.ts"]:::cli
        MCPTransport["MCP Transport\n(stdin/stdout)"]:::cli
    end

    %% Controllers
    subgraph Controllers
        AuthCtrl["Auth Controller"]:::controller
        AccountsCtrl["Accounts Controller"]:::controller
        ExecCtrl["Exec Controller"]:::controller
        Ec2Ctrl["EC2 Controller"]:::controller
        AuthFmt["Auth Formatter"]:::controller
        AccountsFmt["Accounts Formatter"]:::controller
        ExecFmt["Exec Formatter"]:::controller
        Ec2Fmt["EC2 Formatter"]:::controller
        AccountsTypes["Accounts Types"]:::controller
        ExecTypes["Exec Types"]:::controller
        Ec2Types["EC2 Types"]:::controller
    end

    %% Services
    subgraph "Service Layer"
        AuthCore["SSO Auth Core Service"]:::service
        AuthHttp["SSO Auth HTTP"]:::service
        AuthOauth["SSO Auth OAuth Service"]:::service
        AuthVendor["Vendor Auth Service"]:::service
        AccountsSvc["SSO Accounts Service"]:::service
        ExecSvc["SSO Exec Service"]:::service
        Ec2Svc["SSO EC2 Service"]:::service
        TypesAws["AWS SSO Types"]:::service
        TypesVendor["Vendor SSO Types"]:::service
    end

    %% Tools
    subgraph "Tool Definitions"
        AuthTool["Auth Tool"]:::tool
        AccountsTool["Accounts Tool"]:::tool
        ExecTool["Exec Tool"]:::tool
        Ec2Tool["EC2 Tool"]:::tool
        ToolsTypes["Tools Types"]:::tool
    end

    %% Utilities
    subgraph "Utility Modules"
        Cache["Cache Util"]:::util
        AwsUtil["AWS Helpers"]:::util
        Config["Config Loader"]:::util
        Logger["Logger"]:::util
        ErrorHandler["Error Handler"]:::util
        ErrorDetect["Error Detection"]:::util
        ErrorFormat["Error Formatting"]:::util
        ErrorTypes["Error Types"]:::util
        ErrorUtil["Error Util"]:::util
        Retry["Retry Logic"]:::util
        TransportUtil["Transport Util"]:::util
        FormatterUtil["Formatter Helpers"]:::util
        Const["Constants"]:::util
        CliTest["CLI Test Util"]:::util
    end

    %% External Systems
    subgraph "External Systems"
        AWSDevice["AWS SSO Device API"]:::external
        AWSIAM["AWS IAM Identity Center"]:::external
        AWSCloud["AWS Cloud\n(EC2, SSM)"]:::external
        AWSCli["AWS CLI Subprocess"]:::external
    end

    %% Flows: CLI to Controllers
    CLIIndex --> CLIAuthCli
    CLIIndex --> CLIAccountsCli
    CLIIndex --> CLIExecCli
    CLIIndex --> CLIEc2Cli
    CLIIndex --> MCPTransport

    CLIAuthCli --> AuthCtrl
    CLIAccountsCli --> AccountsCtrl
    CLIExecCli --> ExecCtrl
    CLIEc2Cli --> Ec2Ctrl
    MCPTransport --> AuthCtrl
    MCPTransport --> AccountsCtrl
    MCPTransport --> ExecCtrl
    MCPTransport --> Ec2Ctrl

    %% Controllers to Services
    AuthCtrl --> AuthCore
    AuthCtrl --> AuthHttp
    AuthCtrl --> AuthOauth
    AuthCtrl --> AuthVendor
    AccountsCtrl --> AccountsSvc
    ExecCtrl --> ExecSvc
    Ec2Ctrl --> Ec2Svc

    %% Services to Utils
    AuthCore --> Config
    AuthCore --> Cache
    AuthCore --> Retry
    AuthCore --> AwsUtil
    AccountsSvc --> AwsUtil
    ExecSvc --> AwsUtil
    Ec2Svc --> AwsUtil

    %% Services to External
    AuthCore --> AWSDevice
    AccountsSvc --> AWSIAM
    ExecSvc --> AWSCli
    Ec2Svc --> AWSCloud

    AWSDevice --> AuthCore
    AWSIAM --> AccountsSvc
    AWSCli --> ExecSvc
    AWSCloud --> Ec2Svc

    %% Response back through Controllers
    AuthCore --> AuthCtrl
    AccountsSvc --> AccountsCtrl
    ExecSvc --> ExecCtrl
    Ec2Svc --> Ec2Ctrl

    AuthCtrl --> MCPTransport
    AccountsCtrl --> MCPTransport
    ExecCtrl --> MCPTransport
    Ec2Ctrl --> MCPTransport

    %% Tools register Controllers
    AuthTool --> AuthCtrl
    AccountsTool --> AccountsCtrl
    ExecTool --> ExecCtrl
    Ec2Tool --> Ec2Ctrl
    ToolsTypes --> AuthTool
    ToolsTypes --> AccountsTool
    ToolsTypes --> ExecTool
    ToolsTypes --> Ec2Tool
    CLIIndex --> AuthTool
    CLIIndex --> AccountsTool
    CLIIndex --> ExecTool
    CLIIndex --> Ec2Tool

    %% Click Events
    click CLIIndex "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/cli/index.ts"
    click CLIAuthCli "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/cli/aws.sso.auth.cli.ts"
    click CLIAccountsCli "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/cli/aws.sso.accounts.cli.ts"
    click CLIExecCli "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/cli/aws.sso.exec.cli.ts"
    click CLIEc2Cli "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/cli/aws.sso.ec2.cli.ts"
    click AuthCtrl "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/controllers/aws.sso.auth.controller.ts"
    click AccountsCtrl "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/controllers/aws.sso.accounts.controller.ts"
    click ExecCtrl "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/controllers/aws.sso.exec.controller.ts"
    click Ec2Ctrl "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/controllers/aws.sso.ec2.controller.ts"
    click AuthFmt "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/controllers/aws.sso.auth.formatter.ts"
    click AccountsFmt "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/controllers/aws.sso.accounts.formatter.ts"
    click ExecFmt "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/controllers/aws.sso.exec.formatter.ts"
    click Ec2Fmt "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/controllers/aws.sso.ec2.formatter.ts"
    click AccountsTypes "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/controllers/aws.sso.accounts.types.ts"
    click ExecTypes "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/controllers/aws.sso.exec.types.ts"
    click Ec2Types "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/controllers/aws.sso.ec2.types.ts"
    click AuthCore "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/services/vendor.aws.sso.auth.core.service.ts"
    click AuthHttp "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/services/vendor.aws.sso.auth.http.ts"
    click AuthOauth "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/services/vendor.aws.sso.auth.oauth.service.ts"
    click AuthVendor "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/services/vendor.aws.sso.auth.service.ts"
    click AccountsSvc "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/services/vendor.aws.sso.accounts.service.ts"
    click ExecSvc "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/services/vendor.aws.sso.exec.service.ts"
    click Ec2Svc "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/services/vendor.aws.sso.ec2.service.ts"
    click TypesAws "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/services/aws.sso.types.ts"
    click TypesVendor "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/services/vendor.aws.sso.types.ts"
    click AuthTool "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/tools/aws.sso.auth.tool.ts"
    click AccountsTool "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/tools/aws.sso.accounts.tool.ts"
    click ExecTool "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/tools/aws.sso.exec.tool.ts"
    click Ec2Tool "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/tools/aws.sso.ec2.tool.ts"
    click ToolsTypes "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/tools/aws.sso.types.ts"
    click Cache "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/utils/aws.sso.cache.util.ts"
    click AwsUtil "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/utils/aws.sso.util.ts"
    click Config "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/utils/config.util.ts"
    click Logger "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/utils/logger.util.ts"
    click ErrorHandler "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/utils/error-handler.util.ts"
    click ErrorDetect "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/utils/error-detection.util.ts"
    click ErrorFormat "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/utils/error-formatting.util.ts"
    click ErrorTypes "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/utils/error-types.util.ts"
    click ErrorUtil "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/utils/error.util.ts"
    click Retry "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/utils/retry.util.ts"
    click TransportUtil "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/utils/transport.util.ts"
    click FormatterUtil "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/utils/formatter.util.ts"
    click Const "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/utils/constants.util.ts"
    click CliTest "https://github.com/aashari/mcp-server-aws-sso/blob/main/src/utils/cli.test.util.ts"

    %% Styles
    classDef cli fill:#cce5ff,stroke:#004085,color:#004085;
    classDef controller fill:#d0e7ff,stroke:#0056b3,color:#0056b3;
    classDef service fill:#d4edda,stroke:#155724,color:#155724;
    classDef util fill:#f8f9fa,stroke:#6c757d,color:#6c757d;
    classDef external fill:#fff3cd,stroke:#856404,color:#856404;
    classDef tool fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
