xg-cli 1.0__py3-none-any.whl

xg/mcp/models.py

@@ -0,0 +1,86 @@
+"""Data models shared by the MCP configuration and runtime layers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Literal, Mapping
+
+
+McpServerStatus = Literal[
+    "disabled",
+    "starting",
+    "ready",
+    "refreshing",
+    "unavailable",
+    "restarting",
+    "stopping",
+]
+
+
+@dataclass(frozen=True)
+class McpServerConfig:
+    name: str
+    transport: Literal["stdio", "streamable_http"]
+    enabled: bool = True
+    command: str | None = None
+    args: tuple[str, ...] = ()
+    cwd: str | None = None
+    env: Mapping[str, str] = field(default_factory=dict)
+    url: str | None = None
+    headers: Mapping[str, str] = field(default_factory=dict)
+    startup_timeout: float = 15.0
+    request_timeout: float = 120.0
+    shutdown_timeout: float = 5.0
+    max_output_chars: int = 20_000
+    hitl: Literal["default", "never", "confirm", "always"] = "default"
+    tool_overrides: Mapping[str, str] = field(default_factory=dict)
+    max_tools: int = 256
+    max_resources: int = 512
+    max_message_bytes: int = 2_097_152
+    resource_max_chars: int = 32_000
+    log_lines: int = 200
+
+
+@dataclass(frozen=True)
+class McpToolSpec:
+    server: str
+    remote_name: str
+    exposed_name: str
+    description: str
+    input_schema: dict
+    annotations: dict = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class McpResource:
+    server: str
+    uri: str
+    name: str
+    description: str = ""
+    mime_type: str | None = None
+    size: int | None = None
+    metadata: dict = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class McpServerSnapshot:
+    name: str
+    transport: str
+    status: McpServerStatus
+    protocol_version: str | None = None
+    tool_count: int = 0
+    resource_count: int = 0
+    last_error: str = ""
+    started_at: datetime | None = None
+    last_refresh_at: datetime | None = None
+
+
+@dataclass(frozen=True)
+class McpEvent:
+    kind: str
+    server: str = ""
+    text: str = ""
+    tool_count: int | None = None
+    resource_count: int | None = None
+

xg/mcp/protocol.py

@@ -0,0 +1,62 @@
+"""MCP JSON-RPC constants, validation and public exceptions."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+SUPPORTED_PROTOCOL_VERSIONS = ("2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05")
+DEFAULT_PROTOCOL_VERSION = SUPPORTED_PROTOCOL_VERSIONS[0]
+
+
+class McpError(Exception):
+    """Base MCP error with a user-safe message."""
+
+
+class McpConfigError(McpError):
+    pass
+
+
+class McpProtocolError(McpError):
+    pass
+
+
+class McpUnavailableError(McpError):
+    pass
+
+
+class McpRequestError(McpError):
+    def __init__(self, code: int | str, message: str, data: Any = None) -> None:
+        self.code = code
+        self.data = data
+        super().__init__(f"MCP error {code}: {message}")
+
+
+def request_message(request_id: int, method: str, params: dict | None = None) -> dict:
+    message: dict[str, Any] = {"jsonrpc": "2.0", "id": request_id, "method": method}
+    if params is not None:
+        message["params"] = params
+    return message
+
+
+def notification_message(method: str, params: dict | None = None) -> dict:
+    message: dict[str, Any] = {"jsonrpc": "2.0", "method": method}
+    if params is not None:
+        message["params"] = params
+    return message
+
+
+def parse_result(message: dict, expected_id: int | str | None = None) -> dict:
+    if not isinstance(message, dict) or message.get("jsonrpc") != "2.0":
+        raise McpProtocolError("非法 JSON-RPC envelope")
+    if expected_id is not None and message.get("id") != expected_id:
+        raise McpProtocolError("JSON-RPC response id 不匹配")
+    error = message.get("error")
+    if isinstance(error, dict):
+        raise McpRequestError(error.get("code", -32000), str(error.get("message", "unknown error")), error.get("data"))
+    result = message.get("result", {})
+    if result is None:
+        return {}
+    if not isinstance(result, dict):
+        raise McpProtocolError("JSON-RPC result 必须是对象")
+    return result

xg/mcp/resources.py

