pythinker-code 2.0.0__py3-none-any.whl

pythinker_code/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 1.0.0 (2026-05-06)
+
+Initial release of Pythinker CLI.
+
+- Interactive terminal AI coding agent with shell command mode (Ctrl-X)
+- ACP server (`pythinker acp`) for IDE integrations such as Zed and JetBrains
+- MCP tool support: `pythinker mcp` sub-commands and ad-hoc `--mcp-config-file`
+- Multi-provider auth: OpenAI, OpenAI Codex, Anthropic, OpenRouter, DeepSeek, MiniMax, Opencode-Go
+- Skills, plugins, and slash commands across project / user / built-in scopes
+- Session persistence with subagents and approval workflows
+- Print mode and wire mode for non-interactive and programmatic use
+- Plan mode for read-only research and design before code changes
+- YOLO mode (`--yolo` / `/yolo`) to dangerously skip permission approvals while keeping the user reachable via `AskUserQuestion`
+- Auto mode (`--auto` / `/auto`) for unattended runs: auto-approves tool calls and auto-dismisses `AskUserQuestion` so the agent finishes end-to-end without a user

pythinker_code/__main__.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+ROOT_HELP = """Usage: pythinker [OPTIONS] COMMAND [ARGS]...
+
+  Pythinker, your next CLI agent.
+
+Options:
+  -h, --help                       Show this message and exit.
+  -V, --version                    Show version and exit.
+  --verbose                        Print verbose information.
+  --debug                          Log debug information.
+  -w, --work-dir DIRECTORY         Working directory for the agent.
+  --add-dir DIRECTORY              Add an additional workspace directory.
+  -S, -r, --session, --resume TEXT Resume a session.
+  -C, --continue                   Continue the previous session.
+  --config TEXT                    Config TOML/JSON string to load.
+  --config-file FILE               Config TOML/JSON file to load.
+  -m, --model TEXT                 LLM model to use.
+  --thinking / --no-thinking       Enable or disable thinking mode.
+  -y, --yolo, --yes, --auto-approve
+                                   Dangerously skip permission approvals.
+  --plan                           Start in plan mode.
+  --auto                           Run in auto mode (no user present).
+  -p, -c, --prompt, --command TEXT User prompt to the agent.
+  --print                          Run in print mode.
+  --acp                            Deprecated; use `pythinker acp`.
+  --wire                           Run as Wire server.
+  --quiet                          Print only the final assistant message.
+  --agent [default|okabe]          Builtin agent specification to use.
+  --agent-file FILE                Custom agent specification file.
+  --mcp-config-file FILE           MCP config file to load; repeatable.
+  --mcp-config TEXT                MCP config JSON to load; repeatable.
+  --skills-dir DIRECTORY           Custom skills directory; repeatable.
+  --no-telemetry                   Disable anonymous telemetry & error reporting.
+
+Commands:
+  acp      Run Pythinker CLI ACP server.
+  term     Run Toad TUI backed by Pythinker CLI ACP server.
+  login    Login with a model provider.
+  logout   Logout from a model provider.
+  info     Show version and protocol information.
+  export   Export session data.
+  mcp      Manage MCP server configurations.
+  plugin   Manage plugins.
+  vis      Run Pythinker Agent Tracing Visualizer.
+  web      Run Pythinker CLI web interface.
+
+Documentation:        https://mohamed-elkholy95.github.io/Pythinker-Code/
+LLM friendly version: https://mohamed-elkholy95.github.io/Pythinker-Code/llms.txt
+"""
+
+
+def _prog_name() -> str:
+    return Path(sys.argv[0]).name or "pythinker"
+
+
+def main(argv: Sequence[str] | None = None) -> int | str | None:
+    args = list(sys.argv[1:] if argv is None else argv)
+
+    if len(args) == 1 and args[0] in {"--version", "-V"}:
+        from pythinker_code.constant import get_version
+
+        print(f"pythinker, version {get_version()}")
+        return 0
+
+    if len(args) == 1 and args[0] in {"--help", "-h"}:
+        print(ROOT_HELP, end="")
+        return 0
+
+    from pythinker_code.telemetry.crash import install_crash_handlers, set_phase
+    from pythinker_code.utils.proxy import normalize_proxy_env
+
+    # Install excepthook before anything else so startup-phase crashes are captured.
+    install_crash_handlers()
+    normalize_proxy_env()
+
+    from pythinker_code.cli import cli
+
+    try:
+        return cli(args=args, prog_name=_prog_name())
+    except SystemExit as exc:
+        return exc.code
+    finally:
+        set_phase("shutdown")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pythinker_code/acp/AGENTS.md

