# VS Code Setup Guide
This guide will help you set up the HackerNews MCP Server to work with GitHub Copilot in VS Code.
## Prerequisites
- **Node.js 20 LTS or higher** - [Download](https://nodejs.org/)
- **VS Code** - [Download](https://code.visualstudio.com/)
- **GitHub Copilot extension** - Install from VS Code marketplace
- **GitHub Copilot Chat extension** - Install from VS Code marketplace
## Installation Steps
### 1. Clone and Build
```bash
# Clone the repository
git clone <your-repo-url>
cd hn-mcp-server
# Install dependencies
npm install
# Build the TypeScript code
npm run build
```
### 2. Configure VS Code
The MCP server requires two configuration files:
**`.vscode/mcp.json`** - Primary MCP server configuration:
```json
{
"hackernews": {
"command": "node",
"args": ["${workspaceFolder}/dist/index.js"],
"env": {
"DEBUG": "0"
}
}
}
```
**`.vscode/settings.json`** - Additional VS Code settings:
```json
{
"github.copilot.chat.mcp.enabled": true,
"github.copilot.chat.mcp.servers": {
"hackernews": {
"command": "node",
"args": ["dist/index.js"],
"cwd": "${workspaceFolder}",
"env": {
"DEBUG": "0"
}
}
}
}
```
Both files are already configured in this project!
**Configuration Options:**
- `command`: The Node.js executable
- `args`: Path to the built server (uses workspace variable)
- `env.DEBUG`: Set to "1" to enable debug logging
The MCP server returns both text content and structured data matching the output schema, enabling rich integration with GitHub Copilot.
### 3. Activate the Server
1. **Open the project in VS Code:**
```bash
code .
```
2. **Reload VS Code:**
- Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on Mac)
- Type "Developer: Reload Window"
- Press Enter
3. **Verify MCP Server is Running:**
- Open Copilot Chat (Ctrl+Alt+I or icon in sidebar)
- The HackerNews tools should be automatically available
## Using the Server
### Example Prompts
Once configured, you can use these prompts in Copilot Chat:
**Search Stories:**
```
Search Hacker News for stories about "machine learning"
```
**Get Front Page:**
```
Show me what's currently on the HN front page
```
**Get Latest Stories:**
```
What are the latest stories submitted to HN?
```
**Get User Profile:**
```
Tell me about the HN user 'pg'
```
**Get Story with Comments:**
```
Get the full discussion for HN story ID 8863
```
**Advanced Search:**
```
Find HN stories about TypeScript with at least 100 points from the last week
```
### Available Tools
The server provides these MCP tools to Copilot:
1. **search_stories** - Search by relevance
2. **search_by_date** - Search sorted by date
3. **search_comments** - Search comments
4. **get_front_page** - Current front page
5. **get_latest_stories** - Latest submissions
6. **get_ask_hn** - Ask HN posts
7. **get_show_hn** - Show HN posts
8. **get_story** - Story by ID with comments
9. **get_user** - User profile
Copilot will automatically select the appropriate tool based on your question!
## Troubleshooting
### Server Not Starting
**Check the build:**
```bash
npm run build
```
**Verify the dist folder exists:**
```bash
ls dist/
```
You should see `index.js` and related files.
### MCP Tools Not Appearing
1. **Check Copilot extensions are installed:**
- GitHub Copilot
- GitHub Copilot Chat
2. **Verify MCP is enabled:**
- Open VS Code settings (Ctrl+,)
- Search for "mcp"
- Ensure "GitHub Copilot Chat: MCP Enabled" is checked
3. **Reload VS Code:**
- Ctrl+Shift+P → "Developer: Reload Window"
4. **Check for errors:**
- Open VS Code Output panel (Ctrl+Shift+U)
- Select "GitHub Copilot Chat" from dropdown
- Look for MCP-related error messages
### Debug Mode
Enable debug logging to see what's happening:
1. **Update `.vscode/settings.json`:**
```json
{
"github.copilot.chat.mcp.servers": {
"hackernews": {
"command": "node",
"args": ["dist/index.js"],
"cwd": "${workspaceFolder}",
"env": {
"DEBUG": "1"
}
}
}
}
```
2. **Reload VS Code**
3. **Check logs** in the Output panel
### Rate Limiting
The HN Algolia API has a limit of **10,000 requests per hour**. The server:
- Tracks request count automatically
- Warns at 90% usage (9,000 requests)
- Throws error at 95% usage (9,500 requests)
- Resets counter every hour
If you hit the rate limit, wait for the hourly reset.
### Node.js Version
Ensure you're using Node.js 20 or higher:
```bash
node --version
```
Should output: `v20.0.0` or higher.
## Development Mode
While developing, you can run the TypeScript compiler in watch mode:
```bash
npm run dev
```
This will automatically rebuild when you change source files. You'll need to reload VS Code to pick up changes.
## Alternative: Global Installation
You can also install the server globally:
```bash
# From the project directory
npm link
# Now use from anywhere
hn-mcp-server
```
Then configure VS Code to use the global command:
```json
{
"github.copilot.chat.mcp.servers": {
"hackernews": {
"command": "hn-mcp-server"
}
}
}
```
## Next Steps
- Read the [README.md](../README.md) for detailed tool documentation
- Check [docs/API.md](API.md) for complete API reference (coming soon)
- Try the example prompts above
- Experiment with advanced search filters
## Getting Help
- **Issues**: [GitHub Issues](https://github.com/YOUR_USERNAME/hn-mcp-server/issues)
- **Discussions**: [GitHub Discussions](https://github.com/YOUR_USERNAME/hn-mcp-server/discussions)
---
**Happy Hacking!** 🚀
