# mohan-c0des/mcp_alexa architecture

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

- Interactive diagram: https://gitdiagram.com/mohan-c0des/mcp_alexa
- Repository: https://github.com/mohan-c0des/mcp_alexa

## Overview

Alexa+ Laptop Assistant is a local MCP server for screen interaction, safe file chores, data analysis, research, and file discovery, with simulated web and terminal clients. The main workflow is user request → client-side agent → MCP server tool → result; higher-risk screen and file changes add approval and undo stages. Analysis and research can produce PDF reports. The README documents these capabilities, while excerpts show server registration and selected tool behavior; unsampled tool internals and the separate productivity automation module are represented conservatively.

Main entry points: [`server.py`](https://github.com/mohan-c0des/mcp_alexa/blob/main/server.py) (MCP server), [`tools/analyze_data.py`](https://github.com/mohan-c0des/mcp_alexa/blob/main/tools/analyze_data.py) (Data analysis), [`tools/research_topic.py`](https://github.com/mohan-c0des/mcp_alexa/blob/main/tools/research_topic.py) (Web research), [`tools/script_writer.py`](https://github.com/mohan-c0des/mcp_alexa/blob/main/tools/script_writer.py) (Script preview and undo)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Simulated clients"]
  node_web["Web interface<br/>[App.jsx]"]
  node_webentry["Web app entry<br/>[main.jsx]"]
  node_webapi["Web API<br/>[main.py]"]
  node_terminal["Terminal agent<br/>[agent.py]"]
end

subgraph group_orchestration["MCP orchestration"]
  node_agent["Agent orchestration<br/>[main.py]"]
  node_rules["Tool guidance<br/>[instructions.py]"]
  node_mcp["MCP server<br/>[server.py]"]
end

subgraph group_screen["Screen and files"]
  node_screen["Screen control<br/>[screen_control.py]"]
  node_filesystem["File discovery<br/>[fs_tools.py]"]
end

subgraph group_analysis["Analysis and research"]
  node_analysis_tool["Data analysis<br/>[analyze_data.py]"]
  node_research["Web research<br/>[research_topic.py]"]
  node_pdf["PDF rendering<br/>[pdf_utils.py]"]
end

subgraph group_changes["Safe changes"]
  node_script["Script preview and undo<br/>[script_writer.py]"]
  node_sandbox["Script sandbox<br/>[sandbox_runner.py]"]
  node_automations["Productivity automations<br/>[automations.py]"]
end

node_user(("User"))

node_user -->|"requests"| node_web
node_user -->|"requests"| node_terminal
node_webentry -->|"renders"| node_web
node_web -->|"sends HTTP"| node_webapi
node_webapi -->|"handles chat"| node_agent
node_terminal -->|"uses agent"| node_agent
node_agent -->|"calls tools"| node_mcp
node_mcp -->|"configures with"| node_rules
node_mcp -->|"registers tools"| node_screen
node_mcp -->|"registers tool"| node_analysis_tool
node_mcp -->|"registers tool"| node_research
node_mcp -->|"registers tools"| node_script
node_screen -->|"finds paths"| node_filesystem
node_script -->|"finds folders"| node_filesystem
node_script -.->|"runs scripts"| node_sandbox
node_research -->|"analyzes findings"| node_analysis_tool
node_analysis_tool -->|"renders report"| node_pdf
node_research -.->|"writes report"| node_pdf
node_automations -.->|"uses analysis"| node_analysis_tool

click node_web "https://github.com/mohan-c0des/mcp_alexa/blob/main/client/Simulated_frontend/src/App.jsx"
click node_webentry "https://github.com/mohan-c0des/mcp_alexa/blob/main/client/Simulated_frontend/src/main.jsx"
click node_webapi "https://github.com/mohan-c0des/mcp_alexa/blob/main/client/Simulated_backend/main.py"
click node_terminal "https://github.com/mohan-c0des/mcp_alexa/blob/main/client/Simulated_backend/agent.py"
click node_agent "https://github.com/mohan-c0des/mcp_alexa/blob/main/client/Simulated_backend/main.py"
click node_rules "https://github.com/mohan-c0des/mcp_alexa/blob/main/instructions.py"
click node_mcp "https://github.com/mohan-c0des/mcp_alexa/blob/main/server.py"
click node_screen "https://github.com/mohan-c0des/mcp_alexa/blob/main/tools/screen_control.py"
click node_filesystem "https://github.com/mohan-c0des/mcp_alexa/blob/main/tools/fs_tools.py"
click node_script "https://github.com/mohan-c0des/mcp_alexa/blob/main/tools/script_writer.py"
click node_sandbox "https://github.com/mohan-c0des/mcp_alexa/blob/main/tools/sandbox_runner.py"
click node_analysis_tool "https://github.com/mohan-c0des/mcp_alexa/blob/main/tools/analyze_data.py"
click node_research "https://github.com/mohan-c0des/mcp_alexa/blob/main/tools/research_topic.py"
click node_pdf "https://github.com/mohan-c0des/mcp_alexa/blob/main/tools/pdf_utils.py"
click node_automations "https://github.com/mohan-c0des/mcp_alexa/blob/main/extra_productivity/automations.py"

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_web,node_webentry,node_webapi,node_terminal,node_user toneBlue
class node_agent,node_rules,node_mcp toneAmber
class node_screen,node_filesystem toneMint
class node_analysis_tool,node_research,node_pdf toneRose
class node_script,node_sandbox,node_automations toneIndigo
```

## Components

### Simulated clients

- [Web interface](https://github.com/mohan-c0des/mcp_alexa/blob/main/client/Simulated_frontend/src/App.jsx): `client/Simulated_frontend/src/App.jsx`
- [Web app entry](https://github.com/mohan-c0des/mcp_alexa/blob/main/client/Simulated_frontend/src/main.jsx): `client/Simulated_frontend/src/main.jsx`
- [Web API](https://github.com/mohan-c0des/mcp_alexa/blob/main/client/Simulated_backend/main.py): `client/Simulated_backend/main.py`
- [Terminal agent](https://github.com/mohan-c0des/mcp_alexa/blob/main/client/Simulated_backend/agent.py): `client/Simulated_backend/agent.py`

### MCP orchestration

- [Agent orchestration](https://github.com/mohan-c0des/mcp_alexa/blob/main/client/Simulated_backend/main.py): `client/Simulated_backend/main.py`
- [Tool guidance](https://github.com/mohan-c0des/mcp_alexa/blob/main/instructions.py): `instructions.py`
- [MCP server](https://github.com/mohan-c0des/mcp_alexa/blob/main/server.py): `server.py`

### Screen and files

- [Screen control](https://github.com/mohan-c0des/mcp_alexa/blob/main/tools/screen_control.py): `tools/screen_control.py`
- [File discovery](https://github.com/mohan-c0des/mcp_alexa/blob/main/tools/fs_tools.py): `tools/fs_tools.py`

### Analysis and research

- [Data analysis](https://github.com/mohan-c0des/mcp_alexa/blob/main/tools/analyze_data.py): `tools/analyze_data.py`
- [Web research](https://github.com/mohan-c0des/mcp_alexa/blob/main/tools/research_topic.py): `tools/research_topic.py`
- [PDF rendering](https://github.com/mohan-c0des/mcp_alexa/blob/main/tools/pdf_utils.py): `tools/pdf_utils.py`

### Safe changes

- [Script preview and undo](https://github.com/mohan-c0des/mcp_alexa/blob/main/tools/script_writer.py): `tools/script_writer.py`
- [Script sandbox](https://github.com/mohan-c0des/mcp_alexa/blob/main/tools/sandbox_runner.py): `tools/sandbox_runner.py`
- [Productivity automations](https://github.com/mohan-c0des/mcp_alexa/blob/main/extra_productivity/automations.py): `extra_productivity/automations.py`

### Other components

- **User**

## Connections

- User → Web interface: requests (evidence: `README.md`)
- User → Terminal agent: requests (evidence: `README.md`)
- Web app entry → Web interface: renders (evidence: `client/Simulated_frontend/src/main.jsx`)
- Web interface → Web API: sends HTTP (evidence: `README.md`)
- Web API → Agent orchestration: handles chat (evidence: `client/Simulated_backend/main.py`)
- Terminal agent → Agent orchestration: uses agent (evidence: `README.md`)
- Agent orchestration → MCP server: calls tools (evidence: `client/Simulated_backend/main.py`)
- MCP server → Tool guidance: configures with (evidence: `server.py`)
- MCP server → Screen control: registers tools (evidence: `server.py`)
- MCP server → Data analysis: registers tool (evidence: `server.py`)
- MCP server → Web research: registers tool (evidence: `server.py`)
- MCP server → Script preview and undo: registers tools (evidence: `server.py`)
- Screen control → File discovery: finds paths (evidence: `tools/screen_control.py`)
- Script preview and undo → File discovery: finds folders (evidence: `tools/script_writer.py`)
- Script preview and undo → Script sandbox: runs scripts
- Web research → Data analysis: analyzes findings (evidence: `tools/research_topic.py`)
- Data analysis → PDF rendering: renders report (evidence: `tools/analyze_data.py`)
- Web research → PDF rendering: writes report (evidence: `tools/research_topic.py`)
- Productivity automations → Data analysis: uses analysis (evidence: `extra_productivity/automations.py`)
