HN Pulse

HN脉冲


A. 黑客新闻MCP服务器 建造于 街机mcp，再加上一个使用它的克劳德动力研究代理。

HN Pulse允许任何兼容MCP的AI助手（Claude Desktop、Cursor、VS Code）直接读取黑客新闻——头条新闻、搜索、评论、用户资料、工作列表、Ask HN和Show HN——所有这些都是通过公共HN Firebase和Algolia API实现的。服务器不需要API密钥。

______________________________________________________________________

它的作用

HN脉冲MCP服务器 --8个工具：

HN获取MCP服务器 --1个辅助工具（第二次维修）：

包括 研究代理人 用Claude封装这些工具来回答自然语言查询，例如：

• *“HN社区对2025年的Rust有什么看法？”*
• *“查找最近的AI创业公司招聘信息”*
• *“总结本周最受欢迎的Show HN项目”*
• *“用户pg的about部分是什么？”*

______________________________________________________________________

建筑

User → agent/agent.py ──stdio──► src/hn_pulse/server.py
                                        │
                          ┌─────────────┼─────────────────┐
                          ▼             ▼                   ▼
              HN Firebase API    Algolia HN Search    (no auth needed)
          hacker-news.firebaseio.com  hn.algolia.com/api/v1

代理将MCP服务器作为子进程生成，通过stdio传输连接，然后使用 LangGraph 的 create_react_agent 和 langchain-mcp-adapters 将MCP工具桥接到标准ReAct循环中：Claude选择一个工具→ 代理通过MCP调用它→ 结果反馈给克劳德→ 循环直到完成。

会话状态 在交互模式下，通过LangGraph的 MemorySaver 检查指针——代理会记住它在同一会话中早些时候说的话。每个会话都会获得一个UUID thread_id单次模式总是会启动一个新的线程。

多业务：当 ENABLE_FETCH=1 设置后，代理还连接到HN Fetch MCP服务器，允许Claude从任何HN故事URL读取完整的文章内容。

______________________________________________________________________

先决条件

• Python 3.10+
• 紫外线 — brew install uv
• Anthropic API密钥-仅用于研究代理

______________________________________________________________________

安装

git clone https://github.com//hn-pulse.git
cd hn-pulse

# Create virtual environment and install all dependencies
uv venv
uv pip install -e ".[agent,dev]"

# Copy env template
cp .env.example .env
# Edit .env and set ANTHROPIC_API_KEY (only needed for the agent)

______________________________________________________________________

运行MCP服务器

stdio传输（适用于Claude Desktop、CLI工具）

uv run src/hn_pulse/server.py stdio
# or simply:
uv run src/hn_pulse/server.py

HTTP传输（用于游标、VS代码）

uv run src/hn_pulse/server.py http
# API docs available at http://127.0.0.1:8000/docs

连接到克劳德桌面

# Install arcade CLI if you haven't already
uv tool install arcade-mcp

# Auto-configure Claude Desktop to use this server
arcade configure claude

______________________________________________________________________

运行研究代理

本地模式（默认--服务器作为子进程生成）

# Interactive mode — stateful (agent remembers the conversation)
python agent/agent.py

# One-shot mode
python agent/agent.py "What are people saying about Rust in 2025?"

# One-shot with structured output (pipeline-composable)
python agent/agent.py "Summarise top AI stories" --output report.md
python agent/agent.py "What's trending?" --json

# Enable multi-service: also connect the URL fetch server
ENABLE_FETCH=1 python agent/agent.py "What does the top HN story say?"

代理通过stdio自动生成MCP服务器作为子进程。

远程模式（服务器在另一台机器上）

在远程计算机上启动服务器，绑定到所有网络接口：

# On the remote machine (replace 8000 with your preferred port)
uv run src/hn_pulse/server.py http --host 0.0.0.0 --port 8000

然后使用以下命令将代理指向它 MCP_SERVER_URL:

# On the client machine
export MCP_SERVER_URL=http://:8000/mcp/
python agent/agent.py "What's trending on HN today?"

当发生以下情况时，代理会自动从stdio切换到HTTP传输 MCP_SERVER_URL 已设置--无需更改代码。MCP端点始终位于 /mcp/.

Docker部署（两种服务）

# Build and start both MCP servers as containers
docker compose up --build

# Run the agent against the deployed services
MCP_SERVER_URL=http://localhost:8000/mcp/ \
HN_FETCH_URL=http://localhost:8001/mcp/ \
ANTHROPIC_API_KEY=sk-... \
python agent/agent.py "Summarise the top story and read its full article"

docker-compose.yml 启动两个服务： hn-server （端口8000）和 fetch-server （端口8001），每个端口都有健康检查。两者都是用同样的材料建造的 Dockerfile.

______________________________________________________________________

克劳德编程技能

如果您正在使用 克劳德代码，克隆后有两个斜线命令可用：

示例：

/hn-research What are people saying about Rust in 2025?
/run-evals
/run-evals unit
/run-evals eval

这两种技能都需要检查 ANTHROPIC_API_KEY 如果缺少，请打印清晰的修复说明。技能定义见 .claude/commands/.

