finops-framework-mcp

finops-framework-mcp

三个非官方 MCP 服务，为 AI 助手提供结构化且附有来源的 FinOps 和 AI 成本指导，让助手依据发布方的原文和公式作答，而不是临场编造：

服务	涵盖内容	来源
finops-framework-mcp	FinOps 框架：能力、Crawl/Walk/Run 成熟度、KPI、角色	finops.org/framework
finops-focus-mcp	FOCUS 账单数据规范，按版本固定（1.0、1.2）	focus.finops.org
tokenomics-overview-mcp	AI 代币经济学：七层堆栈、Big-T 记法、提示词缓存指标、消耗杠杆（包括模型路由）、FOCUS 1.5 AI 成本	tokeneconomics.com

这三者都为只读（Agent 可以读取指导内容，但绝不能更改你的实践或数据），并且安装后可离线运行（运行时无需网络访问，也没有遥测）。你可以单独使用任意一个；配合使用则能涵盖最佳实践、证明实践成效的账单列，以及驱动 AI 代币成本的因素。

从这里开始：使用指南

aaronmsoto.github.io/finops-framework-mcp 是免费的免安装入门指南，面向 FinOps 从业者和工程师。它介绍各项服务的功能，演示如何在几分钟内将它们连接到 Claude，并通过五个示例逐步讲解，从分摊报告到判断提示词缓存是否值得投入。指南中的每个数字和引文都来自这些服务的实际运行。页面列表请参阅文档。

为什么要创建它

如果没有这些服务，询问 AI 助手“我们的成本分摊实践成熟度如何？”、“哪些 FOCUS 列可以计算有效节省率？”或“我们的提示词缓存是否值得投入？”，它都很可能编造出看似合理的答案。有了这些服务，每个回答都会采用发布方的原文和公式，以便助手读取的结构呈现，并附上来源 URL 和许可证。

服务必须自行推导的内容都会明确标注，绝不会冒充已发布的指导：

• FOCUS 服务的 KPI 到列映射、计算得出的 KPI 值以及跨版本差异，都会标记为非官方（official: false）。
• tokenomics 服务会在每个回答中说明各来源的发布状态，因为 Tokenomics Foundation 的大部分指导内容仍是工作草案或候选发布版。其整理的交叉映射表为非官方内容，且仅在设置 FINOPS_MCP_EXPERIMENTAL=1 时显示。
• framework 服务默认只提供官方内容：不会虚构能力之间的关系，也不会使用 Foundation 的 Crawl/Walk/Run 以外的成熟度级别。

快速入门

这三个包都发布在 npm 上，因此无需克隆或构建。每个包都自带数据，并可离线运行。唯一要求是 Node >= 22。

npx -y finops-framework-mcp
npx -y finops-focus-mcp
npx -y tokenomics-overview-mcp

（-y 会跳过 npx 首次运行时的安装提示，这个提示可能会导致非交互式 MCP 客户端卡住。例如，可通过 npx -y [email protected] 固定版本。）

Claude Code：

claude mcp add finops-framework -- npx -y finops-framework-mcp
claude mcp add focus-spec -- npx -y finops-focus-mcp
claude mcp add tokenomics-overview -- npx -y tokenomics-overview-mcp

Claude Desktop（claude_desktop_config.json）、项目范围的 .mcp.json，或任何 stdio MCP 客户端：

{
  "mcpServers": {
    "finops-framework": {
      "command": "npx",
      "args": ["-y", "finops-framework-mcp"]
    },
    "focus-spec": {
      "command": "npx",
      "args": ["-y", "finops-focus-mcp"]
    },
    "tokenomics-overview": {
      "command": "npx",
      "args": ["-y", "tokenomics-overview-mcp"]
    }
  }
}

环境变量（均为可选）：

变量	服务	作用
FINOPS_MCP_DATA	framework	使用本地刷新的数据文件，而非随包附带的 data/framework
FOCUS_MCP_DATA	FOCUS	同上，用于 data/focus
TOKENOMICS_MCP_DATA	tokenomics	同上，用于 data/tokenomics
FINOPS_MCP_EXPERIMENTAL=1	framework, tokenomics	启用明确标记为非官方的扩展功能：framework 解析出的成熟度 get_actions，以及 tokenomics 交叉映射

每个服务也接受作为首个 CLI 参数传入的数据目录，并会通过 --version 返回其包版本和数据版本（FOCUS：其提供服务的规范版本）。

使用方法

通过每个服务的入口启动会话，然后根据其建议继续操作：

服务	从此处开始	然后
framework	get_framework_info {}	search_framework、list_capabilities、get_capability（使用 include 控制大小）、get_kpis、assess_maturity_path
FOCUS	list_versions {}	search_focus、get_column、get_requirements、compare_versions、get_kpi_mapping、calculate_kpi
tokenomics	get_tokenomics_info {}	list_layers、get_bigt_notation、list_levers、get_metric、calculate_cache_metrics、get_crosslinks

每个服务都擅长回答的问题：

