Skip to content
Back to search

cortex

Cortex - Generates interactive API documentation, typed SDKs, and MCP servers from OpenAPI, AsyncAPI, GraphQL, gRPC, OpenRPC, and Markdown.

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/cortex-docs--cortex/badge.svg)](/listings/cortex-docs--cortex)

HTML

<a href="/listings/cortex-docs--cortex"><img src="/api/listings/cortex-docs--cortex/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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 · 267 lines

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

  1. <p align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="packages/docs-site/assets/logo_dark.svg">
  4. <source media="(prefers-color-scheme: light)" srcset="packages/docs-site/assets/logo_light.svg">
  5. <img alt="Cortex" src="packages/docs-site/assets/logo_light.svg" width="246">
  6. </picture>
  7. </p>
  8. <h2 align="center">Every developer. Every agent.</h2>
  9. <p align="center">
  10. Cortex turns API specifications and Markdown into typed SDKs, interactive documentation, and an MCP server from one project configuration.
  11. </p>
  12. <p align="center">
  13. OpenAPI · AsyncAPI · GraphQL · gRPC · OpenRPC · Markdown
  14. </p>
  15. <p align="center">
  16. <a href="https://github.com/cortex-docs/cortex/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/cortex-docs/cortex/actions/workflows/ci.yml/badge.svg"></a>
  17. <a href="https://www.npmjs.com/package/@cortex-docs/cli"><img alt="npm version" src="https://img.shields.io/npm/v/@cortex-docs/cli.svg"></a>
  18. <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
  19. <a href="https://github.com/cortex-docs/cortex/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/cortex-docs/cortex?style=flat&logo=github"></a>
  20. </p>
  21. <h3 align="center">
  22. <a href="https://docs.cortexdocs.dev"><strong>Documentation</strong></a> ·
  23. <a href="https://demo.cortexdocs.dev"><strong>Live demo</strong></a> ·
  24. <a href="https://cortexdocs.dev"><strong>Website</strong></a> ·
  25. <a href="CHANGELOG.md"><strong>Changelog</strong></a>
  26. </h3>
  27. <p align="center">
  28. <a href="https://www.producthunt.com/products/cortex-25?embed=true&amp;utm_source=badge-top-post-badge&amp;utm_medium=badge&amp;utm_campaign=badge-cortex-27" target="_blank" rel="noopener noreferrer"><img alt="Cortex - Turn API specs into docs, SDKs, and MCP servers | Product Hunt" width="250" height="54" src="https://api.producthunt.com/widgets/embed-image/v1/top-post-badge.svg?post_id=1241923&amp;theme=light&amp;period=daily&amp;t=1789286262611"></a>
  29. </p>
  30. </br>
  31. <p align="center">
  32. <a href="https://demo.cortexdocs.dev">
  33. <picture>
  34. <source media="(prefers-reduced-motion: reduce)" srcset="assets/cortex-overview-poster.png">
  35. <img src="assets/cortex-overview.png" width="1200" alt="Run cortex generate with a configured OpenAPI file, then explore Getting Started, API Reference, SDKs, and MCP in the live demo. Click to try it.">
  36. </picture>
  37. </a>
  38. </p>
  39. Cortex combines OpenAPI, AsyncAPI, GraphQL, Protocol Buffer, OpenRPC, and Markdown sources. Developers get interactive documentation, applications get typed SDKs, and AI agents get an MCP server with project context.
  40. If Cortex helps your team, [star this repository](https://github.com/cortex-docs/cortex) to support its development.
  41. ## Try Cortex in 60 seconds
  42. Start a local demo:
  43. ```bash
  44. mkdir petstore
  45. cd petstore
  46. npm install --global @cortex-docs/cli
  47. cortex init petstore
  48. cortex docs serve
  49. ```
  50. Open `http://localhost:3012`. Press `Ctrl+C` to stop the server.
  51. ## We love open source
  52. Keep your Markdown in Git. Add `cortex.config.yml` to the default branch of your public GitHub repository, then run:
  53. ```bash
  54. npx -y @cortex-docs/cli deploy https://github.com/OWNER/REPO
  55. npx -y @cortex-docs/cli mcp-serve https://github.com/OWNER/REPO
  56. ```
  57. The first command publishes a free documentation site at `PROJECT.cortexdocs.dev`. The second connects AI clients to current documentation through local MCP.
  58. Deploy requires repository write access. MCP works with public read access and checks for changes before each request.
  59. See the [open source hosting guide](packages/docs-site/docs/open-source-hosting.md) for configuration, custom domains, automatic updates, and limits.
  60. ## Features
  61. - Generate SDKs for TypeScript, Python, Go, Java, Kotlin, Ruby, PHP, C#, Rust, C++, and C.
  62. - Combine multiple specification files in one generated SDK.
  63. - Generate HTTP, WebSocket, GraphQL, gRPC, and JSON-RPC clients.
  64. - Build static HTML documentation with interactive API reference pages.
  65. - Generate an MCP server with typed tools, embedded specifications, SDK guides, and project documentation for AI agents.
  66. - Add Markdown pages, SDK guides, and all API specifications to the MCP server.
  67. - Customize generated output with sparse Eta template overrides.
  68. - Publish generated packages and MCP servers to language registries and GitHub repositories.
  69. ## Unlimited specs. Multiple ways to use it.
  70. Generate interactive docs for exploration, typed SDKs for integration, and MCP servers for AI agents.
  71. | Task | Split toolchain | Cortex Docs |
  72. | ------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------- |
  73. | Configuration | Configure SDK, documentation, and MCP generators | Declare all API sources in one project configuration |
  74. | Generation | Coordinate separate commands and output directories | Generate all configured outputs with one command |
  75. | Customization | Maintain templates for each generator | Override only the required Eta templates |
  76. | Publishing | Maintain a release process for each package | Review one publish plan for registries and GitHub |
  77. | Developer interface | Keep guides separate from API references | Combine Markdown, API references, and SDK guides |
  78. | Agent interface | Maintain MCP servers and context separately | Generate MCP servers with specifications, SDK guides, and project documentation |
  79. ## Requirements
  80. - Node.js 20 or later
  81. - npm 10 or later
  82. Some generated SDKs require the normal compiler or package manager for their target language.
  83. ## Configuration
  84. `cortex init` creates `cortex.config.yml`. Relative paths start from the directory that contains this file.
  85. ```yaml
  86. project: my-api
  87. title: My API Docs
  88. logo: ./assets/logo.svg
  89. theme: system
  90. primaryColor: '#ffffff'
  91. custom_head_html: |-
  92. <meta name="theme-color" content="#ffffff">
  93. <link rel="stylesheet" href="/assets/custom.css">
  94. sources:
  95. - title: REST API
  96. type: openapi-spec
  97. spec: ./specs/openapi.yaml
  98. intro: ./docs/rest.md
  99. languages:
  100. - language: typescript
  101. package_name: '@my-org/my-api'
  102. - language: python
  103. package_name: my-api
  104. - title: Realtime API
  105. type: asyncapi-spec
  106. spec: ./specs/asyncapi.yaml
  107. languages:
  108. - language: typescript
  109. package_name: '@my-org/my-api'
  110. - title: GraphQL API
  111. type: graphql-spec
  112. spec: ./specs/schema.graphql
  113. endpoint: https://api.example.com/graphql
  114. languages:
  115. - language: typescript
  116. package_name: '@my-org/my-api'
  117. output:
  118. base_dir: ./generated
  119. docs:
  120. - section: Get started
  121. sources:
  122. - title: Quickstart
  123. document: ./docs/quickstart.md
  124. mcp:
  125. package_name: '@my-org/my-api-mcp'
  126. ```
  127. `primaryColor` sets the documentation accent color as a six-digit hex value.
  128. `custom_head_html` adds trusted HTML to every documentation page. This field supports metadata, stylesheets, and analytics scripts.
  129. Store local head resources in the project `assets` directory. Cortex serves these files from `/assets/*`.
  130. Cortex does not sanitize this value. Add only HTML that you trust.
  131. Add `?appearance=dark` or `?appearance=light` to any documentation URL to select its initial appearance. The parameter takes priority over the project theme and the visitor's stored preference.
  132. For example, `/docs/quickstart?appearance=dark` opens the quickstart in dark mode. The theme button can change the appearance after the page loads.
  133. Sources that use the same language and `package_name` are merged into one SDK. Cortex rejects duplicate operation and type names that would make a merge ambiguous.
  134. See the [configuration reference](packages/docs-site/docs/configuration.md) for all fields.
  135. ## Commands
  136. | Command | Result |
  137. | ----------------------------------------- | ----------------------------------------------------- |
  138. | `cortex init <name>` | Create a project and sample files. |
  139. | `cortex validate` | Validate the config and every API source. |
  140. | `cortex generate` | Generate configured SDKs and the MCP server. |
  141. | `cortex generate --language typescript` | Generate one configured language. |
  142. | `cortex generate --dry-run` | Show planned output without writing files. |
  143. | `cortex docs serve` | Start the development server and watch project files. |
  144. | `cortex docs build --output .cortex/docs` | Build static HTML documentation. |
  145. | `cortex mcp generate` | Generate only the MCP server. |
  146. | `cortex publish --dry-run` | Check package publication without uploading. |
  147. | `cortex publish` | Publish enabled generated packages. |
  148. ## Protocol support
  149. | Source | Generated SDK | Documentation | Generated MCP server |
  150. | --------------- | ----------------------------------------- | ----------------------------- | ----------------------------------- |
  151. | OpenAPI | REST clients | Interactive API reference | Callable tools and embedded specs |
  152. | AsyncAPI | WebSocket clients | Channel and message reference | Payload-preparation tools and specs |
  153. | GraphQL SDL | Query, mutation, and subscription clients | Operation and type reference | Callable tools and embedded schema |
  154. | Protocol Buffer | Unary and streaming gRPC clients | Service and message reference | Embedded `.proto` resources |
  155. | OpenRPC | JSON-RPC clients | Method and schema reference | Callable tools and embedded specs |
  156. The generated MCP server does not call gRPC methods. It exposes Protocol Buffer files as MCP resources so an agent can inspect the service contract.
  157. ## Production documentation
  158. The build command exports the documentation as static HTML, CSS, JavaScript, and data files.
  159. ```bash
  160. cortex docs build --output .cortex/docs
  161. ```
  162. Deploy the output directory to a static web host. Configure the host to resolve page URLs such as `/docs/quickstart` to `/docs/quickstart.html`.
  163. The deployed site needs no Node.js server or access to the original configuration and specifications. Rebuild the site after source changes. Use `cortex docs serve` for a local preview with file watching.
  164. ## MCP output
  165. ```bash
  166. cortex mcp generate --output .cortex/mcp-server
  167. cd .cortex/mcp-server
  168. npm install
  169. npm run build
  170. npm start
  171. ```
  172. The generated package contains local copies of every configured specification. It also embeds configured Markdown and generated SDK README files as tools.
  173. ## Packages
  174. The release workflow publishes `@cortex-docs/cli` and `@cortex-docs/mcp`. The CLI tarball includes the internal runtime workspaces.
  175. | Package | Distribution | Purpose |
  176. | ---------------------- | --------------- | ---------------------------------------------- |
  177. | `@cortex-docs/cli` | npm | Command-line interface and project workflow |
  178. | `@cortex-docs/mcp` | npm | MCP server for the Cortex documentation |
  179. | `@cortex-docs/core` | Included in CLI | Configuration loader and specification parsers |
  180. | `@cortex-docs/codegen` | Included in CLI | SDK generation engine and language templates |
  181. | `@cortex-docs/mcp-gen` | Included in CLI | MCP server generator |
  182. | `@cortex-docs/docs-ui` | Included in CLI | Documentation runtime used by the CLI |
  183. ## Documentation
  184. - [Quickstart](packages/docs-site/docs/quickstart.md)
  185. - [Configuration](packages/docs-site/docs/configuration.md)
  186. - [SDK generation](packages/docs-site/docs/sdk-generation.md)
  187. - [WebSocket SDKs](packages/docs-site/docs/websocket-sdks.md)
  188. - [GraphQL](packages/docs-site/docs/graphql.md)
  189. - [gRPC](packages/docs-site/docs/grpc.md)
  190. - [OpenRPC](packages/docs-site/docs/openrpc.md)
  191. - [MCP servers](packages/docs-site/docs/mcp-servers.md)
  192. - [Publishing](packages/docs-site/docs/publishing.md)
  193. ## Contributing and security
  194. Read [CONTRIBUTING.md](CONTRIBUTING.md) and [DEVELOPMENT.md](DEVELOPMENT.md) before you open a pull request.
  195. Report vulnerabilities through the private process in [SECURITY.md](SECURITY.md).
  196. ## License
  197. Cortex Docs is available under the [MIT License](LICENSE).
  198. If Cortex saves you time, [give the repository a star](https://github.com/cortex-docs/cortex). It helps more developers find the project.

Ratings and comments

Sign in to rate this skill.

Sign in

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