FreshContext

FreshContext

此软件包已停止开发。 0.5.3 是 freshcontext-mcp 的最后一个版本。 此版本及所有早期版本仍按原样依据 MIT License 提供；不会再发布功能更新。有关 FreshContext 服务，请访问 https://freshcontext.dev。 安全问题报告：请参阅 SECURITY.md。

我请 Claude 帮我找工作。它给了我一份职位列表。我申请了其中三个。两个职位已经不存在了。另一个两年前就已关闭。

Claude 完全不知道这些情况。它用同样笃定的语气呈现了所有信息。

这正是 freshcontext 要解决的问题。

此仓库是集成版 FreshContext Core/MCP 软件包。

类别：上下文完整性基础设施。 FreshContext 位于上下文获取与 Agent 行动之间。它负责判断进入 AI 工作流的信息是否足够新鲜、可追溯且连贯，能否供系统信赖。Core 是一个可复用引擎，用于评分、排序、解释并将候选上下文转化为可用于决策的上下文，同时将签名判定记录在可验证的账本中。MCP 是该引擎的首个实时宿主接口——它只是方法论的一个接口，并非产品本身。

在线演示： api.freshcontext.dev/demo — 相同模型、相同查询，却给出截然不同的答案。唯一改变的是时间层。

集成到现有技术栈： freshcontext.dev/integration — 从一个范围明确的 RAG、Agent、检索或治理工作流开始，并设定客观的验收标准。

---

问题

大模型会根据语义检索网络数据。余弦相似度能找出与查询最匹配的文档，但它不知道文档是什么时候写的。

因此，一篇 2022 年的博客文章和一篇 2026 年的论文可能得到几乎相同的分数。模型的上下文窗口里充满了过时文档，于是它会忠实地总结 2022 年的建议来回答 2026 年的问题。

这不是幻觉，而是对已受污染检索结果的正确总结。

大多数 RAG 流水线在语义上正确地对上下文排序，却在时间上排序错误。

---

这一层

FreshContext 是面向 AI Agent 和检索系统的上下文完整性基础设施。它位于检索与推理之间：

candidate context
  -> FreshContext Core
  -> decision-ready context
  -> model / agent / app

在上下文到达 LLM 之前，FreshContext 会评估新鲜度、来源画像、置信度、实用性、溯源材料以及对失败的坦诚程度。时间核心采用衰减调整相关性（DAR）：

R_t = R_0 · e^(−λt)

• R_0 — 基础语义相关性（即检索器已有的评分）
• λ — 特定来源的衰减常数（HN ≈14h 半衰期，博客 ≈29d，学术论文 ≈1.6y）
• t — 自发布以来经过的小时数
• R_t — 查询时经过衰减调整的相关性

这是核心校正。无需更换模型、重新嵌入或重新索引。这一层可直接接入你现有的任意检索流水线。

这一层就是产品。 此仓库附带的具名适配器展示了它对不同来源类别的兼容性。DAR 引擎、新鲜度信封、Source Profiles 和 FreshContext Specification 才是核心壁垒。

---

标准

每个兼容 FreshContext 的响应都会将内容封装在一个结构化信封中：

[FRESHCONTEXT]
Source: https://github.com/owner/repo
Published: 2024-11-03
Retrieved: 2026-03-05T09:19:00Z
Confidence: high
---
... content ...
[/FRESHCONTEXT]

何时检索到。来自何处。我们对日期准确性的置信度。

FreshContext Specification v1.2 已依据 MIT 许可证作为开放标准发布。任何将检索数据封装在此信封中的工具、Agent 或系统都兼容 FreshContext。→ 阅读规范 · 阅读方法论

---

架构边界

FreshContext Core 是当前集成包中可复用的核心。它负责信号规范化、新鲜度评分、Source Profiles、决策输出、信封格式化、故障防护、共享类型、排名／解释基元，以及上下文条件化效用基元。

MCP 是基于 Core 的主要参考实现／接口。支持 Claude Desktop，但并非必需。MCP 工具界面提供具名参考适配器，以及用于使用该系统的实时接口。

生产环境中的 Cloudflare Worker 现在使用基于 Core 的信封生成。Worker 特有的关注点仍位于 Core 之外：MCP 传输、运行时防护、KV 缓存策略、缓存元数据注入、JSON 解析／替换缓存辅助工具、D1 数据源、cron、速率限制，以及 Store／数据源评分与来源追踪。

有关层级边界、包接口，以及尚未拆分的部分，请参阅 架构。

Core 导入路径

