Type Crafter MCP 服务器

使用说明（Markdown 格式）

• 项目简介

  • Type Crafter 的 MCP 服务器实现为一个独立的后端服务，提供对 YAML 规范的写作指南、规则解读与规范校验等功能，供 LLM 客户端在对 YAML 规范进行编写和验证时获得结构化、可交互的帮助与信息。

• 主要功能点

  • 通过 MCP Server 注册并暴露工具，核心工具包括：get-writing-guide、get-rules-section、validate-spec、get-spec-info、list-languages。
  • 会话管理与 TTL（30 分钟）机制，支持教育性错误、常见错误检测，帮助 LLM 客户端更准确地引导 YAML 规范写作。
  • 读取、解析并校验 YAML 规范文件，提供详细的输出用于逐步修正规范中的问题。
  • 支持从本地 YAML 文件中提取信息（如 info、types、groupedTypes），并输出结构化结果。
  • 通过 stdio 传输与客户端通信，方便本地集成与桌面应用的快速连接。

• 安装步骤

  • 全局安装 MCP 服务器命令：
    • 通过 Node.js/npm 安装 Type Crafter 的 MCP 服务器实现（全局可用）。
  • 启动服务器
    • 使用 type-crafter-mcp 命令启动服务器进程（服务器将通过标准输入输出与客户端通信）。
  • 客户端配置（如 Claude 桌面）示例
    • 在客户端的 MCP 服务器配置中添加一条服务器条目，指向 type-crafter 的启动命令。例如将服务器配置为以下逻辑：命令为 type-crafter-mcp，服务器名称为 type-crafter。
  • 说明
    • 该服务器实现当前通过 stdio 传输，若后续扩展为其它传输协议（如 SSE/WebSocket），客户端需相应调整传输方式。

• 服务器配置（JSON 格式，供 MCP 客户端使用的描述信息）

  • 服务器名称: type-crafter
  • 启动命令: type-crafter-mcp
  • 参数 (args): 为空数组（无额外参数，使用默认行为启动）
  • 说明: 客户端在首次启动时应调用 get-writing-guide 以获取会话标识符 sessionId，后续工具请使用该 sessionId 以获得更好的体验。

  伪示例（仅文字描述，不用代码块呈现）： { "server": "type-crafter", "command": "type-crafter-mcp", "args": [] } 说明：上述配置用于 MCP 客户端在本地创建服务器进程并通过标准输入输出建立通信通道。实际客户端实现会读取该服务器的能力表、工具信息并通过 JSON-RPC 调用相应工具。

• 基本使用方法

  • 启动与连接
    • 在本地环境通过指定的启动命令启动 MCP 服务器，该服务器将通过标准输入输出与客户端建立沟通通道。
  • 使用流程（以 Claude Desktop/LLM 客户端为例）
    • 第一步：调用 get-writing-guide 以获得会话标识 sessionId，以及写作指南内容。
    • 第二步：使用 get-rules-section 结合 sessionId 请求相应主题的详细规则（如 structure、types、nullable、references、composition、patterns）。
    • 第三步：使用 validate-spec 指定 YAML 规范文件路径，获取结构性检查结果与建议，必要时可查看会话状态并按需重新获取指南。
    • 第四步：使用 get-spec-info 获取指定 YAML 规范文件的版本、标题以及类型定义信息。
    • 第五步：结合 list-languages 查看服务器支持的目标语言，进行后续的类型生成工作。
  • 运行与调试
    • 服务端在 30 分钟未被使用时会进行会话清理，日志、错误信息与输出内容均以友好格式展示，便于调试和学习。