MCPサーバ - Serenaのソースを表示

== 概要 ==
Serenaは、Oraios AIが開発したオープンソース (MITライセンス) のコーディングエージェントツールキットである。<br>
LLMをコードベース上で動作する完全機能のエージェントに変える強力なツールであり、Model Context Protocol (MCP) とLanguage Server Protocol (LSP) を統合して、IDE的なセマンティック解析・コード編集機能を提供する。<br>
<br>
Serenaは、従来のテキスト検索ベースのアプローチとは異なり、シンボルレベルでコード要素を理解する。<br>
<br>
以下に示すような機能を提供する。<br>
* IDE的なセマンティック解析機能 (find_symbol、find_referencing_symbols、get_symbols_overview等)
* シンボル単位のコード編集機能 (replace_symbol_body、insert_after_symbol、insert_before_symbol等)
* プロジェクト固有のメモリ機能 (write_memory、read_memory、list_memories)
* シェルコマンド実行とWebダッシュボード (execute_shell_command、open_dashboard)
<br>
Serenaを使用することにより、LLMがコンテキストウィンドウのトークン使用量を約38〜80[%]削減しながら、高精度なコード解析・編集を行うことができる。<br>
<br>
40以上のプログラミング言語に対応しており、Claude Code、Claude Desktop、VS Code、Cursor、JetBrains AI Assistant等の主要なMCPクライアントと統合できる。<br>
<br>
SerenaはMITライセンスで公開されており、最新バージョンはv0.1.4である。<br>
<br><br>

== 動作要件 ==
==== システム要件 ====
* Python 3.11〜3.12
*: Python 3.13は現時点では非対応
* uv (Rust製の高速Pythonパッケージマネージャー)
* 対応OS
*: Windows、MacOS、Linux、Docker
<br>
==== 対応MCPクライアント ====
<center>
{| class="wikitable"
|+ 対応MCPクライアント一覧
|-
! クライアント !! 説明
|-
| Claude Desktop || Anthropic公式デスクトップアプリケーション
|-
| Claude Code || AnthropicのCLIツール
|-
| VS Code (GitHub Copilot) || MicrosoftのエディタとGitHub Copilot統合
|-
| Cursor || AI機能統合型コードエディタ
|-
| Windsurf || Codeium製AIコードエディタ
|-
| OpenCode || Go言語製のターミナルベースAIコーディングアシスタント
|-
| JetBrains AI Assistant || JetBrains IDE向けAIアシスタント
|-
| その他 || Antigravity等のMCP対応クライアント
|}
</center>
<br><br>

== uvのインストール ==
SerenaはPythonパッケージマネージャーの<code>uv</code>を必要とする。<br>
以下に示すOSごとのインストール方法を参照すること。<br>
<br>
==== Linux ====
curlを使用してインストールする。<br>
 curl -LsSf https://astral.sh/uv/install.sh | sh
<br>
==== MacOS ====
===== curlの使用 =====
 curl -LsSf https://astral.sh/uv/install.sh | sh
<br>
===== Homebrewの使用 =====
 brew install uv
<br>
==== Windows ====
===== PowerShellの使用 =====
 powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
<br>
===== wingetの使用 =====
 winget install --id=astral-sh.uv -e
<br>
===== scoopの使用 =====
 scoop install main/uv
<br><br>

== Serenaのインストール ==
==== uvxを使用する場合 (推奨) ====
<u>uvx</u> を使用することにより、リポジトリをクローンせずに最新版のSerenaを直接実行できる。<br>
クイックな試験やCI/CDパイプラインに最適な方法である。<br>
<br>
動作確認コマンドを以下に示す。<br>
 uvx --from git+https://github.com/oraios/serena serena start-mcp-server --help
<br>
==== リポジトリをクローンする場合 ====
ローカルにリポジトリをクローンして使用する場合の手順を以下に示す。<br>
<br>
 <syntaxhighlight lang="bash">
 git clone https://github.com/oraios/serena.git
 cd serena
 cp src/serena/resources/serena_config.template.yml serena_config.yml
 </syntaxhighlight>
