🪢 棘手的
*解开你的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开发人员，我厌倦了：
- 挖掘巨大的Swagger用户界面 试图找到正确的端点
- 手动复制请求正文架构 进入我的代码
- 猜测需要哪些字段 vs可选
- 在Postman中测试端点 然后切换回克劳德
- 获取零上下文 来自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仍然不起作用，不要责怪我。😄
______________________________________________________________________