也可以直接从当前 MCP 包使用 FreshContext Core：

import {
  evaluateSignals,
  interpretEvaluations,
  getSourceProfile,
  normalizeSignal,
  calculateHaPriV2,
} from "freshcontext-mcp/core";

这是 freshcontext-mcp 中的 Core 子路径导出，目前还不是独立的 freshcontext-core 包。根包和 freshcontext-mcp 二进制文件仍是 MCP 参考主机。

---

主要 MCP 接口

最清晰的 MCP 使用路径是 evaluate_context。

它接受来自任何检索器、Agent、数据库、本地脚本、笔记解析器或适配器输出的候选上下文：

{
  "profile": "academic_research",
  "intent": "citation_check",
  "signals": [
    {
      "title": "Example source",
      "content": "Candidate context text...",
      "source": "https://example.com/source",
      "source_type": "arxiv",
      "published_at": "2026-05-24T12:00:00.000Z",
      "retrieved_at": "2026-05-24T13:00:00.000Z",
      "semantic_score": 0.92
    }
  ]
}

FreshContext 返回以决策为先的输出：

• 决策
• 含义
• 操作
• 警告
• 来源
• 新鲜度
• 排名分数
• 效用
• 置信度
• 原因

结构化结果还包含一个面向用户的 readable 对象：

{
  "decision": "cite_as_primary",
  "label": "Cite as primary",
  "readable": {
    "label": "Primary source",
    "summary": "This source is strong enough to use as main evidence.",
    "why": [
      "Strong semantic match and current freshness for arxiv.",
      "source profile academic_research uses lenient date policy",
      "intent profile citation_check selected"
    ],
    "action": "Use this as main evidence while preserving citation and provenance.",
    "warnings": [
      "FreshContext judges citation readiness and context usefulness; it does not certify truth."
    ]
  }
}

readable 对象会将 Core 决策转换成面向用户的语言。它不会改变排名、决策标签、效用评分或来源接收方式。效用有助于说明内容对当前问题的用处；它仅用于解释，不会控制默认决策标签或排名。

FreshContext 不会认证事实真伪。它会在上下文送达模型之前，记录其被使用、支持、质疑、刷新、关注或排除的原因。

evaluate_context 不会获取 URL、抓取网页、浏览内容、读取文件夹或调用适配器。它只评估调用方提供的候选上下文。

当前边界：evaluate_context 随 npm／本地 stdio MCP 服务一起发布。托管的 Cloudflare Worker MCP 端点是独立的部署接口，会单独验证——请检查 /v1/health 获取其实时版本和工具数量，不要假定它与该包保持一致。Worker 仍是独立的部署接口，因此在宣称未来的包接口已在线运行之前，应先远程重新验证。

网络边界

FreshContext 的主要 evaluate_context 路径不会获取内容、抓取网页、浏览内容、读取文件夹或调用适配器。MCP 包还包含只读参考适配器，仅在调用这些适配器工具时才会使用网络。因此，供应链扫描器可能会报告该包存在网络访问；这适用于可选的适配器接口，而不适用于对调用方提供的上下文进行评估。

---

高级 Worker／数据源接口

除了按调用运行的 Core／MCP 路径外，生产环境中的 Worker 部署还会提供持续更新、按衰减评分并去重的数据流。这是高级部署接口，并非使用 FreshContext Core 的必需方式：

GET /v1/intel/feed/:profile_id?limit=20&min_rt=0

每个信号都带有 base_score、rt_score、entropy_level（low／stable／high）、ha_pri_sig（Ha-Pri v1 SHA-256 来源追踪引用）、semantic_fingerprint（跨适配器去重标识）和 published_at。可直接供大模型或 Agent 使用——无需合成处理。

生产环境端点：https://api.freshcontext.dev

---

参考适配器

该仓库提供具名参考适配器，用于演示不同来源类别如何转换为与 FreshContext 兼容的格式。每个适配器都保留自己的名称，因为它代表一个来源边界；适配器数量是运行层面的证明，并非产品宣传重点。

情报

适配器	返回内容
extract_github	README、星标数、复刻数、语言、主题、最后一次提交
extract_hackernews	热门故事或搜索结果，包含评分和时间戳
extract_scholar	研究论文——标题、作者、年份、摘要片段
extract_arxiv	通过官方 API 获取 arXiv 论文
extract_reddit	任意 subreddit 的帖子和社区情绪

竞争研究

