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客户端 | ✅ |
安装
- 克隆存储库:```bash
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. 安装依赖项:```bash
npm install
- 构建项目:```bash
npm run build
## 配置
环境变量:
- `PORT`:服务器端口(默认值:3000)
- `APILINTER_URL`:API Linter服务URL(默认值: )
- `RETRY_COUNT`:失败请求的重试次数(默认值:3)
- `CIRCUIT_BREAKER_THRESHOLD`:触发断路器的故障阈值(默认值:5)
## 运行服务器
> **_注:_** 之前,您需要运行Zally Server,您可以在此处查看文档
使用以下命令启动服务器:```bash
npm run dev
MCP服务器将在端点上以流式HTTP模式运行:
测试服务器
使用以下命令运行测试:```bash
npm run test
## 运行示例客户端
要运行MCP服务器的示例交互式客户端,请使用以下命令:```bash
npx tsx example/simpleStreamableHttp.ts
这将启动交互式客户端,允许您测试MCP服务器的各种命令和功能。bash
> 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输入在处理前都经过验证
- 重试逻辑和断路器:通过优雅地处理服务故障来增强弹性和安全性
贡献
欢迎投稿!请随时提交拉取请求。
- 分叉存储库
- 创建功能分支(
git checkout -b feature/amazing-feature) - 安装依赖项(
npm install) - 进行更改
- 运行测试以确保通过(
npm test) - 提交您的更改(
git commit -m 'Add some amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
许可证
该项目根据MIT许可证获得许可。请参阅 许可证 文件以获取详细信息。
