a5sql-mcp AGENTS.md

AGENTS.md

このリポジトリは、ローカルに存在する A5:SQL Mk-2 の設定・メタデータ・SQL 資産を読み取り、AI エージェントが安全に扱いやすい形で配信する MCP サーバーを開発するためのものです。

開発の目的

• A5:SQL のローカル資産を、AI が検索・要約・参照しやすい構造化データとして提供する。
• データベース接続情報、ER 図、テーブル定義、SQL 履歴、SQL ファイルなどを段階的に扱えるようにする。
• まずは読み取り専用を基本とし、ローカル環境や接続先 DB を壊さない。
• 秘密情報を不用意にログ、レスポンス、テストスナップショット、コミットに含めない。

基本方針

• 実装より前に、A5:SQL がローカルに保存するファイル形式・保存場所・文字コードを確認する。
• 保存場所や形式はユーザー環境・A5:SQL のバージョン・Windows/Wine/Linux などの実行形態で変わり得るため、ハードコードを避ける。
• デフォルト動作は読み取り専用にする。
• 書き込み、削除、接続先 DB へのクエリ実行、資格情報の復号・表示は、明示的に実装範囲へ入るまで扱わない。
• AI 向けの配信では「生データをそのまま渡す」のではなく、識別子、要約、参照パス、必要最小限の抜粋に整形する。
• 例外や解析失敗時は、ファイルパスや秘密情報を含みすぎないエラーにする。

想定する公開面

現在の MCP サーバーは、起動時に指定された .a5er / .sql / text ファイルを読み取る stdio サーバーです。独立した packages/mcp-server は持たず、packages/cli の --mcp モードで提供します。

現時点で公開している tool は次のとおりです。

• describe_a5sql_file: 起動時に指定されたファイルのパス、種別、サイズ、更新日時を返す。
• parse_a5sql_file: 起動時に指定された .a5er / .sql ファイルを AI 向けの構造に変換する。デフォルトは summary。mode: "full" でも maxTables / maxRelationships / maxColumnsPerTable による上限つきで返す。
• read_a5sql_file: 起動時に指定されたファイル本文を、最大文字数つきで返す。offsetChars、または startLine / maxLines で読み取り範囲を絞れる。
• detect_a5sql_locations: A5:SQL の設定ディレクトリ候補を、存在有無、読み取り可否、検出理由つきで返す。DB には接続しない。
• read_a5sql_asset: assetId で指定された asset 本文を、サイズ制限と秘密情報マスクつきで返す。バイナリや未対応ファイルは本文を返さず warning を返す。
• list_a5sql_connections: A5:SQL 設定 root 配下から接続候補を抽出し、秘密情報を返さない形で一覧する。非秘密項目もデフォルトではマスクする。
• search_a5sql_assets: roots または A5SQL_MCP_ROOTS で指定された root 配下から A5:SQL 関連 asset を検索し、parse_a5sql_asset に渡せる assetId とマスク済み抜粋を返す。DB には接続しない。
• parse_a5sql_asset: assetId で指定された .a5er / .sql / text asset を AI 向けの構造に変換する。roots または A5SQL_MCP_ROOTS で探索対象を明示する。DB には接続しない。
• list_a5sql_tables: .a5er ファイル内のテーブル/ビュー一覧を返す。offset / limit によるページングに対応し、デフォルトは 100 件。
• describe_a5sql_table: .a5er ファイル内の特定テーブル/ビュー定義を返す。
• explain_a5sql_table: .a5er ファイル内の特定テーブルを、役割・主キー・関連テーブル・注意点つきで要約する。
• list_a5sql_relationships: .a5er ファイル内のリレーション一覧を返す。
• find_a5sql_tables: .a5er ファイル内のテーブルを、テーブル名・論理名・コメント・カラム名から検索する。
• find_a5sql_columns: .a5er ファイル内のカラムを、カラム名・論理名・コメント・型・テーブル名から検索する。
• generate_sql_select: .a5er ファイル内の定義から SELECT SQL のたたき台を生成する。DB には接続しない。maxRelatedTables で JOIN 対象の上限を指定できる。
• generate_mermaid_er_diagram: .a5er ファイル内のテーブルとリレーションから Mermaid ER diagram を生成する。maxTables で出力対象テーブル数を制限できる。
• generate_model_files: .a5er ファイル内のテーブル定義から Laravel Eloquent または SQLAlchemy のモデルファイル案を生成する。ファイルシステムには書き込まない。maxTables で生成対象テーブル数を制限できる。
• generate_schema_markdown: .a5er ファイル内のテーブル定義とリレーションから Markdown の定義書案を生成する。ファイルシステムには書き込まない。
• review_a5sql_schema: .a5er ファイル内のスキーマ品質を、主キー・型・コメント・リレーション整合性の観点でレビューする。
• suggest_schema_changes: .a5er ファイル内のスキーマ品質レビュー結果から、主キー・型・リレーション・コメントの改善提案を返す。
• compare_a5er_with_live_schema: .a5er ファイル内の定義と、外部 DB MCP などから渡された live schema JSON を比較する。DB には接続せず、テーブル/カラム欠落、余剰、型、NULL 許容、主キー差分を返す。
• generate_migration_plan: .a5er ファイル内の定義と live schema JSON の差分から migration 案を生成する。DB には接続せず、実行しない。