适配器	返回内容
extract_yc	按关键词筛选的 YC 公司列表
extract_producthunt	按主题筛选的近期发布产品
search_repos	按星标数排序并包含活跃度信号的 GitHub 仓库
package_trends	npm 和 PyPI 元数据——版本历史、发布频率

市场数据

适配器	返回内容
extract_finance	无需密钥的 Stooq 报价数据——收盘价、OHLC、成交量、报价时间戳、来源。最多支持 5 个股票代码。
search_jobs	来自 Remotive、RemoteOK、HN "Who is Hiring" 的远程职位列表

组合数据——一次调用获取多个来源

适配器	来源数	用途
extract_landscape	6	并行获取 YC + GitHub + HN + Reddit + Product Hunt + npm
extract_idea_landscape	6	HN + YC + GitHub + Jobs + npm + Product Hunt——全面验证创意
extract_gov_landscape	4	政府合同 + HN + GitHub + 更新日志
extract_finance_landscape	5	金融 + HN + Reddit + GitHub + 更新日志
extract_company_landscape	5	全面了解任意公司

官方、监管和采购来源

适配器	来源	返回内容
extract_changelog	GitHub Releases / npm / 自动发现	任意仓库、软件包或网站的更新历史
extract_govcontracts	USASpending.gov	美国联邦合同授予信息——公司、金额、机构、期限
extract_sec_filings	SEC EDGAR	8-K 文件——法律要求披露的重大事件
extract_gdelt	GDELT Project	全球新闻情报——100 多种语言，每 15 分钟更新
extract_gebiz	data.gov.sg	新加坡政府采购招标——开放数据集

---

快速开始

有关 Claude Desktop、Codex、npx、全局 npm 和源代码检出配置，请参阅简明的客户端配置指南。

云端（无需安装）

添加到 Claude Desktop 配置并重启：

Mac： ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "freshcontext": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.freshcontext.dev/mcp"]
    }
  }
}

重启 Claude。完成。

想要按照引导进行配置？访问 freshcontext.dev——3 步完成，无需使用终端。

本地（完整 Playwright）

要求： Node.js 20+（nodejs.org）

git clone https://github.com/PrinceGabriel-lgtm/freshcontext-mcp
cd freshcontext-mcp
npm install
npx playwright install chromium
npm run build

添加到 Claude Desktop 配置：

Mac：

{
  "mcpServers": {
    "freshcontext": {
      "command": "node",
      "args": ["/Users/YOUR_USERNAME/path/to/freshcontext-mcp/dist/server.js"]
    }
  }
}

Windows：

{
  "mcpServers": {
    "freshcontext": {
      "command": "node",
      "args": ["C:\\Users\\YOUR_USERNAME\\path\\to\\freshcontext-mcp\\dist\\server.js"]
    }
  }
}

Mac 故障排查

“command not found: node”——使用完整路径：

which node  # copy this output, replace "node" in config

配置文件不存在：

mkdir -p ~/Library/Application\ Support/Claude
touch ~/Library/Application\ Support/Claude/claude_desktop_config.json

---

使用示例

以下 npm run demo:* 命令适用于贡献者和评估者从克隆的仓库中运行的源代码检出工作流。已发布的 npm 软件包是 MCP 服务/运行时软件包，不包含仅供仓库使用的源代码示例或测试。

从已安装的 npm 软件包运行时，受支持的入口点为 npm start 和 freshcontext-mcp 二进制文件。如果缺少对应源文件，仅供仓库使用的脚本（例如测试、演示、冒烟检查和信任扫描）会显示源代码检出提示。

Apify Actor 入口点仍可在源代码检出中使用，以单独打包 Actor，但它不会包含在已发布的 MCP npm 运行时软件包中。

发布信任门

在发布、审查软件包、演示或审查 PR 之前，运行本地发布门：

npm run trust:gate

该门会运行 Trust Scanner，并生成仓库映射报告、检查 npm 软件包边界、执行确定性声明检查，以及使用 --fail-on fail。它仅在本地运行，不会发布或部署，不会发送遥测数据，也不能替代专用安全扫描器。

需要可分享的摘要时，生成审查报告：

npm run trust:report
npm run trust:report:json

要明确写入 Markdown 报告文件：

npm run trust:report -- --output TRUST_SCAN_REPORT.md

使用自己的来源列表

FreshContext 可以评估你通过本地 JSON 文件提供的候选上下文：

npm run demo:evaluate:file

要传入其他文件：

npm run demo:evaluate:file -- path/to/sources.json

随附示例：

npm run demo:evaluate:file -- examples/sources.academic.example.json
npm run demo:evaluate:file -- examples/sources.jobs.example.json

