# Implementation Plan: HackerNews MCP Server
**Branch**: `001-hackernews-mcp-server` | **Date**: October 12, 2025 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `/specs/001-hackernews-mcp-server/spec.md`
**Note**: This plan was generated by the `/speckit.plan` command following the complete planning workflow.
## Summary
Build a Model Context Protocol (MCP) server that provides AI assistants with structured access to HackerNews content via the Algolia API. The server will expose 5 tools for searching posts, retrieving front page content, fetching latest discussions, viewing item details with nested comments, and accessing user profiles. Implementation uses Node.js with TypeScript (strict mode), MCP TypeScript SDK with stdio transport, Biome for linting/formatting, and Vitest for testing. Architecture follows modular design with one file per tool, comprehensive error handling, and 80%+ test coverage per Constitution requirements
## Technical Context
**Language/Version**: TypeScript 5.x with strict mode, Node.js 18+
**Primary Dependencies**:
- `@modelcontextprotocol/sdk` (MCP TypeScript SDK for server implementation)
- `zod` (Runtime schema validation and type inference)
- Native `fetch` API (Node 18+ built-in HTTP client)
**Storage**: N/A (read-only API client, no persistent storage)
**Testing**: Vitest with 80%+ coverage requirement (unit, integration, contract tests)
**Target Platform**: Node.js 18+ on macOS, Linux, Windows (via stdio transport)
**Project Type**: Single project (MCP server CLI tool)
**Linting/Formatting**: Biome (all-in-one toolchain replacing ESLint + Prettier)
**Performance Goals**:
- Search queries: < 2 seconds for 95% of requests
- Item retrieval: < 3 seconds including nested comments
- User profile: < 1 second
- Front page/latest: < 2 seconds
**Constraints**:
- HackerNews API rate limit: 10,000 requests/hour per IP
- Stdio transport (spawned process, no network server)
- Read-only operations (no write/vote capabilities)
- No caching (always fetch fresh data)
- Response time dependent on HackerNews API latency
**Scale/Scope**:
- 5 MCP tools (search, front page, latest, item, user)
- ~2000 lines of production code estimated
- Comprehensive test suite (unit + integration + contract)
- Full documentation (README, API reference, contributing guide)
## Constitution Check
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
This feature MUST comply with all principles defined in `.specify/memory/constitution.md`:
### Code Quality Standards (Principle I)
- [x] TypeScript strict mode enabled - `tsconfig.json` with `strict: true`
- [x] No unjustified `any` types - Zod schemas provide type inference
- [x] Biome configured for linting and formatting - `biome.json` in project root
- [x] Maximum function complexity ≤ 10 - Tool handlers are simple wrappers around API calls
- [x] All error conditions explicitly handled - Try-catch blocks with typed error responses
### Testing Standards (Principle II) - NON-NEGOTIABLE
- [x] Test-first development plan documented - TDD workflow defined in research.md
- [x] Unit test coverage plan: target ≥80% - Vitest with coverage reporting configured
- [x] Integration tests identified for all external interactions - Tests for all 5 HackerNews API endpoints
- [x] Contract tests defined for all public interfaces - MCP tool input/output schema validation tests
- [x] CI/CD test automation configured - GitHub Actions workflow (to be created during implementation)
### User Experience Consistency (Principle III)
- [x] Response time targets defined (≤200ms sync, ≤2s complex) - Performance goals documented above
- [x] Loading states specified for operations >200ms - MCP handles async naturally; no UI considerations
- [x] Error messages are user-friendly and consistent - Structured error responses with clear messages
- [x] Accessibility requirements specified (WCAG 2.1 AA) - N/A for stdio CLI tool (no UI)
- [x] Progressive enhancement strategy defined - N/A for stdio CLI tool (no web interface)
### Documentation-First (Principle IV)
- [x] Context7 MCP usage planned for all external dependencies - Used for MCP SDK and Biome research
- [x] Architecture decisions documented in ADR format - Key decisions captured in research.md
- [x] API documentation approach defined (OpenAPI/Swagger) - TypeScript interfaces + JSDoc comments
- [x] User documentation scope identified - README, quickstart.md, API reference, contributing guide
- [x] Complex logic documentation requirements noted - Nested comment tree handling, error mapping
### Dependency Hygiene (Principle V)
- [x] All dependencies use latest stable versions - package.json will pin to latest at implementation time
- [x] Security audit process defined - `npm audit` in CI/CD pipeline
- [x] New dependencies justified - MCP SDK (required), Zod (MCP standard), Vitest (testing), Biome (tooling)
- [x] License compatibility verified - MCP SDK (MIT), Zod (MIT), Vitest (MIT), Biome (MIT/Apache-2.0)
- [x] Update schedule established - Monthly dependency review, immediate critical security patches
### Prefer Existing Solutions (Principle VI)
- [x] Existing packages/libraries evaluated before custom code - Using MCP SDK, Zod, native fetch
- [x] Context7 MCP used to find official examples and patterns - Retrieved MCP TypeScript SDK examples
- [x] Custom implementations justified in writing - Only custom code is tool-specific business logic
- [x] Code reuse opportunities identified - MCP SDK patterns, Zod schemas, shared error handlers
- [x] Attribution documented for reused code - MCP SDK examples credited in code comments
**Violations requiring justification:** None - all Constitution principles can be fully satisfied.
## Project Structure
### Documentation (this feature)
```
specs/001-hackernews-mcp-server/
├── plan.md # This file (complete implementation plan)
├── spec.md # Original feature specification
├── research.md # Phase 0 research and technical decisions
├── data-model.md # Phase 1 data models and entities
├── quickstart.md # Phase 1 user quick start guide
├── contracts/ # Phase 1 API contracts
│ ├── types.ts # TypeScript type definitions
│ └── tool-contracts.md # MCP tool specifications
└── tasks.md # Phase 2 (created by /speckit.tasks command)
```
### Source Code (repository root)
```
hn-mcp-server/
├── src/
│ ├── index.ts # Main entry point, server initialization
│ ├── tools/ # MCP tool implementations (one per file)
│ │ ├── search-posts.ts # Search HackerNews posts tool
│ │ ├── get-front-page.ts # Front page retrieval tool
│ │ ├── get-latest-posts.ts # Latest posts tool
│ │ ├── get-item.ts # Item details tool
│ │ └── get-user.ts # User profile tool
│ ├── services/ # Business logic layer
│ │ └── hn-api.ts # HackerNews API client wrapper
│ ├── types/ # TypeScript type definitions
│ │ ├── hn-types.ts # HackerNews API response types
│ │ └── mcp-types.ts # MCP-specific types and schemas
│ └── utils/ # Shared utilities
│ ├── validators.ts # Input validation helpers
│ └── error-handlers.ts # Error handling and mapping
│
├── tests/
│ ├── unit/ # Pure unit tests (no I/O)
│ │ ├── validators.test.ts
│ │ └── error-handlers.test.ts
│ ├── integration/ # Tests with real API calls
│ │ ├── hn-api.test.ts
│ │ └── tools/*.test.ts # Integration tests for each tool
│ └── contract/ # MCP protocol compliance tests
│ └── mcp-tools.test.ts
│
├── docs/
│ ├── API.md # Detailed API reference
│ ├── CONTRIBUTING.md # Contribution guidelines
│ └── ARCHITECTURE.md # System design documentation
│
├── .github/
│ ├── workflows/
│ │ └── ci.yml # CI/CD pipeline (test, lint, build)
│ └── copilot-instructions.md # GitHub Copilot context (updated)
│
├── dist/ # Build output (gitignored)
├── node_modules/ # Dependencies (gitignored)
│
├── package.json # Project metadata and scripts
├── tsconfig.json # TypeScript configuration
├── biome.json # Biome linting/formatting config
├── vitest.config.ts # Vitest test configuration
├── README.md # Main project README
├── LICENSE # MIT license
└── .gitignore # Git ignore rules
```
**Structure Decision**:
Selected **Option 1: Single project** structure as this is a standalone CLI tool (MCP server) with no web UI or mobile components. The modular tool-based architecture with separate files per tool (as requested by user) promotes:
- **Separation of concerns**: Each tool is independently testable
- **Maintainability**: Easy to locate and modify specific functionality
- **Scalability**: Simple to add new tools without affecting existing ones
- **Testing**: Clear test organization mirroring source structure
- **Constitution compliance**: Follows single responsibility principle (Principle I)
The `src/tools/` directory structure directly addresses the user requirement: "structured the app so tool calls are separated by file".
## Complexity Tracking
*Fill ONLY if Constitution Check has violations that must be justified*
**No violations identified.** All Constitution principles can be satisfied without compromises. This section remains empty as no complexity justifications are needed.
---
## Phase Outputs
### Phase 0: Research & Technical Decisions ✅ COMPLETE
**Output**: `research.md` (generated)
**Key Decisions Made**:
- Language: TypeScript (strict) + Node.js 18+
- Transport: stdio via `StdioServerTransport`
- Testing: Vitest with 80%+ coverage
- Linting: Biome (per user request)
- HTTP Client: Native fetch API
- Validation: Zod schemas (MCP standard)
- Structure: Modular tool-per-file design
**All NEEDS CLARIFICATION items resolved**: Yes
---
### Phase 1: Design & Contracts ✅ COMPLETE
**Outputs**:
- `data-model.md` (generated) - Complete entity definitions with validation rules
- `contracts/types.ts` (generated) - TypeScript interfaces for all entities and tools
- `contracts/tool-contracts.md` (generated) - Detailed MCP tool specifications
- `quickstart.md` (generated) - User-facing quick start guide
- `.github/copilot-instructions.md` (updated) - Agent context with new technologies
**Data Models Defined**: 6 entities
- `HNItem` (base type)
- `HNStory` (specialized)
- `HNComment` (specialized)
- `HNUser`
- `SearchResult`
- `ItemResult`
**API Contracts Defined**: 5 MCP tools
- `search-posts` - Search with filters and pagination
- `get-front-page` - Front page posts
- `get-latest-posts` - Recent content sorted by date
- `get-item` - Item details with nested comments
- `get-user` - User profile information
**Agent Context Updated**: Yes - GitHub Copilot instructions now include TypeScript, MCP SDK, and Biome context
---
## Phase 2: Task Breakdown (NOT INCLUDED IN THIS COMMAND)
**Note**: Phase 2 task creation is handled by the separate `/speckit.tasks` command, which generates `tasks.md` with detailed implementation tasks.
---
## Implementation Roadmap
### Milestone 1: Project Setup
- Initialize Node.js project with TypeScript
- Configure Biome for linting and formatting
- Set up Vitest for testing
- Create project structure (src/, tests/, docs/)
- Initialize Git repository
### Milestone 2: Core Infrastructure
- Implement HackerNews API client (`services/hn-api.ts`)
- Create shared utilities (validators, error handlers)
- Define TypeScript types (`types/hn-types.ts`, `types/mcp-types.ts`)
- Write unit tests for utilities
### Milestone 3: MCP Server Setup
- Initialize `McpServer` instance (`index.ts`)
- Configure stdio transport
- Implement error handling middleware
- Write integration tests for server startup
### Milestone 4: Tool Implementation (TDD for each)
For each tool:
1. Write contract tests (input/output validation)
2. Write integration tests (with mock/real API)
3. Implement tool handler
4. Register tool with MCP server
5. Verify all tests pass
**Tool Order** (by priority from spec):
1. `search-posts` (P1)
2. `get-front-page` (P1)
3. `get-latest-posts` (P1)
4. `get-item` (P2)
5. `get-user` (P3)
### Milestone 5: Documentation
- Write comprehensive README.md
- Create API reference documentation
- Write contributing guidelines
- Add architecture documentation
- Include usage examples
### Milestone 6: Testing & Quality
- Achieve 80%+ test coverage
- Run full test suite
- Perform integration testing with real API
- Test with MCP clients (Claude Desktop)
- Security audit (npm audit)
### Milestone 7: CI/CD & Release
- Set up GitHub Actions workflow
- Configure automated testing
- Configure automated linting/formatting checks
- Tag v1.0.0 release
- Publish to npm (optional)
---
## Success Metrics
From spec.md success criteria, mapped to implementation:
| Criterion | Implementation Approach | Verification Method |
|-----------|------------------------|---------------------|
| SC-001: Search < 2s | Use native fetch with 5s timeout | Integration tests + manual testing |
| SC-002: 100% accuracy for front/latest | Direct API pass-through | Contract tests verify response format |
| SC-003: Item retrieval < 3s | Efficient API calls, no preprocessing | Integration tests with timer |
| SC-004: User profile < 1s | Simple GET request | Integration tests with timer |
| SC-005: All endpoints supported | 5 tools cover all API endpoints | Contract tests for each tool |
| SC-006: Pagination works correctly | Validate page/hitsPerPage params | Unit + integration tests |
| SC-007: All filters work | Pass filters directly to API | Integration tests with various filters |
| SC-008: Clear error messages | Structured error responses | Unit tests for error handler |
| SC-009: Rate limit handling | Detect 429, return clear message | Integration test with error injection |
| SC-010: 95% first-attempt success | Comprehensive input validation | User testing (manual) |
| SC-011: API compatibility | Follow API documentation exactly | Contract tests against live API |
| SC-012: All acceptance scenarios pass | Integration tests for each scenario | Automated test suite |
---
## Risk Analysis
| Risk | Impact | Mitigation |
|------|--------|------------|
| HackerNews API changes | High | Pin to stable API version, monitor changelog, contract tests detect breaks |
| Rate limit exceeded | Medium | Clear error messages, document limits, suggest retry strategies |
| Large comment trees slow | Medium | Document expected times, consider timeout warnings, test with large threads |
| MCP SDK breaking changes | Medium | Pin SDK version, test before upgrading, follow MCP release notes |
| Network failures | Low | Comprehensive error handling, clear error messages, timeout configuration |
| Type mismatches | Low | Strict TypeScript mode, Zod validation, comprehensive contract tests |
---
## Dependencies Summary
### Production Dependencies
```json
{
"@modelcontextprotocol/sdk": "^1.0.0",
"zod": "^3.22.0"
}
```
### Development Dependencies
```json
{
"typescript": "^5.3.0",
"@biomejs/biome": "^1.5.0",
"vitest": "^1.2.0",
"@types/node": "^20.10.0"
}
```
**Total Dependencies**: 6 (minimal footprint per Constitution Principle V)
**All MIT licensed** (or compatible): Yes
---
## Open Questions
**None** - All technical questions resolved during Phase 0 research.
---
## References
- **Feature Spec**: [spec.md](./spec.md)
- **Research**: [research.md](./research.md)
- **Data Models**: [data-model.md](./data-model.md)
- **Contracts**: [contracts/](./contracts/)
- **Quick Start**: [quickstart.md](./quickstart.md)
- **HackerNews API**: https://hn.algolia.com/api
- **MCP Documentation**: https://modelcontextprotocol.io
- **MCP TypeScript SDK**: https://github.com/modelcontextprotocol/typescript-sdk
---
## Sign-Off
**Phase 0 (Research)**: ✅ Complete
**Phase 1 (Design)**: ✅ Complete
**Phase 2 (Tasks)**: ⏳ Pending (use `/speckit.tasks` command)
**Implementation**: ⏳ Ready to begin
**Constitution Check**: ✅ All principles satisfied
**Technical Decisions**: ✅ All documented in research.md
**API Contracts**: ✅ All defined in contracts/
**Documentation**: ✅ All planning docs complete
**Ready for Implementation**: YES
**Next Command**: `/speckit.tasks` to generate detailed implementation tasks