KatanA Markdown Linter

katana-markdown-linter

markdownlint 互換の Rust エンジン、kml CLI、フォーマッター、 安全な修正機能、エディターサーバー、エージェント対応の MCP サーバーです。

インストール | CLI の使い方 | ライブラリ API | エディター連携 | MCP サーバー

---

kml とは

katana-markdown-linter は、技術文書、仕様書、AI エージェントを活用したドキュメント作成ワークフロー向けの高速な Markdown リントエンジンです。

本プロジェクトは KatanA のビジュアルアイデンティティを共有しつつ、独立した境界を保っています。 crate、CLI、ラッパー、エディターサーバー、MCP サーバーは、KatanA Desktop に依存しません。

特長

• markdownlint 互換のチェック：有効な上流ルールカタログに対応
• 安全な修正機能：リスクの低いルール違反を修正し、明示的なオプトインで安全でない修正も実行
• フォーマッターモード：作成者の意図を変えずにレイアウトを正規化
• 組み込み可能な Rust API：プロセス内でのリントや修正が必要なアプリケーション向け
• kml CLI：JSON 出力、標準入力への対応、無視設定、統計情報を提供
• エディター連携：stdio の Language Server Protocol サーバーを使用
• MCP サーバー：構造化されたリント機能を必要とするエージェントやツール向け
• 複数チャネルでの配布：Cargo、GitHub Releases、npm、PyPI、Homebrew を通じて配布

ライブラリ API

別の Rust アプリケーションに lint を組み込む場合は、クレートを直接使用してください。

• lint(content, options)
• fix(content, options)
• available_rules()
• localized_available_rules(language_code)
• implemented_rules()
• missing_rules()
• rule_catalog()
• localized_rule_catalog(language_code)
• resolve_locale_code(language_code)
• resolve_locale_code_or(language_code, fallback)
• localized_rule_description(rule_id, fallback_description, language_code)
• supported_locales()
• upstream::get_rule_documentation(rule_id, locale)
• MarkdownLintConfig
• MarkdownLintConfig::schema()
• MarkdownLintConfig::to_lint_options()

available_rules() は、正規の英語メタデータを返します。ユーザー向けのルールカタログには、localized_available_rules(language_code)、localized_rule_catalog(language_code)、RuleMeta::localized_description(...)、または localized_rule_description(...) を呼び出すことで、アプリケーション側で kml のフォールバックポリシーを再実装せずに、UI の言語コードを渡せます。

Locale は v0.6.0 から #[non_exhaustive] です。Locale に対してマッチングするコンシューマーは、ワイルドカードのアームを含め、UI の言語文字列には resolve_locale_code(...) または resolve_locale_code_or(...) を優先して使用してください。ルールの説明とルールの Markdown ドキュメントは、en、ja、zh-CN、zh-TW、ko、pt、fr、de、es、it にローカライズされています。

最小限の組み込み例は examples/ にあります。

• embedding.rs：文字列のチェック、ファイルツリーのチェック、文字列の修正、設定の読み込み、設定からオプションへの変換

インストール

Cargo

cargo install katana-markdown-linter

バイナリターゲットは kml です。同じ配布経路から Rust クレートと CLI の両方を入手する場合は、Cargo を使用してください。

npm

npm パッケージは薄いランチャーで、初回実行時に kml、kml-mcp、または kml-mcp-remote に対応する GitHub Release アーカイブをダウンロードします。

npm install -g katana-markdown-linter
kml version

一度だけ実行する場合は npx を使用してください。

npx --yes [email protected] check README.md
npx --yes [email protected] kml-mcp --workspace-root /absolute/path/to/workspace
bunx --package [email protected] kml-mcp --workspace-root /absolute/path/to/workspace

PyPI

PyPI パッケージは薄い Python ランチャーで、初回実行時に kml、kml-mcp、または kml-mcp-remote に対応する GitHub Release アーカイブをダウンロードします。

pipx install katana-markdown-linter
kml version

pipx を使用しない場合は、通常の Python 環境マネージャーでインストールしてください。

アクティブな環境にランチャーをインストールせずに一度だけ実行する場合は、uvx を使用してください。

uvx --from katana-markdown-linter==0.19.6 kml check README.md
uvx --from katana-markdown-linter==0.19.6 kml-mcp --workspace-root /absolute/path/to/workspace

GitHub Releases

スタンドアロンの kml アーカイブは GitHub Releases に添付されています。Rust のターゲットトリプルに一致するアーカイブを選択してください。

