# Contributing to HN-MCP
Thank you for your interest in contributing to HN-MCP! This guide will help you get started with development.
## 🚀 Quick Start
1. **Fork and clone the repository**
```bash
git clone https://github.com/[your-username]/hn-mcp.git
cd hn-mcp
```
2. **Install dependencies**
```bash
npm install
```
3. **Run in development mode**
```bash
npm run dev
```
## 📁 Project Structure
```
hn-mcp/
├── src/ # Source code
│ ├── index.ts # Entry point
│ ├── cli.ts # CLI interface
│ ├── mcp-server.ts # MCP server implementation
│ ├── core/ # Core utilities (cache, rate-limiter)
│ ├── services/ # Hacker News API client
│ ├── tools/ # MCP tool implementations
│ └── types/ # TypeScript types
├── dist/ # Built JavaScript (generated)
├── CLAUDE.md # AI assistant documentation
└── CONTRIBUTING.md # This file
```
## 🛠️ Development Commands
```bash
# Development
npm run dev # Run with hot reload
npm run build # Build TypeScript
npm run typecheck # Type checking
npm run lint # Run ESLint (if configured)
# Run server modes
npm start # Run in stdio mode (for Claude Desktop)
npm run start:http # Run in HTTP mode (for web clients)
```
## 🧪 Testing
### Manual Testing
1. **Test with Claude Desktop**
```bash
npm run build
npm start
```
2. **Test with HTTP client**
```bash
npm run build
npm run start:http
# Server runs at http://localhost:3000
```
3. **Test individual tools**
```bash
# Use Postman or curl to test the MCP endpoint
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```
### Test Different HN Features
```bash
# Browse top stories
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"browse_stories","arguments":{"type":"top","limit":10}}}'
# Search Hacker News
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_hn","arguments":{"query":"AI","limit":5}}}'
```
## 📝 Code Style
- Use TypeScript for all new code
- Follow existing patterns in the codebase
- Run `npm run typecheck` before committing
- Add JSDoc comments for public APIs
- Keep functions focused and small
- Use descriptive variable names
- No console.log (use console.error for debug output to stderr)
## 🎯 Making Contributions
### Types of Contributions
- **Bug fixes**: Fix issues reported in GitHub Issues
- **Features**: Add new HN tools or enhance existing ones
- **Documentation**: Improve README, add examples, fix typos
- **Tests**: Add test coverage
- **Performance**: Optimize caching, rate limiting, or API calls
### Contribution Process
1. **Check existing issues** or create a new one
2. **Fork** the repository
3. **Create a feature branch**: `git checkout -b feature/your-feature`
4. **Make your changes** following code style
5. **Test thoroughly** including rate limits
6. **Commit** with clear messages
7. **Push** to your fork
8. **Open a Pull Request** with description
**Important**: Never push directly to main. Always create a Pull Request for code review.
### Commit Message Format
```
type: description
[optional body]
[optional footer]
```
Types:
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `style`: Code style changes
- `refactor`: Code refactoring
- `test`: Test additions/changes
- `chore`: Build process or auxiliary tool changes
Examples:
```
feat: add job posts browsing tool
fix: handle deleted story errors gracefully
docs: update search API documentation
```
## 🐛 Debugging
### Enable Debug Logging
Debug output goes to stderr (not stdout which is used for MCP protocol):
```bash
# All debug output is sent to stderr
npm run dev 2> debug.log
```
### Common Issues
1. **Rate limiting during development**
- HN has no official rate limits!
- Our self-imposed limit is 300 req/min
- Disable cache for fresh data: `export HN_MCP_NO_CACHE=true`
2. **Port conflicts in HTTP mode**
- Change port: `HN_MCP_PORT=8080 npm run start:http`
- Kill existing process: `lsof -ti :3000 | xargs kill -9`
3. **TypeScript errors**
- Run `npm run typecheck` to see all errors
- Check `tsconfig.json` settings
## 📦 Publishing Process
**Note**: Only maintainers can publish new versions.
1. Update version in:
- `package.json`
- `src/mcp-server.ts` (SERVER_VERSION constant)
2. Build and test:
```bash
npm run build
npm start # Test locally
```
3. Publish to NPM:
```bash
npm publish --access public
```
4. Create and push tag:
```bash
git tag v1.x.x
git push origin main
git push origin v1.x.x
```
## 🤝 Getting Help
- **Discord**: Join the MCP Discord server
- **Issues**: Open a GitHub issue
- **Discussions**: Use GitHub Discussions for questions
## 📄 License
By contributing, you agree that your contributions will be licensed under the MIT License.
## 🙏 Thank You!
Your contributions make HN-MCP better for everyone. We appreciate your time and effort!
