cortex

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.

If Cortex helps your team, star this repository to support its development.

Try Cortex in 60 seconds

Create a sample project and inspect the generation plan:

mkdir petstore
cd petstore
npm install --global @cortex-docs/cli
cortex init petstore
cortex validate
cortex generate --dry-run

Cortex validates each source and shows every planned output:

✓ Config is valid
✓ Parsed AsyncAPI: WebSocket API
✓ Parsed GraphQL: GraphQL
✓ Parsed OpenRPC: OpenRPC
✓ Parsed OpenAPI: REST API V1
Languages: typescript, python, go, java, kotlin, ruby, php, csharp, rust, cpp, c

typescript [REST + WS + GraphQL + OpenRPC] → generated/typescript/petstore-typescript-client-sdk
python [REST + WS + GraphQL + OpenRPC] → generated/python/petstore-python-sdk
...
mcp-server → generated/mcp-server

The generated MCP server gives AI agents typed tools, specifications, SDK guides, and project documentation.

Generate the files. Then start the documentation server:

cortex generate
cortex docs serve

Open http://localhost:3012. Press Ctrl+C to stop the server.

Features

• Generate SDKs for TypeScript, Python, Go, Java, Kotlin, Ruby, PHP, C#, Rust, C++, and C.
• Combine multiple specification files in one generated SDK.
• Generate HTTP, WebSocket, GraphQL, gRPC, and JSON-RPC clients.
• Generate a production documentation server with interactive API reference pages.
• Generate an MCP server with typed tools, embedded specifications, SDK guides, and project documentation for AI agents.
• Add Markdown pages, SDK guides, and all API specifications to the MCP server.
• Customize generated output with sparse Eta template overrides.
• Publish generated packages and MCP servers to language registries and GitHub repositories.

Unlimited specs. Multiple ways to use it.

Generate interactive docs for exploration, typed SDKs for integration, and MCP servers for AI agents.

Requirements

• Node.js 20 or later
• npm 10 or later

Some generated SDKs require the normal compiler or package manager for their target language.

Configuration

cortex init creates cortex.config.yml. Relative paths start from the directory that contains this file.

project: my-api
title: My API Docs
logo: ./assets/logo.svg
theme: system
custom_head_html: |-
  <meta name="theme-color" content="#ffffff">
  <link rel="stylesheet" href="/assets/custom.css">

sources:
  - title: REST API
    type: openapi-spec
    spec: ./specs/openapi.yaml
    intro: ./docs/rest.md
    languages:
      - language: typescript
        package_name: '@my-org/my-api'
      - language: python
        package_name: my-api

  - title: Realtime API
    type: asyncapi-spec
    spec: ./specs/asyncapi.yaml
    languages:
      - language: typescript
        package_name: '@my-org/my-api'

  - title: GraphQL API
    type: graphql-spec
    spec: ./specs/schema.graphql
    endpoint: https://api.example.com/graphql
    languages:
      - language: typescript
        package_name: '@my-org/my-api'

output:
  base_dir: ./generated

docs:
  - section: Get started
    sources:
      - title: Quickstart
        document: ./docs/quickstart.md

mcp:
  package_name: '@my-org/my-api-mcp'

custom_head_html adds trusted HTML to every documentation page. This field supports metadata, stylesheets, and analytics scripts.

Store local head resources in the project assets directory. Cortex serves these files from /assets/*.

Cortex does not sanitize this value. Add only HTML that you trust.

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.

For example, /docs/quickstart?appearance=dark opens the quickstart in dark mode. The theme button can change the appearance after the page loads.

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.

See the configuration reference for all fields.

Commands

Protocol support

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.

Production documentation

The build command creates a self-contained Next.js server. It is not a static HTML export.

cortex docs build --output .cortex/docs
NODE_ENV=production cortex docs start --output .cortex/docs -