# traves-theberge/hackernews-mcp-typescript architecture

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

- Interactive diagram: https://gitdiagram.com/traves-theberge/hackernews-mcp-typescript
- Repository: https://github.com/traves-theberge/hackernews-mcp-typescript

## Overview

##### Project Type & Purpose
- This is a single‐service Node.js/TypeScript MCP server (no UI) that implements five “tools” (search_posts, get_post, search_user, search_trending, search_comments).
- It sits between an MCP-aware client (e.g., Cursor) and the HackerNews REST API, augmenting raw data with caching, analytics, and structured responses.

##### File Structure
- Top‐level entrypoint:
– Dockerfile / docker-compose.yml / DEPLOYMENT.md → containerized deployment
– src/index.ts → server bootstrap (registers MCP handlers)
– src/api/client.ts → HTTP client for HN API
– src/tools/*.ts → individual MCP “tool” implementations
– src/utils/cache.ts → three‐tier in-memory LRU cache
– src/prompts & src/resources → context builders and resource mappers for MCP
– src/config.ts & env.example → configuration layer
- Tests (jest.config.js) cover each layer.

##### Key Architectural Insights from README
- Three-tier caching (items, users, story lists) with TTL & LRU eviction
- Batch operations, retry logic, rate limiting in API client
- Tool-based design: each MCP command is a first-class module
- Environment‐driven configuration, Docker support

##### Main Components & Relationships
A. External Actors & Services
1. MCP-Capable Client (Cursor)
2. HackerNews REST API (hackernews://… endpoints)
B. Internal Service (HackerNews MCP Server)
1. Transport Layer
– MCP protocol server listening on STDIO or TCP (via src/index.ts)
2. Controller/Tools Layer
– Modules under src/tools/*.ts register handlers for each tool
3. Business Logic & Data Layer
– API Client (src/api/client.ts) with HTTP, rate limiting, retries
– Cache Layer (src/utils/cache.ts): three caches in memory
– Resource & Prompt Builders (src/resources & src/prompts)
4. Cross-Cutting Concerns
– Configuration (src/config.ts reading env)
– Logging (src/utils/logger.ts)
– Type definitions (src/types/*.ts)
C. Infrastructure & Deployment
– Docker container, docker-compose, env files
– CI/CD implied by tests, lint, build scripts

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Actor
    Client["MCP Client (Cursor)"]:::external

    %% HackerNews MCP Server Layers
    subgraph "HackerNews MCP Server"
        direction TB

        Transport["Transport Layer\nMCP Server"]:::layer1
        Tools["Tools Controllers\n(src/tools/*.ts)"]:::layer2
        subgraph "Business / Data Layer"
            direction TB
            Cache["Cache Layer\n(items/users/lists)"]:::layer3
            APIClient["API Client\n(src/api/client.ts)"]:::layer3
        end
        subgraph "Builders Layer"
            direction TB
            Resource["Resource Builders\n(src/resources/*.ts)"]:::layer4
            Prompt["Prompt Builders\n(src/prompts/*.ts)"]:::layer4
        end
    end

    %% External API
    ExternalAPI["HackerNews REST API"]:::external

    %% Cross-Cutting Concerns
    subgraph "Cross-Cutting Concerns"
        direction TB
        Config["Configuration\n(src/config.ts)"]:::crosscut
        Logger["Logging Utility\n(src/utils/logger.ts)"]:::crosscut
        Types["Type Definitions\n(src/types/hackernews.ts)"]:::crosscut
    end

    %% Infrastructure
    Infra["Deployment & Infrastructure\n(Dockerfile,\n docker-compose.yml,\n DEPLOYMENT.md)"]:::infra

    %% Flows
    Client -->|"MCP request"| Transport
    Transport -->|"invoke tool handler"| Tools
    Tools -->|"cache lookup"| Cache
    Cache -->|"cache miss"| APIClient
    APIClient -->|"HTTP GET"| ExternalAPI
    ExternalAPI -->|"response"| APIClient
    APIClient -->|"store result"| Cache
    Tools -->|"build resource"| Resource
    Resource -->|"build prompt"| Prompt
    Prompt -->|"MCP response"| Transport

    %% Click Events
    click Transport "https://github.com/traves-theberge/hackernews-mcp-typescript/blob/main/src/index.ts"
    click Tools "https://github.com/traves-theberge/hackernews-mcp-typescript/blob/main/src/tools/index.ts"
    click APIClient "https://github.com/traves-theberge/hackernews-mcp-typescript/blob/main/src/api/client.ts"
    click Cache "https://github.com/traves-theberge/hackernews-mcp-typescript/blob/main/src/utils/cache.ts"
    click Resource "https://github.com/traves-theberge/hackernews-mcp-typescript/blob/main/src/resources/index.ts"
    click Prompt "https://github.com/traves-theberge/hackernews-mcp-typescript/blob/main/src/prompts/index.ts"
    click Config "https://github.com/traves-theberge/hackernews-mcp-typescript/blob/main/src/config.ts"
    click Logger "https://github.com/traves-theberge/hackernews-mcp-typescript/blob/main/src/utils/logger.ts"
    click Types "https://github.com/traves-theberge/hackernews-mcp-typescript/blob/main/src/types/hackernews.ts"

    %% Styles
    classDef external fill:#FFE5B4,stroke:#E69A00;
    classDef layer1 fill:#B3CDE3,stroke:#357ABD;
    classDef layer2 fill:#B3CDE3,stroke:#357ABD;
    classDef layer3 fill:#C7E9C0,stroke:#28A745;
    classDef layer4 fill:#B3CDE3,stroke:#357ABD;
    classDef crosscut fill:#EAEAEA,stroke:#999999,stroke-dasharray: 2 2;
    classDef infra fill:#DDDDDD,stroke:#666666;
```
