shelfry.app/p/cortex

cortex

Cortex 是一个面向 API 文档与代码生成的命令行工具。它读取 OpenAPI、AsyncAPI、GraphQL、gRPC、OpenRPC 等规范以及 Markdown 文档，通过一份 cortex.config.yml 统一声明所有 API 来源，然后生成三类产物：支持 TypeScript、Python、Go、Java 等十余种语言的类型化 SDK；带交互式 API 参考页的静态 HTML 文档站；以及内嵌规范、SDK 指南和项目文档的 MCP 服务器，供 AI 代理读取上下文。它提供校验、生成、本地预览、发布等子命令，支持按语言单独生成、干跑预览，也可用少量 Eta 模板覆盖来定制输出。

macOSWindowsLinuxMCP Server MIT

访问官网 GitHub

Stars

3.3K

Forks

181

语言

TypeScript

Every developer. Every agent.

Cortex turns API specifications and Markdown into typed SDKs, interactive documentation, and an MCP server from one project configuration.

OpenAPI · AsyncAPI · GraphQL · gRPC · OpenRPC · Markdown

Documentation ·

Live demo · Website · Changelog

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

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.

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.

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.

Task	Split toolchain	Cortex Docs
Configuration	Configure SDK, documentation, and MCP generators	Declare all API sources in one project configuration
Generation	Coordinate separate commands and output directories	Generate all configured outputs with one command
Customization	Maintain templates for each generator	Override only the required Eta templates
Publishing	Maintain a release process for each package	Review one publish plan for registries and GitHub
Developer interface	Keep guides separate from API references	Combine Markdown, API references, and SDK guides
Agent interface	Maintain MCP servers and context separately	Generate MCP servers with specifications, SDK guides, and project documentation

Node.js 20 or later
npm 10 or later

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

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.

Command	Result
`cortex init`	Create a project and sample files.
`cortex validate`	Validate the config and every API source.
`cortex generate`	Generate configured SDKs and the MCP server.
`cortex generate --language typescript`	Generate one configured language.
`cortex generate --dry-run`	Show planned output without writing files.
`cortex docs serve`	Start the development server and watch project files.
`cortex docs build --output .cortex/docs`	Build static HTML documentation.
`cortex mcp generate`	Generate only the MCP server.
`cortex publish --dry-run`	Check package publication without uploading.
`cortex publish`	Publish enabled generated packages.

Source	Generated SDK	Documentation	Generated MCP server
OpenAPI	REST clients	Interactive API reference	Callable tools and embedded specs
AsyncAPI	WebSocket clients	Channel and message reference	Payload-preparation tools and specs
GraphQL SDL	Query, mutation, and subscription clients	Operation and type reference	Callable tools and embedded schema
Protocol Buffer	Unary and streaming gRPC clients	Service and message reference	Embedded `.proto` resources
OpenRPC	JSON-RPC clients	Method and schema reference	Callable tools and embedded specs

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.

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.

The release workflow publishes @cortex-docs/cli and @cortex-docs/mcp. The CLI tarball includes the internal runtime workspaces.

Package	Distribution	Purpose
`@cortex-docs/cli`	npm	Command-line interface and project workflow
`@cortex-docs/mcp`	npm	MCP server for the Cortex documentation
`@cortex-docs/core`	Included in CLI	Configuration loader and specification parsers
`@cortex-docs/codegen`	Included in CLI	SDK generation engine and language templates
`@cortex-docs/mcp-gen`	Included in CLI	MCP server generator
`@cortex-docs/docs-ui`	Included in CLI	Documentation runtime used by the CLI

Contributing and security

Read CONTRIBUTING.md and DEVELOPMENT.md before you open a pull request.

Report vulnerabilities through the private process in SECURITY.md.

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.

核心功能

从多种 API 规范生成十余种语言的类型化 SDK
合并多个规范文件到同一个生成的 SDK
生成带交互式 API 参考的静态 HTML 文档
产出含类型工具与项目文档的 MCP 服务器
用 Eta 模板覆盖按需定制生成结果
一条命令完成校验、生成、预览与发布

内容由编辑整理，部分信息来自 GitHub 与项目官网，版权归原作者所有。发现错误？报告问题

cortex

Every developer. Every agent.

Documentation ·

Try Cortex in 60 seconds

We love open source

Features

Unlimited specs. Multiple ways to use it.

Requirements

Configuration

Commands

Protocol support

Production documentation

MCP output

Packages

Documentation

Contributing and security

License

核心功能