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:

.venv\Scripts\Activate.ps1

Windows CMD:

.venv\Scripts\activate.bat

Bash / Git Bash:

source .venv/bin/activate

3. Configure API Key

Create a .env file in the project root:

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:

python test_app.py

5. Running the MCP Server

To execute the server via the stdio transport protocol:

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):

{
  "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:

   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.