VitePress & MCPでアプリ仕様のオープン化に挑戦する

VitePressのドキュメント検索機能をMCPサーバとして拡張し、AIエージェントからも利用できるようにすることでフロントの開発効率を改善することを目指しました。
ドキュメントを書くことの重要性についても触れています。

Transcript

1. VitePress & Nuxt & MCPで アプリ仕様のオープン化に 挑戦する Hal
2. 自己紹介 Hal (はる) Japan SoE DevOps. Digital E-Application Exp. ▪趣味 Vue.js サイクリング ▪利用技術 TypeScript,Vue.js,Go, Terraform,Google Cloud @hal_spidernight ▪PR Goエンジニア 積極採用しています！
3. Nuxtは使いません （最後に少しだけ触れます）
4. 皆さんは ドキュメントを書いていますか？
5. 開発とドキュメンテーションを並行する重要性 ナレッジの標準化 チーム内での 認識の統一 開発の現状を 把握しやすくなる 外部・新規メンバー への説明コスト減 開発時コミュニケーションの記憶が 新しい状態で作成するので工数を抑えられる
6. ドキュメント運用をうまく続けるためのポイント 適切なカテゴライズ タグ付け レイアウトを 標準化し、統一する 変更時の差分を 見やすくしておく 高い検索性と可読性を保持する
7. Excel製ドキュメント →❌ Markdown製ドキュメント →󰢏
8. マークダウンでドキュメントを書くメリット レイアウトの 揺らぎが少ない リリース単位で 差分が わかりやすい 簡単に書ける デメリット 素のままだと 表現力に 限界がある 生成AIに 解釈させやすい 記法を覚える 必要がある
9. とはいえマークダウンを書いても そこまでアクセス性は高くない
10. マークダウンのドキュメントは GithubやVS Codeのプレビューで見られるが、 情報の探しやすさや見やすさが高いとは言い難い ...
11. 利便性の高いドキュメントをできるだけ 楽に運用するには？
12. 利便性の高いドキュメントをできるだけ 楽に運用するには？ →VitePressを使おう
13. VitePressとは... マークダウン記法でリッチなドキュメントが 作成できるライブラリ。 プラグインを追加でき、 OpenAPIやMermaidなど 様々なレイアウトや記法を取り入れることが可能。
14. よくみるこんなドキュメントが簡単に作れる https://vue3datepicker.com/installation/
15. .vitepress/config.ts で以下の設定を入れることで検索機能を追加できます。 i18nによる拡張や検索の微調整ができます。 特に見出しのキーワードにはヒットしやすく、ドキュメントを探す際に非常に便利です。 検索機能が簡単に導入できる import { defineConfig } from 'vitepress' export default defineConfig({ themeConfig: { search: { provider: 'local' } } }) https://vitepress.dev/reference/default-theme-search#search
16. APIドキュメントも組み込んで 運用したい？
17. vitepress-openapiを利用することでOpenAPIのjsonファイルを埋め込むことができます。 OpenAPIを組み込もう // .vitepress/theme/index.ts import DefaultTheme from 'vitepress/theme' import type { Theme } from 'vitepress' import { theme } from 'vitepress-openapi/client' import { theme, useOpenapi } from 'vitepress-openapi/client' import 'vitepress-openapi/dist/style.css' import spec from '../../public/openapi.json' with { type: 'json' } export default { extends: DefaultTheme, async enhanceApp({ app }) { // Set the OpenAPI specification. useOpenapi({ spec, }) // Use the theme. theme.enhanceApp({ app }) } } satisfies Theme npm install vitepress-openapi
18. フローチャートや UMLなどの図も ドキュメントに描きたい？
19. チャートやフローなどを書くことができる Mermaidですが、 vitepress-plugin-mermaidをインストールすることで使うことができます。 Mermaid記法を使おう npm i vitepress-plugin-mermaid mermaid -D
20. VitePressに内蔵された検索機能を MCPに拡張して再利用したい 🤔
21. VitePressをMCPサーバー化する Vite Pluginを 開発しました！ https://github.com/Hal-Spidernight/vite-plugin-vitepress-mcp
22. VitePress MCP Pluginを設定し、ホストすることで MCPサーバーを 同時に起動できます。
23. こんな感じで VitePress起動時に 一緒にMCPサーバも起動します
24. 1. ドキュメントの表現力が高い a. マークダウン拡張記法 b. OpenAPI c. Mermaid 2. リポジトリをクローンすればすぐ情報にアクセスできる 3. ドキュメントサイトを提供できる 4. セットアップとメンテの手間が少ない 5. マークダウンさえ書ければ運用できる（重要） VitePressをMCPサーバとして利用すると良いこと
25. 1. VitePress MCP Pluginのアップデート a. OpenAPI,Mermaidへの対応 b. SSE対応(現在はStreamable HTTPのみ) c. バグ対応 2. 社内でのドキュメント MCPサーバ実用化 a. 一部システムでの VitePressサーバー化を進行中 今後の取り組み
26. Nuxtで@nuxt/docsが標準ライブラリとしてリリースされ、 Markdownだけでなく ymlファイルもドキュメント化できるようになりました。 Nuxt MCPと組み合わせることでアプリ仕様の標準化に大きく貢献することが期待できます。 VitePress以外にもドキュメンテーション促進は進んでいる Nuxt 3.17.0にて リリースされました 🎉
27. 最後に フロントエンドカンファレンス関西 2025 開催します！ LT・セッションもあるのでこぞってご参加ください！ 開催日：2025年11月30日 会場：マイドームおおさか 8F LT募集開始：公式SNSよりご案内 サイト： https://frontend-conf.osaka.jp/ #fec_kansai で検索！
28. ご清聴ありがとうございました！