@@ -0,0 +1,93 @@
+# ACP Integration Notes (pythinker-code)
+
+## Protocol summary (ACP overview)
+- ACP is JSON-RPC 2.0 with request/response methods plus one-way notifications.
+- Typical flow: `initialize` -> optional `authenticate` -> `session/new` or `session/load`
+  -> `session/prompt`
+  with `session/update` notifications and optional `session/cancel`.
+- Clients provide `session/request_permission` and optional terminal/filesystem methods.
+- All ACP file paths must be absolute; line numbers are 1-based.
+
+## Entry points and server modes
+- **Deprecated single-session server**: `PythinkerCLI.run_acp()` uses `ACP` -> `ACPServerSingleSession`.
+  - Code: `src/pythinker_code/app.py`, `src/pythinker_code/ui/acp/__init__.py`.
+  - Used when running CLI with `--acp` UI mode; every ACP method now raises a deprecation error.
+- **Multi-session server**: `acp_main()` runs `ACPServer` with `use_unstable_protocol=True`.
+  - Code: `src/pythinker_code/acp/__init__.py`, `src/pythinker_code/acp/server.py`.
+  - Exposed via the `pythinker acp` command in `src/pythinker_code/cli/__init__.py`.
+
+## Capabilities advertised
+- `prompt_capabilities`: `embedded_context=True`, `image=True`, `audio=False`.
+- `mcp_capabilities`: `http=True`, `sse=False`.
+- Multi-session: `load_session=True`, `session_capabilities.list` and `session_capabilities.resume` supported.
+- `auth_methods` advertises terminal auth for `pythinker login`.
+
+## Session lifecycle (implemented behavior)
+- `session/new`
+  - Multi-session: creates a persisted `Session`, builds `PythinkerCLI`, stores `ACPSession`.
+  - Sends `AvailableCommandsUpdate` for slash commands on session creation.
+  - MCP servers passed by ACP are converted via `acp_mcp_servers_to_mcp_config`.
+- `session/load`
+  - Multi-session only: loads by `Session.find`, then builds `PythinkerCLI` and `ACPSession`.
+  - No history replay yet (TODO).
+- `session/list`
+  - Multi-session only: lists sessions via `Session.list`, no pagination.
+- `session/resume`
+  - Multi-session only: loads the session if needed and returns current mode/model state.
+- `session/set_mode`
+  - Multi-session only: accepts only `default`.
+- `session/set_model`
+  - Multi-session only: switches the session LLM and persists default model/thinking settings.
+- `session/prompt`
+  - Uses `ACPSession.prompt()` to stream updates and produce a `stop_reason`.
+  - Stop reasons: `end_turn`, `max_turn_requests`, `cancelled`.
+- `session/cancel`
+  - Sets the per-turn cancel event to stop the prompt.
+
+## Streaming updates and content mapping
+- Text chunks -> `AgentMessageChunk`.
+- Think chunks -> `AgentThoughtChunk`.
+- Tool calls:
+  - Start -> `ToolCallStart` with JSON args as text content.
+  - Streaming args -> `ToolCallProgress` with updated title/args.
+  - Results -> `ToolCallProgress` with `completed` or `failed`.
+  - Tool call IDs are prefixed with turn ID to avoid collisions across turns.
+- Plan updates:
+  - `TodoDisplayBlock` is converted into `AgentPlanUpdate`.
+- Available commands:
+  - `AvailableCommandsUpdate` is sent right after session creation.
+
+## Prompt/content conversion
+- Incoming prompt blocks:
+  - Supported: `TextContentBlock`, `ImageContentBlock` (converted to data URL).
+  - Unsupported types are logged and ignored.
+- Tool result display blocks:
+  - `DiffDisplayBlock` -> `FileEditToolCallContent`.
+  - `HideOutputDisplayBlock` suppresses tool output in ACP (used by terminal tool).
+
+## Tool integration and permission flow
+- ACP sessions use `ACPHost` to route filesystem reads/writes through ACP clients.
+- If the client advertises `terminal` capability, the `Shell` tool is replaced by an
+  ACP-backed `Terminal` tool.
+  - Uses ACP `terminal/create`, waits for exit, streams `TerminalToolCallContent`,
+    then releases the terminal handle.
+- Approval requests in the core tool system are bridged to ACP
+  `session/request_permission` with allow-once/allow-always/reject options.
+
+## Current gaps / not implemented
+- `fork_session` is not implemented.
+- `ext_method` / `ext_notification` for custom ACP extensions are stubbed.
+- Deprecated single-session `--acp` rejects all methods and exists only to report migration guidance.
+- `session/load` still has no history replay.
+
+## Filesystem (ACP client-backed)
+- When the client advertises `fs.readTextFile` / `fs.writeTextFile`, `ACPHost` routes
+  reads and writes through ACP `fs/*` methods.
+- `ReadFile` uses `HostPath.read_lines`, which `ACPHost` implements via ACP reads.
+- `ReadMediaFile` uses `HostPath.read_bytes` to load image/video payloads through ACP reads.
+- `WriteFile` uses `HostPath.read_text/write_text/append_text` and still generates diffs
+  and approvals in the tool layer.
+
+## Zed-specific notes (as of current integration)
+- Terminal auth advertises `pythinker login`; `authenticate` verifies that login completed.
+- External agent clients should use `pythinker acp`, not deprecated `pythinker --acp`.

