Knotty MCP

🪢 棘手的

*解开你的API*

](https://nodejs.org/)   

功能强大的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与众不同

______________________________________________________________________

🚀 设置

先决条件

• 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"
      }
    }
  }
}

环境变量

______________________________________________________________________

🛠️ 工具参考

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开发人员|问题解决者|构建者*

](https://github.com/shalin-shah-2002) 

______________________________________________________________________

*建于❤️ 以及大众的沮丧*

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

______________________________________________________________________

📄 许可证

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

______________________________________________________________________

⬆ 返回页首