AI导哈

API解析与执行工具

Knotty是一个强大的MCP服务器，能够将Swagger/OpenAPI文档转换为AI可读的上下文，并让Claude像Postman一样执行API请求。它支持解析OpenAPI规范、智能搜索API端点、执行API请求并提供认证支持，适用于前端和移动开发者在开发过程中快速理解和测试API。

  • by Shalin-Shah-2002
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 Shalin-Shah-2002/Knotty_MCP

使用说明

🪢 棘手的

解开你的API

功能强大的MCP服务器，可将Swagger/OpenAPI文档转换为AI可读上下文，并让Claude执行Postman等API请求！

特性 • 问题 • 设置 • 工具 • 作者

🎯 Knotty能做什么

📄 解析任何OpenAPI规范

  • OpenAPI 3.x和Swagger 2.0
  • JSON和YAML格式
  • 直接URL或Swagger UI页面

🌐 Swagger UI自动刮擦

  • 粘贴Swagger UI URL——Knotty找到规范
  • 从中提取嵌入式规格 swagger-ui-init.js
  • 自动发现通用规范路径

🔍 API智能搜索

  • 按路径、方法、标签、描述搜索
  • 精确过滤端点
  • 立即获取请求/响应模式

🚀 执行API请求（Postman-like）

  • 发送GET、POST、PUT、PATCH、DELETE
  • 自定义标头和身份验证令牌
  • 查看完整的请求/响应详细信息

🔐 身份验证支持

  • 承载令牌身份验证
  • 使用受保护的API文档
  • 安全的凭证处理

⚡ 生产就绪

  • 具有自动刷新功能的智能缓存
  • 内置速率限制
  • Docker就绪部署
  • 结构化日志记录

😤 它解决的问题

“这是Swagger UI链接。构建前端。”

如果你曾经从后端开发人员那里收到过Swagger UI URL，并被期望弄清楚：

  • ❓ 这个端点实际上做了什么？
  • ❓ 请求正文结构是什么？
  • ❓ 所需参数是什么？
  • ❓ 我应该期待什么样的回应？
  • ❓ 我如何测试这是否有效？

你知道痛苦。

前端/移动开发人员的现实

Backend Dev: "API is ready, here's the docs: https://api.example.com/swagger-ui/"
You: *Opens link, sees 200+ endpoints, no context, no examples*
You: "Which endpoint do I use for user registration?"
Backend Dev: "It's in there somewhere 🤷"

听起来很熟悉？

💡 为什么建造Knotty

Knotty出生于挫折。

作为一名不断与后端API集成的Flutter开发人员，我厌倦了：

  1. 挖掘巨大的Swagger用户界面 试图找到正确的端点
  2. 手动复制请求正文架构 进入我的代码
  3. 猜测需要哪些字段 vs可选
  4. 在Postman中测试端点 然后切换回克劳德
  5. 获取零上下文 来自Swagger的URL

所以我建造了 棘手的 --MCP服务器，其：

  • 摄取任何Swagger/OpenAPI规范 （甚至来自UI页面！）
  • 使其可搜索且易于理解 AI助手
  • 让Claude执行实际的API请求 因此，您可以同时进行测试和构建

现在，当有人向我发送Swagger URL时，我只需将其粘贴到Claude中并询问：

“我需要哪些端点进行用户身份验证？显示请求/响应架构并测试登录端点。”

完成。 🎉

✨ 为什么Knotty与众不同

传统方法 使用Knotty
打开Swagger用户界面→ 手动搜索→ 复制架构→ 邮递员测试→ 返回编码 粘贴URL→ 问克劳德→ 立即获取模式+测试结果
4+工具之间的上下文切换 一次对话中的所有内容
“这个端点的作用是什么？” 克劳德用例子解释了这一点
手动请求体构造 AI根据模式生成
无法通过聊天进行测试 直接执行请求！

🚀 设置

先决条件

  • Node.js 18+
  • 克劳德桌面 （或任何兼容MCP的客户端）

安装

# Clone the repository
git clone https://github.com/shalin-shah-2002/knotty.git
cd knotty

# Install dependencies
npm install

# Build
npm run build

为Claude桌面配置

快速设置（推荐）

# Use a predefined API
.\setup-quick.ps1 -API petstore

# Or configure your own URL
.\setup-quick.ps1

手动配置

添加到您的 claude_desktop_config.json:

