奇链 奇链
← 教程库
进阶 约 20 分钟 2026-10-08 17:31:12 · 2 阅读

Oh My Posh 配置校验 MCP 实操：一个 URL 接入，curl 也能直接调

终端提示符配置写错，以前只能靠肉眼找

Oh My Posh 是那类装上就回不去的工具：Windows、macOS、Linux 上都能用，把 PowerShell、zsh、bash 的提示符换成带 Git 分支、执行耗时、内存占用的彩色主题。代价是配置文件——一份 JSON（或 YAML、TOML），字段多、层级深，写错一个属性名，轻则段落不渲染，重则整个主题加载失败。官方文档站为此上线了一个 MCP 校验服务器：把配置原文发给它，它按官方 JSON Schema 逐字段检查，错误定位到 JSON 路径。这篇把接入和调用一次讲透，文中的每段返回结果都在官方端点上实际跑通过。

和需要本地装包的 MCP 服务器不同，这个校验器是远程 HTTP 服务，不装任何东西，加一行 URL 就能用。仓库本身在 GitHub 有 23.5k star（2026-10-08 实时 23564），最新版本 v31.5.0（2026-10-06 发布）。

它校验的是什么

Oh My Posh 的主题是一份结构化配置：顶层 version 加 blocks 数组，每个 block 里再嵌 segments，segment 决定提示符的每一段显示什么（路径、Git 状态、时间……）和怎么显示（配色、字体、模板）。官方主题库里有上百份现成配置可参考，每份渲染出来的效果在文档站 Themes 页能直接预览：

Oh My Posh 官方主题库预览页

官方 Themes 页：每个内置主题配一段终端预览，点 OPEN IN STUDIO 可在线改

校验服务器提供的两个工具都围绕这份结构：validate_config 校验整份配置，validate_segment 只校验单个 segment 片段——适合往现有配置里加一段之前先验一下，不用整文件重跑。两种格式 JSON/YAML/TOML 都收，不指定格式时自动识别。

接入：一个 URL 的事

官方文档的接法（原文照录）是往 MCP 客户端配置里加：

{
  "mcpServers": {
    "oh-my-posh-validator": {
      "url": "https://ohmyposh.dev/api/mcp",
      "transport": "http"
    }
  }
}

Claude Desktop 的配置文件在 macOS ~/Library/Application Support/Claude/config.json（Windows 在 %APPDATA%\Claude\ 下），Cline 等 VS Code 扩展按各自 MCP 设置面板添加同一 URL 即可。加好后对 AI 说一句 Can you validate this oh-my-posh configuration for me? 再粘贴配置，就是官方文档给出的标准用法。

官方 MCP Server 文档的接入配置一节

官方文档 Usage 一节：客户端配置 JSON 就这一个 url 字段，transport 固定 http

不用客户端，curl 直接调

这个服务器同时开放直连 HTTP 调用，官方文档给了三条现成命令（下方截图即文档原文所在小节）：

官方文档 Direct HTTP API 一节的 curl 示例

官方文档 Direct HTTP API 一节：Get Server Information 与 List Available Tools 两条 curl 命令

列出全部工具：

curl -X POST https://ohmyposh.dev/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{ "jsonrpc": "2.0", "method": "tools/list", "id": 1 }'

2026-10-08 实测，返回两个工具，schema 里写明 content 必填、format 可选（json/yaml/toml/auto，默认 auto）：

{
  "jsonrpc": "2.0",
  "result": {
    "tools": [
      { "name": "validate_config",
        "description": "Validate an oh-my-posh configuration against the schema.
        Supports JSON, YAML, and TOML formats.", ... },
      { "name": "validate_segment",
        "description": "Validate a segment snippet against the oh-my-posh schema.
        Useful for validating individual prompt segments ...", ... }
    ]
  },
  "id": 1
}

校验一份配置，把 method 换成 tools/call、参数塞进 arguments。官方文档的完整示例（原文，注意 shell 引号里 JSON 要压成一行或加转义）：

curl -X POST https://ohmyposh.dev/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{ "jsonrpc": "2.0", "method": "tools/call",
        "params": { "name": "validate_config",
          "arguments": { "content": { "$schema": "...schema.json", "version": 4, "blocks": [] },
                         "format": "json" } }, "id": 1 }'

看懂返回：valid、errors、warnings 三层

返回统一是三层结构：valid 总判定、errors 硬错误数组、warnings 建议数组，另有 detectedFormat（识别出的格式）和 parsedConfig（解析后的配置回显）。每个错误带五个字段，最常用的是 path（JSON 路径，直接指到出错属性）和 message（人话描述）。

拿官方文档的非法示例实测——block 类型故意写成 invalid-type：

{ "blocks": [ { "type": "invalid-type" } ] }

真实返回（2026-10-08）：

{
  "valid": false,
  "errors": [
    { "path": "/blocks/0/type",
      "message": "Value must be one of: prompt, rprompt",
      "keyword": "enum",
      "params": { "allowedValues": ["prompt", "rprompt"] },
      "data": "invalid-type" }
  ],
  "warnings": [
    { "path": "$schema",
      "message": "Consider adding \"$schema\" property for better editor support.",
      "type": "recommendation" }
  ],
  "detectedFormat": "json",
  "parsedConfig": { "blocks": [ { "type": "invalid-type" } ] }
}

值得注意的两点：错误不只告诉你错了，还把合法值列表（allowedValues）一并带回，改配置不用翻文档；缺 $schema 不算错误，只给一条 warning——官方的意图是让编辑器（VS Code 等）能自动补全，加上它属于「建议做」而非「必须做」。

再把官方的合法示例（一个 powerline 风格 path 段）发过去，返回 "valid": true, "errors": [], "warnings": []，配置合法时就是三个空/真值，没有多余输出。

yaml 和 toml 也能直接扔进去

同一段配置的 YAML 写法，官方文档示例：

$schema: https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json
version: 4
blocks: []

TOML 更短：

version = 4
blocks = [ ]

格式自动识别偶有失手时（比如片段太短特征不明显），显式传 "format": "yaml" 就好——这是官方 Troubleshooting 一节给出的头号建议。真遇到解析报错（parse errors），先确认语法本身是合法 JSON/YAML/TOML，再谈 Schema 校验，两回事。

官方写明的边界与隐私

能力边界照官方文档列：校验基于 main 分支最新 Schema，老版本 oh-my-posh 上的新属性可能被误报为未知（文档原话：some newer properties might not be recognized）；只做结构校验，不渲染、不执行配置。隐私一节的说法也直接引用：配置内容不存储、不记录（Your configuration content is not stored or logged），校验全程内存中完成，服务端只读仓库里的官方 Schema，无需任何鉴权。

实测还发现一处文档没写的边界：给 validate_segment 传 "style": "not-a-style" 这样的未定义样式值，返回仍是 valid: true——segment 级校验对 style 取值的约束比整配置校验松，样式写错不一定能查出来，配色或样式字段出错时别完全依赖它兜底。

来源

本文步骤、参数与引文依据 ohmyposh.dev 官方文档（Guides → MCP Server）与 JanDeDobbeleer/oh-my-posh 仓库 README 整理；所有 JSON 返回为 2026-10-08 在官方端点的实测结果，版权归原作者所有。

评论 (0)