AI导哈

API规范检查服务

APILinter MCP Server是一个基于Model Context Protocol (MCP)的服务，用于在LLM和REST API之间实现无缝通信，并提供API规范检查、质量评分和设计审查功能。

  • by jbovet
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 jbovet/zally-mcp-server

使用说明

APILinter MCP服务器

OpenAPI MCP服务器通过实现模型上下文协议（MCP）来实现LLM和REST API之间的无缝通信。

特性

能力 已实施 备注
结构化日志记录 ✅
度量与监控 ✅
断路器 ✅
重试模式 ✅
健康检查 ✅
API文档 ❌ 规划
速率限制 ❌ 规划
安全控制 ❌
错误处理 ✅
OpenTeletry ❌ 规划

MCP协议合规性

功能 已实现 备注
协议规范 ✅ v2025-03-26
MCP身份验证 ❌ 没有必要
会话管理 ❌ 无国籍
工具支持 ✅ validate_api_specification list_rules calculate_api_quality_score get_rule_categories get_api_docs get_api_linter_link
资源支持 ❌
提示支持 ✅ api_design_review
可流式HTTP传输 ✅
SSE 运输 ❌ 没有计划
STDIO传输 ❌ 没有计划
SDK客户端 ✅ https://github.com/jbovet/zally-mcp-server.git

安装

  1. 克隆存储库：
   git clone git@github.com:jbovet/zally-mcp-server.git
   cd zally-mcp-server

项目结构：

  • src/：包含TypeScript源代码。
    • circuitbreaker/：断开电路并重试执行。
    • config/：配置文件。
    • controllers/：Express控制器，包括StreamableHttp控制器。
    • models/：数据模型的TypeScript接口。
    • repositories/：API Linter的数据访问层。
    • services/：API Linter和MCP集成的业务逻辑。
    • utils/：实用程序类，包括HTTP客户端和错误处理。
    • target/：编译的JavaScript文件。
  • package.json：项目元数据和依赖关系。
  • tsconfig.json：TypeScript配置文件。
  • curl-mcp-client.sh：通过curl测试MCP服务器端点的Bash脚本。
  • README.md：项目文件。
  1. 安装依赖项：
npm install
  1. 构建项目：
npm run build

配置

环境变量：

  • PORT：服务器端口（默认值：3000）
  • APILINTER_URL：API Linter服务URL（默认值： http://localhost:3000)
  • RETRY_COUNT：失败请求的重试次数（默认值：3）
  • CIRCUIT_BREAKER_THRESHOLD：触发断路器的故障阈值（默认值：5）

运行服务器

注： 之前，您需要运行Zally Server，您可以在此处查看文档 https://github.com/zalando/zally?tab=readme-ov-file#quick-start-guide

使用以下命令启动服务器：

npm run dev

MCP服务器将在端点上以流式HTTP模式运行： http://localhost:3000/mcp

测试服务器

使用以下命令运行测试：

npm run test

运行示例客户端

要运行MCP服务器的示例交互式客户端，请使用以下命令：

npx tsx example/simpleStreamableHttp.ts

这将启动交互式客户端，允许您测试MCP服务器的各种命令和功能。

> list-rules
> list-rules true
> validate-api ./my-api-spec.yaml
> validate-api-rules ./my-api-spec.json id

工具

MCP服务器为API Linting提供以下工具：

  • validate_api_specification：根据API Linter规则验证API规范（OpenAPI/Swagger）

    • 参数： spec （API规范内容）， ruleIds （要使用的规则ID的可选列表）
    • 返回：包含违规和格式的验证结果
    • 重试逻辑：在瞬态故障的情况下重试验证请求
    • 断路器：如果API Linter服务没有响应，则停止验证请求

  • list_rules：列出所有可用的API Linter规则

    • 参数： isActive （可选布尔值，按活动状态过滤）
    • 返回：可用linting规则及其详细信息的列表
    • 重试逻辑：在暂时失败的情况下检索规则列表请求
    • 断路器：如果API Linter服务超过故障阈值，则阻止进一步的请求

  • calculate_api_quality_score：计算API规范的质量分数

    • 参数： spec （API规范内容）
    • 退货：质量评分及明细

  • get_rule_categories：检索API Linter规则的类别

    • 参数：无
    • 返回：规则类别列表

鼓励

MCP服务器提供以下预配置的提示：

  • api_design_review：分析API规范并提供全面的设计反馈
    • 参数：
      • specification （API规范内容为JSON或YAML格式）
      • focusAreas （可选的逗号分隔的关注领域列表，例如“安全性、命名、一致性”）
    • 返回：结构化API设计反馈，包括：
      • API用途和设计执行摘要
      • 优势识别
      • 需要改进的领域（命名、一致性、错误处理、安全性等）
      • API增强的具体建议

安全说明

  • 实施源验证以防止DNS重新绑定攻击
  • 在无状态模式下使用流式HTTP传输以确保安全
  • 在开发中仅处理来自受信任来源（localhost）的请求
  • 所有API输入在处理前都经过验证
  • 重试逻辑和断路器：通过优雅地处理服务故障来增强弹性和安全性

贡献

欢迎投稿！请随时提交拉取请求。

  1. 分叉存储库
  2. 创建功能分支(git checkout -b feature/amazing-feature)
  3. 安装依赖项(npm install)
  4. 进行更改
  5. 运行测试以确保通过(npm test)
  6. 提交您的更改(git commit -m 'Add some amazing feature')
  7. 推到分支(git push origin feature/amazing-feature)
  8. 打开拉取请求

许可证

该项目根据MIT许可证获得许可。请参阅 许可证 文件以获取详细信息。

相关 MCP