How traves-theberge/hackernews-mcp-typescript works
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