[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-harsha-iiiv--openapi-mcp-generator":3,"tool-harsha-iiiv--openapi-mcp-generator":61},[4,18,26,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",150037,2,"2026-04-10T23:33:47",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108322,"2026-04-10T11:39:34",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":32,"last_commit_at":50,"category_tags":51,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[52,13,15,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":32,"last_commit_at":59,"category_tags":60,"status":17},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[52,14],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":66,"readme_en":67,"readme_zh":68,"quickstart_zh":69,"use_case_zh":70,"hero_image_url":71,"owner_login":72,"owner_name":73,"owner_avatar_url":74,"owner_bio":75,"owner_company":76,"owner_location":77,"owner_email":76,"owner_twitter":78,"owner_website":76,"owner_url":79,"languages":80,"stars":89,"forks":90,"last_commit_at":91,"license":92,"difficulty_score":32,"env_os":93,"env_gpu":94,"env_ram":94,"env_deps":95,"category_tags":105,"github_topics":76,"view_count":32,"oss_zip_url":76,"oss_zip_packed_at":76,"status":17,"created_at":106,"updated_at":107,"faqs":108,"releases":137},4990,"harsha-iiiv\u002Fopenapi-mcp-generator","openapi-mcp-generator","A tool that converts OpenAPI specifications to MCP server","openapi-mcp-generator 是一款专为开发者设计的命令行工具，旨在将现有的 OpenAPI 规范自动转换为符合模型上下文协议（MCP）的服务器。它主要解决了 AI 智能体难以直接、安全地调用传统 REST API 的痛点，通过生成一个中间代理层，让大语言模型能够无缝理解并操作您的后端服务，无需手动编写繁琐的适配代码。\n\n这款工具特别适合后端工程师、AI 应用开发者以及希望快速集成外部数据源的研究人员使用。其核心技术亮点在于不仅能自动生成类型安全的 TypeScript 项目脚手架，还利用 Zod 库根据 OpenAPI 定义实时校验输入数据，确保交互的可靠性。此外，它灵活支持多种通信传输方式，包括标准的 stdio、基于 Web 的 SSE 以及 StreamableHTTP，并内置了 API 密钥、OAuth2 等多种认证机制。无论是希望将内部系统接入 AI 工作流的企业团队，还是想要快速构建原型的独立开发者，openapi-mcp-generator 都能帮助您高效打通从 API 文档到 AI 能力的“最后一公里”。","# OpenAPI to MCP Generator (openapi-mcp-generator)\n\n[![npm version](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002Fopenapi-mcp-generator.svg)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fopenapi-mcp-generator)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg)](https:\u002F\u002Fopensource.org\u002Flicenses\u002FMIT)\n[![GitHub repository](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FGitHub-harsha--iiiv\u002Fopenapi--mcp--generator-blue.svg)](https:\u002F\u002Fgithub.com\u002Fharsha-iiiv\u002Fopenapi-mcp-generator)\n\nGenerate [Model Context Protocol (MCP)](https:\u002F\u002Fmodelcontextprotocol.io\u002F) servers from OpenAPI specifications.\n\nThis CLI tool automates the generation of MCP-compatible servers that proxy requests to existing REST APIs—enabling AI agents and other MCP clients to seamlessly interact with your APIs using your choice of transport methods.\n\n---\n\n## ✨ Features\n\n- 🔧 **OpenAPI 3.0 Support**: Converts any OpenAPI 3.0+ spec into an MCP-compatible server.\n- 🔁 **Proxy Behavior**: Proxies calls to your original REST API while validating request structure and security.\n- 🔐 **Authentication Support**: API keys, Bearer tokens, Basic auth, and OAuth2 supported via environment variables.\n- 🧪 **Zod Validation**: Automatically generates Zod schemas from OpenAPI definitions for runtime input validation.\n- ⚙️ **Typed Server**: Fully typed, maintainable TypeScript code output.\n- 🔌 **Multiple Transports**: Communicate over stdio, SSE via Hono, or StreamableHTTP.\n- 🧰 **Project Scaffold**: Generates a complete Node.js project with `tsconfig.json`, `package.json`, and entry point.\n- 🧪 **Built-in HTML Test Clients**: Test API interactions visually in your browser (for web-based transports).\n\n---\n\n## 🚀 Installation\n\n```bash\nnpm install -g openapi-mcp-generator\n```\n\n> You can also use `yarn global add openapi-mcp-generator` or `pnpm add -g openapi-mcp-generator`\n\n---\n\n## 🛠 Usage\n\n```bash\n# Generate an MCP server (stdio)\nopenapi-mcp-generator --input path\u002Fto\u002Fopenapi.json --output path\u002Fto\u002Foutput\u002Fdir\n\n# Generate an MCP web server with SSE\nopenapi-mcp-generator --input path\u002Fto\u002Fopenapi.json --output path\u002Fto\u002Foutput\u002Fdir --transport=web --port=3000\n\n# Generate an MCP StreamableHTTP server\nopenapi-mcp-generator --input path\u002Fto\u002Fopenapi.json --output path\u002Fto\u002Foutput\u002Fdir --transport=streamable-http --port=3000\n```\n\n### CLI Options\n\n| Option              | Alias | Description                                                                                                                                    | Default                           |\n| ------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |\n| `--input`           | `-i`  | Path or URL to OpenAPI specification (YAML or JSON)                                                                                            | **Required**                      |\n| `--output`          | `-o`  | Directory to output the generated MCP project                                                                                                  | **Required**                      |\n| `--server-name`     | `-n`  | Name of the MCP server (`package.json:name`)                                                                                                   | OpenAPI title or `mcp-api-server` |\n| `--server-version`  | `-v`  | Version of the MCP server (`package.json:version`)                                                                                             | OpenAPI version or `1.0.0`        |\n| `--base-url`        | `-b`  | Base URL for API requests. Required if OpenAPI `servers` missing or ambiguous.                                                                 | Auto-detected if possible         |\n| `--transport`       | `-t`  | Transport mode: `\"stdio\"` (default), `\"web\"`, or `\"streamable-http\"`                                                                           | `\"stdio\"`                         |\n| `--port`            | `-p`  | Port for web-based transports                                                                                                                  | `3000`                            |\n| `--default-include` |       | Default behavior for x-mcp filtering. Accepts `true` or `false` (case-insensitive). `true` = include by default, `false` = exclude by default. | `true`                            |\n| `--force`           |       | Overwrite existing files in the output directory without confirmation                                                                          | `false`                           |\n\n## 📦 Programmatic API\n\nYou can also use this package programmatically in your Node.js applications:\n\n```javascript\nimport { getToolsFromOpenApi } from 'openapi-mcp-generator';\n\n\u002F\u002F Extract MCP tool definitions from an OpenAPI spec\nconst tools = await getToolsFromOpenApi('.\u002Fpetstore.json');\n\n\u002F\u002F With options\nconst filteredTools = await getToolsFromOpenApi('https:\u002F\u002Fexample.com\u002Fapi-spec.json', {\n  baseUrl: 'https:\u002F\u002Fapi.example.com',\n  dereference: true,\n  excludeOperationIds: ['deletePet'],\n  filterFn: (tool) => tool.method.toLowerCase() === 'get',\n});\n```\n\nFor full documentation of the programmatic API, see [PROGRAMMATIC_API.md](.\u002FPROGRAMMATIC_API.md).\n\n---\n\n## 🧱 Project Structure\n\nThe generated project includes:\n\n```\n\u003Coutput_directory>\u002F\n├── .gitignore\n├── package.json\n├── tsconfig.json\n├── .env.example\n├── src\u002F\n│   ├── index.ts\n│   └── [transport-specific-files]\n└── public\u002F          # For web-based transports\n    └── index.html   # Test client\n```\n\nCore dependencies:\n\n- `@modelcontextprotocol\u002Fsdk` - MCP protocol implementation\n- `axios` - HTTP client for API requests\n- `zod` - Runtime validation\n- `json-schema-to-zod` - Convert JSON Schema to Zod\n- Transport-specific deps (Hono, uuid, etc.)\n\n---\n\n## 📡 Transport Modes\n\n### Stdio (Default)\n\nCommunicates with MCP clients via standard input\u002Foutput. Ideal for local development or integration with LLM tools.\n\n### Web Server with SSE\n\nLaunches a fully functional HTTP server with:\n\n- Server-Sent Events (SSE) for bidirectional messaging\n- REST endpoint for client → server communication\n- In-browser test client UI\n- Multi-connection support\n- Built with lightweight Hono framework\n\n### StreamableHTTP\n\nImplements the MCP StreamableHTTP transport which offers:\n\n- Stateful JSON-RPC over HTTP POST requests\n- Session management using HTTP headers\n- Proper HTTP response status codes\n- Built-in error handling\n- Compatibility with MCP StreamableHTTPClientTransport\n- In-browser test client UI\n- Built with lightweight Hono framework\n\n### Transport Comparison\n\n| Feature            | stdio               | web (SSE)         | streamable-http    |\n| ------------------ | ------------------- | ----------------- | ------------------ |\n| Protocol           | JSON-RPC over stdio | JSON-RPC over SSE | JSON-RPC over HTTP |\n| Connection         | Persistent          | Persistent        | Request\u002Fresponse   |\n| Bidirectional      | Yes                 | Yes               | Yes (stateful)     |\n| Multiple clients   | No                  | Yes               | Yes                |\n| Browser compatible | No                  | Yes               | Yes                |\n| Firewall friendly  | No                  | Yes               | Yes                |\n| Load balancing     | No                  | Limited           | Yes                |\n| Status codes       | No                  | Limited           | Full HTTP codes    |\n| Headers            | No                  | Limited           | Full HTTP headers  |\n| Test client        | No                  | Yes               | Yes                |\n\n---\n\n## 🔐 Environment Variables for Authentication\n\nConfigure auth credentials in your environment:\n\n| Auth Type  | Variable Format                                                                                    |\n| ---------- | -------------------------------------------------------------------------------------------------- |\n| API Key    | `API_KEY_\u003CSCHEME_NAME>`                                                                            |\n| Bearer     | `BEARER_TOKEN_\u003CSCHEME_NAME>`                                                                       |\n| Basic Auth | `BASIC_USERNAME_\u003CSCHEME_NAME>`, `BASIC_PASSWORD_\u003CSCHEME_NAME>`                                     |\n| OAuth2     | `OAUTH_CLIENT_ID_\u003CSCHEME_NAME>`, `OAUTH_CLIENT_SECRET_\u003CSCHEME_NAME>`, `OAUTH_SCOPES_\u003CSCHEME_NAME>` |\n\n---\n\n## 🔎 Filtering Endpoints with OpenAPI Extensions\n\nYou can control which operations are exposed as MCP tools using a vendor extension flag `x-mcp`. This extension is supported at the root, path, and operation levels. By default, endpoints are included unless explicitly excluded.\n\n- Extension: `x-mcp: true | false`\n- Default: `true` (include by default)\n- Precedence: operation > path > root (first non-undefined wins)\n- CLI option: `--default-include false` to change default to exclude by default\n\nExamples:\n\n```yaml\n# Optional root-level default\nx-mcp: true\n\npaths:\n  \u002Fpets:\n    x-mcp: false # exclude all ops under \u002Fpets\n    get:\n      x-mcp: true # include this operation anyway\n\n  \u002Fusers\u002F{id}:\n    get:\n      # no x-mcp -> included by default\n```\n\nThis uses standard OpenAPI extensions (x-… fields). See the [OpenAPI Extensions guide](https:\u002F\u002Fswagger.io\u002Fdocs\u002Fspecification\u002Fv3_0\u002Fopenapi-extensions\u002F) for details.\n\nNote: `x-mcp` must be a boolean or the strings `\"true\"`\u002F`\"false\"` (case-insensitive). Other values are ignored in favor of higher-precedence or default behavior.\n\n---\n\n## ▶️ Running the Generated Server\n\n```bash\ncd path\u002Fto\u002Foutput\u002Fdir\nnpm install\n\n# Run in stdio mode\nnpm start\n\n# Run in web server mode\nnpm run start:web\n\n# Run in StreamableHTTP mode\nnpm run start:http\n```\n\n### Testing Web-Based Servers\n\nFor web and StreamableHTTP transports, a browser-based test client is automatically generated:\n\n1. Start the server using the appropriate command\n2. Open your browser to `http:\u002F\u002Flocalhost:\u003Cport>`\n3. Use the test client to interact with your MCP server\n\n---\n\n## ⚠️ Requirements\n\n- Node.js v20 or later\n\n---\n\n## Star History\n\n\u003Ca href=\"https:\u002F\u002Fwww.star-history.com\u002F#harsha-iiiv\u002Fopenapi-mcp-generator&Date\">\n \u003Cpicture>\n   \u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fharsha-iiiv_openapi-mcp-generator_readme_3773acd25432.png&theme=dark\" \u002F>\n   \u003Csource media=\"(prefers-color-scheme: light)\" srcset=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fharsha-iiiv_openapi-mcp-generator_readme_3773acd25432.png\" \u002F>\n   \u003Cimg alt=\"Star History Chart\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fharsha-iiiv_openapi-mcp-generator_readme_3773acd25432.png\" \u002F>\n \u003C\u002Fpicture>\n\u003C\u002Fa>\n\n## 🤝 Contributing\n\nContributions are welcome!\n\n1. Fork the repo\n2. Create a feature branch: `git checkout -b feature\u002Famazing-feature`\n3. Run `npm run format.write` to format your code\n4. Commit your changes: `git commit -m \"Add amazing feature\"`\n5. Push and open a PR\n\n📌 Repository: [github.com\u002Fharsha-iiiv\u002Fopenapi-mcp-generator](https:\u002F\u002Fgithub.com\u002Fharsha-iiiv\u002Fopenapi-mcp-generator)\n\n---\n\n## 📄 License\n\nMIT License — see [LICENSE](.\u002FLICENSE) for full details.\n","# OpenAPI 至 MCP 生成器 (openapi-mcp-generator)\n\n[![npm version](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002Fopenapi-mcp-generator.svg)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fopenapi-mcp-generator)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg)](https:\u002F\u002Fopensource.org\u002Flicenses\u002FMIT)\n[![GitHub 仓库](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FGitHub-harsha--iiiv\u002Fopenapi--mcp--generator-blue.svg)](https:\u002F\u002Fgithub.com\u002Fharsha-iiiv\u002Fopenapi-mcp-generator)\n\n根据 OpenAPI 规范生成 [模型上下文协议 (MCP)](https:\u002F\u002Fmodelcontextprotocol.io\u002F) 服务器。\n\n此 CLI 工具可自动构建与 MCP 兼容的代理服务器，将请求转发至现有的 REST API，从而使 AI 代理及其他 MCP 客户端能够通过您选择的传输方式无缝地与您的 API 进行交互。\n\n---\n\n## ✨ 功能\n\n- 🔧 **OpenAPI 3.0 支持**：将任何 OpenAPI 3.0 及以上版本的规范转换为与 MCP 兼容的服务器。\n- 🔁 **代理行为**：在验证请求结构和安全性的同时，将调用代理到您的原始 REST API。\n- 🔐 **身份验证支持**：通过环境变量支持 API 密钥、Bearer 令牌、Basic 认证和 OAuth2。\n- 🧪 **Zod 验证**：根据 OpenAPI 定义自动生成 Zod 模式，用于运行时输入验证。\n- ⚙️ **类型化服务器**：输出完全类型化的、易于维护的 TypeScript 代码。\n- 🔌 **多种传输方式**：可通过标准输入输出、Hono 的 SSE 或 StreamableHTTP 进行通信。\n- 🧰 **项目脚手架**：生成包含 `tsconfig.json`、`package.json` 和入口文件的完整 Node.js 项目。\n- 🧪 **内置 HTML 测试客户端**：可在浏览器中以可视化方式测试 API 交互（适用于基于 Web 的传输）。\n\n---\n\n## 🚀 安装\n\n```bash\nnpm install -g openapi-mcp-generator\n```\n\n> 您也可以使用 `yarn global add openapi-mcp-generator` 或 `pnpm add -g openapi-mcp-generator`\n\n---\n\n## 🛠 使用方法\n\n```bash\n# 生成一个 stdio 传输的 MCP 服务器\nopenapi-mcp-generator --input path\u002Fto\u002Fopenapi.json --output path\u002Fto\u002Foutput\u002Fdir\n\n# 生成一个带有 SSE 的 Web MCP 服务器\nopenapi-mcp-generator --input path\u002Fto\u002Fopenapi.json --output path\u002Fto\u002Foutput\u002Fdir --transport=web --port=3000\n\n# 生成一个 StreamableHTTP 传输的 MCP 服务器\nopenapi-mcp-generator --input path\u002Fto\u002Fopenapi.json --output path\u002Fto\u002Foutput\u002Fdir --transport=streamable-http --port=3000\n```\n\n### CLI 选项\n\n| 选项              | 别名 | 描述                                                                                                                                    | 默认                           |\n| ------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |\n| `--input`           | `-i`  | OpenAPI 规范的路径或 URL（YAML 或 JSON）                                                                                            | **必填**                      |\n| `--output`          | `-o`  | 生成的 MCP 项目的输出目录                                                                                                  | **必填**                      |\n| `--server-name`     | `-n`  | MCP 服务器的名称（`package.json:name`）                                                                                                   | OpenAPI 标题或 `mcp-api-server` |\n| `--server-version`  | `-v`  | MCP 服务器的版本（`package.json:version`）                                                                                             | OpenAPI 版本或 `1.0.0`        |\n| `--base-url`        | `-b`  | API 请求的基础 URL。如果 OpenAPI 的 `servers` 缺失或不明确，则必须提供。                                                                 | 尽可能自动检测         |\n| `--transport`       | `-t`  | 传输模式：`\"stdio\"`（默认）、`\"web\"` 或 `\"streamable-http\"`                                                                           | `\"stdio\"`                         |\n| `--port`            | `-p`  | 基于 Web 的传输所使用的端口                                                                                                                  | `3000`                            |\n| `--default-include` |       | x-mcp 过滤的默认行为。接受 `true` 或 `false`（不区分大小写）。`true` 表示默认包含，`false` 表示默认排除。 | `true`                            |\n| `--force`           |       | 在不进行确认的情况下覆盖输出目录中的现有文件                                                                          | `false`                           |\n\n## 📦 程序化 API\n\n您也可以在自己的 Node.js 应用程序中以编程方式使用此包：\n\n```javascript\nimport { getToolsFromOpenApi } from 'openapi-mcp-generator';\n\n\u002F\u002F 从 OpenAPI 规范中提取 MCP 工具定义\nconst tools = await getToolsFromOpenApi('.\u002Fpetstore.json');\n\n\u002F\u002F 带有选项\nconst filteredTools = await getToolsFromOpenApi('https:\u002F\u002Fexample.com\u002Fapi-spec.json', {\n  baseUrl: 'https:\u002F\u002Fapi.example.com',\n  dereference: true,\n  excludeOperationIds: ['deletePet'],\n  filterFn: (tool) => tool.method.toLowerCase() === 'get',\n});\n```\n\n有关程序化 API 的完整文档，请参阅 [PROGRAMMATIC_API.md](.\u002FPROGRAMMATIC_API.md)。\n\n---\n\n## 🧱 项目结构\n\n生成的项目包括：\n\n```\n\u003Coutput_directory>\u002F\n├── .gitignore\n├── package.json\n├── tsconfig.json\n├── .env.example\n├── src\u002F\n│   ├── index.ts\n│   └── [与传输方式相关的文件]\n└── public\u002F          # 用于基于 Web 的传输\n    └── index.html   # 测试客户端\n```\n\n核心依赖项：\n\n- `@modelcontextprotocol\u002Fsdk` - MCP 协议实现\n- `axios` - 用于 API 请求的 HTTP 客户端\n- `zod` - 运行时验证\n- `json-schema-to-zod` - 将 JSON Schema 转换为 Zod\n- 传输特定的依赖项（Hono、uuid 等）\n\n---\n\n## 📡 传输模式\n\n### Stdio（默认）\n\n通过标准输入输出与 MCP 客户端通信。非常适合本地开发或与 LLM 工具集成。\n\n### 带有 SSE 的 Web 服务器\n\n启动一个功能齐全的 HTTP 服务器，具备以下特性：\n\n- 服务器发送事件 (SSE)，用于双向消息传递\n- REST 端点，用于客户端到服务器的通信\n- 浏览器内测试客户端 UI\n- 多连接支持\n- 基于轻量级 Hono 框架构建\n\n### StreamableHTTP\n\n实现 MCP 的 StreamableHTTP 传输，提供以下功能：\n\n- 基于 HTTP POST 请求的状态感知 JSON-RPC\n- 使用 HTTP 头部进行会话管理\n- 正确的 HTTP 响应状态码\n- 内置错误处理\n- 与 MCP StreamableHTTPClientTransport 兼容\n- 浏览器内测试客户端 UI\n- 基于轻量级 Hono 框架构建\n\n### 传输方式对比\n\n| 特性            | 标准输入输出               | Web (SSE)         | 可流式 HTTP    |\n| ------------------ | ------------------- | ----------------- | ------------------ |\n| 协议           | 基于标准输入输出的 JSON-RPC | 基于 SSE 的 JSON-RPC | 基于 HTTP 的 JSON-RPC |\n| 连接         | 长连接          | 长连接        | 请求\u002F响应       |\n| 双向通信      | 是                 | 是               | 是（有状态）     |\n| 多客户端支持   | 否                  | 是               | 是                |\n| 浏览器兼容性   | 否                  | 是               | 是                |\n| 防火墙友好性   | 否                  | 是               | 是                |\n| 负载均衡       | 否                  | 有限             | 是                |\n| 状态码         | 否                  | 有限             | 完整 HTTP 状态码 |\n| 头信息         | 否                  | 有限             | 完整 HTTP 头     |\n| 测试客户端     | 否                  | 是               | 是                |\n\n---\n\n## 🔐 认证用环境变量\n\n在您的环境中配置认证凭据：\n\n| 认证类型  | 变量格式                                                                                    |\n| ---------- | -------------------------------------------------------------------------------------------------- |\n| API 密钥    | `API_KEY_\u003CSCHEME_NAME>`                                                                            |\n| Bearer 令牌 | `BEARER_TOKEN_\u003CSCHEME_NAME>`                                                                       |\n| Basic 认证 | `BASIC_USERNAME_\u003CSCHEME_NAME>`, `BASIC_PASSWORD_\u003CSCHEME_NAME>`                                     |\n| OAuth2     | `OAUTH_CLIENT_ID_\u003CSCHEME_NAME>`, `OAUTH_CLIENT_SECRET_\u003CSCHEME_NAME>`, `OAUTH_SCOPES_\u003CSCHEME_NAME>` |\n\n---\n\n## 🔎 使用 OpenAPI 扩展筛选端点\n\n您可以使用供应商扩展标志 `x-mcp` 来控制哪些操作作为 MCP 工具公开。此扩展在根、路径和操作级别均受支持。默认情况下，端点会被包含，除非被显式排除。\n\n- 扩展：`x-mcp: true | false`\n- 默认值：`true`（默认包含）\n- 优先级：操作 > 曲线 > 根（第一个非未定义值生效）\n- CLI 选项：`--default-include false` 可将默认行为更改为默认排除。\n\n示例：\n\n```yaml\n# 可选的根级默认值\nx-mcp: true\n\npaths:\n  \u002Fpets:\n    x-mcp: false # 排除 \u002Fpets 下的所有操作\n    get:\n      x-mcp: true # 无论如何都包含此操作\n\n  \u002Fusers\u002F{id}:\n    get:\n      # 没有 x-mcp -> 默认包含\n```\n\n这使用了标准的 OpenAPI 扩展（x-… 字段）。有关详细信息，请参阅 [OpenAPI 扩展指南](https:\u002F\u002Fswagger.io\u002Fdocs\u002Fspecification\u002Fv3_0\u002Fopenapi-extensions\u002F)。\n\n注意：`x-mcp` 必须是布尔值或字符串 `\"true\"`\u002F`\"false\"`（不区分大小写）。其他值将被忽略，以遵循更高优先级或默认行为。\n\n---\n\n## ▶️ 运行生成的服务器\n\n```bash\ncd path\u002Fto\u002Foutput\u002Fdir\nnpm install\n\n# 以标准输入输出模式运行\nnpm start\n\n# 以 Web 服务器模式运行\nnpm run start:web\n\n# 以可流式 HTTP 模式运行\nnpm run start:http\n```\n\n### 测试基于 Web 的服务器\n\n对于 Web 和可流式 HTTP 传输方式，会自动生成一个基于浏览器的测试客户端：\n\n1. 使用相应的命令启动服务器\n2. 在浏览器中打开 `http:\u002F\u002Flocalhost:\u003Cport>`\n3. 使用测试客户端与您的 MCP 服务器交互\n\n---\n\n## ⚠️ 系统要求\n\n- Node.js v20 或更高版本\n\n---\n\n## 星标历史\n\n\u003Ca href=\"https:\u002F\u002Fwww.star-history.com\u002F#harsha-iiiv\u002Fopenapi-mcp-generator&Date\">\n \u003Cpicture>\n   \u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fharsha-iiiv_openapi-mcp-generator_readme_3773acd25432.png&theme=dark\" \u002F>\n   \u003Csource media=\"(prefers-color-scheme: light)\" srcset=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fharsha-iiiv_openapi-mcp-generator_readme_3773acd25432.png\" \u002F>\n   \u003Cimg alt=\"星标历史图表\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fharsha-iiiv_openapi-mcp-generator_readme_3773acd25432.png\" \u002F>\n \u003C\u002Fpicture>\n\u003C\u002Fa>\n\n## 🤝 贡献\n\n欢迎贡献！\n\n1. 分支仓库\n2. 创建功能分支：`git checkout -b feature\u002Famazing-feature`\n3. 运行 `npm run format.write` 来格式化代码\n4. 提交更改：`git commit -m \"添加精彩功能\"`\n5. 推送并打开拉取请求\n\n📌 仓库：[github.com\u002Fharsha-iiiv\u002Fopenapi-mcp-generator](https:\u002F\u002Fgithub.com\u002Fharsha-iiiv\u002Fopenapi-mcp-generator)\n\n---\n\n## 📄 许可证\n\nMIT 许可证 — 详情请参阅 [LICENSE](.\u002FLICENSE) 文件。","# openapi-mcp-generator 快速上手指南\n\n`openapi-mcp-generator` 是一个命令行工具，可自动将 OpenAPI 3.0+ 规范转换为兼容 **Model Context Protocol (MCP)** 的服务器。它允许 AI 代理通过标准输入输出（stdio）、SSE 或 StreamableHTTP 无缝调用现有的 REST API。\n\n## 环境准备\n\n在开始之前，请确保您的开发环境满足以下要求：\n\n*   **Node.js**: 版本 v20 或更高。\n    *   检查版本：`node -v`\n    *   如未安装，请访问 [Node.js 官网](https:\u002F\u002Fnodejs.org\u002F) 下载。\n*   **包管理器**: npm、yarn 或 pnpm（任选其一）。\n*   **OpenAPI 规范文件**: 准备好您的 API 定义文件（`.json` 或 `.yaml` 格式）。\n\n> **国内加速建议**：如果 npm 安装缓慢，建议配置淘宝镜像源：\n> ```bash\n> npm config set registry https:\u002F\u002Fregistry.npmmirror.com\n> ```\n\n## 安装步骤\n\n使用 npm 全局安装该工具：\n\n```bash\nnpm install -g openapi-mcp-generator\n```\n\n如果您使用 yarn 或 pnpm，也可以使用以下命令：\n\n```bash\nyarn global add openapi-mcp-generator\n# 或\npnpm add -g openapi-mcp-generator\n```\n\n## 基本使用\n\n### 1. 生成 MCP 服务器（默认 stdio 模式）\n\n这是最简单的用法，将 OpenAPI 文件转换为本地可运行的 MCP 服务器代码。\n\n```bash\nopenapi-mcp-generator --input path\u002Fto\u002Fopenapi.json --output path\u002Fto\u002Foutput\u002Fdir\n```\n\n*   `--input` (-i): 指向您的 OpenAPI 规范文件路径或 URL。\n*   `--output` (-o): 指定生成项目的输出目录。\n\n### 2. 生成 Web 服务器（SSE 模式）\n\n如果您希望通过 HTTP\u002FSSE 让浏览器或远程客户端连接，可指定 `web` 传输模式：\n\n```bash\nopenapi-mcp-generator --input path\u002Fto\u002Fopenapi.json --output path\u002Fto\u002Foutput\u002Fdir --transport=web --port=3000\n```\n\n### 3. 运行生成的服务\n\n进入生成的目录并安装依赖，然后启动服务：\n\n```bash\ncd path\u002Fto\u002Foutput\u002Fdir\nnpm install\n\n# 运行 stdio 模式（适合本地 LLM 工具集成）\nnpm start\n\n# 运行 Web 模式（适合浏览器测试或远程连接）\nnpm run start:web\n\n# 运行 StreamableHTTP 模式\nnpm run start:http\n```\n\n**测试提示**：对于 `web` 和 `streamable-http` 模式，启动后直接在浏览器访问 `http:\u002F\u002Flocalhost:\u003Cport>`（例如 `http:\u002F\u002Flocalhost:3000`），即可使用内置的可视化测试客户端与您的 MCP 服务器交互。","某电商团队的 AI 助手需要实时调用内部库存与订单系统的 REST API 来回答用户查询，但现有接口仅有标准的 OpenAPI 文档，缺乏直接对接大模型的能力。\n\n### 没有 openapi-mcp-generator 时\n- 开发人员需手动编写大量胶水代码，将 OpenAPI 定义逐个转换为 MCP Server 的工具函数，耗时且易出错。\n- 每次后端接口字段变更，都需要同步修改 AI 侧的调用逻辑和参数校验规则，维护成本极高。\n- 缺乏统一的运行时验证机制，AI 生成的错误参数往往直到请求失败时才被发现，调试困难。\n- 为了支持不同的通信方式（如 Stdio 或 Web SSE），需要重复构建多套服务架构，资源浪费严重。\n- 新加入的开发者难以快速理解如何安全地让 AI 访问敏感业务接口，权限配置混乱。\n\n### 使用 openapi-mcp-generator 后\n- 只需一条命令即可基于现有的 OpenAPI 文件自动生成完整的 MCP Server 项目，将集成时间从数天缩短至几分钟。\n- 工具自动根据接口定义生成 Zod 校验 schema，确保 AI 传入的参数在发送前就符合规范，大幅减少运行错误。\n- 当后端 API 更新时，重新运行生成器即可同步最新逻辑，保证了 AI 能力与业务接口的高度一致。\n- 灵活指定 `--transport` 参数，一键切换 Stdio、SSE 或 StreamableHTTP 模式，无缝适配本地调试或云端部署需求。\n- 内置支持 API Key 和 OAuth2 等多种认证方式，通过环境变量即可安全管理 AI 对敏感数据的访问权限。\n\nopenapi-mcp-generator 通过将标准 API 文档瞬间转化为可交互的 AI 桥梁，彻底消除了传统集成中的手工编码负担与维护断层。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fharsha-iiiv_openapi-mcp-generator_ea1310f2.png","harsha-iiiv","Harsha v","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fharsha-iiiv_adc14046.png","SDE || Indian Institute of Information Technology ,Vadodara | GCI '19' mentor @CircuitVerse ,always excited to try something new.",null,"harshadotvardhan@gmail.com","sdotharsha","https:\u002F\u002Fgithub.com\u002Fharsha-iiiv",[81,85],{"name":82,"color":83,"percentage":84},"TypeScript","#3178c6",90.8,{"name":86,"color":87,"percentage":88},"JavaScript","#f1e05a",9.2,555,79,"2026-04-05T19:31:03","MIT","Linux, macOS, Windows","未说明",{"notes":96,"python":97,"dependencies":98},"该工具基于 Node.js 运行，需要 Node.js v20 或更高版本。支持通过 npm、yarn 或 pnpm 安装。生成的项目包含完整的 TypeScript 配置和依赖，可根据不同传输模式（stdio、web\u002FSSE、streamable-http）启动服务。认证信息需通过环境变量配置。","不适用",[99,100,101,102,103,104],"@modelcontextprotocol\u002Fsdk","axios","zod","json-schema-to-zod","hono","uuid",[13,52],"2026-03-27T02:49:30.150509","2026-04-11T18:33:33.965720",[109,114,119,124,129,133],{"id":110,"question_zh":111,"answer_zh":112,"source_url":113},22670,"遇到 'RangeError: Maximum call stack size exceeded' 错误怎么办？","该错误通常由 OpenAPI 架构中的递归引用或循环结构（例如对象直接或间接引用自身）引起。当前的转换函数在处理此类架构时会无限递归，导致调用栈溢出。这通常发生在缺少循环检测或 `$ref` 解析逻辑的情况下。建议检查您的 OpenAPI JSON 文件是否包含类似 `TreeNode` 引用自身的递归定义。如果存在，可能需要简化架构或在工具更新支持循环检测前避免使用此类结构。","https:\u002F\u002Fgithub.com\u002Fharsha-iiiv\u002Fopenapi-mcp-generator\u002Fissues\u002F21",{"id":115,"question_zh":116,"answer_zh":117,"source_url":118},22671,"运行 SSE 版本服务器时出现 'ERR_HTTP_HEADERS_SENT' 错误如何解决？","此错误是因为在 `\u002Fsse` 路由中头部被设置了两次。解决方法是修改 `src\u002Fweb-server.ts` 文件：\n1. 确保不要重复设置响应头。\n2. 将 `await transport.handlePostMessage(req, res);` 修改为 `await transport.handlePostMessage(req, res, req.body);`。\n这能确保消息处理时正确传递请求体，避免重复写入头部信息。","https:\u002F\u002Fgithub.com\u002Fharsha-iiiv\u002Fopenapi-mcp-generator\u002Fissues\u002F5",{"id":120,"question_zh":121,"answer_zh":122,"source_url":123},22672,"是否支持自定义生成代码的 Node.js 引擎版本？","目前项目正在探讨添加此功能，允许用户在生成 MCP 代码时指定 Node 引擎版本（例如 `--node=24.0.0`）。维护者表示，如果实施该功能，将限制最低版本为 Node.js 18，并会验证所有依赖项在 Node.js 18 及以上版本的兼容性。在此之前，建议默认使用兼容 Node.js 18+ 的环境。","https:\u002F\u002Fgithub.com\u002Fharsha-iiiv\u002Fopenapi-mcp-generator\u002Fissues\u002F28",{"id":125,"question_zh":126,"answer_zh":127,"source_url":128},22673,"使用某些 OpenAPI 规范文件（如 Slack 或 GitHub API）解析失败怎么办？","默认的 `@apidevtools\u002Fswagger-parser` 在处理某些复杂的参考解析时可能会失败（例如报错 'Invalid method'）。解决方案是改用 `@readme\u002Fopenapi-parser` 进行解析，它对这类文件的兼容性更好。此外，社区建议扩展工具以支持直接传入 `OpenAPIV3.Document` 对象而不仅仅是文件路径，从而让用户可以在外部自行处理解析逻辑后再传入工具。","https:\u002F\u002Fgithub.com\u002Fharsha-iiiv\u002Fopenapi-mcp-generator\u002Fissues\u002F35",{"id":130,"question_zh":131,"answer_zh":132,"source_url":113},22674,"为什么我的 OpenAPI v2 文件转换后仍然报错？","即使将文件转换为 OpenAPI v3 格式，如果架构中包含深层的递归引用（ cyclic structures），仍然可能触发 'Maximum call stack size exceeded' 错误。这是因为生成器内部的 `mapOpenApiSchemaToJsonSchema` 函数缺乏对循环引用的检测机制。建议检查转换后的 JSON 文件，移除或重构那些自我引用的 schema 定义。",{"id":134,"question_zh":135,"answer_zh":136,"source_url":118},22675,"如何修复生成的 Web 服务器中 SSE 连接建立失败的问题？","除了修复头部重复发送的问题外，还需要确保在调用 `transport.handlePostMessage` 时显式传递 `req.body` 参数。完整的修复代码应包含正确的 Express 路由设置，确保 CORS 已启用，并在实例化 `SSEServerTransport` 后正确绑定消息处理逻辑。如果问题依旧，请检查是否使用了最新版本的生成器，因为旧版本可能存在已知的传输层 bug。",[]]