illusion-code 0.1.0__py3-none-any.whl

illusion/tools/lsp_tool.py

@@ -0,0 +1,333 @@
+"""
+轻量级代码智能工具
+==================
+
+本模块提供基于 AST 的代码智能查询功能，用于 Python 代码的定义、引用、符号搜索等。
+
+主要组件：
+    - LspTool: 代码智能查询工具
+
+使用示例：
+    >>> from illusion.tools import LspTool
+    >>> tool = LspTool()
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+from illusion.services.lsp import (
+    find_references,
+    go_to_definition,
+    go_to_implementation,
+    hover,
+    incoming_calls,
+    list_document_symbols,
+    outgoing_calls,
+    prepare_call_hierarchy,
+    workspace_symbol_search,
+)
+from illusion.tools.base import BaseTool, ToolExecutionContext, ToolResult
+
+# ---------------------------------------------------------------------------
+# 驼峰 → 蛇形操作名映射（兼容两种命名风格）
+# ---------------------------------------------------------------------------
+_OP_CAMEL_TO_SNAKE: dict[str, str] = {
+    "goToDefinition": "go_to_definition",
+    "findReferences": "find_references",
+    "documentSymbol": "document_symbol",
+    "workspaceSymbol": "workspace_symbol",
+    "goToImplementation": "go_to_implementation",
+    "prepareCallHierarchy": "prepare_call_hierarchy",
+    "incomingCalls": "incoming_calls",
+    "outgoingCalls": "outgoing_calls",
+}
+
+
+class LspToolInput(BaseModel):
+    """代码智能查询参数。
+
+    属性：
+        operation: 要执行的代码智能操作（支持驼峰和蛇形两种命名）
+        file_path: 用于基于文件的操作的源文件路径
+        symbol: 要查找的显式符号名称
+        line: 基于位置查询的 1-based 行号
+        character: 基于位置查询的 1-based 字符偏移
+        query: workspace_symbol 的子字符串查询
+    """
+
+    operation: Literal[
+        "document_symbol",
+        "workspace_symbol",
+        "go_to_definition",
+        "find_references",
+        "hover",
+        "go_to_implementation",
+        "prepare_call_hierarchy",
+        "incoming_calls",
+        "outgoing_calls",
+    ] = Field(description="The code intelligence operation to perform")
+    file_path: str | None = Field(default=None, description="Path to the source file for file-based operations")
+    symbol: str | None = Field(default=None, description="Explicit symbol name to look up")
+    line: int | None = Field(default=None, ge=1, description="1-based line number for position-based lookups")
+    character: int | None = Field(default=None, ge=1, description="1-based character offset for position-based lookups")
+    query: str | None = Field(default=None, description="Substring query for workspace_symbol")
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_operation(cls, data: Any) -> Any:
+        """将驼峰操作名映射为蛇形。"""
+        if isinstance(data, dict) and "operation" in data:
+            op: str = data["operation"]
+            if op in _OP_CAMEL_TO_SNAKE:
+                data["operation"] = _OP_CAMEL_TO_SNAKE[op]
+        return data
+
+    @model_validator(mode="after")
+    def validate_arguments(self) -> "LspToolInput":
+        # workspace_symbol 需要 query 参数
+        if self.operation == "workspace_symbol":
+            if not self.query:
+                raise ValueError("workspace_symbol requires query")
+            return self
+        # 其他操作需要 file_path
+        if not self.file_path:
+            raise ValueError(f"{self.operation} requires file_path")
+        # document_symbol 不需要 symbol 或 line
+        if self.operation == "document_symbol":
+            return self
+        # 其余操作需要 symbol 或 line
+        if not self.symbol and self.line is None:
+            raise ValueError(f"{self.operation} requires symbol or line")
+        return self
+
+
+class LspTool(BaseTool):
+    """Python 源文件的只读代码智能（基于 AST 分析）。
+
+    用于查询代码定义、引用、悬停信息、调用层次等。
+    """
+
+    name = "lsp"
+    description = """Interact with Language Server Protocol (LSP) servers to get code intelligence features.
+
+Supported operations:
+- goToDefinition: Find where a symbol is defined
+- findReferences: Find all references to a symbol
+- hover: Get hover information (documentation, type info) for a symbol
+- documentSymbol: Get all symbols (functions, classes, variables) in a document
+- workspaceSymbol: Search for symbols across the entire workspace
+- goToImplementation: Find implementations of an interface or abstract method
+- prepareCallHierarchy: Get call hierarchy item at a position (functions/methods)
+- incomingCalls: Find all functions/methods that call the function at a position
+- outgoingCalls: Find all functions/methods called by the function at a position
+
+All operations require:
+- filePath: The file to operate on
+- line: The line number (1-based, as shown in editors)
+- character: The character offset (1-based, as shown in editors)
+
+Note: LSP servers must be configured for the file type. If no server is available, an error will be returned."""
+    input_model = LspToolInput
+
+    def is_read_only(self, arguments: LspToolInput) -> bool:
+        del arguments
+        return True
+
+    async def execute(self, arguments: LspToolInput, context: ToolExecutionContext) -> ToolResult:
+        # 获取工作区根目录
+        root = context.cwd.resolve()
+
+        # workspace_symbol 操作 — 不需要 file_path
+        if arguments.operation == "workspace_symbol":
+            results = workspace_symbol_search(root, arguments.query or "")
+            return ToolResult(output=_format_symbol_locations(results, root))
+
+        # 解析文件路径（后续操作都需要）
+        assert arguments.file_path is not None  # 已在上述验证
+        file_path = _resolve_path(root, arguments.file_path)
+        if not file_path.exists():
+            return ToolResult(output=f"File not found: {file_path}", is_error=True)
+        if file_path.suffix != ".py":
+            return ToolResult(output="The lsp tool currently supports Python files only.", is_error=True)
+
+        # document_symbol
+        if arguments.operation == "document_symbol":
+            return ToolResult(output=_format_symbol_locations(list_document_symbols(file_path), root))
+
+        # go_to_definition
+        if arguments.operation == "go_to_definition":
+            results = go_to_definition(
+                root=root,
+                file_path=file_path,
+                symbol=arguments.symbol,
+                line=arguments.line,
+                character=arguments.character,
+            )
+            return ToolResult(output=_format_symbol_locations(results, root))
+
+        # find_references
+        if arguments.operation == "find_references":
+            results = find_references(
+                root=root,
+                file_path=file_path,
+                symbol=arguments.symbol,
+                line=arguments.line,
+                character=arguments.character,
+            )
+            return ToolResult(output=_format_references(results, root))
+
+        # hover
+        if arguments.operation == "hover":
+            result = hover(
+                root=root,
+                file_path=file_path,
+                symbol=arguments.symbol,
+                line=arguments.line,
+                character=arguments.character,
+            )
+            if result is None:
+                return ToolResult(output="(no hover result)")
+            parts = [
+                f"{result.kind} {result.name}",
+                f"path: {_display_path(result.path, root)}:{result.line}:{result.character}",
+            ]
+            if result.signature:
+                parts.append(f"signature: {result.signature}")
+            if result.docstring:
+                parts.append(f"docstring: {result.docstring.strip()}")
+            return ToolResult(output="\n".join(parts))
+
+        # go_to_implementation
+        if arguments.operation == "go_to_implementation":
+            results = go_to_implementation(
+                root=root,
+                file_path=file_path,
+                symbol=arguments.symbol,
+                line=arguments.line,
+                character=arguments.character,
+            )
+            return ToolResult(output=_format_symbol_locations(results, root))
+
+        # prepare_call_hierarchy
+        if arguments.operation == "prepare_call_hierarchy":
+            result = prepare_call_hierarchy(
+                root=root,
+                file_path=file_path,
+                symbol=arguments.symbol,
+                line=arguments.line,
+                character=arguments.character,
+            )
+            if result is None:
+                return ToolResult(output="(no call hierarchy item)")
+            return ToolResult(output=_format_hierarchy_item(result, root))
+
+        # incoming_calls
+        if arguments.operation == "incoming_calls":
+            results = incoming_calls(
+                root=root,
+                file_path=file_path,
+                symbol=arguments.symbol,
+                line=arguments.line,
+                character=arguments.character,
+            )
+            return ToolResult(output=_format_incoming_calls(results, root))
+
+        # outgoing_calls
+        if arguments.operation == "outgoing_calls":
+            results = outgoing_calls(
+                root=root,
+                file_path=file_path,
+                symbol=arguments.symbol,
+                line=arguments.line,
+                character=arguments.character,
+            )
+            return ToolResult(output=_format_outgoing_calls(results, root))
+
+
+# ---------------------------------------------------------------------------
+# 路径辅助函数
+# ---------------------------------------------------------------------------
+
+
+def _resolve_path(base: Path, candidate: str) -> Path:
+    """解析相对路径为绝对路径。"""
+    path = Path(candidate).expanduser()
+    if not path.is_absolute():
+        path = base / path
+    return path.resolve()
+
+
+def _display_path(path: Path, root: Path) -> str:
+    """将路径显示为相对于根目录的路径。"""
+    try:
+        return str(path.relative_to(root))
+    except ValueError:
+        return str(path)
+
+
+# ---------------------------------------------------------------------------
+# 结果格式化函数
+# ---------------------------------------------------------------------------
+
+
+def _format_symbol_locations(results, root: Path) -> str:
+    """格式化符号位置结果。"""
+    if not results:
+        return "(no results)"
+    lines = []
+    for item in results:
+        lines.append(
+            f"{item.kind} {item.name} - {_display_path(item.path, root)}:{item.line}:{item.character}"
+        )
+        if item.signature:
+            lines.append(f"  signature: {item.signature}")
+        if item.docstring:
+            lines.append(f"  docstring: {item.docstring.strip()}")
+    return "\n".join(lines)
+
+
+def _format_references(results: list[tuple[Path, int, str]], root: Path) -> str:
+    """格式化引用结果。"""
+    if not results:
+        return "(no results)"
+    return "\n".join(f"{_display_path(path, root)}:{line}:{text}" for path, line, text in results)
+
+
+def _format_hierarchy_item(item, root: Path) -> str:
+    """格式化调用层次项。"""
+    parts = [
+        f"{item.kind} {item.name}",
+        f"path: {_display_path(item.path, root)}:{item.line}:{item.character}",
+    ]
+    if item.signature:
+        parts.append(f"signature: {item.signature}")
+    if item.docstring:
+        parts.append(f"docstring: {item.docstring.strip()}")
+    return "\n".join(parts)
+
+
+def _format_incoming_calls(results: list[tuple[Path, int, str, str]], root: Path) -> str:
+    """格式化入向调用结果。"""
+    if not results:
+        return "(no incoming calls)"
+    lines = []
+    for path, line, caller, text in results:
+        lines.append(f"{_display_path(path, root)}:{line} [{caller}] {text}")
+    return "\n".join(lines)
+
+
+def _format_outgoing_calls(results: list[tuple[str, Path, int]], root: Path) -> str:
+    """格式化出向调用结果。"""
+    if not results:
+        return "(no outgoing calls)"
+    lines = []
+    for name, path, line in results:
+        if path != Path() and line > 0:
+            lines.append(f"{name} -> {_display_path(path, root)}:{line}")
+        else:
+            lines.append(f"{name} -> (definition not found)")
+    return "\n".join(lines)

illusion/tools/mcp_auth_tool.py

@@ -0,0 +1,100 @@
+"""
+MCP 认证配置工具
+================
+
+本模块提供更新 MCP 认证配置的功能。
+
+主要组件：
+    - McpAuthTool: 配置 MCP 服务器认证的工具
+
+使用示例：
+    >>> from illusion.tools import McpAuthTool
+    >>> tool = McpAuthTool()
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from illusion.config.settings import load_settings, save_settings
+from illusion.mcp.types import McpHttpServerConfig, McpStdioServerConfig, McpWebSocketServerConfig
+from illusion.tools.base import BaseTool, ToolExecutionContext, ToolResult
+
+
+class McpAuthToolInput(BaseModel):
+    """MCP 认证更新参数。
+
+    属性：
+        server_name: 配置的 MCP 服务器名称
+        mode: 认证模式：bearer、header 或 env
+        value: 要保存的密钥值
+        key: 可选的 header 或 env 键覆盖
+    """
+
+    server_name: str = Field(description="Configured MCP server name")
+    mode: str = Field(description="Auth mode: bearer, header, or env")
+    value: str = Field(description="Secret value to persist")
+    key: str | None = Field(default=None, description="Header or env key override")
+
+
+class McpAuthTool(BaseTool):
+    """为服务器持久化 MCP 认证设置。
+
+    用于配置 MCP 服务器的认证信息。
+    """
+
+    name = "mcp_auth"
+    description = "Configure auth for an MCP server and reconnect all active sessions when possible."
+    input_model = McpAuthToolInput
+
+    async def execute(self, arguments: McpAuthToolInput, context: ToolExecutionContext) -> ToolResult:
+        # 加载设置
+        settings = load_settings()
+        mcp_manager = context.metadata.get("mcp_manager")
+        # 尝试从设置或 mcp_manager 获取服务器配置
+        config = settings.mcp_servers.get(arguments.server_name)
+        if config is None and mcp_manager is not None:
+            getter = getattr(mcp_manager, "get_server_config", None)
+            if callable(getter):
+                config = getter(arguments.server_name)
+        if config is None:
+            return ToolResult(output=f"Unknown MCP server: {arguments.server_name}", is_error=True)
+
+        # 根据服务器类型处理认证
+        if isinstance(config, McpStdioServerConfig):
+            # stdio 服务器支持 env 或 bearer 模式
+            if arguments.mode not in {"env", "bearer"}:
+                return ToolResult(output="stdio MCP auth supports env or bearer modes", is_error=True)
+            env_key = arguments.key or "MCP_AUTH_TOKEN"
+            env = dict(config.env or {})
+            env[env_key] = f"Bearer {arguments.value}" if arguments.mode == "bearer" else arguments.value
+            updated = config.model_copy(update={"env": env})
+        elif isinstance(config, (McpHttpServerConfig, McpWebSocketServerConfig)):
+            # http/ws 服务器支持 header 或 bearer 模式
+            if arguments.mode not in {"header", "bearer"}:
+                return ToolResult(output="http/ws MCP auth supports header or bearer modes", is_error=True)
+            header_key = arguments.key or "Authorization"
+            headers = dict(config.headers)
+            headers[header_key] = (
+                f"Bearer {arguments.value}" if arguments.mode == "bearer" else arguments.value
+            )
+            updated = config.model_copy(update={"headers": headers})
+        else:
+            return ToolResult(output="Unsupported MCP server config type", is_error=True)
+
+        # 保存设置
+        settings.mcp_servers[arguments.server_name] = updated
+        save_settings(settings)
+
+        # 尝试重新连接
+        if mcp_manager is not None:
+            try:
+                mcp_manager.update_server_config(arguments.server_name, updated)
+                await mcp_manager.reconnect_all()
+            except Exception as exc:  # 防御性处理
+                return ToolResult(
+                    output=f"Saved MCP auth for {arguments.server_name}, but reconnect failed: {exc}",
+                    is_error=True,
+                )
+
+        return ToolResult(output=f"Saved MCP auth for {arguments.server_name}")

