HackerNews MCP Server

# Implementation Plan: HackerNews MCP Server **Branch**: `001-hackernews-mcp-server` | **Date**: 2025-10-12 | **Spec**: [spec.md](./spec.md) **Input**: Feature specification from `/specs/001-hackernews-mcp-server/spec.md` **Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow. ## Summary Build a Model Context Protocol (MCP) server that provides programmatic access to Hacker News content via the HN Algolia API (https://hn.algolia.com/api). The server exposes MCP tools for searching stories/comments, retrieving front page content, accessing specific items and user profiles, and advanced filtering with pagination. All tools communicate via stdio transport following MCP conventions, enabling AI assistants to interact with HN content in real-time while respecting rate limits (10,000 req/hr). **Technical Approach**: TypeScript MCP server using @modelcontextprotocol/sdk with stdio transport, organized with one tool per file for maintainability, comprehensive test coverage (unit + integration against live API), and Biome for code quality. ## Technical Context **Language/Version**: TypeScript 5.7+ with Node.js 20 LTS (strict mode enabled) **Primary Dependencies**: - @modelcontextprotocol/sdk (latest stable) - MCP server framework - zod (latest) - Schema validation for tool inputs/outputs - Node.js built-in `fetch` - HTTP client for HN Algolia API **Storage**: N/A (read-only API client, no persistence) **Testing**: Vitest for unit tests, integration tests against live HN Algolia API **Target Platform**: Cross-platform (Linux, macOS, Windows) via Node.js, stdio transport **Project Type**: Single project - MCP server with modular tool structure **Performance Goals**: - <2s response time for search queries (95th percentile) - <3s for full story retrieval with nested comments - Handle 1000+ requests/hour without degradation **Constraints**: - Must respect HN Algolia API rate limit (10,000 req/hr per IP) - No external persistence or caching (stateless server) - Stdio transport only (no HTTP/SSE) - Tools must be independently testable **Scale/Scope**: - ~10-15 MCP tools covering all HN API capabilities - Support for all HN content types (stories, comments, polls, users) - Comprehensive error handling and rate limit tracking ## Constitution Check *GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* ### Code Quality First - [x] Zero technical debt policy understood and planned for - [x] Type safety approach defined (TypeScript strict mode enabled) - [x] Linting and formatting tools configured (Biome for TS/JS) - [x] Documentation standards defined for this feature (JSDoc for all tools, README, API docs) - [x] Existing solutions evaluated before planning custom implementations (using @modelcontextprotocol/sdk, not building from scratch) ### Test-First Development - [x] TDD approach planned: Tests → Approval → Fail → Implement → Pass → Refactor - [x] Test types identified: Unit (tool logic), Integration (live HN API), Contract (MCP schemas) - [x] 80% coverage target achievable for this feature (tools are independently testable) - [x] Test infrastructure/framework selected (Vitest with coverage reporting) ### User Experience Consistency - [x] MCP tool naming follows conventions (verb-based: search_stories, get_story, get_user, etc.) - [x] Parameter design consistent with existing tools (query, tags, filters follow patterns) - [x] Error messages are human-readable and actionable (include suggestions, context) - [x] Response formats consistent with existing patterns (JSON with metadata, pagination info) ### Latest Dependencies Always - [x] **Context7 MCP consultation planned** for all external library integrations (retrieved MCP SDK docs) - [x] All dependencies will use latest stable versions (verified via npm) - [x] Security update process understood (npm audit in CI pipeline) - [x] Version pinning strategy defined (exact versions in package-lock.json) ### Documentation-Driven Development - [x] **Context7 retrieval planned** before implementing library features (MCP SDK patterns retrieved) - [x] Feature spec (spec.md) created and approved before coding (completed) - [x] API documentation approach defined (JSDoc + generated tool reference docs) - [x] Quickstart guide planned (will be created in Phase 1) ### Integration Testing Discipline - [x] MCP tool integration tests planned against real Hacker News API (with rate limit awareness) - [x] Contract validation approach defined (Zod schemas for all inputs/outputs) - [x] Error scenario coverage planned (network failures, rate limits, malformed responses, 404s) - [x] Performance baseline targets set (<2s search, <3s full story retrieval) ### Observability & Debuggability - [x] Structured logging approach defined (JSON logging with correlation IDs via pino or similar) - [x] Error context strategy planned (stack traces, request params, API response details) - [x] Performance metrics to track identified (response times, rate limit consumption) - [x] Debug mode approach defined (verbose logging via DEBUG environment variable) ## Project Structure ### Documentation (this feature) ``` specs/001-hackernews-mcp-server/ ├── plan.md # This file (/speckit.plan command output) ├── research.md # Phase 0 output (/speckit.plan command) ├── data-model.md # Phase 1 output (/speckit.plan command) ├── quickstart.md # Phase 1 output (/speckit.plan command) ├── contracts/ # Phase 1 output (/speckit.plan command) │ └── mcp-tools.json # MCP tool schemas └── tasks.md # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan) ``` ### Source Code (repository root) ``` ├── src/ │ ├── index.ts # Main server entry point, stdio transport setup │ ├── server.ts # McpServer initialization and configuration │ ├── tools/ # MCP tools (one file per tool) │ │ ├── search-stories.ts # Search stories by relevance │ │ ├── search-by-date.ts # Search stories/comments by date │ │ ├── get-story.ts # Retrieve specific story with comments │ │ ├── get-user.ts # Retrieve user profile │ │ ├── get-front-page.ts # Get current front page stories │ │ ├── get-latest-stories.ts # Get latest submissions │ │ ├── get-ask-hn.ts # Get Ask HN posts │ │ ├── get-show-hn.ts # Get Show HN posts │ │ └── search-comments.ts # Search comments │ ├── lib/ # Shared utilities │ │ ├── hn-client.ts # HN Algolia API client wrapper │ │ ├── rate-limiter.ts # Rate limit tracking and enforcement │ │ ├── logger.ts # Structured logging utility │ │ ├── errors.ts # Custom error types │ │ └── validators.ts # Zod schemas for validation │ └── types/ # TypeScript type definitions │ ├── hn-api.ts # HN API response types │ └── mcp.ts # MCP-specific types ├── tests/ │ ├── unit/ # Unit tests for individual functions │ │ ├── tools/ # Tool logic tests │ │ └── lib/ # Library function tests │ ├── integration/ # Integration tests against live HN API │ │ ├── tools/ # End-to-end tool tests │ │ └── setup.ts # Test setup and fixtures │ └── contract/ # MCP contract validation tests │ └── schemas.test.ts # Verify tool schemas match MCP spec ├── docs/ │ ├── API.md # Tool reference documentation │ └── DEVELOPMENT.md # Development guide ├── README.md # User-facing documentation ├── package.json # Dependencies and scripts ├── tsconfig.json # TypeScript configuration (strict mode) ├── biome.json # Biome linting/formatting config ├── vitest.config.ts # Vitest test configuration └── .github/ └── workflows/ └── ci.yml # CI pipeline (lint, test, build) ``` **Structure Decision**: Single project structure selected as this is a standalone MCP server with no frontend/backend separation. Tools are organized one-per-file in `/src/tools/` for independent development, testing, and maintenance. Shared API client and utilities in `/src/lib/` promote code reuse. This structure aligns with MCP SDK best practices and enables easy addition of new tools. ## Complexity Tracking *No constitution violations - all checks passed. No justifications needed.* **Estimated Complexity**: **Medium** (5-7 days for single developer) ### Breakdown by Phase **Phase 0 - Research** (1 day) ✅ COMPLETE - Technology evaluation (MCP SDK, HTTP client, logging, testing) - API exploration and contract definition - Architecture decisions documented **Phase 1 - Design & Contracts** (1 day) ✅ COMPLETE - Data models defined (6 entities) - MCP tool contracts specified (9 tools) - Quickstart guide created - Agent context updated **Phase 2 - Implementation** (3 days) - Core infrastructure (API client, error handling, rate limiting): 1 day - Tool implementation (9 tools, one per file): 1.5 days - Testing (unit + integration + contract): 0.5 days **Phase 3 - Documentation & Polish** (1 day) - README.md and API documentation - CI/CD pipeline configuration - Final constitution compliance check ### Risk Factors **LOW RISK**: - Simple read-only API integration - Well-documented MCP SDK with examples - No authentication or complex state management - Proven technology stack (TypeScript + Node.js) **MEDIUM RISK**: - Rate limit handling requires careful tracking - Nested comment tree parsing may have edge cases - Integration tests depend on live API availability **MITIGATION STRATEGIES**: - In-memory rate limiter with hourly reset - Robust error handling for malformed API responses - Mock integration tests + periodic live API validation - Comprehensive logging for debugging --- ## Next Steps **Planning Complete** ✅ This implementation plan is now ready for task generation. Run: ```bash /speckit.tasks ``` This will generate `tasks.md` with: - Detailed task breakdown for all 3 phases - Dependency tracking between tasks - Constitution compliance checkpoints - Testing requirements per task **Artifacts Created**: - ✅ `plan.md` - This implementation plan - ✅ `research.md` - Technology research and decisions - ✅ `data-model.md` - Entity definitions and TypeScript types - ✅ `contracts/mcp-tools.json` - MCP tool schema contracts - ✅ `quickstart.md` - 5-minute getting started guide - ✅ `.github/copilot-instructions.md` - Agent context (auto-updated)