• Framework：“Walk 级预测需要满足什么要求？”、“Rate Optimization 的 Foundation 特性包含哪些 KPI？”、“异常管理中各自负责什么？”
• FOCUS：“1.2 中的 BilledCost 是什么意思？与 1.0 相比有哪些变化？”、“计算有效节省率需要哪些列？”
• Tokenomics：“模型路由和 AI 网关由哪个层负责？”、“这个 Agent 的令牌用量如何随自主程度变化？”、“我们的缓存读取、写入和未缓存输入令牌数分别为 X、Y、Z：缓存是否省钱？”

**配合使用。**这些服务分别发布，彼此之间不会互相调用。相反，答案会通过 URI 交接：tokenomics 服务的 35 个 get_crosslinks 链接都由 Tokenomics Foundation 页面中的原文引述支持，并附带 finops://framework/… 或 focus://spec/… URI，供 Agent 使用另外两个服务读取。FOCUS 1.5 工作草案中的名称尚未出现在任何已批准的版本中，因此不会返回 URI。提示词缓存示例展示了如何通过这三个服务回答一个问题。

服务端表面

• finops-framework-mcp：11 个工具——get_framework_info（入口点）、 search_framework、list_capabilities、get_capability、 get_maturity_assessment、get_kpis、assess_maturity_path、 map_personas、get_entity、get_maturity_model、get_changelog——以及 finops://framework/… 资源和 4 个提示词（explain-framework、 assess-capability-maturity、plan-maturity-roadmap、 map-personas-to-capabilities）。数据：6 项原则、3 个阶段、4 个领域、 22 项能力、11 种角色、5 个技术类别、Scopes 概念，以及一个包含 88 项的 KPI 库。
• finops-focus-mcp：9 个工具，用于查找列和属性、规范性要求、搜索、 1.0 → 1.2 差异，以及非官方的 KPI 到列映射，并支持基于示例数据计算 KPI； 此外还提供 focus://spec/… 资源和 3 个提示词。参见 packages/finops-focus-mcp。
• tokenomics-overview-mcp：20 个工具，涵盖文档、Seven-Layer Stack、Big-T 记法、杠杆、指标（含缓存指标计算器）、角色、价值分类、 FOCUS 1.5 AI 成本功能及交叉链接；此外还提供 tokenomics://overview/… 资源和 3 个提示词 （optimize_consumption、assess_prompt_caching、bigt_review）。数据：14 份源文档、7 个层、6 个 Big-T 类别、32 个杠杆、7 项指标、12 种角色、35 个已声明的交叉链接。参见 packages/tokenomics-overview-mcp。

三个服务端的全部提示词、资源和工具（名称、参数、URI、默认值 和限制）均根据实时 MCP 输出生成，详见 docs/mcp-surface.md。

远程选项：Cloudflare Worker

这三个服务端也都可以通过一个打包的 Cloudflare Worker（src/workers/， 端点 /mcp/framework、/mcp/focus 和 /mcp/tokenomics；参见 docs/deploy-worker.md）以 Streamable HTTP 方式运行。任何支持 Streamable HTTP 的 MCP 客户端都可以连接到已部署的 Worker， 例如：

claude mcp add --transport http tokenomics-overview "$WORKER_URL/mcp/tokenomics"

Worker 是无状态的，并提供每个服务端的默认表面（不含实验性工具）。demo/ 是一个静态浏览器页面，其中有两个演示流程："提示词缓存是否带来了收益？"（使用你自己的 token 数量，涵盖全部三个服务端）和费率优化（framework 和 FOCUS）。

构建方式

每个服务端都由相同的三个解耦部分组成，因此刷新内容无需修改代码：

crawler ──▶ data artifact ──▶ MCP server (stdio)
src/crawlers/<name>   data/<name>/   src/servers/<name>

其中 <name> 可以是 framework、focus 或 tokenomics。framework 和 tokenomics 爬虫遵循 fetch → parse → compose → derive → validate → emit 流程： content/markdown/ 是规范中间产物，由解析后的 HTML 组合而成；所有 JSON 文件 都通过离线 derive 步骤从中重新生成，因此修复 schema 或仅涉及 JSON 的问题无需重新爬取。它们的构建产物包含 JSON Schemas 和 sha256 清单，每个服务端都会在启动时验证其构建产物，并在发现问题时拒绝启动。FOCUS 爬虫则通过 git 标签摄取每个固定版本的规范发布内容，存入 data/focus/<version>/，派生的差异和 KPI 映射位于 data/focus/derived/。

framework 服务端早期的能力关系图 （get_prerequisites/get_related）经过构建和评估后，因其边未达到准确性标准而被删除； 参见 .agents/specs/v1-official-only.md。

刷新数据

npm run build
npm run refresh                                   # framework: crawl → artifact + diff report
node dist/crawlers/focus/cli.js                   # FOCUS: ingest the pinned spec tags (1.0, 1.2)
node dist/crawlers/tokenomics/cli.js refresh      # tokenomics: Tokenomics Foundation pages
node dist/crawlers/framework/cli.js derive        # framework: offline markdown → JSON, byte-identical
node dist/crawlers/tokenomics/cli.js derive       # tokenomics: same, for data/tokenomics