curl -LO https://github.com/HiroyukiFuruno/katana-markdown-linter/releases/download/v0.19.6/kml-v0.19.6-aarch64-apple-darwin.tar.gz
curl -LO https://github.com/HiroyukiFuruno/katana-markdown-linter/releases/download/v0.19.6/kml-v0.19.6-aarch64-apple-darwin.tar.gz.sha256
shasum -a 256 -c kml-v0.19.6-aarch64-apple-darwin.tar.gz.sha256
tar -xzf kml-v0.19.6-aarch64-apple-darwin.tar.gz

Homebrew

Homebrew フォーミュラの公開はリリースフローの一部です。次のコマンドでインストールしてください。

brew install HiroyukiFuruno/katana/kml

VS Code

VS Code Marketplace から KatanA Markdown Linter 拡張機能をインストールするか、ローカルパッケージをサイドロードしてください。この拡張機能は kml lsp サーバーの薄いラッパーとして動作し、起動時にバージョンの互換性を確認します。

# Sideload for MVP testing
cd editors/vscode
npm install
npm run compile
code --extensionDevelopmentPath=$PWD

Zed

Zed 拡張機能レジストリから KatanA Markdown Linter 拡張機能をインストールするか、リポジトリからサイドロードしてください。この拡張機能は kml lsp を Markdown 言語サーバーとして登録し、カスタムのバイナリパスをサポートします。

# Sideload for MVP testing
# Use the "zed: install dev extension" action in Zed
# and select the 'editors/zed' directory.

GitHub Actions

インストール手順を記述せずに CI で kml を実行するには、リポジトリアクションを使用してください。

- uses: actions/checkout@v5
- uses: HiroyukiFuruno/[email protected]
  with: { version: "0.18.0", command: check, paths: "README.md\ndocs", config: .markdownlint.json }

再現性のある実行のため、アクションのタグと version を合わせて固定してください。アクションはデフォルトで crates.io から kml をインストールします。リポジトリ内のスモークテストでは、install-source: path と path: . を設定できます。

extra-args は1行につき1つの引数を受け付けるため、値を取るフラグは別々の行に記述してください。

CLI の使い方

kml check
kml check --locale en
kml check -l ja
kml --locale ja help
kml fix
kml fmt
kml check --fix
kml fix --unsafe --yes README.md
kml check --fix --unsafe --yes README.md
kml check README.md
kml check --file README.md
kml check --output json "docs/**/*.md"
kml check --format json "docs/**/*.md"
kml check --ignore-config-errors README.md
kml check --stdin
kml fix --stdin
kml check --include "**/*.md" --exclude "target/**"
kml check --include-reserved node_modules
kml check --no-ignore --force-exclude --exclude "vendor/**" vendor/README.md
kml check --statistics --quiet
kml fix --diff README.md
kml rule
kml rule --locale ja
kml rule --locale fr
kml rule MD013
kml rule MD013 --locale ja --output json
kml config file
kml config get --output json
kml config schema
kml --help
kml -h
kml help
kml check --help
kml check -h
kml version
kml --version
kml -v
kml fix --config .markdownlint.json README.md
kml init-config

ファイルが指定されていない場合、kml check、kml fix、kml fmt は、カレントディレクトリ配下の Markdown ファイルを再帰的に処理します。単一ファイルを対象とすることを明示するには、--file を使用します。

check は診断結果を報告し、lint 違反が見つかった場合は終了コード 1 で終了します。 fix と check --fix は安全な lint ベースの修正を適用し、書き換え後も 違反が残っている場合は終了コード 1 で終了します。fmt はインデントと 改行を正規化するためのレイアウトフォーマッターです。check で報告される 無関係な lint 診断が残っていても、書式設定が成功すると終了コード 0 で 終了します。ファイルシステムまたは設定のエラーは、終了コード 2 で終了します。

現在、fmt は CRLF/CR の改行を LF に統一し、末尾の改行、連続する 空行、見出し／フェンス／リスト／表の前後の空行、および安全なリストの インデント／マーカー間隔を正規化します。段落の再配置、見出しや強調の スタイル変更、URL／表のスタイル変更、末尾の空白の削除は行いません。また、 デフォルトでは安全でない修正を適用しません。

安全でない修正を適用するには、fix と check --fix で明示的なオプトインが 必要です。対話形式で使用する場合は [Y/n] が表示されます。非対話形式で 使用する場合は、--unsafe --yes を指定する必要があります。

JSON 出力には --output json を推奨します。--format json も互換性のための エイリアスとして引き続き使用できます。修正モードの JSON にはファイルごとの fix_details が含まれるため、適用されたルールを修正前の診断結果や 書き換えられたファイルの差分と比較できます。