最简格式：

{
  "profile": "academic_research",
  "intent": "citation_check",
  "signals": [
    {
      "title": "...",
      "content": "...",
      "source": "...",
      "source_type": "arxiv",
      "published_at": "...",
      "retrieved_at": "...",
      "semantic_score": 0.92
    }
  ]
}

此本地演示不会获取 URL、抓取网页或读取文件夹。它会评估你提供的候选上下文，并优先返回决策结果：Decision、Meaning、Action、Warnings 和支持性指标。

在 MCP 客户端中，如果你已从其他检索器、数据库、Agent 或脚本获得候选上下文，请使用 evaluate_context：

Use evaluate_context with profile "academic_research", intent "citation_check", and these candidate signals: [...]

如果希望 FreshContext 当前的 MCP 软件包为你获取公开来源示例，请使用命名参考适配器。

我应该构建这个创意吗？

Use extract_idea_landscape with idea "procurement intelligence saas"

返回资金信号、痛点信号、竞争拥挤度信号、市场信号、生态系统信号和发布信号——全部附带时间戳。

一次调用获取完整的公司情报：

Use extract_company_landscape with company "Palantir" and ticker "PLTR"

SEC 文件 + 联邦合同 + 全球新闻 + 更新日志 + 市场数据。

这家公司刚刚披露了重大信息吗？

Use extract_sec_filings with url "Palantir Technologies"

法律规定，任何重大事件发生后 4 个工作日内必须提交 8-K 文件——例如 CEO 更换、收购、数据泄露或重大合同。

这个依赖项仍在积极维护吗？

Use extract_changelog with url "https://github.com/org/repo"

返回最近 8 次发布的确切日期。如果上次发布是 18 个月前，你就能在固定版本之前了解这一点。

---

部署与基础设施

参考实现运行在 Cloudflare 的全球边缘网络上：

端点	方法	用途
/	GET	服务信息 + 端点列表
/health	GET	存活状态检查
/mcp	POST	MCP JSON-RPC 传输
/demo	GET	实时前后对比演示（无需身份验证令牌）
/briefing	GET	最新存储的简报
/v1/intel/feed/:profile_id	GET	DAR 评分的情报信息流
/watched-queries	GET	列出所有监控查询
/.well-known/freshcontext-signing-keys.json	GET	已发布的 Ed25519 验证密钥（当前密钥 + 已停用密钥）

• D1 数据库 — 18 条监控查询，每 6 小时运行一次，并进行相关性评分
• 基于 KV 的速率限制 — 所有边缘节点上每个 IP 每分钟 60 个请求
• 防护阀 — 拒绝时钟偏差（容差 5 分钟），R_t<5 时设置硬性下限，在读取时进行惰性衰减
• 来源可追溯性 — 信息流信号仍携带旧版 Ha-Pri v1 SHA-256 来源引用；此外，基于账本的上下文判定使用 Ed25519 V4 签名，并可独立验证
• 架构迁移 — 由 Promise 控制、具有幂等性，并在部署后的首次请求时运行

生产环境：https://api.freshcontext.dev

---

部署模式

引擎刻意设计为可与其接入界面分离。同一个 Core 无需重写，即可在以下每种模式中运行：

模式	含义
独立运行	FreshContext 作为独立的上下文完整性服务运行，与目前相同。
嵌入式子系统	Core 在现有的 AI、数据或安全平台内部运行，对该平台的用户不可见。
SDK / API	以编程方式使用完整性原语；不涉及 MCP。
MCP 基础设施层	FreshContext 在启用 MCP 的工作流周围评估并治理上下文——这是本仓库当前的实际运行路径。
网关 / 控制平面组件	Core 在策略边界运行，在上下文进入 Agent 执行之前进行处理。
白标	引擎以另一款产品的品牌和 API 呈现。

目前只有 MCP 和独立运行模式在生产环境中实际使用。其他模式是架构已支持的集成接口，并非已发布的配置。

---

路线图

拆分为三部分，确保真正的工程风险绝不会被归为可选项。生产核心之外的内容均不代表当前产品能力。

生产核心 — 已构建、运行并可测试