pythinker_code/acp/__init__.py

@@ -0,0 +1,13 @@
+def acp_main() -> None:
+    """Entry point for the multi-session ACP server."""
+    import asyncio
+
+    import acp
+
+    from pythinker_code.acp.server import ACPServer
+    from pythinker_code.app import enable_logging
+    from pythinker_code.utils.logging import logger
+
+    enable_logging()
+    logger.info("Starting ACP server on stdio")
+    asyncio.run(acp.run_agent(ACPServer(), use_unstable_protocol=True))

pythinker_code/acp/convert.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+import acp
+
+from pythinker_code.acp.types import ACPContentBlock
+from pythinker_code.utils.logging import logger
+from pythinker_code.wire.types import (
+    ContentPart,
+    DiffDisplayBlock,
+    DisplayBlock,
+    ImageURLPart,
+    TextPart,
+    ToolReturnValue,
+)
+
+
+def acp_blocks_to_content_parts(prompt: list[ACPContentBlock]) -> list[ContentPart]:
+    content: list[ContentPart] = []
+    for block in prompt:
+        match block:
+            case acp.schema.TextContentBlock():
+                content.append(TextPart(text=block.text))
+            case acp.schema.ImageContentBlock():
+                content.append(
+                    ImageURLPart(
+                        image_url=ImageURLPart.ImageURL(
+                            url=f"data:{block.mime_type};base64,{block.data}"
+                        )
+                    )
+                )
+            case acp.schema.EmbeddedResourceContentBlock():
+                resource = block.resource
+                if isinstance(resource, acp.schema.TextResourceContents):
+                    uri = resource.uri
+                    text = resource.text
+                    content.append(TextPart(text=f"<resource uri={uri!r}>\n{text}\n</resource>"))
+                else:
+                    logger.warning(
+                        "Unsupported embedded resource type: {type}",
+                        type=type(resource).__name__,
+                    )
+            case acp.schema.ResourceContentBlock():
+                # ResourceContentBlock is a link reference without inline content;
+                # include the URI so the model is at least aware of the reference.
+                content.append(
+                    TextPart(text=f"<resource_link uri={block.uri!r} name={block.name!r} />")
+                )
+            case _:
+                logger.warning("Unsupported prompt content block: {block}", block=block)
+    return content
+
+
+def display_block_to_acp_content(
+    block: DisplayBlock,
+) -> acp.schema.FileEditToolCallContent | None:
+    if isinstance(block, DiffDisplayBlock):
+        return acp.schema.FileEditToolCallContent(
+            type="diff",
+            path=block.path,
+            old_text=block.old_text,
+            new_text=block.new_text,
+        )
+
+    return None
+
+
+def tool_result_to_acp_content(
+    tool_ret: ToolReturnValue,
+) -> list[
+    acp.schema.ContentToolCallContent
+    | acp.schema.FileEditToolCallContent
+    | acp.schema.TerminalToolCallContent
+]:
+    from pythinker_code.acp.tools import HideOutputDisplayBlock
+
+    def _to_acp_content(
+        part: ContentPart,
+    ) -> (
+        acp.schema.ContentToolCallContent
+        | acp.schema.FileEditToolCallContent
+        | acp.schema.TerminalToolCallContent
+    ):
+        if isinstance(part, TextPart):
+            return acp.schema.ContentToolCallContent(
+                type="content", content=acp.schema.TextContentBlock(type="text", text=part.text)
+            )
+        logger.warning("Unsupported content part in tool result: {part}", part=part)
+        return acp.schema.ContentToolCallContent(
+            type="content",
+            content=acp.schema.TextContentBlock(type="text", text=f"[{part.__class__.__name__}]"),
+        )
+
+    def _to_text_block(text: str) -> acp.schema.ContentToolCallContent:
+        return acp.schema.ContentToolCallContent(
+            type="content", content=acp.schema.TextContentBlock(type="text", text=text)
+        )
+
+    contents: list[
+        acp.schema.ContentToolCallContent
+        | acp.schema.FileEditToolCallContent
+        | acp.schema.TerminalToolCallContent
+    ] = []
+
+    for block in tool_ret.display:
+        if isinstance(block, HideOutputDisplayBlock):
+            # return early to indicate no output should be shown
+            return []
+
+        content = display_block_to_acp_content(block)
+        if content is not None:
+            contents.append(content)
+    # TODO: better concatenation of `display` blocks and `output`?
+
+    output = tool_ret.output
+    if isinstance(output, str):
+        if output:
+            contents.append(_to_text_block(output))
+    else:
+        # NOTE: At the moment, ToolReturnValue.output is either a string or a
+        # list of ContentPart. We avoid an unnecessary isinstance() check here
+        # to keep pyright happy while still handling list outputs.
+        contents.extend(_to_acp_content(part) for part in output)
+
+    if not contents and tool_ret.message:
+        # Fallback to the `message` for LLM if there's no other content
+        contents.append(_to_text_block(tool_ret.message))
+
+    return contents