@@ -0,0 +1,72 @@
+"""MCP resource decoding and explicit @server:uri reference parsing."""
+
+from __future__ import annotations
+
+import base64
+import re
+from dataclasses import dataclass
+from urllib.parse import urlsplit, urlunsplit
+
+
+_REFERENCE_RE = re.compile(
+    r"@(?P<server>[A-Za-z0-9_-]{1,32}):(?P<uri>[^\s，。；！？,;!?\)\]\}]+)"
+)
+_TRAILING = ".,;!?，。；！？)]}"
+
+
+@dataclass(frozen=True)
+class ResourceReference:
+    server: str
+    uri: str
+    token: str
+
+
+def find_resource_references(text: str, limit: int = 8) -> list[ResourceReference]:
+    found: list[ResourceReference] = []
+    for match in _REFERENCE_RE.finditer(text):
+        uri = match.group("uri").rstrip(_TRAILING)
+        if not uri or ":" not in uri:
+            continue
+        token = f"@{match.group('server')}:{uri}"
+        found.append(ResourceReference(match.group("server"), uri, token))
+        if len(found) >= limit:
+            break
+    return found
+
+
+def decode_resource_contents(result: dict, max_chars: int) -> tuple[str, bool]:
+    contents = result.get("contents", [])
+    if not isinstance(contents, list):
+        return "", False
+    parts: list[str] = []
+    binary_seen = False
+    for item in contents:
+        if not isinstance(item, dict):
+            continue
+        if isinstance(item.get("text"), str):
+            parts.append(item["text"])
+        elif isinstance(item.get("blob"), str):
+            binary_seen = True
+            try:
+                size = len(base64.b64decode(item["blob"], validate=False))
+            except Exception:
+                size = len(item["blob"])
+            parts.append(f"[二进制 MCP resource，约 {size} bytes，未内联]")
+    text = "\n\n".join(parts)
+    truncated = len(text) > max_chars
+    if truncated:
+        text = text[:max_chars] + f"\n... (资源已截断，原始长度 {len(text)} 字符)"
+    return text, truncated or binary_seen
+
+
+def redact_uri(uri: str) -> str:
+    try:
+        parsed = urlsplit(uri)
+    except ValueError:
+        return uri.split("?", 1)[0]
+    if not parsed.scheme:
+        return uri.split("?", 1)[0]
+    host = parsed.hostname or ""
+    if parsed.port:
+        host = f"{host}:{parsed.port}"
+    return urlunsplit((parsed.scheme, host, parsed.path, "", ""))

xg/mcp/schema.py

