使用说明

HackerNews MCP服务器

一个模型上下文协议（MCP）服务器，通过官方网站提供对HackerNews内容的编程访问 HN Algolia API公司这使得AI助手和其他MCP客户端能够搜索、检索和分析HackerNews的故事、评论和用户资料。

特性

🔍 综合搜索：使用高级过滤功能按相关性或日期搜索HackerNews
📰 内容访问：使用完整元数据检索故事、评论和民意调查
👤 用户档案：访问用户信息、提交和评论历史记录
⚡ 高性能：具有连接池和重试逻辑的异步/等待设计
🛡️ 类型安全：全程完整的Pydantic验证和类型提示
🔧 MCP兼容：适用于Claude Desktop、Continue和其他MCP客户端
🌐 双重运输：支持stdio（本地）和HTTP/SSE（云）模式
☁️ 云就绪：部署到Railway、fly.io、Render、AWS Lambda、Google Cloud Run

安装

来自PyPI（推荐）

标准模式（默认-本地使用）：

pip install hn-mcp-server

HTTP/SSE模式（用于云部署）：

pip install hn-mcp-server[http]

来源

git clone https://github.com/CyrilBaah/hn-mcp-server.git
cd hn-mcp-server
pip install -e .

开发安装

pip install -e ".[dev]"

快速开始

标准模式（本地桌面客户端）

本地MCP客户端（如Claude Desktop和Cursor）的默认模式。

测试服务器：

# Test that the server responds to MCP protocol
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"1.0.0","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | python -m hn_mcp_server

您应该看到一个JSON响应，表示初始化成功。

与MCP检查员一起

MCP检查器提供了一个基于web的界面，用于测试和调试您的服务器：

# Using npx (no installation required)
npx @modelcontextprotocol/inspector python -m hn_mcp_server

# Or install globally
npm install -g @modelcontextprotocol/inspector
mcp-inspector python -m hn_mcp_server

这将打开一个浏览器界面，您可以在其中：

交互式测试所有可用工具
检查请求和响应
调试工具参数和输出
实时查看服务器日志

使用VS代码MCP

使用 vscodemcp.com，更新您的 .vscode/mcp.json:

