langchain-agentx-python 2.3.4__py3-none-any.whl → 2.3.5__py3-none-any.whl

langchain_agentx/__init__.py

@@ -1,64 +1,75 @@
-"""
-LangChain-based agent utilities for CodeBaseX.
-
-This package provides:
-- LangChain-AgentX LangGraph agent factory (`loop`)
-
-Typical usage:
-
-```python
-from langchain_agentx import create_loop_agent
-```
-"""
-
-__version__ = "2.3.4"
-
-from .loop import (  # noqa: F401
-    create_loop_agent,
-)
-
-from .loop.hook import (  # noqa: F401
-    ATTACHMENT_HOOK_BLOCKING_ERROR,
-    ATTACHMENT_HOOK_CANCELLED,
-    ATTACHMENT_HOOK_NON_BLOCKING_ERROR,
-    ATTACHMENT_HOOK_STOPPED_CONTINUATION,
-    ATTACHMENT_HOOK_SUCCESS,
-)
-from .observability import (  # noqa: F401
-    EventAdapterState,
-    LangchainAgentEvent,
-    LangchainAgentEventType,
-    LangGraphToLangchainAgentEventAdapter,
-    TraceCollector,
-    TraceSession,
-    TraceSpan,
-)
-from .provider import CompatibleChatOpenAI  # noqa: F401
-from .session import AgentSession, create_agent_session  # noqa: F401
-from .health import HealthCheck, HealthReport, PreflightResult, preflight, sdk_health  # noqa: F401
-from .workflow import BaseWorkflow  # noqa: F401
-
-__all__ = [
-    "ATTACHMENT_HOOK_BLOCKING_ERROR",
-    "ATTACHMENT_HOOK_CANCELLED",
-    "ATTACHMENT_HOOK_NON_BLOCKING_ERROR",
-    "ATTACHMENT_HOOK_STOPPED_CONTINUATION",
-    "ATTACHMENT_HOOK_SUCCESS",
-    "create_loop_agent",
-    "create_agent_session",
-    "AgentSession",
-    "BaseWorkflow",
-    "EventAdapterState",
-    "LangchainAgentEvent",
-    "LangchainAgentEventType",
-    "LangGraphToLangchainAgentEventAdapter",
-    "TraceCollector",
-    "TraceSession",
-    "TraceSpan",
-    "CompatibleChatOpenAI",
-    "HealthCheck",
-    "HealthReport",
-    "PreflightResult",
-    "preflight",
-    "sdk_health",
-]
+"""
+LangChain-based agent utilities for CodeBaseX.
+
+This package provides:
+- LangChain-AgentX LangGraph agent factory (`loop`)
+
+Typical usage:
+
+```python
+from langchain_agentx import create_loop_agent
+```
+"""
+
+__version__ = "2.3.5"
+
+from .mcp.call import McpToolCaller
+from .mcp.client_manager import McpClientManager, McpConnectedClient
+from .mcp.controller import McpRuntimeController
+from .mcp.config.resolver import McpConfigResolver
+from .mcp.events import CollectingEventSink
+from .loop import (  # noqa: F401
+    create_loop_agent,
+)
+
+from .loop.hook import (  # noqa: F401
+    ATTACHMENT_HOOK_BLOCKING_ERROR,
+    ATTACHMENT_HOOK_CANCELLED,
+    ATTACHMENT_HOOK_NON_BLOCKING_ERROR,
+    ATTACHMENT_HOOK_STOPPED_CONTINUATION,
+    ATTACHMENT_HOOK_SUCCESS,
+)
+from .observability import (  # noqa: F401
+    EventAdapterState,
+    LangchainAgentEvent,
+    LangchainAgentEventType,
+    LangGraphToLangchainAgentEventAdapter,
+    TraceCollector,
+    TraceSession,
+    TraceSpan,
+)
+from .provider import CompatibleChatOpenAI  # noqa: F401
+from .session import AgentSession, create_agent_session  # noqa: F401
+from .health import HealthCheck, HealthReport, PreflightResult, preflight, sdk_health  # noqa: F401
+from .workflow import BaseWorkflow  # noqa: F401
+
+__all__ = [
+    "ATTACHMENT_HOOK_BLOCKING_ERROR",
+    "ATTACHMENT_HOOK_CANCELLED",
+    "ATTACHMENT_HOOK_NON_BLOCKING_ERROR",
+    "ATTACHMENT_HOOK_STOPPED_CONTINUATION",
+    "ATTACHMENT_HOOK_SUCCESS",
+    "create_loop_agent",
+    "create_agent_session",
+    "AgentSession",
+    "CollectingEventSink",
+    "McpClientManager",
+    "McpConfigResolver",
+    "McpConnectedClient",
+    "McpRuntimeController",
+    "McpToolCaller",
+    "BaseWorkflow",
+    "EventAdapterState",
+    "LangchainAgentEvent",
+    "LangchainAgentEventType",
+    "LangGraphToLangchainAgentEventAdapter",
+    "TraceCollector",
+    "TraceSession",
+    "TraceSpan",
+    "CompatibleChatOpenAI",
+    "HealthCheck",
+    "HealthReport",
+    "PreflightResult",
+    "preflight",
+    "sdk_health",
+]

