# 3mdistal/css-mcp-server architecture

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

- Interactive diagram: https://gitdiagram.com/3mdistal/css-mcp-server
- Repository: https://github.com/3mdistal/css-mcp-server

## Overview

##### Project Type & Purpose
- This is a Node.js/TypeScript-based MCP (Model Context Protocol) server acting as a “CSS Tutor.”
- Its purpose is to provide an AI client (e.g., Claude desktop or Cursor) with personalized CSS feature updates through defined resources, tools, and prompts.
- Key MCP concepts demonstrated include: defining a persistent Resource (CSS knowledge store), multiple Tools (to fetch CSS updates and manage memory), and a static Prompt for guiding user interactions.

##### Analyzing the File Structure
- Top-Level Files: .env.example, .gitignore, README.md, package.json, tsconfig.json.
- Data Directory: Contains “data/memory.json” which serves as the persistent store for the CSS knowledge resource.
- src Directory: Contains the source code for the server.
- src/index.ts: Main server entry point that initializes and connects everything.
- src/prompts: Contains the definition of prompts (e.g., the “css-tutor-guidance” embedded in the code).
- src/resources: Contains the resource definition (CSS knowledge memory with read/write operations defined along with Zod validations).
- src/tools: Contains definitions of server tools (e.g., get_latest_updates, read_from_memory, write_to_memory).
- This modular organization suggests an architecture that separates concerns: core server initialization, resource management, tool functionality, and client guidance through prompts.

##### Key System Components
a. MCP Server Core:
- Entry point from “src/index.ts”: Initializes the MCP server using @modelcontextprotocol/sdk.
- It wires together prompts, resources, and tools by calling registration functions from their respective modules.
b. Resources:
- “css_knowledge_memory” (defined in src/resources/index.ts): Represents persistent state stored in data/memory.json.
- That this component handles JSON file I/O, including reading validation (using Zod) and writing back updates.
c. Tools:
- Three primary tools:
- get_latest_updates – Calls an external API (OpenRouter/Perplexity) to fetch CSS updates.
- read_from_memory – Reads from “css_knowledge_memory.”
- write_to_memory – Updates the memory file.
- These tools are linked to the server via registration in src/tools/index.ts.
d. Prompt:
- A static CSS tutor guidance prompt (defined in src/prompts/index.ts).
- It provides a set of instructions/workflow for the AI client on how to interact with the tools (e.g., order of operations, decision flow).
e. Client Interface/Transport:
- The server uses StdioServerTransport (from the SDK) for handling communication over standard input/output. This channel is critical as it forms the bridge between the AI client (e.g., Claude or Cursor) and the server.
f. External Dependencies:
- Node.js, TypeScript, and several libraries (zod, node-fetch, dotenv).
- Configuration (.env, package.json) and build process (tsconfig.json).

##### Additional Elements
- Notes about environmental configurations (e.g., use of .env for API keys) and debugging instructions using the MCP Inspector.
- Build flow steps where applicable (compilation via tsc, use of package.json build scripts).

- The core MCP server with its modular components (prompts, tools, resources)
- The interaction pathways between these components and the external entities (AI clients and API services)
- Clear, directional flow of data (user queries and responses, resource updates, API calls).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Nodes
    A["AI Client"]:::client
    B["StdioServerTransport"]:::interface
    C["MCP Server Core"]:::mcp
    D["Prompt (CSS Tutor Guidance)"]:::prompt
    E["Tools (get_latest_updates, read_from_memory, write_to_memory)"]:::tools
    F["Resource Manager (CSS Knowledge Memory)"]:::resources
    G["Persistent Storage"]:::storage
    H["OpenRouter API"]:::external

    %% Environment & External Config subgraph
    subgraph "Environment & External Config"
        I["Env File (.env.example)"]:::config
        J["Package Config (package.json)"]:::config
    end

    %% Connections (vertical layout)
    A -->|"SendsInput"| B
    B -->|"RoutesComm"| C
    C -->|"Registers"| D
    C -->|"Registers"| E
    C -->|"ConnectsTo"| F
    F -->|"Read/Write"| G
    E -->|"AccessMemory"| F
    E -->|"FetchUpdates"| H
    D -->|"Guides"| A
    I -->|"Configures"| C
    J -->|"Configures"| C

    %% Classes definitions with colors
    classDef mcp fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef prompt fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef tools fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef resources fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef storage fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef client fill:#F0E68C,stroke:#333,stroke-width:2px;
    classDef interface fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef external fill:#87CEFA,stroke:#333,stroke-width:2px;
    classDef config fill:#E6E6FA,stroke:#333,stroke-width:2px;

    %% Click Events
    click C "https://github.com/3mdistal/css-mcp-server/blob/main/src/index.ts"
    click F "https://github.com/3mdistal/css-mcp-server/blob/main/src/resources/index.ts"
    click G "https://github.com/3mdistal/css-mcp-server/blob/main/data/memory.json"
    click E "https://github.com/3mdistal/css-mcp-server/blob/main/src/tools/index.ts"
    click D "https://github.com/3mdistal/css-mcp-server/blob/main/src/prompts/index.ts"
    click I "https://github.com/3mdistal/css-mcp-server/blob/main/.env.example"
    click J "https://github.com/3mdistal/css-mcp-server/blob/main/package.json"
```