pythinker_code/acp/host.py

@@ -0,0 +1,298 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncGenerator, Iterable, Mapping
+from contextlib import suppress
+from typing import Literal
+
+import acp
+from pythinker_host import (
+    AsyncReadable,
+    AsyncWritable,
+    Host,
+    HostProcess,
+    StatResult,
+    StrOrHostPath,
+)
+from pythinker_host.local import local_host
+from pythinker_host.path import HostPath
+
+_DEFAULT_TERMINAL_OUTPUT_LIMIT = 50_000
+_DEFAULT_POLL_INTERVAL = 0.2
+_TRUNCATION_NOTICE = "[acp output truncated]\n"
+
+
+class _NullWritable:
+    def can_write_eof(self) -> bool:
+        return False
+
+    def close(self) -> None:
+        return None
+
+    async def drain(self) -> None:
+        return None
+
+    def is_closing(self) -> bool:
+        return False
+
+    async def wait_closed(self) -> None:
+        return None
+
+    def write(self, data: bytes) -> None:
+        return None
+
+    def writelines(self, data: Iterable[bytes], /) -> None:
+        return None
+
+    def write_eof(self) -> None:
+        return None
+
+
+class ACPProcess:
+    """Host process adapter for ACP terminal execution."""
+
+    def __init__(
+        self,
+        client: acp.Client,
+        session_id: str,
+        terminal_id: str,
+        *,
+        poll_interval: float = _DEFAULT_POLL_INTERVAL,
+    ) -> None:
+        self._client = client
+        self._session_id = session_id
+        self._terminal_id = terminal_id
+        self._poll_interval = poll_interval
+        self._stdin = _NullWritable()
+        self._stdout = asyncio.StreamReader()
+        self._stderr = asyncio.StreamReader()
+        self.stdin: AsyncWritable = self._stdin
+        self.stdout: AsyncReadable = self._stdout
+        # ACP does not expose stderr separately; keep stderr empty.
+        self.stderr: AsyncReadable = self._stderr
+        self._returncode: int | None = None
+        self._last_output = ""
+        self._truncation_noted = False
+        self._exit_future: asyncio.Future[int] = asyncio.get_running_loop().create_future()
+        self._poll_task = asyncio.create_task(self._poll_output())
+
+    @property
+    def pid(self) -> int:
+        return -1
+
+    @property
+    def returncode(self) -> int | None:
+        return self._returncode
+
+    async def wait(self) -> int:
+        return await self._exit_future
+
+    async def kill(self) -> None:
+        await self._client.kill_terminal(
+            session_id=self._session_id,
+            terminal_id=self._terminal_id,
+        )
+
+    def _feed_output(self, output_response: acp.schema.TerminalOutputResponse) -> None:
+        output = output_response.output
+        reset = output_response.truncated or (
+            self._last_output and not output.startswith(self._last_output)
+        )
+        if reset and self._last_output and not self._truncation_noted:
+            self._stdout.feed_data(_TRUNCATION_NOTICE.encode("utf-8"))
+            self._truncation_noted = True
+
+        delta = output if reset else output[len(self._last_output) :]
+        if delta:
+            self._stdout.feed_data(delta.encode("utf-8", "replace"))
+        self._last_output = output
+
+    @staticmethod
+    def _normalize_exit_code(exit_code: int | None) -> int:
+        return 1 if exit_code is None else exit_code
+
+    async def _poll_output(self) -> None:
+        exit_task = asyncio.create_task(
+            self._client.wait_for_terminal_exit(
+                session_id=self._session_id,
+                terminal_id=self._terminal_id,
+            )
+        )
+        exit_code: int | None = None
+        try:
+            while True:
+                if exit_task.done():
+                    exit_response = exit_task.result()
+                    exit_code = exit_response.exit_code
+                    break
+
+                output_response = await self._client.terminal_output(
+                    session_id=self._session_id,
+                    terminal_id=self._terminal_id,
+                )
+                self._feed_output(output_response)
+                if output_response.exit_status:
+                    exit_code = output_response.exit_status.exit_code
+                    try:
+                        exit_response = await exit_task
+                        exit_code = exit_response.exit_code or exit_code
+                    except Exception:
+                        pass
+                    break
+
+                await asyncio.sleep(self._poll_interval)
+
+            final_output = await self._client.terminal_output(
+                session_id=self._session_id,
+                terminal_id=self._terminal_id,
+            )
+            self._feed_output(final_output)
+        except Exception as exc:
+            error_note = f"[acp terminal error] {exc}\n"
+            self._stdout.feed_data(error_note.encode("utf-8", "replace"))
+            if exit_code is None:
+                exit_code = 1
+        finally:
+            if not exit_task.done():
+                exit_task.cancel()
+                with suppress(Exception):
+                    await exit_task
+            self._returncode = self._normalize_exit_code(exit_code)
+            self._stdout.feed_eof()
+            self._stderr.feed_eof()
+            if not self._exit_future.done():
+                self._exit_future.set_result(self._returncode)
+            with suppress(Exception):
+                await self._client.release_terminal(
+                    session_id=self._session_id,
+                    terminal_id=self._terminal_id,
+                )
+
+
+class ACPHost:
+    """Host backend that routes supported operations through ACP."""
+
+    name: str = "acp"
+
+    def __init__(
+        self,
+        client: acp.Client,
+        session_id: str,
+        client_capabilities: acp.schema.ClientCapabilities | None,
+        fallback: Host | None = None,
+        *,
+        output_byte_limit: int | None = _DEFAULT_TERMINAL_OUTPUT_LIMIT,
+        poll_interval: float = _DEFAULT_POLL_INTERVAL,
+    ) -> None:
+        self._client = client
+        self._session_id = session_id
+        self._fallback = fallback or local_host
+        fs = client_capabilities.fs if client_capabilities else None
+        self._supports_read = bool(fs and fs.read_text_file)
+        self._supports_write = bool(fs and fs.write_text_file)
+        self._supports_terminal = bool(client_capabilities and client_capabilities.terminal)
+        self._output_byte_limit = output_byte_limit
+        self._poll_interval = poll_interval
+
+    def pathclass(self):
+        return self._fallback.pathclass()
+
+    def normpath(self, path: StrOrHostPath) -> HostPath:
+        return self._fallback.normpath(path)
+
+    def gethome(self) -> HostPath:
+        return self._fallback.gethome()
+
+    def getcwd(self) -> HostPath:
+        return self._fallback.getcwd()
+
+    async def chdir(self, path: StrOrHostPath) -> None:
+        await self._fallback.chdir(path)
+
+    async def stat(self, path: StrOrHostPath, *, follow_symlinks: bool = True) -> StatResult:
+        return await self._fallback.stat(path, follow_symlinks=follow_symlinks)
+
+    def iterdir(self, path: StrOrHostPath) -> AsyncGenerator[HostPath]:
+        return self._fallback.iterdir(path)
+
+    def glob(
+        self, path: StrOrHostPath, pattern: str, *, case_sensitive: bool = True
+    ) -> AsyncGenerator[HostPath]:
+        return self._fallback.glob(path, pattern, case_sensitive=case_sensitive)
+
+    async def readbytes(self, path: StrOrHostPath, n: int | None = None) -> bytes:
+        return await self._fallback.readbytes(path, n=n)
+
+    async def readtext(
+        self,
+        path: StrOrHostPath,
+        *,
+        encoding: str = "utf-8",
+        errors: Literal["strict", "ignore", "replace"] = "strict",
+    ) -> str:
+        abs_path = self._abs_path(path)
+        if not self._supports_read:
+            return await self._fallback.readtext(abs_path, encoding=encoding, errors=errors)
+        response = await self._client.read_text_file(path=abs_path, session_id=self._session_id)
+        return response.content
+
+    async def readlines(
+        self,
+        path: StrOrHostPath,
+        *,
+        encoding: str = "utf-8",
+        errors: Literal["strict", "ignore", "replace"] = "strict",
+    ) -> AsyncGenerator[str]:
+        text = await self.readtext(path, encoding=encoding, errors=errors)
+        for line in text.splitlines(keepends=True):
+            yield line
+
+    async def writebytes(self, path: StrOrHostPath, data: bytes) -> int:
+        return await self._fallback.writebytes(path, data)
+
+    async def writetext(
+        self,
+        path: StrOrHostPath,
+        data: str,
+        *,
+        mode: Literal["w", "a"] = "w",
+        encoding: str = "utf-8",
+        errors: Literal["strict", "ignore", "replace"] = "strict",
+    ) -> int:
+        abs_path = self._abs_path(path)
+        if mode == "a":
+            if self._supports_read and self._supports_write:
+                existing = await self.readtext(abs_path, encoding=encoding, errors=errors)
+                await self._client.write_text_file(
+                    path=abs_path,
+                    content=existing + data,
+                    session_id=self._session_id,
+                )
+                return len(data)
+            return await self._fallback.writetext(
+                abs_path, data, mode="a", encoding=encoding, errors=errors
+            )
+
+        if not self._supports_write:
+            return await self._fallback.writetext(
+                abs_path, data, mode=mode, encoding=encoding, errors=errors
+            )
+
+        await self._client.write_text_file(
+            path=abs_path,
+            content=data,
+            session_id=self._session_id,
+        )
+        return len(data)
+
+    async def mkdir(
+        self, path: StrOrHostPath, parents: bool = False, exist_ok: bool = False
+    ) -> None:
+        await self._fallback.mkdir(path, parents=parents, exist_ok=exist_ok)
+
+    async def exec(self, *args: str, env: Mapping[str, str] | None = None) -> HostProcess:
+        return await self._fallback.exec(*args, env=env)
+
+    def _abs_path(self, path: StrOrHostPath) -> str:
+        host_path = path if isinstance(path, HostPath) else HostPath(path)
+        return str(host_path.canonical())