langchain_agentx/command/mcp/__init__.py

@@ -0,0 +1,5 @@
+"""command/mcp — MCP prompts → CommandDefinition 适配。"""
+
+from langchain_agentx.command.mcp.adapter import McpPromptCommandAdapter
+
+__all__ = ["McpPromptCommandAdapter"]

langchain_agentx/command/mcp/adapter.py

@@ -0,0 +1,60 @@
+"""MCP prompts/list → CommandDefinition。
+
+职责：
+    对标 CC ``fetchCommandsForClient``：已连接 session 上 prompts/list，
+    映射 ``command_type=prompt``、``source=mcp``、名 ``mcp__{server}__{prompt}``。
+
+链路位置：
+    McpClientManager.list_prompts(connect=False) → 本适配器 → CommandRegistry.register_many。
+
+当前裁剪：
+    不 connect / 不 ensure；slash UX 由宿主投影；不扩展 CommandType。
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from langchain_agentx.command.result import CommandResult
+from langchain_agentx.command.types import CommandDefinition
+from langchain_agentx.protocol.mcp.naming import build_mcp_tool_name
+from langchain_agentx.protocol.mcp.types import McpPromptRef
+
+if TYPE_CHECKING:
+    from langchain_agentx.command.context import CommandContext
+    from langchain_agentx.mcp.client_manager import McpClientManager
+
+
+class McpPromptCommandAdapter:
+    """已连接 Manager 上的 prompts 适配；禁止在此拉起 session。"""
+
+    def __init__(self, manager: McpClientManager) -> None:
+        self._manager = manager
+
+    async def list_definitions(self) -> list[CommandDefinition]:
+        definitions: list[CommandDefinition] = []
+        for spec in self._manager.connected_specs():
+            refs = await self._manager.list_prompts(spec.name, connect=False)
+            for ref in refs:
+                definitions.append(self._to_definition(ref))
+        return definitions
+
+    def _to_definition(self, ref: McpPromptRef) -> CommandDefinition:
+        return CommandDefinition(
+            name=build_mcp_tool_name(ref.server_name, ref.name),
+            description=ref.description,
+            command_type="prompt",
+            source="mcp",
+            handler=self._make_handler(ref),
+        )
+
+    def _make_handler(self, ref: McpPromptRef):
+        manager = self._manager
+
+        async def _handler(context: CommandContext) -> CommandResult:
+            _ = context
+            messages = await manager.get_prompt(ref.server_name, ref.name, connect=False)
+            text = "\n\n".join(messages.messages)
+            return CommandResult(should_query=True, injected_prompt=text)
+
+        return _handler

langchain_agentx/command/prompt_shell.py

@@ -1,123 +1,123 @@
-"""
-command/prompt_shell.py — Prompt 内嵌 shell 命令执行（CC executeShellCommandsInPrompt 对齐）。
-
-职责：
-    解析并执行 prompt 中的 !`command` 占位，将输出内联替换；执行前走路由权限检查。
-
-链路位置：
-    由 command/builtin/commit* 在展开 prompt 前调用。
-"""
-
-from __future__ import annotations
-
-import re
-from collections.abc import Callable, Sequence
-from pathlib import Path
-from typing import Protocol
-
-from langchain_agentx.tool_runtime.models import ToolExecutionContext
-from langchain_agentx.tool_runtime.permission_context import set_command_bash_allow_rules
-from langchain_agentx.tool_runtime.session_store import AgentSessionStore
-from langchain_agentx.utils.subprocess_text import TextSubprocessRunner, default_text_subprocess_runner
-
-_INLINE_PATTERN = re.compile(r"!`([^`]+)`")
-
-
-class PromptShellPermissionError(RuntimeError):
-    """prompt 内嵌 shell 命令未通过 Bash 权限检查。"""
-
-
-class _ShellRunner(Protocol):
-    def run_text(
-        self,
-        argv: list[str],
-        *,
-        cwd: str | Path | None = None,
-        timeout_sec: float | None = None,
-    ) -> tuple[int, str, str]: ...
-
-
-def _default_runner_call(
-    runner: TextSubprocessRunner,
-    command: str,
-    *,
-    cwd: str | Path | None,
-) -> tuple[int, str, str]:
-    completed = runner.run(
-        ["bash", "-lc", command],
-        cwd=cwd,
-        timeout=30.0,
-        capture_output=True,
-    )
-    stdout = completed.stdout or ""
-    stderr = completed.stderr or ""
-    if completed.returncode != 0 and not stdout.strip():
-        return completed.returncode, "", stderr.strip() or f"exit {completed.returncode}"
-    return completed.returncode, stdout, stderr
-
-
-def _assert_prompt_shell_permission(
-    command: str,
-    *,
-    bash_allow_rules: Sequence[str] | None,
-    cwd: str | Path | None,
-) -> None:
-    from langchain_agentx.tools.bash.tool import BashRuntimeTool
-
-    store = AgentSessionStore("prompt-shell")
-    if bash_allow_rules:
-        set_command_bash_allow_rules(store, bash_allow_rules)
-    workspace_root = str(cwd) if cwd is not None else None
-    ctx = ToolExecutionContext(
-        tool_name="Bash",
-        tool_call_id="prompt-shell",
-        input_args={"command": command},
-        state={},
-        session_store=store,
-        workspace_root=workspace_root,
-        cwd=workspace_root,
-    )
-    l1 = BashRuntimeTool().run_l1_permission_check({"command": command}, ctx)
-    if l1.outcome == "deny":
-        message = (l1.decision.message if l1.decision else None) or "Permission denied"
-        raise PromptShellPermissionError(
-            f'Shell command permission check failed for "!`{command}`": {message}',
-        )
-
-
-async def execute_shell_commands_in_prompt(
-    text: str,
-    *,
-    cwd: str | Path | None = None,
-    runner: TextSubprocessRunner | None = None,
-    shell_runner: Callable[[str], tuple[int, str, str]] | None = None,
-    bash_allow_rules: Sequence[str] | None = None,
-    check_permissions: bool = True,
-) -> str:
-    """将 text 中所有 !`command` 替换为命令 stdout（失败时内联 stderr/exit）。"""
-    if "!`" not in text:
-        return text
-
-    text_runner = runner or default_text_subprocess_runner()
-    result = text
-
-    for match in list(_INLINE_PATTERN.finditer(text)):
-        command = match.group(1).strip()
-        if not command:
-            continue
-        if check_permissions and shell_runner is None:
-            _assert_prompt_shell_permission(
-                command,
-                bash_allow_rules=bash_allow_rules,
-                cwd=cwd,
-            )
-        if shell_runner is not None:
-            _code, stdout, stderr = shell_runner(command)
-        else:
-            _code, stdout, stderr = _default_runner_call(text_runner, command, cwd=cwd)
-        replacement = stdout.strip() if stdout.strip() else stderr.strip()
-        if not replacement:
-            replacement = "(no output)"
-        result = result.replace(match.group(0), replacement, 1)
-
-    return result
+"""
+command/prompt_shell.py — Prompt 内嵌 shell 命令执行（CC executeShellCommandsInPrompt 对齐）。
+
+职责：
+    解析并执行 prompt 中的 !`command` 占位，将输出内联替换；执行前走路由权限检查。
+
+链路位置：
+    由 command/builtin/commit* 在展开 prompt 前调用。
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Sequence
+from pathlib import Path
+from typing import Protocol
+
+from langchain_agentx.tool_runtime.models import ToolExecutionContext
+from langchain_agentx.tool_runtime.permission_context import set_command_bash_allow_rules
+from langchain_agentx.tool_runtime.session_store import AgentSessionStore
+from langchain_agentx.utils.subprocess_text import TextSubprocessRunner, default_text_subprocess_runner
+
+_INLINE_PATTERN = re.compile(r"!`([^`]+)`")
+
+
+class PromptShellPermissionError(RuntimeError):
+    """prompt 内嵌 shell 命令未通过 Bash 权限检查。"""
+
+
+class _ShellRunner(Protocol):
+    def run_text(
+        self,
+        argv: list[str],
+        *,
+        cwd: str | Path | None = None,
+        timeout_sec: float | None = None,
+    ) -> tuple[int, str, str]: ...
+
+
+def _default_runner_call(
+    runner: TextSubprocessRunner,
+    command: str,
+    *,
+    cwd: str | Path | None,
+) -> tuple[int, str, str]:
+    completed = runner.run(
+        ["bash", "-lc", command],
+        cwd=cwd,
+        timeout=30.0,
+        capture_output=True,
+    )
+    stdout = completed.stdout or ""
+    stderr = completed.stderr or ""
+    if completed.returncode != 0 and not stdout.strip():
+        return completed.returncode, "", stderr.strip() or f"exit {completed.returncode}"
+    return completed.returncode, stdout, stderr
+
+
+def _assert_prompt_shell_permission(
+    command: str,
+    *,
+    bash_allow_rules: Sequence[str] | None,
+    cwd: str | Path | None,
+) -> None:
+    from langchain_agentx.tools.bash.tool import BashRuntimeTool
+
+    store = AgentSessionStore("prompt-shell")
+    if bash_allow_rules:
+        set_command_bash_allow_rules(store, bash_allow_rules)
+    workspace_root = str(cwd) if cwd is not None else None
+    ctx = ToolExecutionContext(
+        tool_name="Bash",
+        tool_call_id="prompt-shell",
+        input_args={"command": command},
+        state={},
+        session_store=store,
+        workspace_root=workspace_root,
+        cwd=workspace_root,
+    )
+    l1 = BashRuntimeTool().run_l1_permission_check({"command": command}, ctx)
+    if l1.outcome == "deny":
+        message = (l1.decision.message if l1.decision else None) or "Permission denied"
+        raise PromptShellPermissionError(
+            f'Shell command permission check failed for "!`{command}`": {message}',
+        )
+
+
+async def execute_shell_commands_in_prompt(
+    text: str,
+    *,
+    cwd: str | Path | None = None,
+    runner: TextSubprocessRunner | None = None,
+    shell_runner: Callable[[str], tuple[int, str, str]] | None = None,
+    bash_allow_rules: Sequence[str] | None = None,
+    check_permissions: bool = True,
+) -> str:
+    """将 text 中所有 !`command` 替换为命令 stdout（失败时内联 stderr/exit）。"""
+    if "!`" not in text:
+        return text
+
+    text_runner = runner or default_text_subprocess_runner()
+    result = text
+
+    for match in list(_INLINE_PATTERN.finditer(text)):
+        command = match.group(1).strip()
+        if not command:
+            continue
+        if check_permissions and shell_runner is None:
+            _assert_prompt_shell_permission(
+                command,
+                bash_allow_rules=bash_allow_rules,
+                cwd=cwd,
+            )
+        if shell_runner is not None:
+            _code, stdout, stderr = shell_runner(command)
+        else:
+            _code, stdout, stderr = _default_runner_call(text_runner, command, cwd=cwd)
+        replacement = stdout.strip() if stdout.strip() else stderr.strip()
+        if not replacement:
+            replacement = "(no output)"
+        result = result.replace(match.group(0), replacement, 1)
+
+    return result