@@ -0,0 +1,137 @@
+"""Sanitize MCP input schemas for OpenAI-compatible tool definitions."""
+
+from __future__ import annotations
+
+import copy
+import re
+from typing import Any
+
+
+_NAME_RE = re.compile(r"[^A-Za-z0-9_-]+")
+_ALLOWED = {
+    "type", "properties", "required", "items", "description", "enum", "default",
+    "minimum", "maximum", "minLength", "maxLength", "minItems", "maxItems",
+    "additionalProperties", "format",
+}
+
+
+def exposed_tool_name(server: str, remote_name: str, max_length: int = 128) -> str:
+    clean = _NAME_RE.sub("_", remote_name).strip("_") or "tool"
+    return f"mcp__{server}__{clean}"[:max_length]
+
+
+def sanitize_description(value: Any, max_chars: int = 4000) -> str:
+    text = " ".join(str(value or "").split())
+    if len(text) <= max_chars:
+        return text
+    return text[: max(0, max_chars - 8)] + "…[截断]"
+
+
+def sanitize_schema(schema: Any, *, max_depth: int = 8, max_properties: int = 128) -> tuple[dict, list[str]]:
+    warnings: list[str] = []
+    root = copy.deepcopy(schema) if isinstance(schema, dict) else {}
+    definitions = root.get("$defs") or root.get("definitions") or {}
+    resolving: set[str] = set()
+
+    def resolve_ref(ref: str) -> dict | None:
+        if not ref.startswith("#/") or ref in resolving:
+            return None
+        node: Any = root
+        try:
+            for part in ref[2:].split("/"):
+                part = part.replace("~1", "/").replace("~0", "~")
+                node = node[part]
+        except (KeyError, TypeError):
+            return None
+        if not isinstance(node, dict):
+            return None
+        resolving.add(ref)
+        try:
+            return clean(node, 1)
+        finally:
+            resolving.discard(ref)
+
+    def merge_all_of(items: list, depth: int) -> dict:
+        merged: dict[str, Any] = {"type": "object", "properties": {}, "required": []}
+        for item in items:
+            part = clean(item, depth + 1)
+            if part.get("type") != "object":
+                warnings.append("allOf 含非 object，已降级")
+                continue
+            merged["properties"].update(part.get("properties", {}))
+            merged["required"].extend(part.get("required", []))
+        merged["required"] = list(dict.fromkeys(merged["required"]))
+        return merged
+
+    def clean(node: Any, depth: int) -> dict:
+        if depth > max_depth or not isinstance(node, dict):
+            warnings.append("schema 深度超限，已降级为 string")
+            return {"type": "string"}
+        if isinstance(node.get("$ref"), str):
+            resolved = resolve_ref(node["$ref"])
+            if resolved is None:
+                warnings.append(f"无法解析 $ref: {node['$ref']}")
+                return {"type": "string", "description": "原 schema reference 无法展开"}
+            return resolved
+        if isinstance(node.get("allOf"), list):
+            merged = merge_all_of(node["allOf"], depth)
+            if node.get("description"):
+                merged["description"] = sanitize_description(node["description"])
+            return merged
+        union = node.get("anyOf") or node.get("oneOf")
+        if isinstance(union, list) and union:
+            options = [clean(item, depth + 1) for item in union if isinstance(item, dict)]
+            non_null = [item for item in options if item.get("type") != "null"]
+            if len(non_null) == 1:
+                chosen = non_null[0]
+                if node.get("description"):
+                    chosen["description"] = sanitize_description(node["description"])
+                return chosen
+            types = {str(item.get("type")) for item in non_null if item.get("type")}
+            if len(types) == 1 and non_null:
+                return non_null[0]
+            warnings.append("anyOf/oneOf 无法无损表达，已降级为 string")
+            return {"type": "string", "description": sanitize_description(node.get("description") or "联合类型参数")}
+
+        inferred = node.get("type")
+        if isinstance(inferred, list):
+            values = [value for value in inferred if value != "null"]
+            inferred = values[0] if len(values) == 1 else "string"
+        if not isinstance(inferred, str):
+            inferred = "object" if isinstance(node.get("properties"), dict) else "string"
+        if inferred not in {"object", "array", "string", "integer", "number", "boolean", "null"}:
+            inferred = "string"
+        out: dict[str, Any] = {"type": inferred}
+        for key in _ALLOWED - {"type", "properties", "required", "items", "description", "enum"}:
+            if key in node and isinstance(node[key], (str, int, float, bool)):
+                out[key] = node[key]
+        if node.get("description"):
+            out["description"] = sanitize_description(node["description"])
+        if isinstance(node.get("enum"), list):
+            out["enum"] = node["enum"][:100]
+            if len(node["enum"]) > 100:
+                warnings.append("enum 超过 100 项，已截断")
+        if inferred == "object":
+            props = node.get("properties", {})
+            if not isinstance(props, dict):
+                props = {}
+            selected = list(props.items())[:max_properties]
+            if len(props) > max_properties:
+                warnings.append("properties 超过上限，已截断")
+            out["properties"] = {str(name): clean(value, depth + 1) for name, value in selected}
+            required = node.get("required", [])
+            if isinstance(required, list):
+                out["required"] = [str(name) for name in required if str(name) in out["properties"]]
+            if "additionalProperties" in node and isinstance(node["additionalProperties"], bool):
+                out["additionalProperties"] = node["additionalProperties"]
+        elif inferred == "array":
+            out["items"] = clean(node.get("items", {}), depth + 1)
+        return out
+
+    cleaned = clean(root, 0)
+    if cleaned.get("type") != "object":
+        warnings.append("工具 inputSchema 顶层不是 object，已包装为空 object")
+        cleaned = {"type": "object", "properties": {}}
+    cleaned.setdefault("properties", {})
+    return cleaned, warnings
+

xg/mcp/stdio.py

