# hellokaton/unsplash-mcp-server architecture

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

- Interactive diagram: https://gitdiagram.com/hellokaton/unsplash-mcp-server
- Repository: https://github.com/hellokaton/unsplash-mcp-server

## Overview

##### Project Type and Purpose
- This project is a lightweight server application written in Python. It is designed to integrate Unsplash’s image library search capabilities and act as an MCP (Multi-Client Protocol) server. Its primary function is to receive image search requests (from various IDE clients like Cursor, Windsurf, and Cline) and then interface with Unsplash’s API using a provided access key.

##### File Structure
- Top-level files like server.py indicate that the core server logic is implemented in a single Python file.
- The presence of Dockerfile, pyproject.toml, and uv.lock suggests containerization and dependency management are part of the deployment.
- Additional files (smithery.yaml, README_*, LICENSE) indicate configuration for Smithery and project metadata.
- The screenshots folder and README files provide demonstration and usage guidelines for integrating with external clients.

##### Core Components
a. Client/IDE Integration Layer:
b. MCP Server Core:
- Unsplash MCP Server (implemented in server.py) as the central middleware. Indicate that it manages incoming search requests and forwards them appropriately.
- As the backend component, outline that this server might internally implement routing, controller logic, and error handling.
c. External Unsplash API:
- A component for the Unsplash API. This external system is accessed via HTTP calls from the server for image search functionality.
d. Configuration and Deployment:
- Docker container (via Dockerfile) and Python dependency management (pyproject.toml, uv.lock).
- Smithery.yaml configuration file which is used by the Smithery platform for integration and deployment purposes.

##### Relationships and Data Flow
- Additionally, indicate configuration flows (such as environment variables like UNSPLASH_ACCESS_KEY) from the deployment/initialization phase into the server.

##### Architectural Patterns/Design Principles to Highlight
- Separation of concerns: the server acts solely as an integration and routing layer while the unsplash API remains an external dependency.
- Mention that the system is designed for simplicity and modular integration via command line and containerization.
- If applicable, note that the lightweight single-file server structure is advantageous for fast iteration and ease of deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "IDE Clients"
        Cursor["Cursor"]:::client
        Windsurf["Windsurf"]:::client
        Cline["Cline"]:::client
    end

    subgraph "MCP Server Core"
        Server["Unsplash MCP Server"]:::server
    end

    subgraph "External Service"
        External["Unsplash API Service"]:::external
    end

    subgraph "Deployment/Configuration"
        Deploy["Deployment/Configuration"]:::config
        Docker["Dockerfile"]:::config
        PyDep["pyproject.toml"]:::config
        UV["uv.lock"]:::config
        Smithery["smithery.yaml"]:::config
        Docker --> Deploy
        PyDep --> Deploy
        UV --> Deploy
        Smithery --> Deploy
    end

    Cursor -->|"SearchQuerySent"| Server
    Windsurf -->|"SearchQuerySent"| Server
    Cline -->|"SearchQuerySent"| Server

    Server -->|"HTTPRequest"| External
    External -->|"ResultsReturned"| Server

    Deploy -->|"APIKeyInjection"| Server

    click Cursor "https://github.com/hellokaton/unsplash-mcp-server/blob/main/README.md"
    click Windsurf "https://github.com/hellokaton/unsplash-mcp-server/blob/main/README_zh.md"
    click Cline "https://github.com/hellokaton/unsplash-mcp-server/blob/main/README.md"
    click Server "https://github.com/hellokaton/unsplash-mcp-server/blob/main/server.py"
    click Docker "https://github.com/hellokaton/unsplash-mcp-server/tree/main/Dockerfile"
    click PyDep "https://github.com/hellokaton/unsplash-mcp-server/blob/main/pyproject.toml"
    click UV "https://github.com/hellokaton/unsplash-mcp-server/blob/main/uv.lock"
    click Smithery "https://github.com/hellokaton/unsplash-mcp-server/blob/main/smithery.yaml"

    classDef client fill:#f9e79f,stroke:#000,stroke-width:1px;
    classDef server fill:#aed6f1,stroke:#000,stroke-width:1px;
    classDef external fill:#f5b7b1,stroke:#000,stroke-width:1px;
    classDef config fill:#abebc6,stroke:#000,stroke-width:1px;
```
