Skip to content
Back to search

openapi-to-mcpserver

A tool&lib that can automatically convert OpenAPI documents into Higress remote MCP server configurations.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/higress-group--openapi-to-mcpserver/badge.svg)](/listings/higress-group--openapi-to-mcpserver)

HTML

<a href="/listings/higress-group--openapi-to-mcpserver"><img src="/api/listings/higress-group--openapi-to-mcpserver/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

go install github.com/higress-group/openapi-to-mcpserver/cmd/openapi-to-mcp@latest

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 520 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # OpenAPI to MCP Server
  2. A tool to convert OpenAPI specifications to MCP (Model Context Protocol) server configurations.
  3. ## Installation
  4. ```bash
  5. go install github.com/higress-group/openapi-to-mcpserver/cmd/openapi-to-mcp@latest
  6. ```
  7. ## Usage
  8. ```bash
  9. openapi-to-mcp --input path/to/openapi.json --output path/to/mcp-server.yaml
  10. ```
  11. ### Options
  12. - `--input`: Path to the OpenAPI specification file (JSON or YAML) (required)
  13. - `--output`: Path to the output MCP configuration file (YAML) (required)
  14. - `--server-name`: Name of the MCP server (default: "openapi-server")
  15. - `--tool-prefix`: Prefix for tool names (default: "")
  16. - `--format`: Output format (yaml or json) (default: "yaml")
  17. - `--validate`: Validate the OpenAPI specification (default: false)
  18. - `--template`: Path to a template file to patch the output (default: "")
  19. ## Example
  20. ```bash
  21. openapi-to-mcp --input petstore.json --output petstore-mcp.yaml --server-name petstore
  22. ```
  23. ### Converting OpenAPI to Higress REST-to-MCP Configuration
  24. This tool can be used to convert an OpenAPI specification to a Higress REST-to-MCP configuration. Here's a complete example:
  25. 1. Start with an OpenAPI specification (petstore.json):
  26. ```json
  27. {
  28. "openapi": "3.0.0",
  29. "info": {
  30. "version": "1.0.0",
  31. "title": "Swagger Petstore",
  32. "description": "A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification"
  33. },
  34. "servers": [
  35. {
  36. "url": "http://petstore.swagger.io/v1"
  37. }
  38. ],
  39. "paths": {
  40. "/pets": {
  41. "get": {
  42. "summary": "List all pets",
  43. "operationId": "listPets",
  44. "parameters": [
  45. {
  46. "name": "limit",
  47. "in": "query",
  48. "description": "How many items to return at one time (max 100)",
  49. "required": false,
  50. "schema": {
  51. "type": "integer",
  52. "format": "int32"
  53. }
  54. }
  55. ],
  56. "responses": {
  57. "200": {
  58. "description": "A paged array of pets",
  59. "content": {
  60. "application/json": {
  61. "schema": {
  62. "type": "object",
  63. "properties": {
  64. "pets": {
  65. "type": "array",
  66. "items": {
  67. "type": "object",
  68. "properties": {
  69. "id": {
  70. "type": "integer",
  71. "description": "Unique identifier for the pet"
  72. },
  73. "name": {
  74. "type": "string",
  75. "description": "Name of the pet"
  76. },
  77. "tag": {
  78. "type": "string",
  79. "description": "Tag of the pet"
  80. }
  81. }
  82. }
  83. },
  84. "nextPage": {
  85. "type": "string",
  86. "description": "URL to get the next page of pets"
  87. }
  88. }
  89. }
  90. }
  91. }
  92. }
  93. }
  94. },
  95. "post": {
  96. "summary": "Create a pet",
  97. "operationId": "createPets",
  98. "requestBody": {
  99. "description": "Pet to add to the store",
  100. "required": true,
  101. "content": {
  102. "application/json": {
  103. "schema": {
  104. "type": "object",
  105. "required": ["name"],
  106. "properties": {
  107. "name": {
  108. "type": "string",
  109. "description": "Name of the pet"
  110. },
  111. "tag": {
  112. "type": "string",
  113. "description": "Tag of the pet"
  114. }
  115. }
  116. }
  117. }
  118. }
  119. },
  120. "responses": {
  121. "201": {
  122. "description": "Null response"
  123. }
  124. }
  125. }
  126. },
  127. "/pets/{petId}": {
  128. "get": {
  129. "summary": "Info for a specific pet",
  130. "operationId": "showPetById",
  131. "parameters": [
  132. {
  133. "name": "petId",
  134. "in": "path",
  135. "required": true,
  136. "description": "The id of the pet to retrieve",
  137. "schema": {
  138. "type": "string"
  139. }
  140. }
  141. ],
  142. "responses": {
  143. "200": {
  144. "description": "Expected response to a valid request",
  145. "content": {
  146. "application/json": {
  147. "schema": {
  148. "type": "object",
  149. "properties": {
  150. "id": {
  151. "type": "integer",
  152. "description": "Unique identifier for the pet"
  153. },
  154. "name": {
  155. "type": "string",
  156. "description": "Name of the pet"
  157. },
  158. "tag": {
  159. "type": "string",
  160. "description": "Tag of the pet"
  161. }
  162. }
  163. }
  164. }
  165. }
  166. }
  167. }
  168. }
  169. }
  170. }
  171. }
  172. ```
  173. 2. Convert it to a Higress REST-to-MCP configuration:
  174. ```bash
  175. openapi-to-mcp --input petstore.json --output petstore-mcp.yaml --server-name petstore
  176. ```
  177. 3. The resulting petstore-mcp.yaml file:
  178. ```yaml
  179. server:
  180. name: petstore
  181. tools:
  182. - name: showPetById
  183. description: Info for a specific pet
  184. args:
  185. - name: petId
  186. description: The id of the pet to retrieve
  187. type: string
  188. required: true
  189. position: path
  190. requestTemplate:
  191. url: /pets/{petId}
  192. method: GET
  193. responseTemplate:
  194. prependBody: |
  195. # API Response Information
  196. Below is the response from an API call. To help you understand the data, I've provided:
  197. 1. A detailed description of all fields in the response structure
  198. 2. The complete API response
  199. ## Response Structure
  200. > Content-Type: application/json
  201. - **id**: Unique identifier for the pet (Type: integer)
  202. - **name**: Name of the pet (Type: string)
  203. - **tag**: Tag of the pet (Type: string)
  204. ## Original Response
  205. - name: createPets
  206. description: Create a pet
  207. args:
  208. - name: name
  209. description: Name of the pet
  210. type: string
  211. required: true
  212. position: body
  213. - name: tag
  214. description: Tag of the pet
  215. type: string
  216. position: body
  217. requestTemplate:
  218. url: /pets
  219. method: POST
  220. headers:
  221. - key: Content-Type
  222. value: application/json
  223. responseTemplate: {}
  224. - name: listPets
  225. description: List all pets
  226. args:
  227. - name: limit
  228. description: How many items to return at one time (max 100)
  229. type: integer
  230. position: query
  231. requestTemplate:
  232. url: /pets
  233. method: GET
  234. responseTemplate:
  235. prependBody: |
  236. # API Response Information
  237. Below is the response from an API call. To help you understand the data, I've provided:
  238. 1. A detailed description of all fields in the response structure
  239. 2. The complete API response
  240. ## Response Structure
  241. > Content-Type: application/json
  242. - **pets**: (Type: array)
  243. - **pets[].id**: Unique identifier for the pet (Type: integer)
  244. - **pets[].name**: Name of the pet (Type: string)
  245. - **pets[].tag**: Tag of the pet (Type: string)
  246. - **nextPage**: URL to get the next page of pets (Type: string)
  247. ## Original Response
  248. ```
  249. 4. This configuration can be used with Higress by adding it to your Higress gateway configuration.
  250. Note how the tool automatically sets the `position` field for each parameter based on its location in the OpenAPI specification:
  251. - The `petId` parameter is set to `position: path` because it's defined as `in: path` in the OpenAPI spec
  252. - The `limit` parameter is set to `position: query` because it's defined as `in: query` in the OpenAPI spec
  253. - The request body properties (`name` and `tag`) are set to `position: body`
  254. The MCP server will automatically handle these parameters in the correct location when making API requests.
  255. For more information about using this configuration with Higress REST-to-MCP, please refer to the [Higress REST-to-MCP documentation](https://higress.cn/en/ai/mcp-quick-start/#configuring-rest-api-mcp-server).
  256. ## Features
  257. - Converts OpenAPI paths to MCP tools
  258. - Supports both JSON and YAML OpenAPI specifications
  259. - Generates MCP configuration with server and tool definitions
  260. - Preserves parameter descriptions and types
  261. - Automatically sets parameter positions based on OpenAPI parameter locations
  262. - Handles path, query, header, cookie, and body parameters
  263. - Generates response templates with field descriptions and improved formatting for LLM understanding
  264. - **NEW**: Generates output schemas for MCP Protocol 2025-06-18 support
  265. - **NEW**: Supports structured content responses for enhanced MCP compatibility
  266. - Optional validation of OpenAPI specifications (disabled by default)
  267. - Supports template-based patching of the generated configuration
  268. ## Template-Based Patching
  269. You can use the `--template` flag to provide a YAML file that will be used to patch the generated configuration. This is useful for adding common headers, authentication, or other customizations to all tools in the configuration.
  270. Example template file:
  271. ```yaml
  272. server:
  273. name: "openapi-server"
  274. config:
  275. apiKey: ""
  276. tools:
  277. outputSchema:
  278. type: object
  279. description: "Default output schema for all tools"
  280. properties:
  281. success:
  282. type: boolean
  283. description: "Indicates if the operation was successful"
  284. message:
  285. type: string
  286. description: "Response message"
  287. requestTemplate:
  288. headers:
  289. - key: Authorization
  290. value: "APPCODE {{.config.apiKey}}"
  291. - key: X-Ca-Nonce
  292. value: "{{uuidv4}}"
  293. ```
  294. When applied, this template will:
  295. 1. Add an `apiKey` field to the server config
  296. 2. Add a default output schema to all tools (enabling MCP 2025-06-18 support)
  297. 3. Add the specified headers to all tools in the configuration
  298. Usage:
  299. ```bash
  300. openapi-to-mcp --input api-spec.json --output mcp-server.yaml --server-name my-server --template template.yaml
  301. ```
  302. The template values like `{{.config.apiKey}}` or `"{{uuidv4}}"` are not processed by the tool but are preserved in the output for use by the MCP server at runtime.
  303. ## Security Scheme Conversion
  304. The tool now supports the conversion of security schemes defined in your OpenAPI specification.
  305. ### Server-Level Security Schemes
  306. Security schemes defined in the `components.securitySchemes` section of your OpenAPI document are converted into a list under `server.securitySchemes` in the generated MCP configuration.
  307. **Example OpenAPI Snippet (`components.securitySchemes`):**
  308. ```json
  309. {
  310. "components": {
  311. "securitySchemes": {
  312. "BasicAuth": {
  313. "type": "http",
  314. "scheme": "basic"
  315. },
  316. "ApiKeyAuth": {
  317. "type": "apiKey",
  318. "in": "header",
  319. "name": "X-API-KEY"
  320. }
  321. }
  322. }
  323. }
  324. ```
  325. **Corresponding MCP YAML Output (`server.securitySchemes`):**
  326. ```yaml
  327. server:
  328. name: your-server-name
  329. securitySchemes:
  330. - id: ApiKeyAuth # Note: Schemes are sorted by ID in the output
  331. type: apiKey
  332. in: header
  333. name: X-API-KEY
  334. - id: BasicAuth
  335. type: http
  336. scheme: basic
  337. # ... other server config ...
  338. ```
  339. The `defaultCredential` field within a security scheme is an MCP-specific extension (not part of the OpenAPI standard fields). During conversion, this tool reads `x-defaultCredential` (recommended) and also supports `defaultCredential` for backward compatibility.
  340. If you run with `--validate`, use `x-defaultCredential` because non-`x-` custom fields may be rejected by OpenAPI validation.
  341. ### Tool-Level Security Requirements
  342. Security requirements defined at the operation level in your OpenAPI document (using the `security` keyword) are converted into a list under `requestTemplate.security` for the corresponding tool. Each entry in this list will reference the `id` of a security scheme defined in `server.securitySchemes`.
  343. **Example OpenAPI Snippet (Operation with security):**
  344. ```json
  345. {
  346. "paths": {
  347. "/protected_resource": {
  348. "get": {
  349. "summary": "Access a protected resource",
  350. "operationId": "getProtectedResource",
  351. "security": [
  352. {
  353. "ApiKeyAuth": []
  354. }
  355. ],
  356. "responses": {
  357. "200": { "description": "Success" }
  358. }
  359. }
  360. }
  361. }
  362. }
  363. ```
  364. **Corresponding MCP YAML Output (Tool's `requestTemplate.security`):**
  365. ```yaml
  366. tools:
  367. - name: getProtectedResource
  368. description: Access a protected resource
  369. # ... args ...
  370. requestTemplate:
  371. url: /protected_resource # Actual URL depends on your server config in OpenAPI
  372. method: GET
  373. security:
  374. id: ApiKeyAuth
  375. # ... responseTemplate ...
  376. ```
  377. ### Template Overrides for Security
  378. You can use the `--template` option to:
  379. - Add new security schemes to `server.securitySchemes`.
  380. - Override existing security schemes (e.g., to add `defaultCredential`).
  381. - Override or set `security` requirements for all tools via the `tools.requestTemplate.security` path in your template file.
  382. If the template defines `server.securitySchemes` or `tools.requestTemplate.security`, these will replace any schemes/requirements derived from the OpenAPI specification.
  383. ## MCP Protocol 2025-06-18 Support
  384. This tool now supports the latest MCP Protocol version 2025-06-18, which introduces two key features:
  385. ### 1. Output Schema
  386. Tools can now define schemas for their structured outputs. The tool automatically generates output schemas based on your OpenAPI response definitions.
  387. **Example generated output schema:**
  388. ```yaml
  389. tools:
  390. - name: getUser
  391. description: Get user information
  392. # ... other fields ...
  393. outputSchema:
  394. type: object
  395. description: User information
  396. properties:
  397. id:
  398. type: integer
  399. description: User ID
  400. name:
  401. type: string
  402. description: User name
  403. email:
  404. type: string
  405. description: User email
  406. required:
  407. - id
  408. - name
  409. ```
  410. ### 2. Structured Content
  411. For MCP 2025-06-18 clients, responses include both traditional text content and structured JSON data. This allows MCP clients to process responses in a more structured way.
  412. **MCP 2025-06-18 is automatically enabled when output schemas are present.**
  413. ### Backward Compatibility
  414. The tool maintains full backward compatibility:
  415. - Older MCP clients continue to work without changes
  416. - New features are automatically enabled when output schemas are generated
  417. - Existing functionality remains unchanged
  418. ### Known Limitations
  419. **Array Root Responses**: The tool does not generate `outputSchema` for endpoints that return arrays at the root level (e.g., `GET /users` returning `[{...}]` instead of `{"users": [{...}]}`). This is due to a compatibility issue with mainstream MCP client SDKs like [mcp-inspector](https://github.com/modelcontextprotocol/inspector/issues/872), which expect `outputSchema` to be an object type, not an array. For such endpoints, the tool will still generate the tool definition but without the `outputSchema` field. The response will still be processed correctly, but without structured content support.
  420. ### Using with Higress
  421. When using the generated configuration with Higress:
  422. 1. The tool automatically generates output schemas for all endpoints with response definitions
  423. 2. MCP clients that support 2025-06-18 will automatically use the structured content
  424. 3. MCP clients that don't support 2025-06-18 will continue to work with the traditional text responses
  425. 4. No additional configuration is required - the presence of output schemas enables the new features
  426. For more information about MCP Protocol 2025-06-18, refer to the [MCP specification](https://modelcontextprotocol.io/specification).
  427. ## Contributing
  428. We welcome contributions from the community! Please see our [Contributing Guide](CONTRIBUTING.md) for information on how to get started.
  429. ## License
  430. This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.