HackerNews MCP Server

--- description: "Task list for HackerNews MCP Server implementation" --- # Tasks: HackerNews MCP Server **Input**: Design documents from `/specs/001-hn-mcp-server/` **Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/ **Tests**: Test tasks are NOT included per feature specification (no TDD requirement mentioned) **Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story. ## Format: `[ID] [P?] [Story] Description` - **[P]**: Can run in parallel (different files, no dependencies) - **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3) - Include exact file paths in descriptions ## Path Conventions - **Single project**: `src/`, `tests/` at repository root - Paths follow TypeScript/Node.js project structure with ESM modules --- ## Phase 1: Setup (Shared Infrastructure) **Purpose**: Project initialization and basic structure - [X] T001 Create project directory structure (src/, tests/, dist/) - [X] T002 Initialize Node.js project with package.json (TypeScript 5.x, Node 22+) - [X] T003 [P] Install core dependencies (@modelcontextprotocol/sdk, zod, zod-to-json-schema) - [X] T004 [P] Install dev dependencies (typescript, @types/node, vitest, @vitest/coverage-v8) - [X] T005 [P] Configure TypeScript with tsconfig.json (strict mode, ES2022, Node16 modules) - [X] T006 [P] Configure Biome with biome.json (linting + formatting) - [X] T007 [P] Configure Vitest with vitest.config.ts - [X] T008 [P] Create .gitignore for node_modules, dist, coverage - [X] T009 [P] Add npm scripts to package.json (build, test, lint, format, dev) - [X] T010 [P] Create README.md with installation and usage instructions --- ## Phase 2: Foundational (Blocking Prerequisites) **Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented **⚠️ CRITICAL**: No user story work can begin until this phase is complete - [X] T011 Create type definitions in src/types/index.ts (HackerNewsPost, HackerNewsUser, SearchQuery, SearchResult) - [X] T012 Create Zod schemas in src/schemas/index.ts (HackerNewsPostSchema, HackerNewsUserSchema, SearchQuerySchema, SearchResultSchema) - [X] T013 Create HackerNews API client in src/services/hn-api-client.ts (base HTTP client, error handling, rate limit tracking) - [X] T014 Create utility functions in src/utils/index.ts (date conversion, URL building, filter formatting) - [X] T015 Create error types in src/errors/index.ts (APIError, ValidationError, RateLimitError, NotFoundError) - [X] T016 Create MCP server setup in src/index.ts (Server instance, stdio transport, request handlers skeleton) - [X] T017 [P] Create tool registry in src/tools/index.ts (tool list, registration helpers) **Checkpoint**: Foundation ready - user story implementation can now begin in parallel --- ## Phase 3: User Story 1 - Search HackerNews Posts (Priority: P1) 🎯 MVP **Goal**: Enable keyword-based search with multiple filters (content type, author, points, comments, date) **Independent Test**: Search for "Python" with minPoints=50, verify results contain matching posts with correct metadata ### Implementation for User Story 1 - [X] T018 [US1] Create SearchPostsInputSchema in src/schemas/tools/search-posts.ts with all filter parameters - [X] T019 [US1] Implement buildSearchParams function in src/services/search-service.ts (converts input to HN API parameters) - [X] T020 [US1] Implement searchPosts API method in src/services/hn-api-client.ts (calls /search or /search_by_date endpoint) - [X] T021 [US1] Implement search_posts tool handler in src/tools/search-posts.ts (validation, service call, response formatting) - [X] T022 [US1] Register search_posts tool in src/index.ts tool list handler - [X] T023 [US1] Register search_posts tool in src/index.ts call tool handler - [X] T024 [US1] Add input validation for search parameters (max query length, page limits, numeric filters format) - [X] T025 [US1] Add error handling for no results, invalid filters, API errors - [X] T026 [US1] Add pagination metadata to response (totalResults, currentPage, totalPages, resultsPerPage) **Checkpoint**: At this point, User Story 1 should be fully functional - can search with all filters and get paginated results --- ## Phase 4: User Story 2 - View Front Page Content (Priority: P2) **Goal**: Retrieve current front page posts matching HackerNews trending content **Independent Test**: Request front page, verify returned posts match what's on news.ycombinator.com front page ### Implementation for User Story 2 - [X] T027 [US2] Create GetFrontPageInputSchema in src/schemas/tools/get-front-page.ts (page, hitsPerPage) - [X] T028 [US2] Implement getFrontPage API method in src/services/hn-api-client.ts (calls /search with front_page tag) - [X] T029 [US2] Implement get_front_page tool handler in src/tools/get-front-page.ts (validation, service call, response formatting) - [X] T030 [US2] Register get_front_page tool in src/index.ts tool list handler - [X] T031 [US2] Register get_front_page tool in src/index.ts call tool handler - [X] T032 [US2] Add pagination support (default 30 items per page, max 30) - [X] T033 [US2] Add error handling for pagination errors, API failures **Checkpoint**: At this point, User Stories 1 AND 2 should both work independently --- ## Phase 5: User Story 3 - Retrieve Post Details (Priority: P3) **Goal**: Get complete post data including full comment tree with nested structure **Independent Test**: Request known post ID, verify full details returned including nested comments in correct hierarchy ### Implementation for User Story 3 - [X] T034 [US3] Create GetPostInputSchema in src/schemas/tools/get-post.ts (postId required) - [X] T035 [US3] Implement getPostById API method in src/services/hn-api-client.ts (calls /items/:id endpoint) - [X] T036 [US3] Implement buildCommentTree function in src/services/comment-service.ts (recursively constructs nested structure) - [X] T037 [US3] Implement get_post tool handler in src/tools/get-post.ts (validation, service call, tree building, response formatting) - [X] T038 [US3] Register get_post tool in src/index.ts tool list handler - [X] T039 [US3] Register get_post tool in src/index.ts call tool handler - [X] T040 [US3] Add validation for post ID format (numeric string) - [X] T041 [US3] Add error handling for non-existent post IDs (404), deleted posts - [X] T042 [US3] Add comment count and nesting depth metadata to response **Checkpoint**: At this point, User Stories 1, 2, AND 3 should all work independently --- ## Phase 6: User Story 4 - Get User Information (Priority: P4) **Goal**: Retrieve user profile with karma, about text, account creation date **Independent Test**: Request known username (e.g., "pg"), verify profile data returned accurately ### Implementation for User Story 4 - [X] T043 [US4] Create GetUserInputSchema in src/schemas/tools/get-user.ts (username required, 1-15 chars) - [X] T044 [US4] Implement getUserByUsername API method in src/services/hn-api-client.ts (calls /users/:username endpoint) - [X] T045 [US4] Implement get_user tool handler in src/tools/get-user.ts (validation, service call, response formatting with computed fields) - [X] T046 [US4] Register get_user tool in src/index.ts tool list handler - [X] T047 [US4] Register get_user tool in src/index.ts call tool handler - [X] T048 [US4] Add computed fields (account age in years, karma per year) - [X] T049 [US4] Add validation for username format (1-15 chars, case-sensitive) - [X] T050 [US4] Add error handling for non-existent usernames (404) **Checkpoint**: All core user stories should now be independently functional --- ## Phase 7: User Story 5 - Advanced Search Filtering (Priority: P5) **Goal**: Enable complex queries with combined filters (author AND content type AND date range, OR logic for types) **Independent Test**: Combine author + story type + minPoints filters, verify only matching results returned ### Implementation for User Story 5 - [X] T051 [US5] Extend buildSearchParams in src/services/search-service.ts to support OR logic for tags - [X] T052 [US5] Add support for multiple author filters in src/services/search-service.ts (if needed by API) - [X] T053 [US5] Implement date range to Unix timestamp conversion in src/utils/date-utils.ts - [X] T054 [US5] Add validation for filter combinations in src/tools/search-posts.ts (ensure logical constraints) - [X] T055 [US5] Update search_posts tool to document OR logic usage in tool description - [X] T056 [US5] Add examples of complex filter combinations to error messages/documentation **Checkpoint**: All user stories including advanced filtering should work independently --- ## Phase 8: Polish & Cross-Cutting Concerns **Purpose**: Improvements that affect multiple user stories - [X] T057 [P] Add comprehensive JSDoc comments to all public functions in src/ - [X] T058 [P] Create integration tests in tests/integration/ (one per tool, mocking HN API) - [X] T059 [P] Create contract tests in tests/contract/ (validate HN API response structure) - [X] T060 [P] Add unit tests for utility functions in tests/unit/ - [X] T061 [P] Update README.md with complete API documentation and examples - [X] T062 [P] Create quickstart examples in examples/ directory matching quickstart.md scenarios - [X] T063 [P] Add rate limiting visualization (remaining requests) to tool responses (optional enhancement) - [X] T064 [P] Add logging with debug levels for troubleshooting - [X] T065 [P] Run Biome linting and fix all issues - [X] T066 [P] Run Biome formatting on all source files - [X] T067 [P] Validate package.json metadata (name, version, description, keywords, repository, license) - [X] T068 [P] Create CHANGELOG.md with initial release notes - [X] T069 [P] Add npm publish configuration (files, bin entry point) - [X] T070 Run quickstart.md validation (manual testing of all examples) --- ## Dependencies & Execution Order ### Phase Dependencies - **Setup (Phase 1)**: No dependencies - can start immediately - **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories - **User Stories (Phase 3-7)**: All depend on Foundational phase completion - User stories can then proceed in parallel (if staffed) - Or sequentially in priority order (P1 → P2 → P3 → P4 → P5) - **Polish (Phase 8)**: Depends on all desired user stories being complete ### User Story Dependencies - **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories - **User Story 2 (P2)**: Can start after Foundational (Phase 2) - Reuses API client from US1 but independently testable - **User Story 3 (P3)**: Can start after Foundational (Phase 2) - Adds comment tree logic but independently testable - **User Story 4 (P4)**: Can start after Foundational (Phase 2) - Completely independent user profile feature - **User Story 5 (P5)**: Depends on User Story 1 completion - Extends search functionality with advanced filters ### Within Each User Story - Schema definition before service implementation - Service implementation before tool handler - Tool handler before registration in index.ts - Validation before error handling - Core implementation before metadata/enhancements - Story complete before moving to next priority ### Parallel Opportunities - **Phase 1 (Setup)**: Tasks T003-T010 marked [P] can run in parallel (different config files) - **Phase 2 (Foundational)**: Task T017 marked [P] can run parallel with T011-T016 - **After Foundational completes**: User Stories 1, 2, 3, 4 can all start in parallel (different tool files) - **Phase 8 (Polish)**: Tasks T057-T069 marked [P] can run in parallel (different concerns) ### Blocking Tasks - **T001-T010 MUST complete** before T011 (need project structure) - **T011-T017 MUST complete** before any user story tasks (need foundation) - **User Story 5 SHOULD wait** for User Story 1 completion (extends search) --- ## Parallel Example: User Story 1 ```bash # After foundational phase, launch User Story 1: Task T018: "Create SearchPostsInputSchema in src/schemas/tools/search-posts.ts" Task T019: "Implement buildSearchParams in src/services/search-service.ts" Task T020: "Implement searchPosts in src/services/hn-api-client.ts" # Then sequentially: Task T021: "Implement search_posts tool handler" (depends on T018-T020) Task T022-T023: "Register tool" (depends on T021) Task T024-T026: "Add validation and enhancements" (depends on T021) ``` --- ## Parallel Example: Multiple User Stories ```bash # After foundational phase completes, if team has 3 developers: Developer A works on User Story 1 (T018-T026) - Search functionality Developer B works on User Story 2 (T027-T033) - Front page feature Developer C works on User Story 3 (T034-T042) - Post details feature # All three can work simultaneously since they touch different files ``` --- ## Implementation Strategy ### MVP First (User Story 1 Only) 1. Complete Phase 1: Setup (T001-T010) 2. Complete Phase 2: Foundational (T011-T017) - CRITICAL checkpoint 3. Complete Phase 3: User Story 1 (T018-T026) 4. **STOP and VALIDATE**: Test search functionality with various filters 5. Deploy/demo if ready - users can now search HackerNews! ### Incremental Delivery 1. **Setup + Foundational** → Foundation ready 2. **+ User Story 1** → Test independently → Deploy/Demo (MVP! - Search works) 3. **+ User Story 2** → Test independently → Deploy/Demo (Can now browse front page) 4. **+ User Story 3** → Test independently → Deploy/Demo (Can now view full discussions) 5. **+ User Story 4** → Test independently → Deploy/Demo (Can now check user profiles) 6. **+ User Story 5** → Test independently → Deploy/Demo (Advanced filtering available) 7. **+ Polish** → Production-ready with tests and documentation Each story adds value without breaking previous stories! ### Parallel Team Strategy With multiple developers after foundational phase: 1. Team completes Setup + Foundational together (T001-T017) 2. Once Foundational is done: - Developer A: User Story 1 - Search (T018-T026) - Developer B: User Story 2 - Front Page (T027-T033) - Developer C: User Story 3 - Post Details (T034-T042) 3. After initial stories complete: - Developer A: User Story 4 - User Profiles (T043-T050) - Developer B: User Story 5 - Advanced Filters (T051-T056, after US1 done) - Developer C: Start Polish phase (T057-T070) 4. Stories complete and integrate independently --- ## Summary **Total Tasks**: 70 **Task Breakdown**: - Phase 1 (Setup): 10 tasks - Phase 2 (Foundational): 7 tasks (BLOCKS everything) - Phase 3 (User Story 1 - Search): 9 tasks 🎯 MVP - Phase 4 (User Story 2 - Front Page): 7 tasks - Phase 5 (User Story 3 - Post Details): 9 tasks - Phase 6 (User Story 4 - User Info): 8 tasks - Phase 7 (User Story 5 - Advanced Filtering): 6 tasks - Phase 8 (Polish): 14 tasks **Parallel Opportunities**: 25 tasks marked [P] can run in parallel within their phase **Independent Test Criteria**: Each user story (P1-P5) has clear test scenario for validation **Suggested MVP Scope**: Phases 1-3 (Tasks T001-T026) deliver working search functionality --- ## Notes - All tasks follow strict checklist format with ID, optional [P], story label [US#], and file path - [P] tasks = different files, no dependencies within phase - [Story] label maps task to specific user story for traceability - Each user story is independently completable and testable - Commit after each task or logical group - Stop at any checkpoint to validate story independently - Constitution adherence: TypeScript strict mode, Biome linting, Node.js 22+, ESM modules