pythinker_code/acp/mcp.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import Any
+
+import acp.schema
+from fastmcp.mcp_config import MCPConfig
+from pydantic import ValidationError
+
+from pythinker_code.acp.types import MCPServer
+from pythinker_code.exception import MCPConfigError
+
+
+def acp_mcp_servers_to_mcp_config(mcp_servers: list[MCPServer]) -> MCPConfig:
+    if not mcp_servers:
+        return MCPConfig()
+
+    try:
+        return MCPConfig.model_validate(
+            {"mcpServers": {server.name: _convert_acp_mcp_server(server) for server in mcp_servers}}
+        )
+    except ValidationError as exc:
+        raise MCPConfigError(f"Invalid MCP config from ACP client: {exc}") from exc
+
+
+def _convert_acp_mcp_server(server: MCPServer) -> dict[str, Any]:
+    """Convert an ACP MCP server to a dictionary representation."""
+    match server:
+        case acp.schema.HttpMcpServer():
+            return {
+                "url": server.url,
+                "transport": "http",
+                "headers": {header.name: header.value for header in server.headers},
+            }
+        case acp.schema.SseMcpServer():
+            return {
+                "url": server.url,
+                "transport": "sse",
+                "headers": {header.name: header.value for header in server.headers},
+            }
+        case acp.schema.McpServerStdio():
+            return {
+                "command": server.command,
+                "args": server.args,
+                "env": {item.name: item.value for item in server.env},
+                "transport": "stdio",
+            }