窗户： %APPDATA%\Claude\claude_desktop_config.json
macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
Linux： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "knotty": {
      "command": "node",
      "args": ["PATH_TO_KNOTTY/dist/index.js"],
      "env": {
        "OPENAPI_SPEC_URL": "https://petstore.swagger.io/v2/swagger.json",
        "LOG_LEVEL": "info"
      }
    }
  }
}

环境变量

变量 描述 默认值
OPENAPI_SPEC_URL OpenAPI规范或Swagger UI页面的URL 必需的
SWAGGER_AUTH_TOKEN 受保护规格的承载令牌 -
CACHE_REFRESH_MINUTES 刷新缓存的频率 10
RATE_LIMIT_MAX 每分钟最大请求数 60
LOG_LEVEL 日志记录级别 info

🛠️ 工具参考

1️⃣ getApiSchema

搜索与查询匹配的API端点。

非常适合在知道要查找的内容但不知道确切路径的情况下查找端点。

"Find all endpoints related to user authentication"
"Show me the POST endpoint for creating orders"
"What endpoints are tagged with 'payments'?"

您将获得：

  • 完整路径和HTTP方法
  • 请求具有必填字段的正文架构
  • 所有状态代码的响应模式
  • 参数详细信息（路径、查询、标头）
  • 安全要求

2️⃣ getApiInfo

了解整个API。

首先使用这个来了解你正在使用什么。

"What does this API do?"
"How many endpoints are there?"
"What authentication does it use?"

您将获得：

  • API标题、版本、说明
  • 基础URL
  • 端点总数
  • 可用标签/类别
  • 安全方案

3️⃣ listEndpoints

以紧凑的格式列出所有端点。

非常适合鸟瞰。

"List all POST endpoints"
"Show endpoints tagged 'users'"
"What endpoints are available?"

4️⃣ analyzeApiFromUrl

实时分析任何OpenAPI规范。

不想配置默认URL？直接通过一个！

"Analyze https://api.example.com/swagger-ui/ and find the login endpoint"
"Check this spec URL and show me all user-related endpoints"

支持：

  • 直接JSON/YAML规范URL
  • Swagger UI页面（自动抓取！）
  • 受身份验证令牌保护的规范

5️⃣ executeApiRequest 🔥

执行实际的HTTP请求——就像Postman一样，但在聊天中！

这是游戏规则的改变者。在不离开Claude的情况下测试API。

"Call GET https://api.example.com/users/1"
"Send a POST to create a new user with this body: {...}"
"Test the login endpoint with these credentials"

特征：

  • 所有HTTP方法（GET、POST、PUT、PATCH、DELETE）
  • 自定义标头和请求正文
  • 承载令牌身份验证
  • 可配置超时
  • 完整的响应详细信息（状态、标题、正文、时间）

示例响应：

{
  "status": 200,
  "statusText": "OK",
  "responseTime": 127,
  "body": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com"
  }
}

6️⃣ refreshCache

强制刷新缓存的API规范。

当后端团队更新其API并且您需要最新的架构时使用。

7️⃣ getCacheStatus

检查上次获取规格的时间。

有助于调试或了解是否有过时的数据。

🐳 Docker部署

# Build
docker build -t knotty .

# Run
docker run -it \
  -e OPENAPI_SPEC_URL=https://your-api.com/swagger.json \
  knotty

或者使用Docker Compose：

cp .env.example .env
# Edit .env with your settings
docker-compose up -d

📁 项目结构

knotty/
├── src/
│   ├── index.ts          # MCP server entry point
│   ├── config.ts         # Configuration management
│   ├── fetcher/          # Spec fetching + Swagger UI scraping
│   ├── parser/           # OpenAPI parsing & normalization
│   ├── cache/            # Smart caching layer
│   ├── tools/            # MCP tool implementations
│   └── utils/            # Logger, rate limiter
├── bin/
│   └── knotty.js         # CLI entry point
├── Dockerfile
├── docker-compose.yml
└── package.json

🧪 测试

# Run tests
npm test

# Watch mode
npm run test:watch

👨‍💻 作者

沙林·沙阿

Flutter开发人员|问题解决者|构建者

建于❤️ 以及大众的沮丧

如果Knotty帮助你解决了API的混乱，考虑给它一个⭐!

📄 许可证

麻省理工学院-使用它，修改它，运送它。如果你的API仍然不起作用，不要责怪我。😄

⬆ 返回页首

相关 MCP