<br>
==== Dockerを使用する場合 ====
Dockerコンテナを使用してSerenaを起動する場合のコマンドを以下に示す。<br>
<br>
 docker run --rm -i --network host -v /path/to/projects:/workspaces/projects ghcr.io/oraios/serena:latest serena start-mcp-server --transport stdio
<br>
<u>/path/to/projects</u>には、実際のプロジェクトディレクトリのパスを指定すること。<br>
<br><br>

== MCPクライアントの設定 ==
==== Claude Desktop ====
Claude Desktopの設定ファイルを編集する。<br>
<br>
設定ファイルの場所は、以下の通りである。<br>
* MacOS
*: ~/Library/Application Support/Claude/claude_desktop_config.json
* Windows
*: %APPDATA%\Claude\claude_desktop_config.json
<br>
設定例を以下に示す。<br>
<br>
 <syntaxhighlight lang="json">
 {
    "mcpServers": {
       "serena": {
          "command": "uvx",
          "args": [
             "--from",
             "git+https://github.com/oraios/serena",
             "serena",
             "start-mcp-server"
          ]
       }
    }
 }
 </syntaxhighlight>
<br>
設定ファイルを編集した後は、Claude Desktopを再起動する必要がある。<br>
<br>
==== Claude Code ====
Claude Codeでは、以下のコマンドを実行してSerenaをMCPサーバとして追加する。<br>
<br>
 claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context claude-code --project "$(pwd)"
<br>
または、プロジェクトルートに<code>.mcp.json</code>ファイルを作成して設定する方法もある。<br>
<br>
 <syntaxhighlight lang="json">
 {
    "mcpServers": {
       "serena": {
          "command": "uvx",
          "args": [
             "--from",
             "git+https://github.com/oraios/serena",
             "serena",
             "start-mcp-server",
             "--context",
             "claude-code",
             "--project",
             "."
          ]
       }
    }
 }
 </syntaxhighlight>
<br>
==== VS Code (GitHub Copilot) ====
VS Codeでは、<u>.vscode/mcp.json</u>ファイルを作成して設定する。<br>
<br>
 <syntaxhighlight lang="json">
 {
    "servers": {
       "oraios/serena": {
          "type": "stdio",
          "command": "uvx",
          "args": [
             "--from",
             "git+https://github.com/oraios/serena",
             "serena",
             "start-mcp-server",
             "--context",
             "ide",
             "--project",
             "${workspaceFolder}"
          ]
       }
    }
 }
 </syntaxhighlight>
<br>
==== Cursor / Windsurf ====
CursorおよびWindsurfでは、<code>--context ide</code> 引数を指定することにより、IDE側のツールと重複する機能を無効化できる。<br>
<br>
設定例を以下に示す。<br>
<br>
 <syntaxhighlight lang="json">
 {
    "mcpServers": {
       "serena": {
          "command": "uvx",
          "args": [
             "--from",
             "git+https://github.com/oraios/serena",
             "serena",
             "start-mcp-server",
             "--context",
             "ide",
             "--project",
             "/path/to/your/project"
          ]
       }
    }
 }
 </syntaxhighlight>
<br>
==== OpenCode ====
OpenCodeは、Go言語で構築されたターミナルベースのAIコーディングアシスタントである。<br>
複数のAIプロバイダー (OpenAI、Claude、Google Gemini等) をサポートしている。<br>
<br>
設定ファイルの場所は、以下の通りである。<br>
* グローバル設定
*: ~/.config/opencode/opencode.json
* プロジェクト設定
*: /<プロジェクトのパス>/opencode.json
<br>
設定例を以下に示す。<br>
<br>
 <syntaxhighlight lang="json">
 {
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
       "serena": {
          "type": "local",
          "command": [
             "uvx",
             "--from",
             "git+https://github.com/oraios/serena",
             "serena",
             "start-mcp-server",
             "--context",
             "ide-assistant"
          ],
          "environment": {
             "PYTHONUNBUFFERED": "1"
          }
       }
    }
 }
 </syntaxhighlight>
<br>
OpenCodeでは、<code>--context ide-assistant</code> を指定することにより、IDE側のツールとの重複を避けることが推奨される。<br>
<br>
設定ファイルを作成した後、OpenCodeを起動してSerena MCPサーバが正常に読み込まれたことを確認する。<br>
<br><br>

