# Contributing to HackerNews MCP Server
Thank you for your interest in contributing to the HackerNews MCP Server! This document provides guidelines and information for contributors.
## 🚀 Quick Start
1. **Fork** the repository on GitHub
2. **Clone** your fork locally:
```bash
git clone https://github.com/YOUR_USERNAME/hn-mcp-server.git
cd hn-mcp-server
```
3. **Install dependencies**:
```bash
npm install
```
4. **Create a feature branch**:
```bash
git checkout -b feature/your-feature-name
```
5. **Make your changes** following our development guidelines
6. **Run quality checks**:
```bash
npm run ci
```
7. **Commit and push**:
```bash
git commit -m "Add your feature description"
git push origin feature/your-feature-name
```
8. **Open a Pull Request** on GitHub
## 📋 Development Guidelines
### Constitution Principles
**⚠️ IMPORTANT**: All development MUST comply with the project constitution. Before starting any work, review these non-negotiable principles:
1. **Code Quality First**: Zero technical debt, full type safety, linting clean
2. **Test-First Development**: TDD mandatory - tests → approval → fail → implement → pass → refactor
3. **UX Consistency**: Follow MCP naming conventions, consistent parameters, clear error messages
4. **Latest Dependencies**: Always use Context7 MCP to retrieve latest docs before using libraries
5. **Documentation-Driven**: Specs written first, API docs complete, examples provided
6. **Integration Testing**: Real API tests, contract validation, error scenario coverage
7. **Observability**: Structured logging, error context, performance metrics, debug mode
### Development Workflow
1. **Before Starting**: Read feature spec, check constitution compliance requirements
2. **Research Phase**: Use Context7 MCP to retrieve latest docs for any external libraries
3. **Test Phase**: Write tests first, get approval, verify they fail
4. **Implementation**: Write code following quality standards, with observability
5. **Validation**: Run all quality gates (linter, types, tests, coverage)
6. **Documentation**: Update API docs, examples, CHANGELOG
7. **Review**: Complete constitution compliance checklist
### Code Style
- **TypeScript 5.7+** with Node.js 20 LTS (strict mode enabled)
- Follow standard TypeScript conventions
- Use Biome for linting and formatting
- All code style rules must align with "Code Quality First" principle
### Project Structure
```
src/
├── index.ts # Main entry point
├── server.ts # MCP server initialization
├── tools/ # MCP tool implementations (one per file)
├── lib/ # Shared utilities
└── types/ # TypeScript type definitions
tests/
├── unit/ # Unit tests
├── integration/ # Integration tests
└── contract/ # Contract tests
```
## 🧪 Testing
We follow Test-Driven Development (TDD):
1. **Write tests first** - Define expected behavior
2. **Verify tests fail** - Ensure test captures the requirement
3. **Implement code** - Make tests pass
4. **Refactor** - Improve code while keeping tests passing
### Running Tests
```bash
# Run all tests
npm test
# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:contract
# Run tests in watch mode
npm run test:watch
# Run tests with coverage
npm run test:coverage
```
### Test Coverage Requirements
- Minimum 80% code coverage
- All public APIs must be tested
- Integration tests for API interactions
- Contract tests for MCP protocol compliance
## 📝 Quality Gates
All changes must pass these checks:
- ✅ **Linter clean** (zero warnings/errors)
- ✅ **Type checker passing** (strict mode)
- ✅ **Tests passing** (unit + integration + contract)
- ✅ **Coverage ≥80%** (no decrease from baseline)
- ✅ **Documentation complete**
- ✅ **Security audit clean** (`npm audit`)
- ✅ **Constitution compliance** checklist completed
### Running Quality Checks
```bash
# Run all quality gates
npm run ci
# Individual checks
npm run lint # Linting
npm run check # Linting + TypeScript
npm run test:coverage # Tests with coverage
```
## 🛠️ Available Commands
```bash
npm run build # Compile TypeScript
npm run dev # Watch mode development
npm run start # Run the server
npm run lint # Lint code
npm run format # Format code
npm run check # Lint + type check
npm run ci # Full CI workflow
npm test # Run all tests
npm run test:watch # Test watch mode
npm run test:coverage # Tests with coverage
```
## 📚 Documentation
### API Documentation
- All public functions must have JSDoc comments
- MCP tools must have complete parameter documentation
- Error conditions must be documented
- Examples must be provided for complex APIs
### User Documentation
- Update README.md for new features
- Update docs/ for detailed guides
- Keep examples up to date
- Update CHANGELOG.md for all changes
## 🔒 Security
- Run `npm audit` regularly
- Report security vulnerabilities privately
- Never commit secrets or credentials
- Use environment variables for configuration
- Follow OWASP guidelines for web security
## 📋 Pull Request Process
1. **Update documentation** - README, CHANGELOG, examples
2. **Add tests** - Ensure coverage doesn't decrease
3. **Run quality gates** - `npm run ci` must pass
4. **Update dependencies** - Keep packages current
5. **Squash commits** - Clean commit history
6. **Write clear PR description** - What, why, how
### PR Template
Please use our PR template with:
- [ ] Description of changes
- [ ] Testing instructions
- [ ] Screenshots (if UI changes)
- [ ] Breaking changes noted
- [ ] Documentation updated
## 🎯 Types of Contributions
### 🐛 Bug Fixes
- Fix reported issues
- Include test case that reproduces the bug
- Verify fix doesn't break existing functionality
### ✨ Features
- Follow specification-driven development
- Write comprehensive tests
- Update documentation and examples
- Consider backward compatibility
### 📚 Documentation
- Improve existing docs
- Add missing documentation
- Create tutorials or guides
- Translate documentation
### 🧪 Testing
- Add missing test coverage
- Improve test quality
- Add integration tests
- Performance testing
### 🔧 Maintenance
- Update dependencies
- Improve build process
- Code refactoring
- Performance optimizations
## 🤝 Code of Conduct
This project follows a code of conduct to ensure a welcoming environment for all contributors. See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for details.
## 📞 Getting Help
- **Issues**: [GitHub Issues](https://github.com/sam3690/Hackernews_mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/sam3690/Hackernews_mcp/discussions)
- **Documentation**: [docs/](docs/) directory
## 🙏 Recognition
Contributors are recognized in:
- CHANGELOG.md for significant contributions
- GitHub's contributor insights
- Release notes
Thank you for contributing to the HackerNews MCP Server! 🎉
