# Clean Architecture LangGraph MCP Server

A Model Context Protocol (MCP) server written in Python from scratch using **LangGraph** for orchestration, structured around the principles of **Clean Architecture**.

---

## 🏛️ Architecture Overview

This project is divided into four concentric layers to enforce the **Dependency Inversion Principle** (outer layers can import inner layers, but inner layers must NEVER know about outer layers):

```
[Domain] <-- [Use Cases] <-- [Adapters] <-- [Frameworks]
```

1. **Domain (`src/domain/`)**: Contains core entity dataclasses (`Message`, `ConversationState`). Entirely framework-free.
2. **Use Cases (`src/usecases/`)**: Application business rules (`RunAgentUseCase`) and abstract gateway interfaces (`AgentGateway`, `HistoryRepository`).
3. **Interface Adapters (`src/adapters/`)**: Gateway implementations (`InMemoryHistoryRepository`) and interface bindings for external communication (`McpController`).
4. **Frameworks & Drivers (`src/frameworks/`)**: External libraries and composition root (`LangGraphAgent`, `config.py`, `main.py`).

---

## 🚀 Getting Started

### 1. Requirements
*   Python >= 3.13

### 2. Set Up Virtual Environment (Already Done)
The virtual environment has already been created in this folder at `.venv`. To activate it:

**Windows PowerShell:**
```powershell
.venv\Scripts\Activate.ps1
```

**Windows CMD:**
```cmd
.venv\Scripts\activate.bat
```

**Bash / Git Bash:**
```bash
source .venv/bin/activate
```

### 3. Configure API Key
Create a `.env` file in the project root:
```env
OPENAI_API_KEY=your_openai_api_key_here
```
*Note: If no API key is specified, the application will fallback to **Simulation Mode**, which lets you test the execution pipeline locally without incurring cost or requiring keys.*

### 4. Running the Verification Test
Verify the layers and data flow run properly inside the virtual environment:
```bash
python test_app.py
```

### 5. Running the MCP Server
To execute the server via the `stdio` transport protocol:
```bash
python src/main.py
```
*Note: Normal logs are written to `sys.stderr` to avoid corrupting the protocol communication channel on `stdout`.*

---

## 🔌 Connecting to Host Clients

### Claude Desktop
Add this server to your Claude Desktop config file (located at `%APPDATA%\Claude\claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "langgraph-clean-arch": {
      "command": "C:\\Users\\faria\\.gemini\\antigravity-ide\\scratch\\mcp-langgraph-clean-arch\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\faria\\.gemini\\antigravity-ide\\scratch\\mcp-langgraph-clean-arch\\src\\main.py"]
    }
  }
}
```

### Cursor
Go to **Settings > Features > MCP**:
1. Click **+ Add New MCP Server**.
2. Set **Name** to `langgraph-clean-arch`.
3. Set **Type** to `command`.
4. Set **Command** to:
   ```cmd
   C:\Users\faria\.gemini\antigravity-ide\scratch\mcp-langgraph-clean-arch\.venv\Scripts\python.exe C:\Users\faria\.gemini\antigravity-ide\scratch\mcp-langgraph-clean-arch\src\main.py
   ```
5. Click **Save** and verify the status shows active green.