== プロジェクト設定 ==
==== project.yml ====
Serenaはプロジェクトごとの設定ファイルを自動生成する。<br>
<br>
* 場所
*: /<プロジェクト>/.serena/project.yml
* 主な設定内容
*: 使用プログラミング言語の指定
*: 検索対象ディレクトリの設定
*: 除外ディレクトリの設定
<br>
==== グローバル設定 ====
SerenaのグローバルなデフォルトはYAML形式の設定ファイルで管理する。<br>
<br>
設定ファイルの場所は、以下の通りである。<br>
* Linux / MacOS
*: ~/.serena/serena_config.yml
* Windows
*: %USERPROFILE%\.serena\serena_config.yml
<br>
主な設定項目は以下の通りである。<br>
* ツールの有効・無効設定
* 言語サーバ固有の設定
* タイムアウト・回答長などの実行パラメータ
* ロギング設定
<br>
言語サーバのパスをカスタマイズする場合の設定例を以下に示す。<br>
<br>
 <syntaxhighlight lang="yaml">
 ls_specific_settings:
    <language>:
       ls_path: "/custom/path"
 </syntaxhighlight>
<br>
==== コンテキスト ====
コンテキストは、Serena起動時に <code>--context</code> オプションで指定する。<br>
セッション開始後はコンテキストを変更できないため、用途に応じて適切なコンテキストを選択すること。<br>
<br>
下表に、利用可能なコンテキストを示す。<br>
<br>
<center>
{| class="wikitable"
|+ コンテキストの一覧
! コンテキスト !! 説明
|-
| <code>desktop-app</code> || デスクトップアプリケーション向けのデフォルトコンテキスト<br>フルセットのSerenaツールを提供する。
|-
| <code>claude-code</code> || Claude Code統合用コンテキスト<br>Claude Code固有の機能と重複するツールを無効化する。
|-
| <code>ide</code> || VS Code、Cursor等のIDEアシスタント向けコンテキスト
|-
| <code>agent</code> || 自律エージェント用コンテキスト
|-
| <code>oaicompat-agent</code> || OpenAI互換ツール記述対応コンテキスト
|}
</center>
<br>
==== モード ====
モードは複数同時有効化が可能な動作調整ツールである。<br>
起動時に<code>--mode</code>オプションで指定する。<br>
<br>
下表に、ビルトインモードに示す。<br>
<br>
<center>
{| class="wikitable"
|+ モードの一覧
! モード !! 説明
|-
| <code>planning</code> || 計画・分析タスク向けのモード
|-
| <code>editing</code> || コード修正を最適化するモード
|-
| <code>interactive</code> || 対話型モード（デフォルト）
|-
| <code>one-shot</code> || 単一応答で完結するモード
|-
| <code>onboarding</code> || プロジェクトの初期化・分析向けモード
|-
| <code>no-memories</code> || メモリツールを無効化するモード
|}
</center>
<br>
複数のモードを同時に指定する例を以下に示す。<br>
<br>
 serena start-mcp-server --mode planning --mode no-onboarding
<br><br>

