types2docs

types2docs

TypeScript API のドキュメント化では通常、型に合わせて Markdown のリファレンスを手作業で更新し続けるため、両者にずれが生じます。types2docs は別の方法を取ります。すでにお持ちの宣言情報を渡してください。各宣言の名前、それがインターフェース、型エイリアス、列挙型、関数のいずれか、ドキュメントコメント、そして種類に応じた内容（メンバー、エイリアスの右辺、または関数シグネチャ）を指定すると、それらの情報だけを使い、固定のレイアウトでリファレンスを生成します。何も作り出さず、言い換えもしません。ドキュメント内のすべての文字列は、入力した内容そのままです。

レイアウトは常に同じです。ドキュメントは # のタイトル行で始まり、title を指定しない場合は「API Reference」になります。その後、指定した順序で宣言ごとにセクションが続きます。各セクションは宣言名を含む ## 見出し、ドキュメントテキストがある場合は独立した段落、Kind: <kind> の行、そして種類ごとの本文で構成されます。インターフェースはメンバーごとに1行のテーブルとして出力されます。列はメンバー名、型テキスト、メンバーが必須かどうか（optional が省略されているか false の場合は yes、true の場合は no）です。その後、ドキュメントがある各メンバーについて、ドキュメントコメントをまとめた行が1行ずつ続きます。列挙型はメンバーごとに1行で出力され、値がある場合は = <value> が付き、ドキュメントコメントがある場合はその後に続きます。メンバーのないインターフェースまたは列挙型は、(no members) の1行だけを出力します。型エイリアスと関数は、それぞれフェンス付きの ts ブロックとして出力されます。エイリアスの場合は type <name> = <definition>、関数の場合は指定されたシグネチャがそのまま出力されます。段落とセクションは空行1行だけで区切られ、ドキュメントの末尾には改行がちょうど1つ付きます。Markdown に加えて、結果には件数も含まれます。指定された宣言の数、種類ごとの集計、インターフェースと列挙型に含まれるメンバーの合計数です。

種類ごとのルールは構造に関するもので、違反はレンダリング方法の選択ではなく、検証エラーになります。インターフェースと列挙型では members が必須で、型エイリアスと関数では指定できません。型エイリアスでは definition が必須で、それ以外のすべての種類では指定できません。関数では signature が必須で、それ以外のすべての種類では指定できません。メンバー内では、インターフェースのメンバーに type が必須で、列挙型のメンバーでは指定できません。value は列挙型のメンバーにのみ使用できます。また、列挙型のメンバーに optional を指定することはできません。同じ宣言内で名前が重複する宣言、またはメンバーもエラーになります。各検証エラーには、問題のあるパスが示されます。たとえば、types[1].members[0].type is required for interface members のようになります。エラーがある場合、部分的なドキュメントは生成されません。宣言やメンバー内を含め、認識されない余分なフィールドは無視されます。

CLI

npx @reneturcios/types2docs render --input args.json
npx @reneturcios/types2docs --version

args.json には引数オブジェクト全体が含まれます。

{
  "title": "Widget API",
  "types": [
    {
      "name": "Widget",
      "kind": "interface",
      "doc": "A widget in the catalogue.",
      "members": [
        { "name": "id", "type": "string", "doc": "Unique identifier." },
        { "name": "label", "type": "string", "optional": true }
      ]
    },
    {
      "name": "WidgetId",
      "kind": "type",
      "definition": "string & { readonly brand: \"WidgetId\" }"
    },
    {
      "name": "Colour",
      "kind": "enum",
      "members": [
        { "name": "Red", "value": "\"red\"" },
        { "name": "Blue", "value": "\"blue\"", "doc": "The calm one." }
      ]
    },
    {
      "name": "makeWidget",
      "kind": "function",
      "signature": "function makeWidget(id: WidgetId): Widget"
    }
  ]
}

レンダリング結果は JSON として出力されます。

{
  "markdown": "# Widget API\n\n## Widget\n\nA widget in the catalogue.\n\nKind: interface\n\n| Member | Type | Required |\n| --- | --- | --- |\n| id | string | yes |\n| label | string | no |\n\n- `id` — Unique identifier.\n\n## WidgetId\n\nKind: type\n\n```ts\ntype WidgetId = string & { readonly brand: \"WidgetId\" }\n```\n\n## Colour\n\nKind: enum\n\n- `Red` = \"red\"\n- `Blue` = \"blue\" — The calm one.\n\n## makeWidget\n\nKind: function\n\n```ts\nfunction makeWidget(id: WidgetId): Widget\n```\n",
  "counts": {
    "types": 4,
    "interfaces": 1,
    "type_aliases": 1,
    "enums": 1,
    "functions": 1,
    "members": 4
  }
}

終了コード：成功時は 0、ランタイムエラー時（読み取り不能または無効な入力ファイル、無効な入力を含む）は 1、使用方法のエラー時は 2 です。

MCP サーバー

npx -y @reneturcios/types2docs mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "types2docs": {
      "command": "npx",
      "args": ["-y", "@reneturcios/types2docs", "mcp"]
    }
  }
}

ツール

• render_api_reference — 呼び出し元から渡された TypeScript の型宣言（インターフェース、型エイリアス、列挙型、関数）から、固定された決定論的なレイアウトで Markdown の API リファレンスを生成します。内容を捏造することはありません。すべての文字列は入力に由来します。

  • types（配列、必須、1 項目以上）— ドキュメントに記載する型宣言。ドキュメント内の順に指定します。各項目：
    • name（文字列、必須、空でない）— 宣言名
    • kind（文字列、必須）— "interface"、"type"、"enum"、"function" のいずれか
    • doc（文字列、任意）— 宣言のドキュメントコメントテキスト
    • members（配列）— interface と enum では必須、type と function では禁止。各項目：
      • name（文字列、必須、空でない）— メンバー名
      • type（文字列）— メンバーの型テキスト。interface のメンバーでは必須、enum のメンバーでは禁止
      • value（文字列、任意）— enum メンバーの値テキスト（enum メンバーのみ）
      • optional（ブール値、任意）— メンバーが任意かどうか（interface のメンバーのみ）。省略した場合は false
      • doc（文字列、任意）— メンバーのドキュメントコメントテキスト
    • definition（文字列）— エイリアスの右辺。そのままのテキスト。kind が "type" の場合は必須、それ以外では禁止
    • signature（文字列）— 関数シグネチャ。そのままのテキスト。kind が "function" の場合は必須、それ以外では禁止
  • title（文字列、任意）— ドキュメントのタイトル。既定値は "API Reference" です。空文字列も指定でき、その場合は # として出力されます。

  {markdown, counts} を返します。counts は {types, interfaces, type_aliases, enums, functions, members} で、このキー順です。

Docker

docker run -i ghcr.io/cloudcorprecords/types2docs
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/types2docs render --input /w/args.json

開発

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

ライセンス

MIT — Copyright (c) 2026 Rene Turcios