md-md

md.md

md.md は、社内のエンジニアリング知識をバージョン管理された Markdown ブロックに変換し、AI 支援開発ワークフローに適切なコンテキストを注入するチーム向けインテリジェンスプラットフォームです。

以下を組み合わせています。

• バックエンドのレジストリとポリシーエンジン
• ナレッジブロックの作成と公開を行う React ダッシュボード
• IDE とアシスタントの統合向け MCP サーバー
• 統合ドキュメントとプロダクト設計ドキュメント

解決する課題

AI コーディングアシスタントは一般的なコーディングには強い一方、チーム固有のコンテキストには弱い傾向があります。共有コンテキストがないと、チームは規約、アーキテクチャ上の決定、ワークフローを何度も説明し直すことになります。

md.md では、チームが次のことを行えます。

• ナレッジを一度作成する
• 安定したバージョンを公開する
• タスクの実行時に適切なコンテキストを解決する
• IDE や AI ツールをまたいで同じコンテキストを再利用する

リポジトリ構成

• app-backend/：認証、ブロックのライフサイクル、ポリシー解決、オブザーバビリティを担う NestJS API
• app-client/：ブロックの作成、公開、解決プレビューを行う React + Vite ダッシュボード
• mcp-server/：stdio 経由で md.md のツールを公開する Model Context Protocol サーバー
• ide-integrations/：IDE 統合ドキュメント（現在は Cursor を中心に記載）
• docs/：プロダクトビジョン、フェーズ計画、解決モデルの設計ドキュメント

アーキテクチャの概要

1. チームはブロック内に Markdown ファイルを作成します。
2. ブロックはバージョン管理され、公開されます。
3. IDE／アシスタントの統合機能が、タスクのコンテキストとともに解決ツールまたは API を呼び出します。
4. バックエンドが関連する公開済みブロックを選択し、ペイロードを構成します。
5. そのペイロードが AI のコンテキストに注入されます。
6. オブザーバビリティのため、解決と使用状況のメタデータがログに記録されます。

統合経路

• IDE または AI クライアント
• stdio 経由の MCP プロトコル
• mcp-server のツール
• バックエンドの REST API
• Postgres による永続化（Supabase 互換）

主な概念

ブロック

1 つ以上の Markdown ファイルを含む、名前付きのチームナレッジ単位です。

ドラフト版と公開版

ドラフトの内容は自由に編集できます。公開版は安定しており、利用を目的としています。

スコープ付きアクセス

データと権限は、チームおよびワークスペースごとにスコープが設定されます。

解決

利用時に、システムが関連する公開済みブロックを解決して構成し、AI ですぐに利用できるペイロードを生成します。

コンポーネントの詳細

1) バックエンド（app-backend）

技術スタック：

• NestJS 11
• pg を介した PostgreSQL（Supabase 互換の接続）
• TypeScript

役割：

• 認証と認可
• RBAC と API キーの管理
• ブロックの CRUD、バージョン管理、公開、アーカイブ
• 解決のオーケストレーション
• 注入ログおよび監査ログの API

主なバックエンド機能：

• API キー形式：mdmd_<token>
• ロール：reader、author、admin
• ブロック単位の権限上書き
• MCP が使用するヘルスチェックおよびオブザーバビリティのエンドポイント

2) クライアントダッシュボード（app-client）

技術スタック：

• React 19
• Vite
• TypeScript
• MUI + Emotion

役割：

• ブロックの作成と編集
• ブロックファイルの管理
• バージョンの公開
• 解決結果のプレビュー
• 利用時の認証情報／スコープ情報の設定

3) MCP サーバー（mcp-server）

技術スタック：

• Node.js + TypeScript
• @modelcontextprotocol/sdk
• 引数の検証に Zod を使用

役割：

• md.md の機能を MCP ツールとして公開する
• ツール呼び出しをバックエンド API に転送する
• リトライ、タイムアウト、ヘルスチェックを処理する

主なツール：

• resolve_context
• attach_blocks
• list_blocks
• get_block
• health_check
• ブロックのライフサイクル管理ツール（create_block、update_block、publish_block など）
• アクセスおよびオブザーバビリティのツール（whoami、list_injection_logs）

4) IDE 統合（ide-integrations）

エディターを MCP サーバーに接続するためのセットアップ方法が含まれています。

現在、次の統合について記載しています。

• Cursor（MCP クライアントの設定）

5) プロダクトおよび設計ドキュメント（docs）

• idea_1.0.md：プロダクトの根拠とシステムのビジョン
• phases_1.0.md：実装ロードマップ（フェーズ別）
• resolution_model.md：選択、順序付け、構成に関する詳細な目標モデル

ローカル開発環境のセットアップ

前提条件

• Node.js 18+
• npm
• PostgreSQL データベース（Supabase Postgres を推奨）

1) バックエンド

cd app-backend
npm install

app-backend/.env を作成し、少なくとも次の内容を設定します。

SUPABASE_DATABASE_URL=postgresql://<user>:<password>@<host>:<port>/<db>

バックエンドを起動します。

npm run start:dev

2) 管理者 API キーの作成

app-backend から実行します。

npm run create-admin -- \
  --email [email protected] \
  --name "Admin User" \
  --team team-alpha \
  --workspace workspace-core

生成された mdmd_... キーを安全に保管します。

3) クライアントダッシュボード

cd ../app-client
npm install
npm run dev

4) MCP サーバー

cd ../mcp-server
npm install
npm run build
npm start

MCP ランタイム用の環境変数を設定します（シェルまたは IDE の設定）。

MD_MD_API_URL=http://localhost:3000
MD_MD_API_KEY=mdmd_your_key_here

よくある開発ワークフロー

バックエンド

cd app-backend
npm run start:dev
npm run build
npm run test
npm run test:e2e
npm run lint

クライアント

cd app-client
npm run dev
npm run build
npm run lint
npm run preview

MCP サーバー

cd mcp-server
npm run dev
npm run build
npm start

セキュリティとシークレット

• API キーやトークンファイルをコミットしないでください。
• シークレットは環境ファイルまたは安全なシークレットマネージャーで管理してください。
• インテグレーションには、最小権限の API キーを使用してください。
• キーは定期的にローテーションしてください。
• 機密性の高い操作について、監査ログを確認してください。

mcp-server/.gitignore に最近追加されたローカルの除外設定には、次の項目が含まれています。

• .mcpregistry_github_token
• .mcpregistry_registry_token

現在の製品ステータス

実装済み：

• ブロックのライフサイクル全体（作成、編集、公開）
• ダッシュボードでの作成と解決プレビュー
• バックエンドの RBAC と API キー管理
• コンテキスト解決とブロック操作のツールを備えた MCP サーバー

開発中または計画中：

• ポリシーに基づく、よりスマートなコンテキスト選択と順序付け
• IDE インテグレーションの拡充
• 分析機能とガバナンス機能の追加

次のステップ

• バックエンドの実装と認証に関するドキュメント：app-backend/docs/
• MCP の使用方法とインテグレーションの詳細：mcp-server/README.md
• IDE のセットアップに関する説明：ide-integrations/README.md
• 製品ビジョンとロードマップ：docs/

ライセンス

各パッケージ（app-backend、app-client、mcp-server）のライセンス宣言を参照してください。