== 主なツール ==
==== コード検索・解析ツール ====
<center>
{| class="wikitable"
|+ コード検索・解析ツール
! ツール !! 説明
|-
| find_symbol || グローバル（またはローカル）シンボルを検索する。
|-
| find_referencing_symbols || 特定シンボルの参照元を検索する。
|-
| get_symbols_overview || ファイル内のトップレベルシンボルの概要を取得する。
|-
| rename_symbol || 全参照箇所を一括でリネームする。
|}
</center>
<br>
==== コード編集ツール ====
<center>
{| class="wikitable"
|+ コード編集ツール
! ツール !! 説明
|-
| replace_symbol_body || シンボル定義を完全に置換する。
|-
| insert_after_symbol || 特定シンボルの後に新しいコードを挿入する。
|-
| insert_before_symbol || 特定シンボルの前に新しいコードを挿入する。
|-
| replace_lines || 指定した行範囲を置換する。
|-
| replace_content || ファイル内容を置換する。(正規表現対応)
|-
| delete_lines || ファイル内の指定した行範囲を削除する。
|}
</center>
<br>
==== ファイル管理ツール ====
<center>
{| class="wikitable"
|+ ファイル管理ツール
! ツール !! 説明
|-
| read_file || プロジェクトディレクトリ内のファイルを読み取る。
|-
| create_text_file || ファイルを新規作成または上書きする。
|-
| list_dir || ディレクトリの内容を一覧表示する。
|}
</center>
<br>
==== プロジェクト分析ツール ====
<center>
{| class="wikitable"
|+ プロジェクト分析ツール
! ツール !! 説明
|-
| activate_project || プロジェクトを有効化する。
|-
| onboarding || プロジェクト構造と必須タスクを特定する。
|-
| get_current_config || 現在のエージェント設定を表示する。
|}
</center>
<br>
==== メモリ・その他のツール ====
<center>
{| class="wikitable"
|+ メモリ・その他のツール
! ツール !! 説明
|-
| write_memory / read_memory / list_memories || プロジェクト固有のメモリ機能
|-
| execute_shell_command || シェルコマンドを実行する。
|-
| open_dashboard || Webダッシュボードを起動する。
|-
| switch_modes || セッション内でモードを変更する。
|}
</center>
<br>
Serenaは上記を含む合計40個以上のツールを提供する。<br>
<br><br>

== 使用方法 ==
==== Claude Codeでの使用例 ====
Claude Codeで作業するプロジェクトディレクトリに移動して、MCPサーバとしてSerenaを追加した上でClaude Codeを起動する。<br>
<br>
 # 使用例 :
 
 コードベースの概要を把握してください。
<br>
 # 使用例 :
 
 UserAuthクラスのloginメソッドの実装を確認してください。
<br>
 # 使用例 :
 
 fetchData関数を参照している箇所を全て列挙してください。
<br>
==== Claude Desktopでの使用例 ====
Claude Desktop設定ファイルにSerenaを追加した後、Claude Desktopを再起動して、Serenaツールを利用できる状態にする。<br>
<br>
 # 使用例 :
 
 @serena このプロジェクトのディレクトリ構造を分析して概要を教えてください。
<br>
 # 使用例 :
 
 @serena src/api/users.ts のUserServiceクラスにgetAllUsersメソッドを追加してください。
<br>
==== プロジェクトインデックス ====
Serenaのシンボル検索を活用するために、プロジェクトのインデックスを作成する。<br>
<br>
* 手動でインデックスを作成する場合
*: <syntaxhighlight lang="text">
 serena project index
 </syntaxhighlight>
*: <br>
* 並列処理でインデックスを作成する場合
*: <syntaxhighlight lang="text">
 serena project index --parallel 4
 </syntaxhighlight>
*: <br>
* 差分インデックスを作成する場合
*: <syntaxhighlight lang="text">
 serena project index --incremental
 </syntaxhighlight>
<br><br>

== 対応プログラミング言語 ==
Serenaは40以上のプログラミング言語に対応している。<br>
<br>
以下に示す言語は、デフォルト設定で利用可能である。<br>
<br>
<center>
{| class="wikitable"
|+ デフォルト設定で利用可能な言語
|-
! 言語 !! 言語サーバ
|-
| Bash || デフォルト
|-
| Java || デフォルト
|-
| JavaScript || デフォルト
|-
| Python || デフォルト
|-
| Rust || デフォルト
|-
| TypeScript || デフォルト
|-
| YAML || デフォルト
|-
| Dart || デフォルト
|-
| Swift || デフォルト
|-
| Lua || デフォルト
|-
| Markdown || デフォルト
|-
| Zig || デフォルト
|-
| Clojure || デフォルト
|-
| Elm || デフォルト
|}
</center>
<br>
以下に示す言語は、追加の言語サーバインストールが必要である。<br>
<br>
<center>
{| class="wikitable"
|+ 追加インストールが必要な言語
|-
! 言語 !! 言語サーバ !! 備考
|-
| C / C++ || clangd (デフォルト) / ccls || compile_commands.jsonが必要
|-
| C# || Roslyn / OmniSharp || .NET 10以上が必須
|-
| Go || gopls || 要インストール
|-
| Scala || Metals || 手動セットアップが必要
|-
| Vue || - || Node.js v18以上が必要
|-
| R || languageserver || Rパッケージが必要
|-
| Elixir || ElixirLS || -
|-
| F# || FSharp言語サーバ || -
|-
| Fortran || fortls || -
|-
| Haskell || Haskell言語サーバ || -
|-
| Kotlin || Kotlin言語サーバ || -
|-
| Perl || Perl言語サーバ || -
|-
| PHP || Intelephense || INTELEPHENSE_LICENSE_KEY設定可
|-
| Ruby || - || 言語サーバが別途必要
|-
| Nix || Nix言語サーバ || -
|-
| Pascal || pasls || FPCコンパイラのパス指定可
|-
| Erlang || erlang_ls || -
|}
</center>
<br><br>

