If Cortex helps your team, star this repository to support its development.
Try Cortex in 60 seconds
Start a local demo:
mkdir petstore
cd petstore
npm install --global @cortex-docs/cli
cortex init petstore
cortex docs serve
Open http://localhost:3012. Press Ctrl+C to stop the server.
We love open source
Keep your Markdown in Git. Add cortex.config.yml to the default branch of your public GitHub repository, then run:
npx -y @cortex-docs/cli deploy https://github.com/OWNER/REPO
npx -y @cortex-docs/cli mcp-serve https://github.com/OWNER/REPO
The first command publishes a free documentation site at PROJECT.cortexdocs.dev. The second connects AI clients to current documentation through local MCP.
Deploy requires repository write access. MCP works with public read access and checks for changes before each request.
See the open source hosting guide for configuration, custom domains, automatic updates, and limits.
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.
- Build static HTML documentation 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
primaryColor: '#ffffff'
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'
primaryColor sets the documentation accent color as a six-digit hex value.
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 exports the documentation as static HTML, CSS, JavaScript, and data files.
cortex docs build --output .cortex/docs
Deploy the output directory to a static web host. Configure the host to resolve page URLs such as /docs/quickstart to /docs/quickstart.html.
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.
MCP output
cortex mcp generate --output .cortex/mcp-server
cd .cortex/mcp-server
npm install
npm run build
npm start
The generated package contains local copies of every configured specification. It also embeds configured Markdown and generated SDK README files as tools.
Packages
The release workflow publishes @cortex-docs/cli and @cortex-docs/mcp. The CLI tarball includes the internal runtime workspaces.
Documentation
Contributing and security
Read CONTRIBUTING.md and DEVELOPMENT.md before you open a pull request.
Report vulnerabilities through the private process in SECURITY.md.
License
Cortex Docs is available under the MIT License.
If Cortex saves you time, give the repository a star. It helps more developers find the project.