langchain_agentx/command/registry.py

@@ -36,6 +36,22 @@ class CommandRegistry:
         for alias in command.aliases:
             self._alias_to_name[self._normalize(alias)] = normalized_name
 
+    def register_many(
+        self,
+        commands: Iterable[CommandDefinition],
+        *,
+        skip_existing: bool = True,
+    ) -> list[str]:
+        """批量注册。默认跳过已有名（内置优先于 MCP）。"""
+        registered: list[str] = []
+        for command in commands:
+            normalized_name = self._normalize(command.name)
+            if skip_existing and normalized_name in self._commands:
+                continue
+            self.register(command)
+            registered.append(normalized_name)
+        return registered
+
     def register_plugin(
         self,
         commands: Iterable[CommandDefinition],

langchain_agentx/loop/config/loop_config.py

@@ -313,6 +313,12 @@ class AgentLoopConfig:
     )
     model_retry: ModelRetrySettings = field(default_factory=ModelRetrySettings)
 
+    # MCP：默认空，不 connect / 不扫盘。仅显式 specs / controller / plugin 片段时 Loop 接线（S2）。
+    mcp_servers: tuple[Any, ...] = ()
+    mcp_plugins: tuple[Any, ...] = ()
+    mcp_skills_enabled: bool = True
+    mcp_elicitation_auto_accept: bool = False
+
     # -----------------------------------------------------------------------
     # 便捷构造器
     # -----------------------------------------------------------------------