--stdin は標準入力から Markdown を読み込みます。check --stdin は <stdin> に対する診断結果を報告します。fix --stdin は修正後の Markdown を 標準出力に書き込みます。fmt --stdin は整形後の Markdown のみを標準出力に 書き込みます。

ディレクトリのスキャンでは、デフォルトで gitignore ファイルを尊重します。 無視対象のパスをすべて含めるには --no-ignore を使用します。.agents など、 明示的に指定したディレクトリの配下にある無視対象のパスのみを含めるには --include-ignored を使用します。.git、node_modules、target、dist、 build、coverage などの予約済みディレクトリは、gitignore の記載がなくても デフォルトでスキップされます。これらを意図的にスキャンする場合に限り、 --include-reserved を使用してください。プロジェクト固有の生成ディレクトリや エージェント用ディレクトリは、gitignore または --exclude に指定してください。 --exclude は検出されたファイルを除外します。明示的に指定されたファイルは、 --force-exclude も指定しない限り対象に含まれます。

コマンドを指定せずに kml を実行すると、グローバルヘルプが表示されます。 kml help、kml --help、kml -h、kml <command> --help は、 ファイルをスキャンせずにヘルプを表示します。

--locale <locale> と -l <locale> は、CLI のユーザー向けメッセージと ヘルプテキストのロケールを選択します。 対応する値は、en、ja、zh-CN、zh-TW、ko、pt、fr、de、 es、it に解決されます。fr-FR、pt-BR、ko-KR など、一般的な地域形式も 使用できます。省略した場合、kml は OS のロケール環境変数を読み取り、 そのロケールが利用できないか未対応であれば英語にフォールバックします。 明示的に指定した未対応のロケールは、CLI エラーになります。--local は v0.4.0 ユーザー向けの後方互換エイリアスとして使用できます。

kml rule と kml rule <id> も --locale に対応しています。テキスト出力では ローカライズされたルールの説明が使用され、JSON 出力には description （ローカライズ版）と english_description（正規の英語版）の両方が含まれます。

ルール一覧

kml には、現在有効な markdownlint ルールカタログの lint チェックが含まれています。 以下のルール ID は、available_rules() と kml rule --output json が返す公開 カタログに対応しています。状態列には、フィクスチャに基づく実装状況が記載されています。 ルールを 1 つ確認するには、kml rule MD013 を実行してください。上流のドキュメント URL も表示されます。

概要：

機能	状態
チェックの対応範囲	有効な 53 個すべてのルールに対して Implemented
安全な修正の対応範囲	38 個のルールで安全な修正が利用可能。15 個のルールは診断のみ
安全でない修正の対応範囲	1 個のルールに対し、明示的なオプトインによる安全でない修正を提供。残りのルールは対象外、または手動での意図確認が必要
削除された上流 ID	過去の ID 7 個を、修正状態 - の Deleted として表示
安全な修正は意図的に保守的になっています。実装済みのサブセットは、kml がそのルールに関する、フィクスチャで固定された低リスクの違反形式を書き換えることを意味します。診断のみはチェックが実装済みですが、安全な修正は提供されないことを意味します。手動で意図を指定する必要ありは、自動書き換えでは作成者の意図を選択することになることを意味します。該当なしは、安全な修正のポリシーを超えて、個別の安全でない候補が現時点で特定されていないことを意味します。削除済みの行は、アクティブな上流のルールカタログには含まれていない、過去の markdownlint ID です。

フィクスチャで裏付けられたルール一覧