illusion/tools/mcp_tool.py

@@ -0,0 +1,75 @@
+"""
+MCP 工具适配器
+=============
+
+本模块提供将 MCP（Model Context Protocol）工具暴露为普通 IllusionCode 工具的功能。
+
+主要组件：
+    - McpToolAdapter: 将一个 MCP 工具作为普通工具暴露
+
+使用示例：
+    >>> from illusion.tools.mcp_tool import McpToolAdapter
+"""
+
+from __future__ import annotations
+
+import re
+
+from pydantic import BaseModel, Field, create_model
+
+from illusion.mcp.client import McpClientManager
+from illusion.mcp.types import McpToolInfo
+from illusion.tools.base import BaseTool, ToolExecutionContext, ToolResult
+
+
+class McpToolAdapter(BaseTool):
+    """将一个 MCP 工具作为普通 IllusionCode 工具暴露。
+
+    用于集成 MCP 服务器提供的工具。
+    """
+
+    def __init__(self, manager: McpClientManager, tool_info: McpToolInfo) -> None:
+        self._manager = manager
+        self._tool_info = tool_info
+        # 清理服务器和工具名称以形成有效的工具名
+        server_segment = _sanitize_tool_segment(tool_info.server_name)
+        tool_segment = _sanitize_tool_segment(tool_info.name)
+        self.name = f"mcp__{server_segment}__{tool_segment}"
+        self.description = tool_info.description or f"MCP tool {tool_info.name}"
+        self.input_model = _input_model_from_schema(self.name, tool_info.input_schema)
+
+    async def execute(self, arguments: BaseModel, context: ToolExecutionContext) -> ToolResult:
+        del context
+        # 调用 MCP 工具
+        output = await self._manager.call_tool(
+            self._tool_info.server_name,
+            self._tool_info.name,
+            arguments.model_dump(mode="json"),
+        )
+        return ToolResult(output=output)
+
+
+def _input_model_from_schema(tool_name: str, schema: dict[str, object]) -> type[BaseModel]:
+    """从 JSON schema 创建 Pydantic 输入模型。"""
+    properties = schema.get("properties", {})
+    if not isinstance(properties, dict):
+        return create_model(f"{tool_name.title()}Input")
+
+    fields = {}
+    required = set(schema.get("required", [])) if isinstance(schema.get("required", []), list) else set()
+    for key in properties:
+        default = ... if key in required else None
+        fields[key] = (object | None, Field(default=default))
+    return create_model(f"{tool_name.title().replace('-', '_')}Input", **fields)
+
+
+def _sanitize_tool_segment(value: str) -> str:
+    """清理工具段以形成有效的标识符。"""
+    # 移除非字母数字字符
+    sanitized = re.sub(r"[^A-Za-z0-9_-]", "_", value)
+    if not sanitized:
+        return "tool"
+    # 确保以字母开头
+    if not sanitized[0].isalpha():
+        return f"mcp_{sanitized}"
+    return sanitized