README.md
An MCP server for the Horizon content aggregation and analysis pipeline.
Horizon MCP
面向 Horizon 的 MCP Server。
服务直接复用 Horizon 原生 Python 实现，按阶段暴露工具，不重复造业务逻辑。
1. 能力概览
工具（Tools）
hz_validate_config：校验 Horizon 配置有效性与关键环境变量是否齐全。hz_fetch_items：抓取并去重新闻内容，写入raw阶段。hz_score_items：调用 AI 对指定阶段内容打分，写入scored阶段。hz_filter_items：按分数阈值过滤并做主题去重，写入filtered阶段。hz_enrich_items：对高分内容执行背景富化，写入enriched阶段。hz_generate_summary：从指定阶段内容生成 Markdown 摘要。hz_run_pipeline：一键执行抓取、打分、过滤、富化、摘要全流程。hz_list_runs：列出最近 run 记录及各阶段产物状态。hz_get_run_meta：读取指定 run 的元数据。hz_get_run_stage：读取指定 run 的阶段内容（raw/scored/filtered/enriched）。hz_get_run_summary：读取指定 run 的摘要内容。hz_get_metrics：读取服务内存指标与调用统计。
资源（Resources）
horizon://server/infohorizon://metricshorizon://runshorizon://runs/{run_id}/metahorizon://runs/{run_id}/items/{stage}horizon://runs/{run_id}/summary/{language}horizon://config/effective
2. 前置要求
- Python 3.11+
- 本地可访问 Horizon 仓库（自动发现顺序）
$HORIZON_PATH./Horizon../Horizon/Users/Zhuanz/work-space/Horizon/tmp/Horizon
Horizon 配置文件存在：
<horizon_path>/data/config.json（可选）MCP 密钥配置文件（避免手动 export）：
.cursor/mcp.secrets.json.cursor/mcp.secrets.local.jsonconfig/mcp.secrets.jsonconfig/mcp.secrets.local.json<horizon_path>/data/mcp.secrets.json<horizon_path>/data/mcp-secrets.json
支持字段：
{
"OPENAI_API_KEY": "sk-xxxx",
"GITHUB_TOKEN": "ghp_xxxx"
}
也支持嵌套写法：
{
"env": {
"OPENAI_API_KEY": "sk-xxxx",
"GITHUB_TOKEN": "ghp_xxxx"
}
}
3. 安装与启动
cd /Users/Zhuanz/work-space/Horizon-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e .
# stdio 启动（给 MCP 客户端使用）
horizon-mcp
4. 运行产物
每次 run 会写入：data/mcp-runs/<run_id>/
meta.jsonraw_items.jsonscored_items.jsonfiltered_items.jsonenriched_items.jsonsummary-<lang>.md
5. 设计原则
- 默认无外部副作用：不自动写 Horizon docs、不自动发邮件。
- 阶段可重入：同一
run_id可分步执行。 - 保持主逻辑一致：抓取、评分、富化、总结全部复用 Horizon 原生模块。
6. 客户端接入
接入示例见：docs/integration.md
快速连通检查：
cd /Users/Zhuanz/work-space/Horizon-mcp
make check-mcp
7. Git 身份（当前仓库）
本仓库已设置：
user.name=henry-insomniacuser.email=lovedangdang@outlook.com
Tools (12)
hz_validate_configValidates Horizon configuration and checks for required environment variables.hz_fetch_itemsFetches and deduplicates news content, writing to the raw stage.hz_score_itemsCalls AI to score content at a specified stage and writes to the scored stage.hz_filter_itemsFilters content by score threshold and performs topic deduplication.hz_enrich_itemsExecutes background enrichment for high-scoring content.hz_generate_summaryGenerates a Markdown summary from content at a specified stage.hz_run_pipelineExecutes the full pipeline: fetching, scoring, filtering, enrichment, and summary.hz_list_runsLists recent run records and the status of each stage.hz_get_run_metaReads metadata for a specific run.hz_get_run_stageReads content from a specific stage of a run.hz_get_run_summaryReads the summary content for a specific run.hz_get_metricsReads service memory metrics and call statistics.Environment Variables
HORIZON_PATHPath to the local Horizon repository.OPENAI_API_KEYrequiredAPI key for AI-based scoring and summarization.GITHUB_TOKENGitHub token for enrichment tasks.Configuration
claude_desktop_config.json
{"mcpServers": {"horizon": {"command": "horizon-mcp", "env": {"HORIZON_PATH": "/path/to/Horizon"}}}}Try it
→Run the full Horizon pipeline to fetch, score, and summarize the latest news.
→List my recent Horizon runs and check the status of the latest one.
→Get the summary for the most recent run.
→Fetch new items and then score them using the AI pipeline.