# hn-mcp-server Development Guidelines
Auto-generated from all feature plans. Last updated: 2025-10-12
## Active Technologies
- TypeScript 5.x (strict mode)
- Node.js 18+ with native fetch API
- Model Context Protocol (MCP) TypeScript SDK
- Zod for schema validation
- Biome for linting and formatting
- Vitest for testing
- HackerNews Algolia API
## Project Structure
```
src/
├── index.ts # MCP server entry point
├── tools/ # Tool implementations (one per file)
│ ├── search-posts.ts
│ ├── get-front-page.ts
│ ├── get-latest-posts.ts
│ ├── get-item.ts
│ └── get-user.ts
├── services/ # Business logic
│ └── hn-api.ts
├── types/ # Type definitions
└── utils/ # Validators and error handlers
tests/
├── unit/ # Unit tests (no I/O)
├── integration/ # Integration tests (real API)
└── contract/ # MCP protocol compliance
```
## Commands
```bash
# Build
npm run build
npm run dev # Watch mode
# Testing
npm test
npm run test:coverage
npm run test:ui
# Code Quality
npm run lint
npm run lint:fix
npm run format
npm run format:check
# Clean
npm run clean
```
## Code Style
- TypeScript strict mode enabled
- Tabs for indentation (Biome configuration)
- Line width: 100 characters
- Double quotes for strings
- Trailing commas (ES5)
- No `any` types without justification
- Explicit return types on public functions
## MCP Tools
All 5 tools implemented:
1. **search-posts** - Search HN by keyword with filters
2. **get-front-page** - Current front page posts
3. **get-latest-posts** - Recent posts by date
4. **get-item** - Item details with nested comments
5. **get-user** - User profile information
## Architecture Patterns
- **Tool Pattern**: Input validation (Zod) → API call → Output validation → Response
- **Error Handling**: Consistent error responses with type, message, details
- **Testing**: Unit + Integration + Contract tests, 80%+ coverage required
- **Separation**: One file per tool for maintainability
## Recent Changes
- All 5 MCP tools implemented and registered
- Complete type system with HN and MCP types
- HN API client with timeout handling
- Validators and error handlers with comprehensive coverage
- Full documentation (API, Architecture, Contributing)
- CI/CD workflow with GitHub Actions
<!-- MANUAL ADDITIONS START -->
<!-- MANUAL ADDITIONS END -->