| ルール | チェック | 修正（安全） | 修正（危険） | | --- | --- | --- | --- | | `MD001` | 実装済み | 診断のみ | 手動での意図の指定が必要 | | `MD002` | 削除済み | - | - | | `MD003` | 実装済み | 一部を実装済み | 該当なし | | `MD004` | 実装済み | 一部を実装済み | 該当なし | | `MD005` | 実装済み | 一部を実装済み | 該当なし | | `MD006` | 削除済み | - | - | | `MD007` | 実装済み | 一部を実装済み | 該当なし | | `MD008` | 削除済み | - | - | | `MD009` | 実装済み | 一部を実装済み | 該当なし | | `MD010` | 実装済み | 一部を実装済み | 該当なし | | `MD011` | 実装済み | 一部を実装済み | 該当なし | | `MD012` | 実装済み | 一部を実装済み | 該当なし | | `MD013` | 実装済み | 診断のみ | 手動での意図の指定が必要 | | `MD014` | 実装済み | 一部を実装済み | 該当なし | | `MD015` | 削除済み | - | - | | `MD016` | 削除済み | - | - | | `MD017` | 削除済み | - | - | | `MD018` | 実装済み | 一部を実装済み | 該当なし | | `MD019` | 実装済み | 一部を実装済み | 該当なし | | `MD020` | 実装済み | 一部を実装済み | 該当なし | | `MD021` | 実装済み | 一部を実装済み | 該当なし | | `MD022` | 実装済み | 一部を実装済み | 該当なし | | `MD023` | 実装済み | 一部を実装済み | 該当なし | | `MD024` | 実装済み | 診断のみ | 手動での意図の指定が必要 | | `MD025` | 実装済み | 一部を実装済み | 該当なし | | `MD026` | 実装済み | 一部を実装済み | 該当なし | | `MD027` | 実装済み | 一部を実装済み | 該当なし | | `MD028` | 実装済み | 診断のみ | 手動での意図の指定が必要 | | `MD029` | 実装済み | 一部を実装済み | 該当なし | | `MD030` | 実装済み | 一部を実装済み | 該当なし | | `MD031` | 実装済み | 一部を実装済み | 該当なし | | `MD032` | 実装済み | 一部を実装済み | 該当なし | | `MD033` | 実装済み | 診断のみ | 手動での意図の指定が必要 | | `MD034` | 実装済み | 一部を実装済み | 該当なし | | `MD035` | 実装済み | 一部を実装済み | 該当なし | | `MD036` | 実装済み | 診断のみ | 一部を実装済み | | `MD037` | 実装済み | 一部を実装済み | 該当なし | | `MD038` | 実装済み | 一部を実装済み | 該当なし | | `MD039` | 実装済み | 一部を実装済み | 該当なし | | `MD040` | 実装済み | 一部を実装済み | 該当なし | | `MD041` | 実装済み | 診断のみ | 手動での意図の指定が必要 | | `MD042` | 実装済み | 診断のみ | 手動での意図の指定が必要 | | `MD043` | 実装済み | 診断のみ | 手動での意図の指定が必要 | | `MD044` | 実装済み | 一部を実装済み | 該当なし | | `MD045` | 実装済み | 診断のみ | 手動での意図の指定が必要 | | `MD046` | 実装済み | 一部を実装済み | 該当なし | | `MD047` | 実装済み | 一部を実装済み | 該当なし | | `MD048` | 実装済み | 一部を実装済み | 該当なし | | `MD049` | 実装済み | 一部を実装済み | 該当なし | | `MD050` | 実装済み | 一部を実装済み | 該当なし | | `MD051` | 実装済み | 一部を実装済み | 該当なし | | `MD052` | 実装済み | 診断のみ | 手動での意図の指定が必要 | | `MD053` | 実装済み | 一部を実装済み | 該当なし | | `MD054` | 実装済み | 一部を実装済み | 該当なし | | `MD055` | 実装済み | 一部を実装済み | 該当なし | | `MD056` | 実装済み | 実装済み（短い行にはパディングを追加し、あふれる行は診断のみ） | 該当なし | | `MD057` | 削除済み | - | - | | `MD058` | 実装済み | 一部を実装済み | 該当なし | | `MD059` | 実装済み | 診断のみ | 手動での意図の指定が必要 | | `MD060` | 実装済み | 一部を実装済み | 該当なし |

## 設定

このクレートは、markdownlint 互換の JSON および JSONC 設定ファイルを読み書きします。

• .markdownlint.json
• .markdownlint.jsonc

kml init-config を使うと、デフォルトの .markdownlint.json を作成できます。

kml config schema を使うと、エディター連携と設定の検証に使用される JSON Schema を出力できます。安定版スキーマ ID は https://schemas.katana.tools/kml/markdownlint.schema.json です。

設定エラーがある場合、ファイルの診断結果を報告する前に check、fix、fmt が停止します。まず設定を修正してください。または、実行中に無効な設定項目を無視することを明示的に希望する場合は、--ignore-config-errors を渡してください。first-line-h1、first-line-heading、no-duplicate-heading、no-inline-html などの公式 markdownlint エイリアスを使用できます。

エディター連携

kml lsp を実行すると、Markdown の診断、フォーマット、範囲フォーマット、安全なクイックフィックスに対応する stdio Language Server Protocol サーバーが起動します。VS Code、Zed、Neovim のセットアップ例は docs/editor-integration.md に記載されています。

品質ゲート

デフォルトのローカルゲートには just check を使用してください。フォーマット、Clippy、AST リント、テストを実行します。