{
  "servers": {
    "hackernews": {
      "command": "python",
      "args": ["-m", "hn_mcp_server"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

备注：如果您安装在虚拟环境中，请使用Python可执行文件的完整路径：

{
  "servers": {
    "hackernews": {
      "command": "/path/to/your/venv/bin/python",
      "args": ["-m", "hn_mcp_server"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

带光标

或者手动更新您的 .cursor/mcp.json:

{
  "servers": {
    "hackernews": {
      "command": "python",
      "args": ["-m", "hn_mcp_server"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

备注：如果您安装在虚拟环境中，请使用Python可执行文件的完整路径：

{
  "servers": {
    "hackernews": {
      "command": "/path/to/your/venv/bin/python",
      "args": ["-m", "hn_mcp_server"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

使用Claude桌面版

克劳德桌面版

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "hackernews": {
      "command": "python",
      "args": ["-m", "hn_mcp_server"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

重新启动Claude Desktop，HackerNews工具将可用。

HTTP/SSE模式（云部署）

用于部署到云平台或从远程客户端访问。

安装：

pip install hn-mcp-server[http]

正在运行HTTP服务器：

# Default: runs on 0.0.0.0:8000
python -m hn_mcp_server --transport http

# Custom host and port
python -m hn_mcp_server --transport http --host 127.0.0.1 --port 3000

终点：

上海证券交易所 http://localhost:8000/sse -MCP通信
健康： http://localhost:8000/health -健康检查

客户端配置（HTTP）：

{
  "mcpServers": {
    "hackernews-remote": {
      "url": "https://your-server.example.com/sse"
    }
  }
}

Docker部署：

FROM python:3.11-slim

WORKDIR /app
RUN pip install hn-mcp-server[http]

EXPOSE 8000
CMD ["python", "-m", "hn_mcp_server", "--transport", "http"]

部署到Railway/Render/fly.io：

# Set environment variable
TRANSPORT=http

# Start command
python -m hn_mcp_server --transport http --port $PORT

独立使用

HN客户端也可以在没有MCP的情况下直接使用：

import asyncio
from hn_mcp_server.services import HNClient

async def main():
    async with HNClient() as client:
        # Search for Python stories
        result = await client.search(
            query="python",
            tags=["story"],
            hits_per_page=10
        )
        
        for hit in result.hits:
            print(f"{hit.title} - {hit.points} points")

asyncio.run(main())

看 examples/direct_api_usage.py 更多示例。

可用工具

搜索工具

`search_hn`

按相关性搜索HackerNews内容（按相关性排序→ 点→ 评论）。

{
  "query": "artificial intelligence",
  "tags": ["story"],
  "hits_per_page": 20
}

`search_hn_by_date`

按日期搜索HackerNews内容（最近的内容排在第一位）。

{
  "query": "python",
  "tags": ["story", "show_hn"],
  "hits_per_page": 10
}

`get_front_page`

检索当前HackerNews头版故事。

{
  "page": 0,
  "hits_per_page": 30
}

`get_latest_stories`

检索最新的HackerNews故事。

{
  "hits_per_page": 20
}

`get_latest_comments`

检索最新的HackerNews评论。

{
  "hits_per_page": 20
}

`search_by_time_range`

在特定时间范围内搜索项目。

{
  "start_timestamp": 1704067200,
  "end_timestamp": 1736078400,
  "query": "AI",
  "hits_per_page": 10
}

`search_by_metrics`

搜索具有最低分数或评论的项目。

{
  "min_points": 100,
  "min_comments": 50,
  "tags": ["story"]
}

项目工具

`get_item`

按ID检索特定项目（故事、评论、投票）。

{
  "item_id": 1
}

`get_story_comments`

检索一个故事及其所有评论（全树）。

{
  "story_id": 39195605
}

用户工具

`get_user`

检索用户配置文件信息。

{
  "username": "pg"
}

`get_user_stories`

检索用户提交的所有故事。

{
  "username": "pg",
  "hits_per_page": 20
}

`get_user_comments`

检索用户的所有评论。

{
  "username": "pg",
  "hits_per_page": 20
}

配置

通过环境变量进行配置：

# API Configuration
export HN_API_BASE_URL="https://hn.algolia.com/api/v1"  # Default
export HN_REQUEST_TIMEOUT="10"  # Seconds, default: 10
export HN_MAX_RETRIES="3"  # Default: 3

# Logging
export LOG_LEVEL="INFO"  # DEBUG, INFO, WARNING, ERROR

搜索标签

可用于筛选的标签：

类型: story, comment, poll, pollopt
特别: show_hn, ask_hn, front_page
作者: author_USERNAME （例如。， author_pg)
故事: story_ID （例如。， story_12345)

数字过滤器

按数字字段筛选：

created_at_i -Unix时间戳
points -故事要点
num_comments -评论数量

操作员： <, <=, =, >, >=

示例：

points>100 -100分以上的故事
created_at_i>1704067200 -2024年1月1日之后的项目
num_comments>=50 -有50+条评论的项目

例子

看示例/ 使用示例目录：

direct_api_usage.py -在没有MCP的情况下直接使用API客户端
basic_usage.py -MCP客户端使用情况（需要MCP客户端库）
mcp_config.json -Claude桌面配置

运行示例

# Run direct API example (no MCP client needed)
python examples/direct_api_usage.py

# Run MCP client example (requires mcp library)
python examples/basic_usage.py

直接的API示例演示了直接使用HackerNews客户端库，而基本使用示例演示了如何通过编程与MCP服务器进行交互。

发展

设置

# Clone repository
git clone https://github.com/yourusername/hn-mcp-server.git
cd hn-mcp-server

# Create virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode with dev dependencies
pip install -e ".[dev]"

测试安装

# Test the MCP server starts correctly
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"1.0.0","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | python -m hn_mcp_server

# Run the direct API example
python examples/direct_api_usage.py

测试

# Run all tests
pytest

# Run unit tests only
pytest tests/unit/

# Run with coverage
pytest --cov=hn_mcp_server --cov-report=html

# Run integration tests (requires internet)
pytest tests/integration/ -m integration

装订和格式化

# Format code
ruff format .

# Lint code
ruff check .

# Type checking
mypy src/

建筑

hn-mcp-server/
├── src/hn_mcp_server/
│   ├── server.py          # MCP server setup
│   ├── models/            # Pydantic data models
│   ├── services/          # API client & rate limiting
│   └── tools/             # MCP tool implementations
├── tests/
│   ├── unit/              # Unit tests
│   ├── integration/       # Integration tests
│   └── contract/          # MCP protocol tests
└── examples/              # Usage examples

API费率限制

HackerNews API的速率限制为 每个IP每小时10000个请求。客户端包括内置的速率限制，以保持在这些范围内。

故障排除

服务器未启动

如果MCP服务器无法启动：

检查Python版本确保你使用的是Python 3.11或更高版本
```
python --version
```
验证安装：确保软件包安装正确
```
pip list | grep hn-mcp-server
```

直接测试服务器：尝试手动初始化服务器

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"1.0.0","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | python -m hn_mcp_server

虚拟环境问题

如果使用带有VS Code或Claude Desktop的虚拟环境：

使用完整路径：在配置文件中，使用Python可执行文件的完整路径：
```
{
  "command": "/full/path/to/.venv/bin/python",
  "args": ["-m", "hn_mcp_server"]
}
```
查找Python路径：要获取虚拟环境Python的完整路径：
```
which python  # On Unix/macOS
where python  # On Windows
```

MCP客户端示例不起作用

MCP客户端示例(basic_usage.py)要求服务器子进程通过stdio进行通信。如果您遇到问题：

使用 API直接示例 相反(direct_api_usage.py)
确保您正在使用 sys.executable 在客户端配置中（已在示例中更新）

API错误

如果遇到API错误：

检查网络连接：确保您可以联系到 hn.algolia.com
速率限制：如果您已超过10000个请求/小时的限制，请稍候
项目ID无效：确保HackerNews上存在项目ID

发布到PyPI

先决条件

安装构建工具：
```
pip install build twine
```
确保您拥有PyPI凭据（在以下位置创建帐户 pypi.org)

快速发布（自动）

使用发布脚本进行自动发布：

# Publish to PyPI (production)
python scripts/release.py 1.0.1

# Or using Make
make publish       # PyPI

脚本将自动执行以下操作：

更新版本号
运行测试和梳理
构建包
创建git标签
发布到PyPI

看 docs/PUBLISHING.md 详细说明。

手动构建和发布

更新版本 在 pyproject.toml:

[project]
version = "1.1.0"  # Increment appropriately

清理以前的构建:
```
rm -rf dist/ build/ *.egg-info
```
构建包:
```
python -m build
```
检查分布情况:
```
twine check dist/*
```
上传到PyPI:
```
twine upload dist/*
```

创建一个git标签:

git tag -a v1.1.0 -m "Release version 1.1.0"
git push origin v1.1.0

使用API令牌（推荐）

使用API令牌而不是用户名/密码：

在以下位置生成令牌 pypi.org/manage/account/token/

创建 ~/.pypirc:

[pypi]
username = __token__
password = pypi-AgEIcHlwaS5vcmc...

贡献

欢迎投稿！拜托：

分叉存储库
创建要素分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

致谢

黑客新闻 API
阿尔戈利亚为HN搜索提供动力
模型上下文协议规格

支持

在PyPI上可用: pip install hn-mcp-server

使用说明

HackerNews MCP服务器

特性

安装

来自PyPI（推荐）

来源

开发安装

快速开始

标准模式（本地桌面客户端）

与MCP检查员一起

使用VS代码MCP

带光标

使用Claude桌面版

HTTP/SSE模式（云部署）

独立使用

可用工具

搜索工具

search_hn

search_hn_by_date

get_front_page

get_latest_stories

get_latest_comments

search_by_time_range

search_by_metrics