@@ -394,6 +400,9 @@ class LoopServices:
     queued_command_providers: Sequence[Any] = field(default_factory=tuple)
     active_files_getter: Callable[[], list[str]] | None = None
 
+    mcp_controller: Any = None  # McpRuntimeController；默认 None 零成本
+    command_registry: Any = None  # CommandRegistry；MCP prompts register_many
+
 
 __all__ = [
     "PromptConfig",

langchain_agentx/loop/graph/factory.py

@@ -317,6 +317,7 @@ def _flatten_config_for_runtime(config: AgentLoopConfig) -> _FlatLoopConfig:
         trace_enabled=config.trace.enabled,
         trace_persist=config.trace.persist,
         headless=config.headless,
+        container_type=config.container_type,
         model_profile=config.model_profile,
         model_profile_registry=config.model_profile_registry,
         compact_buffer_tokens=config.compact_buffer_tokens,
@@ -549,6 +550,15 @@ class LoopGraphBuilder:
                 available_tools=self._loader_tools,
             ).build_sections()
         )
+        if (
+            self._loop_loader is not None
+            and getattr(self._loop_loader, "mcp_controller", None) is not None
+        ):
+            from ...loop.prompt.mcp_instructions import mcp_instructions_section
+
+            self._dynamic_sections.append(
+                mcp_instructions_section(self._loop_loader.mcp_controller)
+            )
         system_message = self._build_system_message(
             base_prompt=base_prompt,
             append_system_prompt=append_system_prompt,
@@ -783,6 +793,10 @@ class LoopGraphBuilder:
                         )
                     continue
                 self._loop_loader.register(tool)
