serena-mcp-agent

Serena MCP エージェント統合

Serena は、Language Server Protocol（LSP）を活用してコードを構造的に理解し、LLM を IDE のようなインテリジェンスを備えた高機能なコーディングエージェントへと変換します。

主な価値

機能	メリット
セマンティックなコード検索	テキストではなくシンボルを基準に移動でき、トークンを 30 倍以上削減できます
ピンポイントな編集	構造を維持したまま関数本体を変更できます
プロジェクトのメモリ	.serena/memories/ にセッションをまたいで知識を保持できます
マルチクライアント対応	Claude Desktop、Claude Code、Codex、ChatGPT、カスタムエージェント

プロジェクトのライフサイクル

1. アクティベーション

操作を始める前に、プロジェクトをアクティベートします。

"Activate the project /path/to/my_project"

初回のアクティベーション時に、デフォルト設定で .serena/project.yml が作成されます。

2. オンボーディング

初回のセッションで自動的に実行されます。.serena/memories/ に次のメモリが作成されます。

• tech_stack_and_dependencies.md
• code_style_and_conventions.md
• task_completion_guidelines.md

自動的に開始されない場合は、次を実行します。

"Start the Serena onboarding process for this project."

重要： オンボーディング後に新しい会話を開始してください（分析中にコンテキストがいっぱいになります）。

3. インデックス作成（大規模プロジェクト）

ツールのタイムアウトを防ぐため、事前にインデックスを作成します。

serena project index

一度実行すれば、その後は使用中に自動更新されます。

ツールの使用戦略

優先順位（上位を優先）：

1. シンボルベースのツール - 最も効率的で、LSP を活用します

   • get_symbols_overview → 内容を読み取らずにファイル構造を確認
   • find_symbol → 定義を正確に特定
   • find_referencing_symbols → 変更前に影響を分析
   • replace_symbol_body → 関数を安全に書き換え

2. 行ベースのツール - シンボルを使用できない場合

   • replace_lines、insert_at_line、delete_lines

3. ファイル全体の操作 - 最後の手段

   • read_file、create_text_file

参照： ツールの分類の全容については、references/tools-reference.md をご覧ください。

メモリ管理

.serena/memories/ に知識を保持します。

ツール	目的
write_memory	契約、スキーマ、進捗を保存
read_memory	前のセッションのコンテキストを読み込み
list_memories	利用可能なメモリを確認
prepare_for_new_conversation	続きの作業用の要約を生成
summarize_changes	セッションでの作業を記録

パターン： セッションの最後に summarize_changes → write_memory を実行します。

思考ツール

複雑な操作中に自己省察を促します。

ツール	使用するタイミング
think_about_collected_information	実装の前
think_about_task_adherence	長時間の操作中
think_about_whether_you_are_done	完了を宣言する前

クライアントの設定

Claude Desktop： claude_desktop_config.json を編集します

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/oraios/serena",
               "serena", "start-mcp-server", "--context", "desktop-app"]
    }
  }
}

Claude Code： プロジェクトディレクトリから実行します。

claude mcp add serena -- uvx --from git+https://github.com/oraios/serena \
  serena start-mcp-server --context ide-assistant --project "$(pwd)"

参照： Codex、ChatGPT、Docker などについては、references/client-setup.md をご覧ください。

コンテキストとモード

コンテキスト（起動時に設定し、変更不可）：

• desktop-app - Claude Desktop（すべてのツールセット）
• claude-code - Claude Code（重複なし）
• ide-assistant - IDE 拡張機能（最小限のツール）
• codex - OpenAI Codex
• chatgpt - MCPO 経由の ChatGPT

モード（組み合わせ可能、切り替え可能）：

• editing + interactive - 標準的な開発（デフォルト）
• planning - 実装前の分析
• one-shot - 単一応答のタスク
• no-onboarding - メモリが存在する場合にオンボーディングをスキップ

動的に切り替えます：「planning mode に切り替えて」

参照： 詳細については、references/contexts-and-modes.md をご覧ください。

セキュリティ設定

.serena/project.yml で設定します。

read_only: true  # Disable all editing (analysis only)
excluded_tools:
  - execute_shell_command  # Always disable for untrusted contexts

必須事項：

1. すべてのプロジェクトでバージョン管理（Git）を使用する
2. 明示的に必要な場合を除き、execute_shell_command を無効にする
3. コードレビュー／分析タスクでは read_only: true を設定する
4. MCPO API キーを決して公開しない

デバッグフレームワーク

複雑な自動化ワークフロー（n8n、Zapier など）では：

1. 動作契約 - 変更前に期待される動作を文書化します
2. 変更前のスナップショット - 現在の状態を記録します
3. パリティグリッド - 契約 → 現状 → 必要な修正を対応付けます
4. ドライラン - 適用前に変更を検証します
5. 適用と検証 - 証跡を残しながら実行します
6. メモリの強化 - 最終状態を保存します

参照： 正式なプロンプトとワークフローについては、references/debugging-framework.md をご覧ください。

セッションプロトコル

開始時：

1. プロジェクトの有効化を確認します：get_current_config
2. オンボーディングを確認します：check_onboarding_performed
3. 関連するメモリを読み込みます：list_memories → read_memory
4. ビルド／型チェックコマンドを実行します（ベースラインを確立します）

実行中：

• 編集前にファイルを読み込みます（重複を防ぎます）
• シンボリックツールを優先的に使用します
• 変更のたびに検証を実行します
• 複雑なタスクには思考ツールを使用します

終了時：

1. 最終検証（ビルド／lint／テスト）
2. summarize_changes → write_memory
3. 続行する場合：prepare_for_new_conversation

Serena を使用する場面

最適な場面：

• 大規模／複雑／レガシーなコードベース
• 複数ファイルにまたがるリファクタリング
• 依存関係とアーキテクチャの分析
• トークン数に制約のある操作

不要な場面：

• 空の新規プロジェクト（分析対象がありません）
• 単一ファイルのスクリプト
• コンテキスト全体を容易に収められる場合

ダッシュボード

操作状況は次の場所で監視できます：http://localhost:24282/dashboard/index.html

表示内容：ツール呼び出し、ログ、設定、有効な言語。