MCP Spectral

MCP Spectral

用于检查 OpenAPI 规范的 Spectral 模型上下文协议（MCP）服务

概述

通过模型上下文协议（MCP）服务，让大语言模型（LLM）检查OpenAPI 规范是否有效。

MCP Spectral 服务在 Docker 镜像中封装了 Spectral 命令行工具。

使用 OpenAPI 规范描述 API，可以确保 API 之间的一致性、记录 API、定义 API 的使用约定、生成用于调用和提供 API 的代码桩，并对 API 进行版本管理。这些功能有助于加快 API 开发和 API 服务的采用，并减少 API 维护工作。

使用 MCP Spectral 可以进一步缩短 API 开发时间，帮助完成 OpenAPI 规范阶段的工作。

可用工具

MCP Spectral 提供的工具

• lint_openapi - 检查 OpenAPI 规范
• lint_openapi_with_ruleset - 使用 Spectral 规则集检查 OpenAPI 规范
• spectral_version - 返回所用 Spectral 的版本

设置说明

这些说明假定 Anthropic 的 Claude Desktop 将与 MCP Spectral 服务交互。如果使用其他大语言模型工具，请相应调整设置说明。

安装前提

确保本地计算机已安装以下应用程序

• 安装 Claude Desktop
• 安装 Docker

更新 Claude Desktop

将以下内容添加到 Claude Desktop 安装目录中的 claude_desktop_config.json 文件，以告知 Claude Desktop 如何访问 MCP Spectral

{
  "mcpServers": {
    "OpenAPI linting (Spectral)": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "marksivill/mcp-spectral"
      ]
    }
  }
}

例如，如果还安装了 mcp/fetch，完整的 claude_desktop_config.json 文件应为

{
  "mcpServers": {
    "fetch": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "mcp/fetch"
      ]
    },
    "OpenAPI linting (Spectral)": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "marksivill/mcp-spectral"
      ]
    }
  }
}

更新文件后，重启 Claude Desktop。

Claude Desktop 将自动从 Docker Hub 拉取 最新的 MCP Spectral Docker 版本

本地构建

也可以选择在本地构建 Docker 镜像，而不是从 Docker Hub 拉取，使用以下命令

docker build --tag marksivill/mcp-spectral:latest .

例如，如果需要更改源代码或默认规则集，这种方式就很有用

Claude Desktop 提示词示例

以下是 Claude Desktop 的提示词示例，也可能适用于其他调用 MCP Spectral 的大语言模型（LLM）工具。

注意，可能还需要在 Claude Desktop 中安装 mcp/fetch，以获取 URL。

提示词 1

What version of Spectral do we have access to

提示词 2

Validate the OpenAPI specification from OpenWeatherMap API.
If any errors are found, fix them, then revalidate, repeat the last steps until the OpenAPI specification is valid.

提示词 3

Using the API documentation found at https://wheretheiss.at/w/developer build an OpenAPI specification.
Ensure that there are no validation errors.
If any errors are found, fix them, then revalidate, repeat the last steps until the OpenAPI specification is valid.

提示词 4

Build an OpenAPI specification version 3.1 for the Rick and Morty API.
Ensure that there are no validation errors.
If any errors are found, fix them, then revalidate, repeat the last steps until the OpenAPI specification is valid.

提示词 5

Using the API documentation found at https://wheretheiss.at/w/developer build an OpenAPI specification version 3.1 using the rules
1) ensure all operationIds use kebab case
2) add info and contact information using your details
3) ensure servers are defined
4) ensure all operations contains a description
5) ensure all operations have one or more relevant tags
6) ensure there is a tag section

Ensure that there are no validation errors.
If any errors are found, fix them, then revalidate, repeat the last steps until the OpenAPI specification is valid.

实用链接

• 什么是 MCP 服务？
• Docker Hub 上的 MCP Spectral
• 用于检查 OpenAPI 规范的 Spectral
• 使用 MCP Spectral 减少生成 OpenAPI 规范时的 AI 幻觉