+            self._mcp_bind_session_store = session_store
+            self._mcp_bind_model = model
+            self._mcp_bind_schema_ns = schema_cache_namespace
+            self._bind_optional_mcp()
             self._runtime_tools = self._loop_loader.registry.list()
             from ...loop.prompt.tool_aware_sections import collect_enabled_tool_names
 
@@ -799,6 +813,62 @@ class LoopGraphBuilder:
                 if self._skill_runtime_tool is None and rt.__class__.__name__ == "SkillRuntimeTool":
                     self._skill_runtime_tool = rt
 
+    def _bind_optional_mcp(self) -> None:
+        if self._loop_loader is None:
+            return
+        controller = self._services.mcp_controller
+        specs = self._config.mcp_servers
+        plugins = self._config.mcp_plugins
+        if controller is None and not specs and not plugins:
+            return
+        self._loop_loader.set_mcp_skills_enabled(
+            bool(getattr(self._config, "mcp_skills_enabled", True))
+        )
+        for tool in self._loop_loader.registry.list():
+            if tool.__class__.__name__ != "SkillRuntimeTool":
+                continue
+            catalog = getattr(tool, "_catalog", None)
+            if catalog is not None:
+                self._loop_loader.set_mcp_skill_catalog(catalog)
+            break
+        self._loop_loader.attach_mcp(
+            controller=controller,
+            specs=specs or None,
+            plugins=plugins or None,
+            schema_cache_namespace=getattr(self, "_mcp_bind_schema_ns", None),
+            after_refresh=self._rebuild_views_after_mcp_refresh,
+            command_registry=self._services.command_registry,
+        )
+        self._apply_mcp_elicitation_auto_accept()
+
+    def _apply_mcp_elicitation_auto_accept(self) -> None:
+        if self._loop_loader is None:
+            return
+        if not bool(getattr(self._config, "mcp_elicitation_auto_accept", False)):
+            return
+        ctrl = self._loop_loader.mcp_controller
+        if ctrl is None:
+            return
+        from langchain_agentx.mcp.elicitation import AcceptingElicitationInterceptor
+
+        ctrl.manager.elicitation.set_interceptor(AcceptingElicitationInterceptor())
+
+    def _rebuild_views_after_mcp_refresh(self) -> None:
+        if self._loop_loader is None:
+            return
+        from ...loop.prompt.tool_aware_sections import collect_enabled_tool_names
+
+        self._runtime_tools = self._loop_loader.registry.list()
+        self._enabled_tool_names = collect_enabled_tool_names(self._runtime_tools)
+        self._tool_prompt_ctx = self._build_tool_prompt_context(
+            session_store=getattr(self, "_mcp_bind_session_store", None),
+            model=getattr(self, "_mcp_bind_model", None),
+            schema_cache_namespace=getattr(self, "_mcp_bind_schema_ns", None),
+        )
+        self._loader_tools = self._loop_loader.registry.to_langchain_tools(
+            prompt_ctx=self._tool_prompt_ctx,
+        )
+
     def refresh_permission_settings(
         self,
         *,

langchain_agentx/loop/prompt/mcp_instructions.py

@@ -0,0 +1,40 @@
+"""MCP server instructions → SystemPromptSection。
+
+职责：
+    截断 2048；只经 ModelRequest.system_message 动态段，不写入 state messages。
+
+链路位置：
+    LoopGraphBuilder._prepare_compile_context 在 MCP 显式启用时追加。
+
+当前裁剪：
+    无进度条；无 CC UI 折叠。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from langchain_agentx.loop.prompt.sections import SystemPromptSection, section
+from langchain_agentx.protocol.mcp.truncate import truncate_for_model
+
+
+def format_mcp_instructions(snapshots: Any) -> str | None:
+    lines: list[str] = []
+    for item in snapshots or ():
+        text = getattr(item, "instructions", None)
+        if not text:
+            continue
+        name = getattr(item, "name", "") or "mcp"
+        lines.append(f"## MCP server `{name}`\n{truncate_for_model(str(text))}")
+    if not lines:
+        return None
+    return "# MCP server instructions\n\n" + "\n\n".join(lines)
+
+
+def mcp_instructions_section(controller: Any) -> SystemPromptSection:
+    def _compute() -> str | None:
+        status = getattr(controller, "status", None)
+        snapshots = status() if callable(status) else ()
+        return format_mcp_instructions(snapshots)
+
+    return section("mcp_server_instructions", _compute)