== トラブルシューティング ==
==== 接続・起動関連 ====
uvコマンドが見つからないエラーが発生する場合は、以下の項目を確認する。<br>
* uvがインストールされているか確認
*: <code>uv --version</code> コマンドでインストール状態を確認する。
* PATH設定が正しいか確認
*: uvのインストールディレクトリがPATHに含まれているか確認する。
*: シェルの設定ファイル (~/.profile、~/.zprofile等) を再読み込みする。
<br>
WindowsでSerenaを使用する時に相対パスエラーが発生する場合は、設定ファイル内でプロジェクトパスを絶対パスで指定すること。<br>
<br>
Webダッシュボードを使用する場合は、設定ファイルで <code>web_dashboard</code> オプションを有効化する設定が必要である。<br>
<br>
==== Claude統合関連 ====
Serenaのツール呼び出しが動作しない場合は、以下の項目を確認する。<br>
* FileSystem MCPとのツール名競合を確認
*: Claude DesktopでFileSystem MCPサーバを同時に有効化している場合、ツール名が競合することがある。
*: Serenaのツール名をユニークにするか、競合するMCPサーバを無効化する。
<br>
Claude CodeでSerenaへの接続が失敗する場合は、以下の項目を確認する。<br>
* タイムアウト設定を確認
*: デフォルトのタイムアウト値が短い場合は、設定で延長する。
* MCPサーバの起動ログを確認
*: <code>claude mcp list</code> コマンドで登録されているMCPサーバを確認する。
<br>
==== デバッグ方法 ====
問題が解決しない場合は、以下に示すデバッグ手段を試みること。<br>
<br>
* ログファイルの確認
*: SerenaのMCPログ (mcp.log等) を確認する
* MCP Inspectorの使用
*: MCP Inspectorツールを使用してMCPサーバの動作を詳細に確認する。
*: <code>npx @modelcontextprotocol/inspector uvx --from git+https://github.com/oraios/serena serena start-mcp-server</code> で起動する。
<br><br>

== 関連リソース ==
* [https://oraios.github.io/serena/ 公式ドキュメント]
* [https://github.com/oraios/serena GitHub - Serena]
* [https://modelcontextprotocol.io/ Model Context Protocol公式サイト]
<br><br>


{{#seo:
|title={{PAGENAME}} : Exploring Electronics and SUSE Linux | MochiuWiki
|keywords=MochiuWiki,Mochiu,Wiki,Mochiu Wiki,Electric Circuit,Electric,pcb,Mathematics,AVR,TI,STMicro,AVR,ATmega,MSP430,STM,Arduino,Xilinx,FPGA,Verilog,HDL,PinePhone,Pine Phone,Raspberry,Raspberry Pi,C,C++,C#,Qt,Qml,MFC,Shell,Bash,Zsh,Fish,SUSE,SLE,Suse Enterprise,Suse Linux,openSUSE,open SUSE,Leap,Linux,uCLnux,電気回路,電子回路,基板,プリント基板
|description={{PAGENAME}} - 電子回路とSUSE Linuxに関する情報 | This page is {{PAGENAME}} in our wiki about electronic circuits and SUSE Linux
|image=/resources/assets/MochiuLogo_Single_Blue.png
}}

__FORCETOC__
[[カテゴリ:設定]]