Agent-almanac analyze-codebase-for-mcp

install

source · Clone the upstream repo

git clone https://github.com/pjt222/agent-almanac

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/ja/skills/analyze-codebase-for-mcp" ~/.claude/skills/pjt222-agent-almanac-analyze-codebase-for-mcp-d4ba87 && rm -rf "$T"

manifest: i18n/ja/skills/analyze-codebase-for-mcp/SKILL.md

source content

MCP向けコードベース分析

コードベースをスキャンして、MCPツール公開の候補となる関数、RESTエンドポイント、CLIコマンド、データアクセスパターンを発見し、構造化されたツール仕様書を作成する。

使用タイミング

既存プロジェクトのMCPサーバーを計画しており、何を公開すべきか知る必要がある時
AI対応ツールサーフェスとしてラップする前にコードベースを監査する時
コードベースの機能とMCP経由で既に公開されている機能を比較する時
```
scaffold-mcp-server
```
に渡すツール仕様書を生成する時
サードパーティライブラリをMCPツールとしてラップする価値があるか評価する時

入力

必須: コードベースのルートディレクトリへのパス
必須: コードベースの対象言語（例: TypeScript、Python、R、Go）
任意: 比較対象の既存MCPサーバーコード（ギャップ分析）
任意: ドメインフォーカス（例: 「データ分析」「ファイル操作」「API統合」）
任意: 推奨ツールの最大数（デフォルト: 20）

手順

ステップ1: コードベース構造をスキャンする

1.1.

Glob

を使用してディレクトリツリーをマッピングし、ソースディレクトリに焦点を当てる:

```
src/**/*.{ts,js,py,R,go,rs}
```
ソースファイル用
```
**/routes/**
```
、
```
**/api/**
```
、
```
**/controllers/**
```
エンドポイント定義用
```
**/cli/**
```
、
```
**/commands/**
```
CLIエントリポイント用

**/package.json

、

**/setup.py

、

**/DESCRIPTION

依存関係メタデータ用

1.2. ファイルを役割別に分類する:

エントリポイント: メインファイル、ルートハンドラー、CLIコマンド
コアロジック: ビジネスロジック関数、アルゴリズム、データトランスフォーマー
データアクセス: データベースクエリ、ファイルI/O、APIクライアント
ユーティリティ: ヘルパー、フォーマッター、バリデーター

1.3. 総ファイル数、コード行数、エクスポートされたシンボルを数えてプロジェクトの規模を把握する。

期待結果: 役割アノテーション付きの分類されたファイルインベントリ。

失敗時: コードベースが大きすぎる場合（10,000ファイル以上）、ドメインフォーカス入力を使用して特定のディレクトリやモジュールにスキャンを絞る。ソースファイルが見つからない場合、ルートパスと言語パラメータを確認する。

ステップ2: 公開された関数とエンドポイントを特定する

2.1.

Grep

を使用してエクスポートされた関数とパブリックAPIを見つける:

TypeScript/JavaScript:

export (async )?function

、

export default

、

module.exports

Python:
```
_
```
プレフィックスのない関数、
```
@app.route
```
、
```
@router
```
R: NAMESPACEにリストされた関数または
```
#' @export
```
roxygenタグ
Go: 大文字で始まる関数名（規約によりエクスポート）

2.2. 各候補関数について以下を抽出する:

名前: 関数名またはエンドポイント名
シグネチャ: 型とデフォルト値を含むパラメータ
戻り値型: 関数が生成するもの
ドキュメント: docstring、JSDoc、roxygen、godoc
場所: ファイルパスと行番号

2.3. REST APIについては追加で以下を抽出する:

HTTPメソッドとルートパターン
リクエストボディスキーマ
レスポンスの形状
認証要件

2.4. 潜在的な有用性でソートされた候補リストを構築する（パブリック、ドキュメント済み、型付き関数を優先）。

期待結果: 抽出されたメタデータ付きの20-100個の候補関数/エンドポイントのリスト。

失敗時: 候補が少ない場合、パブリックにできる内部関数も含めて検索を広げる。ドキュメントが不足している場合、出力にリスクとしてフラグを立てる。

ステップ3: MCP適合性を評価する

3.1. 各候補について、MCPツール基準に対して評価する:

入力契約の明確さ: パラメータは適切に型付けされドキュメント化されているか？ JSON Schemaで記述できるか？
出力の予測可能性: 関数は構造化データ（JSONシリアライズ可能）を返すか？戻り値の形状は一貫しているか？
副作用: 関数は状態を変更するか（ファイル、データベース、外部サービス）？副作用は明確にラベル付けが必要。
冪等性: 操作は安全にリトライできるか？非冪等ツールは明示的な警告が必要。
実行時間: 合理的なタイムアウト内（30秒未満）で完了するか？長時間実行操作は非同期パターンが必要。
エラーハンドリング: 構造化エラーをスローするか、サイレントに失敗するか？

3.2. 各候補を1-5のスケールでスコアリングする:

