APILinter MCP Server

APILinter MCP 服务

OpenAPI MCP 服务通过实现 Model Context Protocol (MCP)，实现大模型与 REST API 之间的无缝通信。

功能

能力	已实现	备注
结构化日志记录	✅
指标与监控	✅
熔断器	✅
重试模式	✅
健康检查	✅
API 文档	❌	计划中
速率限制	❌	计划中
安全控制	❌
错误处理	✅
OpenTelemtry	❌	计划中

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 [email protected]: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

2. 构建项目：

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（可选布尔值，用于按启用状态筛选）
  • 返回：可用 Lint 规则及其详情列表
  • 重试逻辑：在发生暂时性故障时重试规则列表请求
  • 熔断器：如果 API Linter 服务的故障次数超出阈值，则阻止后续请求

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

  • 参数：spec（API 规范内容）
  • 返回：包含详细分解的质量分数

• get_rule_categories：获取 API Linter 规则的类别

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

提示词

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

• api_design_review：分析 API 规范并提供全面的设计反馈
  • 参数：
    • specification（JSON 或 YAML 格式的 API 规范内容）
    • focusAreas（可选的逗号分隔领域列表，用于指定关注重点，例如 "security,naming,consistency"）
  • 返回：结构化的 API 设计反馈，包括：
    • API 用途和设计的概要
    • 优势识别
    • 待改进领域（命名、一致性、错误处理、安全性等）
    • API 改进的具体建议

安全说明

• 实施来源验证，以防止 DNS 重绑定攻击
• 出于安全考虑，在无状态模式下使用 Streamable HTTP 传输
• 在开发环境中，仅处理来自可信来源（localhost）的请求
• 处理前会验证所有 API 输入
• 重试逻辑和熔断器：通过优雅处理服务故障来增强弹性和安全性

贡献

欢迎贡献！请随时提交 Pull Request。

1. Fork 此仓库
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. 发起 Pull Request

许可证

本项目采用 MIT License 授权。详情请参阅 LICENSE 文件。