爬取过程遵循礼貌原则、使用缓存并遵守 robots 规则。上游没有变化时，构建产物会保持字节级一致，且不会提升版本号；内容发生变化时，则会添加变更日志条目并提升数据版本的 semver 版本号。tokenomics 刷新还会将找到但未摄取的页面（例如工作组草案）列在其清单的 unregistered 下。docs/proposed/refresh-data.yml 提供了定时刷新工作流；这里的 .github/workflows/ 是受保护路径，因此需由所有者安装：

git mv docs/proposed/refresh-data.yml .github/workflows/refresh-data.yml

数据版本管理策略

使用方通过固定软件包版本或此仓库的 git 引用来固定数据版本。每个 manifest.json 都包含 data_version、schema_version、crawled_at、逐文件 sha256 和实体数量；derived/changelog.json 记录版本之间的变更（由框架服务通过 get_changelog 提供）。会导致架构不兼容的变更需要提升 schema_version，并要求发布服务新版本。发布基于 v* 标签进行；参见 docs/release-runbook.md。

许可证与署名

代码：MIT（参见 LICENSE）。内容均采用 CC BY 4.0，经过重组和改编——所需的署名和修改声明请参见 NOTICE.md：

• data/framework/**：© FinOps Foundation
• data/focus/**：© FinOps Foundation / FOCUS 项目贡献者
• data/tokenomics/**：© Tokenomics Foundation（Series of LF Projects, LLC）

FinOps™、FinOps Foundation™ 和 FOCUS™ 是 FinOps Foundation 的商标。本项目独立运营，与 FinOps Foundation、FOCUS 项目或 Tokenomics Foundation 无关联，也未获其认可。

文档

docs/guide/ 是使用指南：共九个独立页面，其中每个数字、引述和转录内容均来自对这些服务的实时探测，或根据已提交的示例数据计算得出。它同时也是已发布的网站：.github/workflows/pages.yml 会在每次推送到 main 且涉及该目录时，将且仅将 docs/guide/ 部署到 https://aaronmsoto.github.io/finops-framework-mcp/（部署设置和冒烟测试见 docs/deploy-pages.md）。

页面	内容
简介与入门	三个服务并列介绍；安装、Claude Code / Claude Desktop / .mcp.json 配置、Worker 远程选项，以及对每个服务的首次调用
Framework MCP 参考	数据模型、按用途分组的全部 11 个工具、提示词和资源、分页，以及异常管理演示
FOCUS MCP 参考	版本模型、全部 9 个工具、focus:// 资源、BilledCost 深入讲解，以及 1.0→1.2 差异
Tokenomics MCP 参考	来源及其状态、Seven-Layer Stack 和 Big-T、全部 20 个工具、提示词、tokenomics:// 资源、交叉链接，以及模型路由和 AI 网关演示
Showback 报告	分配 + 报告与分析 → showback 所需的 FOCUS 列 → 根据官方示例计算出的报告
费率优化（ESR）	能力 → 精选 KPI → 1.0 与 1.2 的 FOCUS 列 → 根据官方示例计算的有效节省率
预测实践路径	迈向 Walk 级预测的成熟度路径：官方 Crawl/Walk 特征、KPI，以及为预测提供数据的来源
快速问答	一次会话中，针对框架和 FOCUS 服务进行的四次即兴实时提示词交互
提示词缓存是否有成效？	三个服务：框架的缓存命中率 KPI → Tokenomics 公式和针对两个工作负载的计算器 → 缓存 Token 数据在 FOCUS 1.2 和 1.5 中的位置

每个页面也可以通过 file:// 打开；指南不依赖外部资源。指南页面采用丰富的 HTML 格式，这是有意为之的设计，也是本仓库“文档使用 Markdown”惯例的例外；相关记录见 .agents/memory/decisions.md。

开发

• Agent 指南：AGENTS.md · 设计：docs/architecture.md （对抗性审查：docs/critique-1.md、docs/critique-2.md、 docs/critique-3-publish-gate.md、docs/critique-4-focus-gate.md、 docs/final-status-review.md）· 代币经济设计： docs/designs/tokenomics-overview-mcp.html
• 门禁：./scripts/agentic gates · 测试：npm test（基于 fixture，不访问 网络）· 评估：evals/framework/（docs/eval-results.md）
• 在克隆仓库中开发：已提交的 .mcp.json 会将全部三个服务加载到读取该文件的 MCP 客户端中，并通过 npx 运行已发布的软件包，因此全新克隆无需构建即可使用。若要改用工作树中的代码，请执行 cp .mcp.json.example .mcp.json 并先进行构建（dist/ 已被 git 忽略）， 然后重启客户端；客户端只会在启动时读取 MCP 配置。请参阅 CONTRIBUTING.md。
• 发布：docs/release-runbook.md。