• 已发布 FreshContext Specification v1.2（MIT，开放标准）
• DAR 引擎，使用针对来源的 lambda 常量
• 已存储信号上的 Ha-Pri v1 来源签名
• Ha-Pri v2 Core helper 和确定性黄金向量
• 公共 /v1/verify 端点 — 基于账本验证判定结果，既支持旧版 HMAC 路径，也支持 Ed25519，并通过 verification_method 报告所用方法
• 通用 MCP evaluate_context 工具，用于评估调用方提供的候选上下文
• Core 支持的信封生成，在 npm/MCP 与 Cloudflare Worker 之间共享
• 通过指纹进行语义去重
• 覆盖情报、竞争研究、市场数据和复合数据的命名引用适配器
• Cloudflare Workers 部署 — 全球边缘节点、KV 缓存、原子限流
• /demo 上的实时前后对比演示
• METHODOLOGY.md — 方法论和工程文档
• 已发布到 npm 并列入 MCP 用途清单；Apify/feed 资源与 MCP 运行时软件包分开
• 可信发布工作流 — 仅手动触发 workflow_dispatch，基于 OIDC、启用来源证明，并受版本/验证检查把关。一次明确的运行会先发布 npm 并验证，然后通过 GitHub OIDC 将匹配的清单发布到官方 MCP Registry
• 可独立验证的 Ed25519 证明（E-2）。 账本中的每条新判定记录都使用 Ed25519 签名为 FRESHCONTEXT_HA_PRI_V4。第三方无需 FreshContext 账户、API 密钥，也无需调用 FreshContext，即可验证判定结果 — 只需使用 Worker 在 /.well-known/freshcontext-signing-keys.json 发布的密钥文档，以及 npm tarball 中随附的任一验证器：scripts/verify-offline.mjs（Node，标准库）或 scripts/verify_offline.py（Python，完全无依赖）。面向怀疑者而非维护者编写的说明见 VERIFYING.md。
• 签名密钥 fc-2026-09-ceced1ab 已发布并启用。密钥仅追加，因此轮换密钥不会使使用已退役密钥签名的判定结果失效。
• attestation-proof.yml — 获取实时判定结果，使用两个随附的验证器进行验证，运行篡改载荷和篡改签名的负向测试，并确认存储的账本记录为 V4，而不只是发出的响应块。支持按需运行和每日运行；使用的所有输入均为公开信息，因此无需凭据即可运行。

核心仍在进行中，不属于扩展范围：

• 对已存储信号实施 Ha-Pri v2 Worker/D1 生产强制验证 — feed 记录仍带有 Ha-Pri v1 SHA-256 印记。这与上方的判定账本是独立路径：当前判定结果为 V4/Ed25519，信号则不是。设计文档已完成；信号路径上的强制防篡改尚未启用。

扩展方向——刻意留白，尚未构建

这些是架构支持、引擎尚未实现的集成接口。特意使用将来时态描述。

• 上下文安全防护机制。 在上下文到达 Agent 之前执行策略：通过／警告／刷新／隔离／阻止，并为每项决策附上证据。目前，evaluate_context 会生成决策和警告；但尚不存在执行状态机——代码库中没有任何地方实现 quarantine 和 block。
• 企业控制平面。 用于查看源健康状态、信任评分、上下文漂移和溯源链路的仪表板。判定账本是该仪表板读取的数据契约；界面尚未构建。
• 可观测性遥测。 历史完整性状态、事件、上游降级情况和修复历史。
• 自主修复。 自动刷新、替换来源并重新评估——形成闭环，而非仅检测。
• 垂直领域策略包。 面向受监管工作流的领域专属完整性阈值。
• Webhook 触发器——达到阈值时推送高熵信号

研究前沿——探索，而非承诺

• 为 extract_gdelt 升级 GKG——语气评分、Goldstein 量表、事件代码
• 检测并发来源之间的矛盾

未来工作按 FreshContext 未来方向 组织。路线图项目在实现并验证之前，不代表现行产品能力。

---

贡献

欢迎提交 PR。最有价值的贡献包括改进调用方提供的上下文路径、决策输出、宿主集成，以及与 FreshContext 兼容的信号质量。只要新的参考适配器能够保留来源边界，并输出带时间戳、如实反映失败情况的上下文，它们就很有用——示例见 src/adapters/，兼容性约定见 FRESHCONTEXT_SPEC.md。

如果你正在构建与 FreshContext 兼容的项目，请提交 issue，我们会将你添加到生态列表中。

---

信任与安全

• 许可证
• SECURITY.md
• NOTICE.md
• TRADEMARKS.md
• 依赖项审查说明
• 发布完整性说明
• 发布说明

---

许可证

MIT

---

由 Immanuel Gabriel 构建——纳米比亚 🇳🇦 “工作并未消失，只是在等待继续。”

---

也可在以下平台找到： MCP 注册表 · npm