______________________________________________________________________

运行测试

# Unit tests — zero API cost, mocked HTTP
pytest tests/unit/ -v

# Integration tests — starts the real server, zero API cost
pytest tests/integration/ -m integration -v

# Eval tests — requires ANTHROPIC_API_KEY, ~$0.002 total (uses claude-haiku)
pytest tests/evals/ -m eval -v

# All tests except evals
pytest -m "not eval" -v

或者使用 生成文件 快捷方式：

make install       # install all deps
make test          # unit + integration (no API key needed)
make test-eval     # eval tier only (requires ANTHROPIC_API_KEY)
make lint          # ruff check
make typecheck     # mypy
make check         # lint + typecheck + test (full local CI)

测试覆盖率

______________________________________________________________________

项目结构

hn-pulse/
├── .claude/
│   └── commands/
│       ├── hn-research.md     # /hn-research — runs the research agent
│       └── run-evals.md       # /run-evals — three-tier test runner
├── .github/
│   └── workflows/
│       └── ci.yml             # CI: lint + typecheck + tests on PR; evals on main
├── src/
│   ├── hn_pulse/
│   │   ├── server.py      # MCPApp entrypoint — registers all 8 tools
│   │   ├── client.py      # httpx client factory (HN + Algolia)
│   │   ├── types.py       # TypedDict definitions (Story, SearchResponse, …)
│   │   └── tools/
│   │       ├── common.py  # Shared fetch_item, gather_items, constants
│   │       ├── stories.py # get_top_stories, get_new_stories
│   │       ├── item.py    # get_story_details
│   │       ├── search.py  # search_stories (Algolia)
│   │       ├── users.py   # get_user_profile
│   │       └── specials.py # get_job_listings, get_ask_hn, get_show_hn
│   └── hn_extras/
│       ├── fetch.py       # fetch_article tool (HTML → plain text)
│       └── server.py      # Second MCPApp — URL article fetcher
├── agent/
│   └── agent.py           # Stateful LangGraph agent — multi-service, --output/--json
├── tests/
│   ├── unit/              # pytest-httpx mocked tests (51 total, incl. error scenarios)
│   ├── integration/       # real MCP server startup tests
│   └── evals/             # Claude tool-selection accuracy tests
├── docs/
│   ├── spec.md            # Spec-driven development prompt to recreate this project
│   └── systems-design.html # Architecture diagram + design trade-offs
├── Dockerfile             # Single image for both MCP servers
├── docker-compose.yml     # hn-server (8000) + fetch-server (8001)
├── Makefile               # make check, make test, make lint, make typecheck
├── .pre-commit-config.yaml
├── pyproject.toml
└── .env.example

______________________________________________________________________

设计说明

作为普通异步函数的工具：每个工具都是一个普通的Python async def --没有框架装饰器。他们已注册 app.add_tool() 在 server.py这使得单元测试变得微不足道：调用 await get_top_stories(count=5) 直接无需MCP服务器。

并发项目获取：HN Firebase API仅从提要终结点返回ID数组。天真地获取N个故事需要N次连续的往返。所有工具使用 asyncio.gather() 并行获取项目，无论计数多少，都将延迟减少到约2次往返。

Algolia元数据剥离：Algolia搜索结果包括 _highlightResult, children （注释ID数组）和使LLM上下文膨胀的其他元数据。 _clean_hit() 在返回之前剥离这些数据，将每个结果从约2KB减少到约200字节。

共享助手 (tools/common.py): fetch_item 和 gather_items 是所有提要工具使用的单一规范实现，没有重复的私有助手。常量(MAX_STORY_COUNT等）生活在这里，所以神奇的数字永远不会出现在工具文件中。

LangGraph代理: agent/agent.py 用途 create_react_agent 来自LangGraph MultiServerMCPClient 从 langchain-mcp-adapters --ArcadeAI参考项目使用的相同模式。 MemorySaver + thread_id 为交互代理提供跨回合的持久对话记忆。

多服务编排: MultiServerMCPClient 连接到两者 hn_pulse 和 hn_fetch 同时。代理可以在HN中搜索故事，然后在单个推理循环中获取完整的文章——每个服务独立地位于本地或远程。

结构化交付成果: --output report.md 编写格式化的Markdown报告； --json 打印结构化有效载荷(query, answer, tools_used, timestamp)用于下游管道消耗。

集装箱化的: Dockerfile + docker-compose.yml 将两个MCP服务器部署为具有健康检查的隔离容器。 docker compose up --build 取代了整个手动venv/install流程。

有关用于构建此项目的完整规范（适用于用AI编码代理复制它），请参阅 docs/spec.md.

______________________________________________________________________

外部资源和归属

• 黑客新闻API -Firebase REST API（公共，无身份验证）
• Algolia HN搜索API --全文搜索（公开，无身份验证）
• 街机mcp --MCP服务器框架
• Anthropic Python SDK -API客户
• mcp Python SDK --MCP协议客户端

______________________________________________________________________

许可证

麻省理工学院