これは、なにをしたくて書いたもの？
Serenaを使う時は、コンテキストの指定をしていることが多いと思います。
たとえばClaude Code向けだとclaude-codeというコンテキストを指定しているでしょう。
$ claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context claude-code --project "$(pwd)"
Connecting Your MCP Client — Serena Documentation
またモードという概念もあるみたいです。
Configuration / Modes and Contexts
このあたりがよくわからなかったので、確認してみました。
Serenaのコンテキストとモード
ドキュメントを読んでいると、コンテキストもモードもSerenaが提供するツールセットのどれを使えるようにするかを
コントロールするものみたいです。
Serenaが提供するツールに関するドキュメントはこちらですが、完全なリストはserena tools list --allを実行するように
書かれていますね。後で確認してみましょう。
List of Tools — Serena Documentation
コンテキストでは、デスクトップアプリケーション向け、Claude Code向けのような、どの環境で使われるのかをざっくり
指定します。初期システムプロンプトと利用可能なツールに影響を与え、アクティブなセッション中は変更できません。
Configuration / Modes and Contexts / Contexts
またコンテキストは複数指定できません。
モードはさらに細かく調整するものみたいですね。システムプロンプトに影響を与え、特定のツールを除外したりできます。
Configuration / Modes and Contexts / Modes
モードは複数有効にできます。
まずコンテキストを見てみます。
たとえばdesktop-appコンテキストでは除外ツールはありません。またモードの切り替えができるswitch_modesツールが
含まれています。
description: Desktop application context (chat application detached from code) where Serena's full toolset is provided prompt: | You are running in a desktop application context. Serena's tools give you access to the code base as well as some access to the file system (if enabled). You interact with the user through a chat interface that is separated from the code base. As a consequence, if you are in interactive mode, your communication with the user should involve high-level thinking and planning as well as some summarization of any code edits that you make. To view the code edits you make, the user will have switch to a separate application. To illustrate complex relationships, consider creating diagrams in addition to your text-based communication (depending on the options for text, html, mermaid diagrams, etc. that you are provided with in your initial instructions). excluded_tools: [] included_optional_tools: - switch_modes tool_description_overrides: {}
claude-codeコンテキストでは、Claude Codeの機能と重複するものが除外されます。
description: Claude Code (CLI agent where file operations, basic edits, etc. are already covered; single project mode) prompt: | You are running in a CLI coding agent context where file operations, basic (line-based) edits and reads as well as shell commands are handled by your own, internal tools. If Serena's tools can be used to achieve your task, you should prioritize them. In particular, it is important that you avoid reading entire source code files unless it is strictly necessary! Instead, for exploring and reading code in a token-efficient manner, use Serena's overview and symbolic search tools. For non-code files or for reads where you don't know the symbol's name path, you can use the pattern search tool. excluded_tools: - create_text_file - read_file - execute_shell_command - prepare_for_new_conversation - replace_content tool_description_overrides: {} # whether to assume that Serena shall only work on a single project in this context (provided that a project is given # when Serena is started). # If set to true and a project is provided at startup, the set of tools is limited to those required by the project's # concrete configuration, and other tools are excluded completely, allowing the set of tools to be minimal. # Tools explicitly disabled by the project will not be available at all. # The `activate_project` tool is always disabled in this case, as project switching cannot be allowed. single_project: true
各コンテキスト向けのファイルを見比べると、意外と似たものが多いことに気づきます。descriptionやpromptは違うんですけどね。
次はモードを見てみましょう。
たとえばonboarding。
description: Only read-only tools, focused on analysis and planning prompt: | You are operating in onboarding mode. This is the first time you are seeing the project. Your task is to collect relevant information about it and to save memories using the tools provided. Call relevant onboarding tools for more instructions on how to do this. In this mode, you should not be modifying any existing files. If you are also in interactive mode and something about the project is unclear, ask the user for clarification. excluded_tools: - create_text_file - replace_symbol_body - insert_after_symbol - insert_before_symbol - delete_lines - replace_lines - insert_at_line - execute_shell_command
https://github.com/oraios/serena/blob/main/src/serena/resources/config/modes/onboarding.yml
interactiveでは無効になるものがありません。
description: Interactive mode for clarification and step-by-step work prompt: | You are operating in interactive mode. You should engage with the user throughout the task, asking for clarification whenever anything is unclear, insufficiently specified, or ambiguous. Break down complex tasks into smaller steps and explain your thinking at each stage. When you're uncertain about a decision, present options to the user and ask for guidance rather than making assumptions. Focus on providing informative results for intermediate steps, such that the user can follow along with your progress and provide feedback as needed. excluded_tools: []
https://github.com/oraios/serena/blob/main/src/serena/resources/config/modes/interactive.yml
editing。
description: All tools, with detailed instructions for code editing prompt: | You are operating in editing mode. You can edit files with the provided tools. You adhere to the project's code style and patterns. Use symbolic editing tools whenever possible for precise code modifications. If no explicit editing task has yet been provided, wait for the user to provide one. Do not be overly eager. When writing new code, think about where it belongs best. Don't generate new files if you don't plan on actually properly integrating them into the codebase. You have two main approaches for editing code: (a) editing at the symbol level and (b) file-based editing. The symbol-based approach is appropriate if you need to adjust an entire symbol, e.g. a method, a class, a function, etc. It is not appropriate if you need to adjust just a few lines of code within a larger symbol. **Symbolic editing** Use symbolic retrieval tools to identify the symbols you need to edit. If you need to replace the definition of a symbol, use the `replace_symbol_body` tool. If you want to add some new code at the end of the file, use the `insert_after_symbol` tool with the last top-level symbol in the file. Similarly, you can use `insert_before_symbol` with the first top-level symbol in the file to insert code at the beginning of a file. You can understand relationships between symbols by using the `find_referencing_symbols` tool. If not explicitly requested otherwise by the user, you make sure that when you edit a symbol, the change is either backward-compatible or you find and update all references as needed. The `find_referencing_symbols` tool will give you code snippets around the references as well as symbolic information. You can assume that all symbol editing tools are reliable, so you never need to verify the results if the tools return without error. {% if 'replace_content' in available_tools %} **File-based editing** The `replace_content` tool allows you to perform regex-based replacements within files (as well as simple string replacements). This is your primary tool for editing code whenever replacing or deleting a whole symbol would be a more expensive operation, e.g. if you need to adjust just a few lines of code within a method. You are extremely good at regex, so you never need to check whether the replacement produced the correct result. In particular, you know how to use wildcards effectively in order to avoid specifying the full original text to be replaced! {% endif %} excluded_tools: - replace_lines - insert_at_line - delete_lines
この組み合わせで、実際にどのツールを使うのかを制御するんでしょうね。
独自のコンテキストやモードも作れるようです。
MCPサーバーとして使う場合は不要なツールがあるとコンテキストをムダに消費することになるので、
コーディングエージェントと重複するツールを除外するというのはなるほどな、と思いました。
それでは少し確認してみましょう。
追記
この後を見ていくとわかりますが、コンテキストはSerenaが提供するツールに影響を与えますが、モードを指定しても
リストアップされるツールは変わりません。これはなぜか？ということを疑問に思いましたが、いろいろ調べたり考えたりして
以下のようなことでは？と思いました。
- コンテキストはSerenaをどのような環境で利用するかを決める
- Serenaが提供するツールでどれが使えるようにするかを決めてしまう
- 途中で変更できない
- モードは状況に応じてさらに細かくカスタマイズする
- 現在の利用形態に応じて動作を変えたり使えるツールを制限する
- 実行中にモードを切り替えられるswitch_modesツールが存在する
- デスクトップアプリケーションで使うコンテキストdesktop-appがこのツールを有効にしているのは、状況に応じて会話、計画、編集といったモードが切り替わるから
- 起動時にモードを指定した時点でSerenaからの提供ツールを設定に従って除外してしまうと、モードを切り替えた時に整合性が取れなくなる
だから、モードを指定してもSerenaが提供するツールには影響を与えないんでしょうね。実行中にツールを使われないように
制御する、という感じでしょうか。
ただdesktop-appコンテキスト以外でswitch_modesツールが有効になっていないのは、困る場面もあるような気がします。
このような時にはカスタムコンテキストを作成するのでしょう。
またMCPサーバーとして登録する時に、モード指定や切り替えをどうするかは難しいところですね。
特にコーディングエージェントを非インタラクティブモードで使っている場合は悩みそうだなと。
環境
今回の環境はこちら。
$ uvx --version uvx 0.9.15
Serenaはこちらのコマンドで導入します。
$ uvx --from git+https://github.com/oraios/serena serena --help Updated https://github.com/oraios/serena (904a25053eb74e5dd0c66f161dce8334c76cd6b6) Built serena-agent @ git+https://github.com/oraios/serena@904a25053eb74e5dd0c66f161dce8334c76cd6b6 Installed 58 packages in 45ms Usage: serena [OPTIONS] COMMAND [ARGS]... Serena CLI commands. You can run `<command> --help` for more info on each command. Options: --help Show this message and exit. Commands: config Manage Serena configuration. context Manage Serena contexts. mode Manage Serena modes. print-system-prompt Print the system prompt for a project. project Manage Serena projects. prompts Commands related to Serena's prompts that are... start-mcp-server Starts the Serena MCP server. tools Commands related to Serena's tools.
今回はバージョンではなく、最新のmainですね。コミットハッシュで判別します。
Serenaで使えるツールを確認する
まずはSerenaで使えるツールを確認してみましょう。serena tools list --allで確認できるという話でした。
$ uvx --from git+https://github.com/oraios/serena serena tools list --all
結果。38個のツールがありました。
* `activate_project`: Activates a project based on the project name or path. * `check_onboarding_performed`: Checks whether project onboarding was already performed. * `create_text_file`: Creates/overwrites a file in the project directory. * `delete_lines`: Deletes a range of lines within a file. * `delete_memory`: Deletes a memory from Serena's project-specific memory store. * `edit_memory`: * `execute_shell_command`: Executes a shell command. * `find_file`: Finds files in the given relative paths * `find_referencing_symbols`: Finds symbols that reference the given symbol using the language server backend * `find_symbol`: Performs a global (or local) search using the language server backend. * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes. * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file. * `initial_instructions`: Provides instructions on how to use the Serena toolbox. Should only be used in settings where the system prompt is not read automatically by the client. NOTE: Some MCP clients (including Claude Desktop) do not read the system prompt automatically! * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol. * `insert_at_line`: Inserts content at a given line in a file. * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol. * `jet_brains_find_referencing_symbols`: Finds symbols that reference the given symbol using the JetBrains backend * `jet_brains_find_symbol`: Performs a global (or local) search for symbols using the JetBrains backend * `jet_brains_get_symbols_overview`: Retrieves an overview of the top-level symbols within a specified file using the JetBrains backend * `list_dir`: Lists files and directories in the given directory (optionally with recursion). * `list_memories`: Lists memories in Serena's project-specific memory store. * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building). * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context). * `read_file`: Reads a file within the project directory. * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store. * `remove_project`: Removes a project from the Serena configuration. * `rename_symbol`: Renames a symbol throughout the codebase using language server refactoring capabilities. * `replace_content`: Replaces content in a file (optionally using regular expressions). * `replace_lines`: Replaces a range of lines within a file with new content. * `replace_symbol_body`: Replaces the full definition of a symbol using the language server backend. * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen. * `search_for_pattern`: Performs a search for a pattern in the project. * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase. * `switch_modes`: Activates modes by providing a list of their names * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information. * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task. * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed. * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
--allを付けないとデフォルトで有効なツールが表示されるようです。こちらは28個でした。
$ uvx --from git+https://github.com/oraios/serena serena tools list * `activate_project`: Activates a project based on the project name or path. * `check_onboarding_performed`: Checks whether project onboarding was already performed. * `create_text_file`: Creates/overwrites a file in the project directory. * `delete_memory`: Deletes a memory from Serena's project-specific memory store. * `edit_memory`: * `execute_shell_command`: Executes a shell command. * `find_file`: Finds files in the given relative paths * `find_referencing_symbols`: Finds symbols that reference the given symbol using the language server backend * `find_symbol`: Performs a global (or local) search using the language server backend. * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes. * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file. * `initial_instructions`: Provides instructions on how to use the Serena toolbox. Should only be used in settings where the system prompt is not read automatically by the client. NOTE: Some MCP clients (including Claude Desktop) do not read the system prompt automatically! * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol. * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol. * `list_dir`: Lists files and directories in the given directory (optionally with recursion). * `list_memories`: Lists memories in Serena's project-specific memory store. * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building). * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context). * `read_file`: Reads a file within the project directory. * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store. * `rename_symbol`: Renames a symbol throughout the codebase using language server refactoring capabilities. * `replace_content`: Replaces content in a file (optionally using regular expressions). * `replace_symbol_body`: Replaces the full definition of a symbol using the language server backend. * `search_for_pattern`: Performs a search for a pattern in the project. * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information. * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task. * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed. * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
なにが違うんでしょうね？
$ uvx --from git+https://github.com/oraios/serena serena tools list > default.txt $ uvx --from git+https://github.com/oraios/serena serena tools list --all > all.txt
違いはこのあたりのようです。
$ diff default.txt all.txt 3a4 > * `delete_lines`: Deletes a range of lines within a file. 16a18 > * `insert_at_line`: Inserts content at a given line in a file. 17a20,22 > * `jet_brains_find_referencing_symbols`: Finds symbols that reference the given symbol using the JetBrains backend > * `jet_brains_find_symbol`: Performs a global (or local) search for symbols using the JetBrains backend > * `jet_brains_get_symbols_overview`: Retrieves an overview of the top-level symbols within a specified file using the JetBrains backend 23a29 > * `remove_project`: Removes a project from the Serena configuration. 25a32 > * `replace_lines`: Replaces a range of lines within a file with new content. 26a34 > * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen. 27a36,37 > * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase. > * `switch_modes`: Activates modes by providing a list of their names
ちなみに、現在使えるコンテキストとモードはserena context list、serena mode listでそれぞれ確認できます。
$ uvx --from git+https://github.com/oraios/serena serena context list agent (internal) chatgpt (internal) claude-code (internal) codex (internal) context.template (internal) desktop-app (internal) ide (internal) oaicompat-agent (internal) $ uvx --from git+https://github.com/oraios/serena serena mode list editing (internal) interactive (internal) no-memories (internal) no-onboarding (internal) onboarding (internal) one-shot (internal) planning (internal)
MCPサーバーとして使う時にどのツールが有効になっているか確認する
MCPサーバーとして使う時に、どのツールが有効になっているかは気になるところです。
ちなみにデフォルトではコンテキストはdesktop-app、モードはinteractiveとeditingです。複数指定できます。
$ uvx --from git+https://github.com/oraios/serena serena start-mcp-server --help Usage: serena start-mcp-server [OPTIONS] Starts the Serena MCP server. Options: --project [PROJECT_NAME|PROJECT_PATH] Path or name of project to activate at startup. --project-file [PROJECT_NAME|PROJECT_PATH] [DEPRECATED] Use --project instead. --context TEXT Built-in context name or path to custom context YAML. [default: desktop-app] --mode TEXT Built-in mode names or paths to custom mode YAMLs. [default: interactive, editing] --transport [stdio|sse|streamable-http] Transport protocol. [default: stdio] --host TEXT [default: 0.0.0.0] --port INTEGER [default: 8000] --enable-web-dashboard BOOLEAN Override dashboard setting in config. --enable-gui-log-window BOOLEAN Override GUI log window setting in config. --log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL] Override log level in config. --trace-lsp-communication BOOLEAN Whether to trace LSP communication. --tool-timeout FLOAT Override tool execution timeout in config. --help Show this message and exit.
確認は動かしてみるのが早い、ということになります。
$ uvx --from git+https://github.com/oraios/serena serena start-mcp-server
この時、ログにこのように使えるツールが表示されます。29個ですね。
INFO 2025-12-07 00:48:37,814 [MainThread] serena.mcp:_set_mcp_tools:240 - Starting MCP server with 29 tools: ['read_file', 'create_text_file', 'list_dir', 'find_file', 'replace_content', 'search_for_pattern', 'get_symbols_overview', 'find_symbol', 'find_referencing_symbols', 'replace_symbol_body', 'insert_after_symbol', 'insert_before_symbol', 'rename_symbol', 'write_memory', 'read_memory', 'list_memories', 'delete_memory', 'edit_memory', 'execute_shell_command', 'activate_project', 'switch_modes', 'get_current_config', 'check_onboarding_performed', 'onboarding', 'think_about_collected_information', 'think_about_task_adherence', 'think_about_whether_you_are_done', 'prepare_for_new_conversation', 'initial_instructions']
デフォルトでは28個のツールが有効になっているはずで、interactiveとeditingの2つのモードで無効になるツールはデフォルトで
有効にならないものです。
よくよく見ると、違いはswitch_modesですね。
コンテキストをclaude-codeにしてみましょう。
$ uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context claude-code
有効になるツールは23個になりました。
INFO 2025-12-07 00:58:38,594 [MainThread] serena.mcp:_set_mcp_tools:240 - Starting MCP server with 23 tools: ['list_dir', 'find_file', 'search_for_pattern', 'get_symbols_overview', 'find_symbol', 'find_referencing_symbols', 'replace_symbol_body', 'insert_after_symbol', 'insert_before_symbol', 'rename_symbol', 'write_memory', 'read_memory', 'list_memories', 'delete_memory', 'edit_memory', 'activate_project', 'get_current_config', 'check_onboarding_performed', 'onboarding', 'think_about_collected_information', 'think_about_task_adherence', 'think_about_whether_you_are_done', 'initial_instructions']
こちらの5つが減ったわけですね。
- create_text_file - read_file - execute_shell_command - prepare_for_new_conversation - replace_content
モードをonboardingにしてみます。
$ uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context claude-code --mode onboarding
23個のままですね…。replace_symbol_body、insert_after_symbolなどは減ってもよさそうですが、減っていません。
INFO 2025-12-07 01:00:55,708 [MainThread] serena.mcp:_set_mcp_tools:240 - Starting MCP server with 23 tools: ['list_dir', 'find_file', 'search_for_pattern', 'get_symbols_overview', 'find_symbol', 'find_referencing_symbols', 'replace_symbol_body', 'insert_after_symbol', 'insert_before_symbol', 'rename_symbol', 'write_memory', 'read_memory', 'list_memories', 'delete_memory', 'edit_memory', 'activate_project', 'get_current_config', 'check_onboarding_performed', 'onboarding', 'think_about_collected_information', 'think_about_task_adherence', 'think_about_whether_you_are_done', 'initial_instructions']
モードだけを指定してみます。この場合、コンテキストはdesktop-appですね。
$ uvx --from git+https://github.com/oraios/serena serena start-mcp-server --mode onboarding
…やっぱり減っていません。デフォルトの29個のままです。
INFO 2025-12-07 01:07:11,825 [MainThread] serena.mcp:_set_mcp_tools:240 - Starting MCP server with 29 tools: ['read_file', 'create_text_file', 'list_dir', 'find_file', 'replace_content', 'search_for_pattern', 'get_symbols_overview', 'find_symbol', 'find_referencing_symbols', 'replace_symbol_body', 'insert_after_symbol', 'insert_before_symbol', 'rename_symbol', 'write_memory', 'read_memory', 'list_memories', 'delete_memory', 'edit_memory', 'execute_shell_command', 'activate_project', 'switch_modes', 'get_current_config', 'check_onboarding_performed', 'onboarding', 'think_about_collected_information', 'think_about_task_adherence', 'think_about_whether_you_are_done', 'prepare_for_new_conversation', 'initial_instructions']
ここで、モードの説明をもう1度よく見てみます。
Modes influence the system prompt and can also alter the set of available tools by excluding certain ones.
Configuration / Modes and Contexts / Modes
モードはシステムプロンプトに影響を与えると言っているので、ツールのリストには存在するけれども実際に使われにくく
するなどといったところなのでしょうか…？
onboardingモードのプロンプトでは、ファイルを編集しないこととは書かれていますが…。
prompt: | You are operating in onboarding mode. This is the first time you are seeing the project. Your task is to collect relevant information about it and to save memories using the tools provided. Call relevant onboarding tools for more instructions on how to do this. In this mode, you should not be modifying any existing files. If you are also in interactive mode and something about the project is unclear, ask the user for clarification.
このあたりで調べたり考えたことは、先に追記しておきました。
たぶん実行中に変更できることも視野に入れつつ、動作を変更できるのがモードですね。
おわりに
Serenaのコンテキストとモードの意味を確認してみました。
ちょっとモードの扱いが難しいところではありますが、状況に応じてSerenaの提供するツールを絞り込む仕組みということは
わかりました。それにプロンプトも付いていますね。
ひとまず雰囲気はわかったので今回はここまでにしておきます。