@@ -0,0 +1,210 @@
+"""MCP stdio transport implemented with asyncio subprocesses."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from contextlib import suppress
+from typing import Any
+
+from xg.mcp.models import McpServerConfig
+from xg.mcp.protocol import McpProtocolError, McpRequestError, McpUnavailableError, notification_message, request_message
+from xg.mcp.transport import McpTransport
+
+
+class StdioTransport(McpTransport):
+    def __init__(self, config: McpServerConfig) -> None:
+        super().__init__(log_lines=config.log_lines)
+        self.config = config
+        self.process: asyncio.subprocess.Process | None = None
+        self._reader_task: asyncio.Task | None = None
+        self._stderr_task: asyncio.Task | None = None
+        self._wait_task: asyncio.Task | None = None
+        self._pending: dict[int, asyncio.Future[dict]] = {}
+        self._next_id = 1
+        self._write_lock = asyncio.Lock()
+        self._closing = False
+        self._disconnect_notified = False
+
+    async def connect(self) -> None:
+        if self.process is not None and self.process.returncode is None:
+            return
+        if not self.config.command:
+            raise McpUnavailableError("stdio Server 缺少 command")
+        child_env = os.environ.copy()
+        child_env.update(self.config.env)
+        try:
+            self.process = await asyncio.create_subprocess_exec(
+                self.config.command,
+                *self.config.args,
+                cwd=self.config.cwd,
+                env=child_env,
+                stdin=asyncio.subprocess.PIPE,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                limit=self.config.max_message_bytes + 1,
+            )
+        except (OSError, ValueError) as exc:
+            raise McpUnavailableError(f"无法启动 stdio Server: {exc}") from exc
+        self._closing = False
+        self._disconnect_notified = False
+        self._reader_task = asyncio.create_task(self._read_stdout(), name=f"mcp-{self.config.name}-stdout")
+        self._stderr_task = asyncio.create_task(self._read_stderr(), name=f"mcp-{self.config.name}-stderr")
+        self._wait_task = asyncio.create_task(self._watch_process(), name=f"mcp-{self.config.name}-wait")
+
+    async def _send(self, message: dict) -> None:
+        process = self.process
+        if process is None or process.returncode is not None or process.stdin is None:
+            raise McpUnavailableError("MCP stdio Server 未连接")
+        payload = json.dumps(message, ensure_ascii=False, separators=(",", ":")).encode("utf-8") + b"\n"
+        if len(payload) > self.config.max_message_bytes:
+            raise McpProtocolError("JSON-RPC 请求超过消息上限")
+        async with self._write_lock:
+            process.stdin.write(payload)
+            try:
+                await process.stdin.drain()
+            except (BrokenPipeError, ConnectionResetError) as exc:
+                raise McpUnavailableError("MCP stdio 连接已断开") from exc
+
+    async def request(self, method: str, params: dict | None = None) -> dict:
+        request_id = self._next_id
+        self._next_id += 1
+        future = asyncio.get_running_loop().create_future()
+        self._pending[request_id] = future
+        try:
+            await self._send(request_message(request_id, method, params))
+            message = await asyncio.wait_for(future, timeout=self.config.request_timeout)
+        except asyncio.TimeoutError as exc:
+            raise McpUnavailableError(f"MCP 请求超时: {method}") from exc
+        finally:
+            self._pending.pop(request_id, None)
+        error = message.get("error")
+        if isinstance(error, dict):
+            raise McpRequestError(error.get("code", -32000), str(error.get("message", "unknown error")), error.get("data"))
+        result = message.get("result", {})
+        if result is None:
+            return {}
+        if not isinstance(result, dict):
+            raise McpProtocolError("JSON-RPC result 必须是对象")
+        return result
+
+    async def notify(self, method: str, params: dict | None = None) -> None:
+        await self._send(notification_message(method, params))
+
+    async def _read_stdout(self) -> None:
+        process = self.process
+        if process is None or process.stdout is None:
+            return
+        try:
+            while not self._closing:
+                line = await process.stdout.readline()
+                if not line:
+                    break
+                if len(line) > self.config.max_message_bytes:
+                    raise McpProtocolError("MCP stdio 消息超过上限")
+                try:
+                    message = json.loads(line.decode("utf-8"))
+                except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+                    self.log(f"protocol error: invalid JSON ({exc})")
+                    continue
+                if not isinstance(message, dict) or message.get("jsonrpc") != "2.0":
+                    self.log("protocol error: invalid JSON-RPC envelope")
+                    continue
+                if "id" in message and ("result" in message or "error" in message):
+                    future = self._pending.get(message["id"])
+                    if future is not None and not future.done():
+                        future.set_result(message)
+                    continue
+                method = message.get("method")
+                if isinstance(method, str) and "id" not in message:
+                    await self.dispatch_notification(method, message.get("params"))
+                elif isinstance(method, str) and "id" in message:
+                    if method == "ping":
+                        await self._send({"jsonrpc": "2.0", "id": message["id"], "result": {}})
+                    else:
+                        await self._send({
+                            "jsonrpc": "2.0",
+                            "id": message["id"],
+                            "error": {"code": -32601, "message": "Method not found"},
+                        })
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            self.log(f"protocol error: {type(exc).__name__}: {exc}")
+        finally:
+            if not self._closing:
+                error = McpUnavailableError("MCP stdio 连接已关闭")
+                await self._notify_disconnect(error)
+
+    async def _read_stderr(self) -> None:
+        process = self.process
+        if process is None or process.stderr is None:
+            return
+        try:
+            while not self._closing:
+                line = await process.stderr.readline()
+                if not line:
+                    break
+                self.log(line.decode("utf-8", errors="replace"))
+        except asyncio.CancelledError:
+            raise
+
+    async def _watch_process(self) -> None:
+        process = self.process
+        if process is None:
+            return
+        code = await process.wait()
+        if not self._closing:
+            self.log(f"process exited with code {code}")
+            error = McpUnavailableError(f"MCP Server 已退出（code={code}）")
+            await self._notify_disconnect(error)
+
+    async def _notify_disconnect(self, error: Exception) -> None:
+        """Notify the owner once when the child connection is lost.
+
+        Both stdout EOF and process.wait() observe the same child exit. The
+        first observer owns failure propagation; the other observer must not
+        emit a duplicate lifecycle event.
+        """
+        if self._closing or self._disconnect_notified:
+            return
+        self._disconnect_notified = True
+        self._fail_pending(error)
+        await self.dispatch_disconnect(error)
+
+    def _fail_pending(self, error: Exception) -> None:
+        for future in list(self._pending.values()):
+            if not future.done():
+                future.set_exception(error)
+        self._pending.clear()
+
+    async def close(self) -> None:
+        if self._closing:
+            return
+        self._closing = True
+        self._fail_pending(McpUnavailableError("MCP Server 正在关闭"))
+        process = self.process
+        if process is not None and process.stdin is not None:
+            process.stdin.close()
+            with suppress(Exception):
+                await process.stdin.wait_closed()
+        if process is not None and process.returncode is None:
+            try:
+                await asyncio.wait_for(process.wait(), timeout=self.config.shutdown_timeout)
+            except asyncio.TimeoutError:
+                process.terminate()
+                try:
+                    await asyncio.wait_for(process.wait(), timeout=self.config.shutdown_timeout)
+                except asyncio.TimeoutError:
+                    process.kill()
+                    await process.wait()
+        current = asyncio.current_task()
+        for task in (self._reader_task, self._stderr_task, self._wait_task):
+            if task is not None and task is not current and not task.done():
+                task.cancel()
+        for task in (self._reader_task, self._stderr_task, self._wait_task):
+            if task is not None and task is not current:
+                with suppress(asyncio.CancelledError, Exception):
+                    await task
+        self.process = None

xg/mcp/transport.py

@@ -0,0 +1,66 @@
+"""Transport abstraction and common logging helpers."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections import deque
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+
+NotificationHandler = Callable[[str, dict], Awaitable[None] | None]
+DisconnectHandler = Callable[[Exception], Awaitable[None] | None]
+
+
+class McpTransport(ABC):
+    def __init__(self, *, log_lines: int = 200) -> None:
+        self._logs: deque[str] = deque(maxlen=max(1, log_lines))
+        self.notification_handler: NotificationHandler | None = None
+        self.disconnect_handler: DisconnectHandler | None = None
+        self.protocol_version: str | None = None
+
+    def set_protocol_version(self, version: str) -> None:
+        self.protocol_version = version
+
+    def set_notification_handler(self, handler: NotificationHandler | None) -> None:
+        self.notification_handler = handler
+
+    def set_disconnect_handler(self, handler: DisconnectHandler | None) -> None:
+        self.disconnect_handler = handler
+
+    async def dispatch_disconnect(self, error: Exception) -> None:
+        handler = self.disconnect_handler
+        if handler is None:
+            return
+        result = handler(error)
+        if result is not None:
+            await result
+
+    async def dispatch_notification(self, method: str, params: dict | None) -> None:
+        handler = self.notification_handler
+        if handler is None:
+            return
+        result = handler(method, params or {})
+        if result is not None:
+            await result
+
+    def log(self, message: str) -> None:
+        self._logs.append(str(message).replace("\r", "").rstrip("\n"))
+
+    def recent_logs(self, limit: int = 50) -> list[str]:
+        return list(self._logs)[-max(1, limit):]
+
+    @abstractmethod
+    async def connect(self) -> None: ...
+
+    @abstractmethod
+    async def request(self, method: str, params: dict | None = None) -> dict: ...
+
+    @abstractmethod
+    async def notify(self, method: str, params: dict | None = None) -> None: ...
+
+    async def start_notifications(self) -> None:
+        """Start an optional server-initiated notification stream."""
+
+    @abstractmethod
+    async def close(self) -> None: ...

xg/memory/__init__.py

@@ -0,0 +1,15 @@
+"""第五期：项目记忆、长期记忆与上下文压缩。"""
+
+from xg.memory.context import CompressionResult, ConversationContext
+from xg.memory.manager import MemoryManager, SharedSection
+from xg.memory.models import MemoryEntry
+from xg.memory.store import SQLiteMemoryStore
+
+__all__ = [
+    "CompressionResult",
+    "ConversationContext",
+    "MemoryEntry",
+    "MemoryManager",
+    "SharedSection",
+    "SQLiteMemoryStore",
+]