ファイルを変更せずに、このリポジトリの Markdown ドキュメントに対して kml を実行するには just dogfood を使用してください。安全な Markdown 修正を適用する場合に限り、just dogfood-fix を使用してください。アーカイブ済みの OpenSpec ドキュメントはデフォルトの dogfood ターゲットから除外されています。明示的にチェックするには just dogfood-archive を実行してください。

公開されている Rust 埋め込み例をコンパイルするには just examples を使用してください。

品質ゲートの詳細、CI の必須チェック、カバレッジモード、リリース準備については、docs/quality-gates.md に記載されています。

配布チャネルのステータスと延期に関する注記については、 docs/distribution.md に記載されています。

MCP サーバー

kml-mcp は、コアクレートを MCP 依存関係から独立させたまま、stdio 経由で構造化されたライブラリアクセスを必要とするエージェントやエディター向けのオプションの MCP サーバーです。

mcp フィーチャーを使ってビルドまたはインストールします。

cargo build --bin kml-mcp --features mcp --locked
cargo install katana-markdown-linter --locked --features mcp --bin kml-mcp

v0.19.3 以降、npm および PyPI ラッパーを使うと、Rust ツールチェーンなしで同じ stdio サーバーを起動できます。

npx --yes [email protected] kml-mcp --workspace-root /absolute/path/to/workspace
bunx --package [email protected] kml-mcp --workspace-root /absolute/path/to/workspace
uvx --from katana-markdown-linter==0.19.6 kml-mcp --workspace-root /absolute/path/to/workspace

このサーバーは、テキスト、設定、ルールのメタデータ、およびワークスペース内に制限されたファイル操作ツールを公開します。

• check_text
• fix_text
• config_validate
• rule_list
• rule_get
• check_file
• check_directory
• fix_file_preview
• fix_file_apply

ワークスペースのパスは、設定された --workspace-root の配下にとどまる必要があります。ファイルへの書き込みは fix_file_apply に限定され、apply: true が必要です。ディレクトリへの変更を適用するツールは公開されていません。

インストール済みの MCP サーバーを JSON-RPC stdio 呼び出し経由で実行するには、just mcp-stdio-smoke を実行してください。

kml-mcp-remote は、stdio サブプロセスを起動できない API ホスト型 LLM クライアント向けの、別個のセルフホスト可能な Streamable HTTP サーバーです。デフォルトではテキスト専用ツールを公開し、ワークスペースのファイル操作ツールは公開しません。

cargo build --bin kml-mcp-remote --features mcp-remote --locked
KML_MCP_REMOTE_TOKEN=change-me target/debug/kml-mcp-remote

セルフホスト型リモート MCP 用のラッパーエントリーポイントも利用できます。

KML_MCP_REMOTE_TOKEN=change-me \
  npx --yes --package [email protected] kml-mcp-remote
KML_MCP_REMOTE_TOKEN=change-me \
  uvx --from katana-markdown-linter==0.19.6 kml-mcp-remote

ベアラー認証、テキスト専用のツール機能、テキスト診断、リクエスト本文のサイズ制限を確認するには、just mcp-remote-smoke を実行してください。

v0.14.0 では、GitHub Releases から入手できる Linux MCPB バンドルと、ローカル stdio サーバー用の MCP Registry メタデータが導入されました。公開前にバンドルをビルドし、バンドルに含まれる kml-mcp バイナリを実行して動作を確認してください。

just VERSION=v0.19.6 mcpb-smoke

MCP サーバーのドキュメント、リモート MCP のデプロイガイド、MCP 配布計画、および以前のMCP 連携の評価を参照してください。

リリースポリシー

• ライブラリ API が主要な契約です。
• CLI はライブラリを薄くラップしたものです。
• Cargo.toml のパッケージバージョンが、リリースバージョンの正式な情報源です。
• 公開前に just VERSION=vX.Y.Z release-check を実行してください。
• GitHub Release のみを作成または更新するには、just VERSION=vX.Y.Z release-github を実行してください。
• レジストリへの公開を行う場合にのみ、just VERSION=vX.Y.Z release を実行してください。
• 公開後に just VERSION=vX.Y.Z release-verify を実行し、タグの参照先、GitHub Release の参照先、crates.io、npm、PyPI、ラッパーの起動、Homebrew の formula、およびバイナリのリリースアセットを照合してください。
• GitHub Releases には、GitHub が Verified と報告する署名済みの注釈付き vX.Y.Z タグが必要です。
• 要求されたバージョンがすでに crates.io に存在する場合、just release はディスパッチの前に停止します。
• crates.io への公開には、GitHub シークレット CARGO_REGISTRY_TOKEN が必要です。