5: 純粋関数、型付きI/O、ドキュメント済み、高速、副作用なし
4: 適切に型付けされドキュメント済み、軽微な副作用（例: ロギング）
3: 合理的なI/O契約だがラッピングが必要（例: 生オブジェクトを返す）
2: 重大な副作用または不明確な契約、大幅な適応が必要
1: 大規模なリファクタリングなしには不適切

3.3. スコア3以上の候補にフィルタリングする。スコア2の項目はリファクタリングが必要な「将来の候補」としてフラグを立てる。

期待結果: 各候補の適合性根拠付きのスコアリングおよびフィルタリングされた候補リスト。

失敗時: ほとんどの候補が3未満のスコアの場合、MCP公開前にコードベースのリファクタリングが必要な可能性がある。ギャップを文書化し、具体的な改善（型の追加、純粋関数の抽出、副作用のラッピング）を推奨する。

ステップ4: ツール仕様を設計する

4.1. 選択された各候補（スコア >= 3）について、ツール仕様を起草する:

- name: tool_name
  description: >
    One-line description of what the tool does.
  source_function: module.function_name
  source_file: src/path/to/file.ts:42
  parameters:
    param_name:
      type: string | number | boolean | object | array
      description: What this parameter controls
      required: true | false
      default: value_if_optional
  returns:
    type: string | object | array
    description: What the tool returns
  side_effects:
    - description of any side effect
  estimated_latency: fast | medium | slow
  suitability_score: 5

4.2. ツールを論理的なカテゴリにグループ化する（例: 「データクエリ」「ファイル操作」「分析」「設定」）。

4.3. ツール間の依存関係を特定する（例: 「list_datasets」は「query_dataset」の前に呼ぶべき）。

4.4. ラッパーが必要なツールがあるか判断する:

複雑なパラメータオブジェクトをフラットな入力に簡素化する
生の戻り値を構造化テキストまたはJSONに変換する
安全ガードを追加する（例: データベース関数の読み取り専用ラッパー）

期待結果: カテゴリ、依存関係、ラッパーノート付きの完全なYAMLツール仕様。

失敗時: ツール仕様が曖昧な場合、ステップ2に戻ってソースコードからより多くの詳細を抽出する。パラメータ型が推論できない場合、手動レビュー用にフラグを立てる。

ステップ5: ツール仕様書を生成する

5.1. 以下のセクションを含む最終仕様書を作成する:

サマリー: コードベースの概要、言語、規模、分析日
推奨ツール: ステップ4のフル仕様、カテゴリ別にグループ化
将来の候補: リファクタリング推奨付きのスコア2項目
除外項目: 除外根拠付きのスコア1項目
依存関係: ツール依存関係グラフ
実装ノート: ラッパー要件、認証ニーズ、トランスポート推奨

5.2.

mcp-tool-spec.yml

（機械可読）として保存し、オプションで

mcp-tool-spec.md

（人間可読のサマリー）も保存する。

5.3. 既存のMCPサーバーが提供された場合、ギャップ分析セクションを含める:

仕様にあるが未実装のツール
実装されているが仕様にないツール（古い可能性あり）
仕様のドリフトがあるツール（実装が仕様から乖離）

期待結果:

scaffold-mcp-server

で利用可能な完全なツール仕様書。

失敗時: ドキュメントが合理的なサイズを超える場合（200ツール以上）、クロスリファレンス付きのモジュールに分割する。コードベースに適切な候補がない場合、代わりにリファクタリング推奨付きの「準備状況評価」ドキュメントを作成する。

バリデーション

よくある落とし穴

ツールを公開しすぎる: AIアシスタントは10-30の集中したツールで最もよく機能する。深さよりも機能の幅を優先する。すべてのパブリック関数を公開する誘惑に抵抗する。
副作用を無視する: 「読み取りのみ」だがログやキャッシュにも書き込む関数にはまだ副作用がある。
```
Grep
```
でファイル書き込み、ネットワーク呼び出し、データベース変更を注意深く監査する。
型安全性を仮定する: 動的言語（Python、R、JavaScript）には型アノテーションのない関数がある可能性がある。使用パターンとテストから型を推論するが、仕様に不確実性をフラグとして立てる。
認証コンテキストの欠落: 認証されたWebリクエストで動作する関数は、セッションコンテキストなしにMCP経由で呼ばれると失敗する可能性がある。セッションCookie、JWTトークン、環境注入された認証情報などの暗黙的な認証依存をチェックする。
ラッパーの過剰設計: 関数がMCP互換にするために50行のラッパーを必要とする場合、良い候補ではない可能性がある。ツールインターフェースに自然にマッピングされる関数を優先する。
エラーパスの軽視: MCPツールは構造化エラーを返す必要がある。型なし例外をスローする関数にはエラーハンドリングラッパーが必要。
内部APIと外部APIの混同: 他の内部コードから呼ばれる内部ヘルパー関数はMCP候補として不適切。外部利用向けに設計された関数や明確な境界APIに焦点を当てる。
ギャップ分析のスキップ: 既存のMCPサーバーが提供された場合、常に仕様を現在の実装と比較する。ギャップ分析なしでは、作業の重複や古いツールの見落としのリスクがある。