serena.mcp

serena.mcp#

Source code: serena/mcp.py

The Serena Model Context Protocol (MCP) Server

class SerenaMCPRequestContext(agent: serena.agent.SerenaAgent)[source]#

Bases: object

Parameters:

agent (SerenaAgent)

class SerenaFastMCPTool(tool, openai_tool_compatible, structured_output)[source]#

Bases: Tool

Parameters:

  • tool (Tool) – the Serena tool

  • openai_tool_compatible (bool) – whether to process the tool schema to be compatible with OpenAI tools (doesn’t accept integer, needs number instead, etc.). This allows using Serena MCP within Codex.

  • structured_output (bool | None) – whether to use structured output for the tool (None = auto)

async run(arguments, context=None, convert_result=False)[source]#

Run the tool with arguments.

Parameters:

  • arguments (dict[str, Any])

  • context (Context | None)

  • convert_result (bool)

Return type:

Any

model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class SerenaMCPFactory(
transport,
context='desktop-app',
project=None,
memory_log_handler=None,
)[source]#

Bases: object

Factory for the creation of the Serena MCP server with an associated SerenaAgent.

Parameters:

  • transport (Literal['stdio', 'sse', 'streamable-http']) – The transport to use for the MCP server.

  • context (str) – The context name or path to context file

  • project (str | None) – Either an absolute path to the project directory or a name of an already registered project. If the project passed here hasn’t been registered yet, it will be registered automatically and can be activated by its name afterward.

  • memory_log_handler (MemoryLogHandler | None) – the in-memory log handler to use for the agent’s logging

static make_mcp_tool(
tool,
openai_tool_compatible=True,
structured_output=None,
)[source]#

Creates an MCP tool from a Serena Tool instance.

Parameters:

  • tool (Tool) – the Serena Tool instance to convert.

  • openai_tool_compatible (bool) – whether to process the tool schema to be compatible with OpenAI tools (doesn’t accept integer, needs number instead, etc.). This allows using Serena MCP within codex.

  • structured_output (bool | None) – whether to use structured output for the tool (None = auto)

Return type:

SerenaFastMCPTool

create_mcp_server(
host='127.0.0.1',
port=8000,
mode_selection_def=None,
language_backend=None,
enable_web_dashboard=None,
enable_gui_log_window=None,
open_web_dashboard=None,
log_level=None,
trace_lsp_communication=None,
tool_timeout=None,
project_activation_error=None,
)[source]#

Create an MCP server with process-isolated SerenaAgent to prevent asyncio contamination.

Parameters:

  • host (str) – The host to bind to

  • port (int) – The port to bind to

  • mode_selection_def (ModeSelectionDefinition | None) – the mode selection definition to apply

  • language_backend (LanguageBackend | None) – the language backend to use, overriding the configuration setting.

  • enable_web_dashboard (bool | None) – Whether to enable the web dashboard. If not specified, will take the value from the serena configuration.

  • enable_gui_log_window (bool | None) – Whether to enable the GUI log window. It currently does not work on macOS, and setting this to True will be ignored then. If not specified, will take the value from the serena configuration.

  • open_web_dashboard (bool | None) – Whether to open the web dashboard on launch. If not specified, will take the value from the serena configuration.

  • log_level (Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] | None) – Log level. If not specified, will take the value from the serena configuration.

  • trace_lsp_communication (bool | None) – Whether to trace the communication between Serena and the language servers. This is useful for debugging language server issues.

  • tool_timeout (float | None) – Timeout in seconds for tool execution. If not specified, will take the value from the serena configuration.

  • project_activation_error (str | None) – an initial project activation error to report back to the client

Return type:

FastMCP

server_lifespan(mcp_server)[source]#

Manages the lifespan of MCP server instances and performs necessary setup and teardown. For stdio transport, there is a single server instance. For other transports, this is called once per connection!

Parameters:

mcp_server (FastMCP) – the MCP server instance to configure

Return type:

AsyncIterator[None]