sym-mcp 0.0.0.post1.dev3__py3-none-any.whl

sym_mcp/__init__.py

@@ -0,0 +1,2 @@
+"""sym_mcp package."""
+

sym_mcp/__main__.py

@@ -0,0 +1,6 @@
+from sym_mcp.server import main
+
+
+if __name__ == "__main__":
+    main()
+

sym_mcp/config.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Settings:
+    pool_size: int = 10
+    exec_timeout_sec: float = 3.0
+    memory_limit_mb: int = 150
+    queue_wait_sec: float = 2.0
+    log_level: str = "INFO"
+    max_output_chars: int = 1200
+    hint_level: str = "medium"
+
+
+def load_settings() -> Settings:
+    return Settings(
+        pool_size=int(os.getenv("SYMMCP_POOL_SIZE", "10")),
+        exec_timeout_sec=float(os.getenv("SYMMCP_EXEC_TIMEOUT_SEC", "3")),
+        memory_limit_mb=int(os.getenv("SYMMCP_MEMORY_LIMIT_MB", "150")),
+        queue_wait_sec=float(os.getenv("SYMMCP_QUEUE_WAIT_SEC", "2")),
+        log_level=os.getenv("SYMMCP_LOG_LEVEL", "INFO"),
+        max_output_chars=max(100, int(os.getenv("SYMMCP_MAX_OUTPUT_CHARS", "1200"))),
+        hint_level=os.getenv("SYMMCP_HINT_LEVEL", "medium"),
+    )

sym_mcp/errors/__init__.py

@@ -0,0 +1,2 @@
+"""Error parsing helpers."""
+

sym_mcp/errors/parser.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import re
+
+DEFAULT_HINT_LEVEL = "medium"
+
+
+@dataclass(frozen=True)
+class ParsedError:
+    code: str
+    line: int | None
+    err: str
+    hint: str
+
+
+def parse_traceback(tb_text: str, hint_level: str = DEFAULT_HINT_LEVEL) -> ParsedError:
+    line = _extract_user_line(tb_text)
+    err_text = _extract_error_text(tb_text)
+    code = _classify_error(err_text)
+    hint = build_hint(code, hint_level=hint_level)
+    return ParsedError(code=code, line=line, err=err_text, hint=hint)
+
+
+def parse_guard_message(message: str, hint_level: str = DEFAULT_HINT_LEVEL) -> ParsedError:
+    if message.startswith("语法错误"):
+        code = "E_SYNTAX"
+        line = _extract_line_from_guard(message)
+        err = message
+    else:
+        code = "E_AST_BLOCK"
+        line = _extract_line_from_guard(message)
+        err = message
+    return ParsedError(code=code, line=line, err=err, hint=build_hint(code, hint_level=hint_level))
+
+
+def parse_pool_error(message: str, hint_level: str = DEFAULT_HINT_LEVEL) -> ParsedError:
+    if "超时" in message:
+        code = "E_TIMEOUT"
+    else:
+        code = "E_WORKER"
+    return ParsedError(code=code, line=None, err=message, hint=build_hint(code, hint_level=hint_level))
+
+
+def parse_internal_error(message: str, hint_level: str = DEFAULT_HINT_LEVEL) -> ParsedError:
+    clean = (message or "").strip() or "internal error"
+    return ParsedError(code="E_INTERNAL", line=None, err=clean, hint=build_hint("E_INTERNAL", hint_level=hint_level))
+
+
+def build_hint(code: str, hint_level: str = DEFAULT_HINT_LEVEL) -> str:
+    if hint_level == "none":
+        return ""
+    if hint_level == "short":
+        return "根据错误码与行号最小改动后重试。"
+
+    hints = {
+        "E_AST_BLOCK": "检测到不安全语句。请仅保留 sympy/math 相关计算代码，并移除系统调用后重试。",
+        "E_SYNTAX": "代码存在语法错误。请先修正报错行附近的括号、缩进或符号，再重新执行。",
+        "E_TIMEOUT": "计算超时。请减少计算规模、拆分步骤或先做代数化简后再求解。",
+        "E_MEMORY": "内存不足。请降低矩阵维度/展开规模，避免一次性构造超大对象。",
+        "E_RUNTIME": "运行时错误。请根据行号检查变量类型、零除、未定义变量等问题后重试。",
+        "E_WORKER": "执行进程异常。请保持代码简洁后重试；若持续失败请重新发起调用。",
+        "E_INTERNAL": "服务内部异常。请重试一次；若仍失败请保留输入代码用于排查。",
+    }
+    return hints.get(code, hints["E_RUNTIME"])
+
+
+def _extract_user_line(tb_text: str) -> int | None:
+    if not tb_text.strip():
+        return None
+    lines = tb_text.strip().splitlines()
+    for ln in lines:
+        s = ln.strip()
+        if s.startswith('File "<user_code>", line '):
+            try:
+                return int(s.split("line ")[1].split(",")[0])
+            except (IndexError, ValueError):
+                return None
+    return None
+
+
+def _extract_error_text(tb_text: str) -> str:
+    default = "RuntimeError: 未知错误"
+    if not tb_text.strip():
+        return default
+    tail = tb_text.strip().splitlines()[-1].strip()
+    # 兼容无消息的异常尾行，例如 "MemoryError"
+    if ":" not in tail and re.fullmatch(r"[A-Za-z_]\w*", tail):
+        return f"{tail}: 未知错误"
+    if ":" not in tail:
+        return default
+    etype, msg = tail.split(":", 1)
+    etype = etype.strip() or "RuntimeError"
+    msg = msg.strip() or "未知错误"
+    return f"{etype}: {msg}"
+
+
+def _classify_error(err_text: str) -> str:
+    etype = err_text.split(":", 1)[0]
+    if etype in {"MemoryError"}:
+        return "E_MEMORY"
+    if etype in {"TimeoutError"}:
+        return "E_TIMEOUT"
+    return "E_RUNTIME"
+
+
+def _extract_line_from_guard(message: str) -> int | None:
+    m = re.search(r"第\s*(\d+)\s*行", message)
+    if not m:
+        return None
+    try:
+        return int(m.group(1))
+    except ValueError:
+        return None

sym_mcp/executor/__init__.py

@@ -0,0 +1,2 @@
+"""Execution and worker pool modules."""
+

sym_mcp/executor/pool.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import multiprocessing as mp
+import time
+from dataclasses import dataclass
+from multiprocessing.connection import Connection
+from typing import Any
+
+from sym_mcp.executor.worker_main import run_worker
+
+LOGGER = logging.getLogger(__name__)
+
+
+class WorkerPoolError(RuntimeError):
+    """Errors from worker pool."""
+
+
+@dataclass
+class Worker:
+    worker_id: int
+    process: mp.Process
+    conn: Connection
+
+
+class WorkerPool:
+    def __init__(
+        self,
+        size: int,
+        exec_timeout_sec: float,
+        queue_wait_sec: float,
+        memory_limit_mb: int,
+    ) -> None:
+        self._size = size
+        self._exec_timeout_sec = exec_timeout_sec
+        self._queue_wait_sec = queue_wait_sec
+        self._memory_limit_mb = memory_limit_mb
+        self._ctx = mp.get_context("spawn")
+        self._queue: asyncio.Queue[Worker] = asyncio.Queue(maxsize=size)
+        self._workers: dict[int, Worker] = {}
+        self._lock = asyncio.Lock()
+        self._started = False
+        self.timeout_count = 0
+        self.rebuild_count = 0
+        self.reject_count = 0
+
+    async def start(self) -> None:
+        async with self._lock:
+            if self._started:
+                return
+            for i in range(self._size):
+                worker = self._spawn_worker(worker_id=i)
+                await self._wait_worker_ready(worker)
+                await self._queue.put(worker)
+                self._workers[worker.worker_id] = worker
+            self._started = True
+            LOGGER.info("Worker pool started with size=%s", self._size)
+
+    async def close(self) -> None:
+        async with self._lock:
+            workers = list(self._workers.values())
+            self._workers.clear()
+            self._started = False
+            while not self._queue.empty():
+                self._queue.get_nowait()
+
+        for worker in workers:
+            await self._shutdown_worker(worker)
+
+    async def exec(self, code: str) -> dict[str, Any]:
+        if not self._started:
+            raise WorkerPoolError("worker pool not started")
+        borrow_start = time.perf_counter()
+        try:
+            worker = await asyncio.wait_for(self._queue.get(), timeout=self._queue_wait_sec)
+        except TimeoutError as exc:
+            self.reject_count += 1
+            raise WorkerPoolError("执行排队超时，请稍后重试。") from exc
+        borrow_ms = (time.perf_counter() - borrow_start) * 1000
+        LOGGER.debug("borrow worker=%s cost=%.2fms", worker.worker_id, borrow_ms)
+
+        try:
+            result = await self._exec_on_worker(worker, code)
+        finally:
+            if self._is_alive(worker):
+                await self._queue.put(worker)
+            else:
+                await self._replace_worker(worker)
+        return result
+
+    async def health_check(self) -> None:
+        for worker in list(self._workers.values()):
+            if not self._is_alive(worker):
+                await self._replace_worker(worker)
+                continue
+            try:
+                await self._request(worker, {"cmd": "ping"}, timeout=1.0)
+            except Exception:
+                await self._replace_worker(worker)
+
+    def _spawn_worker(self, worker_id: int) -> Worker:
+        parent_conn, child_conn = self._ctx.Pipe(duplex=True)
+        proc = self._ctx.Process(
+            target=run_worker,
+            args=(child_conn, self._memory_limit_mb, self._exec_timeout_sec),
+            daemon=True,
+            name=f"sym-worker-{worker_id}",
+        )
+        proc.start()
+        child_conn.close()
+        return Worker(worker_id=worker_id, process=proc, conn=parent_conn)
+
+    async def _replace_worker(self, old_worker: Worker) -> None:
+        self.rebuild_count += 1
+        LOGGER.warning("replace dead worker=%s", old_worker.worker_id)
+        await self._shutdown_worker(old_worker)
+        new_worker = self._spawn_worker(old_worker.worker_id)
+        await self._wait_worker_ready(new_worker)
+        self._workers[new_worker.worker_id] = new_worker
+        await self._queue.put(new_worker)
+
+    async def _shutdown_worker(self, worker: Worker) -> None:
+        try:
+            if self._is_alive(worker):
+                await self._request(worker, {"cmd": "stop"}, timeout=0.5)
+        except Exception:
+            pass
+        try:
+            if self._is_alive(worker):
+                worker.process.terminate()
+                await asyncio.to_thread(worker.process.join, 0.5)
+            if self._is_alive(worker):
+                worker.process.kill()
+                await asyncio.to_thread(worker.process.join, 0.5)
+        finally:
+            if worker.worker_id in self._workers and self._workers[worker.worker_id] is worker:
+                self._workers.pop(worker.worker_id, None)
+            try:
+                worker.conn.close()
+            except OSError:
+                pass
+
+    async def _exec_on_worker(self, worker: Worker, code: str) -> dict[str, Any]:
+        start = time.perf_counter()
+        try:
+            result = await self._request(worker, {"cmd": "exec", "code": code}, timeout=self._exec_timeout_sec)
+            exec_ms = (time.perf_counter() - start) * 1000
+            LOGGER.debug("exec worker=%s cost=%.2fms", worker.worker_id, exec_ms)
+            return result
+        except TimeoutError as exc:
+            self.timeout_count += 1
+            LOGGER.warning("worker=%s timeout, terminate", worker.worker_id)
+            await self._kill_worker(worker)
+            raise WorkerPoolError("代码执行超时（超过限制）。") from exc
+        except (EOFError, BrokenPipeError, ConnectionError, OSError) as exc:
+            LOGGER.warning("worker=%s communication broken, terminate", worker.worker_id)
+            await self._kill_worker(worker)
+            raise WorkerPoolError("执行进程异常，请重试。") from exc
+
+    async def _kill_worker(self, worker: Worker) -> None:
+        if self._is_alive(worker):
+            worker.process.terminate()
+            await asyncio.to_thread(worker.process.join, 0.5)
+        if self._is_alive(worker):
+            worker.process.kill()
+            await asyncio.to_thread(worker.process.join, 0.5)
+
+    async def _request(self, worker: Worker, payload: dict[str, Any], timeout: float) -> dict[str, Any]:
+        worker.conn.send(payload)
+        ready = await asyncio.wait_for(asyncio.to_thread(worker.conn.poll, timeout), timeout=timeout + 0.2)
+        if not ready:
+            raise TimeoutError("worker response timeout")
+        return worker.conn.recv()
+
+    async def _wait_worker_ready(self, worker: Worker) -> None:
+        startup_timeout = max(15.0, self._exec_timeout_sec * 5)
+        await self._request(worker, {"cmd": "ping"}, timeout=startup_timeout)
+
+    @staticmethod
+    def _is_alive(worker: Worker) -> bool:
+        return worker.process.is_alive()

sym_mcp/executor/sandbox.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import contextlib
+import io
+import traceback
+from dataclasses import dataclass
+from typing import Any
+
+import math
+import sympy
+
+
+SAFE_BUILTINS = {
+    "abs": abs,
+    "all": all,
+    "any": any,
+    "bool": bool,
+    "dict": dict,
+    "enumerate": enumerate,
+    "float": float,
+    "int": int,
+    "len": len,
+    "list": list,
+    "max": max,
+    "min": min,
+    "pow": pow,
+    "print": print,
+    "range": range,
+    "reversed": reversed,
+    "round": round,
+    "set": set,
+    "sorted": sorted,
+    "str": str,
+    "sum": sum,
+    "tuple": tuple,
+    "zip": zip,
+}
+
+ALLOWED_IMPORT_ROOTS = {"sympy", "math"}
+
+
+@dataclass
+class ExecResult:
+    success: bool
+    stdout: str = ""
+    stderr: str = ""
+    traceback_text: str = ""
+
+
+def build_exec_globals() -> dict[str, Any]:
+    def _safe_import(name: str, globals=None, locals=None, fromlist=(), level=0):
+        root = name.split(".")[0]
+        if root not in ALLOWED_IMPORT_ROOTS:
+            raise ImportError(f"禁止导入模块: {name}")
+        return __import__(name, globals, locals, fromlist, level)
+
+    safe_builtins = dict(SAFE_BUILTINS)
+    safe_builtins["__import__"] = _safe_import
+    return {
+        "__builtins__": safe_builtins,
+        "sympy": sympy,
+        "math": math,
+    }
+
+
+def execute_user_code(code: str) -> ExecResult:
+    glb = build_exec_globals()
+    loc: dict[str, Any] = {}
+    out_buf = io.StringIO()
+    err_buf = io.StringIO()
+    try:
+        compiled = compile(code, "<user_code>", "exec")
+        with contextlib.redirect_stdout(out_buf), contextlib.redirect_stderr(err_buf):
+            exec(compiled, glb, loc)
+    except Exception:
+        return ExecResult(
+            success=False,
+            stdout=out_buf.getvalue(),
+            stderr=err_buf.getvalue(),
+            traceback_text=traceback.format_exc(),
+        )
+    return ExecResult(success=True, stdout=out_buf.getvalue(), stderr=err_buf.getvalue())

sym_mcp/executor/worker_main.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import os
+from multiprocessing.connection import Connection
+from typing import Any
+
+from sym_mcp.executor.sandbox import execute_user_code
+
+try:
+    import resource
+except ImportError:  # pragma: no cover
+    resource = None  # type: ignore[assignment]
+
+
+def run_worker(conn: Connection, memory_limit_mb: int, cpu_limit_sec: float) -> None:
+    _apply_resource_limits(memory_limit_mb=memory_limit_mb, cpu_limit_sec=cpu_limit_sec)
+    _preload_heavy_modules()
+    while True:
+        msg = conn.recv()
+        cmd = msg.get("cmd")
+        if cmd == "ping":
+            conn.send({"ok": True, "pong": True})
+            continue
+        if cmd == "stop":
+            conn.send({"ok": True, "stopped": True})
+            break
+        if cmd != "exec":
+            conn.send({"ok": False, "error": f"unknown command: {cmd}"})
+            continue
+        code = msg.get("code", "")
+        result = execute_user_code(code)
+        conn.send(
+            {
+                "ok": True,
+                "success": result.success,
+                "stdout": result.stdout,
+                "stderr": result.stderr,
+                "traceback": result.traceback_text,
+            }
+        )
+
+
+def _preload_heavy_modules() -> None:
+    import sympy  # noqa: F401
+    import math as _math  # noqa: F401
+
+
+def _apply_resource_limits(memory_limit_mb: int, cpu_limit_sec: float) -> None:
+    if resource is None:
+        return
+
+    memory_bytes = memory_limit_mb * 1024 * 1024
+    for limit_name in ("RLIMIT_AS", "RLIMIT_DATA"):
+        limit = getattr(resource, limit_name, None)
+        if limit is None:
+            continue
+        try:
+            resource.setrlimit(limit, (memory_bytes, memory_bytes))
+        except (OSError, ValueError):
+            pass
+
+    try:
+        os.nice(5)
+    except OSError:
+        pass

sym_mcp/schemas.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class SympyInput(BaseModel):
+    code: str = Field(..., min_length=1, description="包含 Python/SymPy 逻辑并通过 print 输出结果")
+

sym_mcp/security/__init__.py

@@ -0,0 +1,2 @@
+"""Security helpers."""
+

sym_mcp/security/ast_guard.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+
+
+ALLOWED_MODULES = {"sympy", "math"}
+BLOCKED_NAMES = {
+    "eval",
+    "exec",
+    "open",
+    "compile",
+    "input",
+    "globals",
+    "locals",
+    "vars",
+    "getattr",
+    "setattr",
+    "delattr",
+    "__import__",
+    "help",
+    "dir",
+    "type",
+    "super",
+}
+BLOCKED_ROOT_NAMES = {"os", "sys", "subprocess", "pathlib", "socket", "importlib", "builtins"}
+
+ALLOWED_NODES = {
+    ast.Module,
+    ast.Expr,
+    ast.Assign,
+    ast.AugAssign,
+    ast.Name,
+    ast.Load,
+    ast.Store,
+    ast.Call,
+    ast.BinOp,
+    ast.UnaryOp,
+    ast.Compare,
+    ast.BoolOp,
+    ast.If,
+    ast.For,
+    ast.While,
+    ast.Break,
+    ast.Continue,
+    ast.Pass,
+    ast.Return,
+    ast.List,
+    ast.Tuple,
+    ast.Dict,
+    ast.Set,
+    ast.Subscript,
+    ast.Slice,
+    ast.Constant,
+    ast.Import,
+    ast.ImportFrom,
+    ast.alias,
+    ast.FunctionDef,
+    ast.arguments,
+    ast.arg,
+    ast.keyword,
+    ast.IfExp,
+    ast.ListComp,
+    ast.SetComp,
+    ast.DictComp,
+    ast.GeneratorExp,
+    ast.comprehension,
+    ast.Attribute,
+    ast.Try,
+    ast.ExceptHandler,
+    ast.Raise,
+    ast.Assert,
+    ast.Lambda,
+    ast.NamedExpr,
+    ast.JoinedStr,
+    ast.FormattedValue,
+    ast.Delete,
+    ast.With,
+    ast.withitem,
+    ast.Starred,
+    ast.And,
+    ast.Or,
+    ast.Not,
+    ast.Add,
+    ast.Sub,
+    ast.Mult,
+    ast.Div,
+    ast.FloorDiv,
+    ast.Mod,
+    ast.Pow,
+    ast.MatMult,
+    ast.USub,
+    ast.UAdd,
+    ast.Eq,
+    ast.NotEq,
+    ast.Lt,
+    ast.LtE,
+    ast.Gt,
+    ast.GtE,
+    ast.Is,
+    ast.IsNot,
+    ast.In,
+    ast.NotIn,
+}
+
+
+@dataclass(frozen=True)
+class GuardResult:
+    ok: bool
+    message: str = ""
+
+
+class SecurityViolation(ValueError):
+    """Code failed AST security validation."""
+
+
+def validate_code(code: str) -> GuardResult:
+    try:
+        tree = ast.parse(code, mode="exec")
+    except SyntaxError as exc:
+        return GuardResult(ok=False, message=f"语法错误: 第 {exc.lineno} 行, {exc.msg}")
+
+    try:
+        _AstValidator().visit(tree)
+    except SecurityViolation as exc:
+        return GuardResult(ok=False, message=str(exc))
+
+    return GuardResult(ok=True)
+
+
+class _AstValidator(ast.NodeVisitor):
+    def generic_visit(self, node: ast.AST) -> None:
+        if type(node) not in ALLOWED_NODES:
+            raise SecurityViolation(f"安全拦截: 不允许的语法节点 `{type(node).__name__}`。")
+        super().generic_visit(node)
+
+    def visit_Import(self, node: ast.Import) -> None:
+        for alias in node.names:
+            root = alias.name.split(".")[0]
+            if root not in ALLOWED_MODULES:
+                raise SecurityViolation(f"安全拦截: 禁止导入模块 `{alias.name}`。")
+        self.generic_visit(node)
+
+    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
+        module = (node.module or "").split(".")[0]
+        if module not in ALLOWED_MODULES:
+            raise SecurityViolation(f"安全拦截: 禁止从模块 `{node.module}` 导入。")
+        self.generic_visit(node)
+
+    def visit_Name(self, node: ast.Name) -> None:
+        name = node.id
+        self._check_identifier(name, node.lineno)
+        if name in BLOCKED_ROOT_NAMES:
+            raise SecurityViolation(f"安全拦截: 第 {node.lineno} 行禁止访问 `{name}`。")
+        self.generic_visit(node)
+
+    def visit_Attribute(self, node: ast.Attribute) -> None:
+        self._check_identifier(node.attr, node.lineno)
+        root = _root_name(node)
+        if root in BLOCKED_ROOT_NAMES:
+            raise SecurityViolation(f"安全拦截: 第 {node.lineno} 行禁止访问 `{root}`。")
+        self.generic_visit(node)
+
+    def visit_Call(self, node: ast.Call) -> None:
+        func_name = _callable_name(node.func)
+        if func_name and func_name in BLOCKED_NAMES:
+            raise SecurityViolation(f"安全拦截: 第 {node.lineno} 行禁止调用 `{func_name}`。")
+        self.generic_visit(node)
+
+    @staticmethod
+    def _check_identifier(name: str, lineno: int) -> None:
+        if "__" in name:
+            raise SecurityViolation(f"安全拦截: 第 {lineno} 行出现双下划线标识符。")
+
+
+def _root_name(node: ast.AST) -> str | None:
+    cur = node
+    while isinstance(cur, ast.Attribute):
+        cur = cur.value
+    if isinstance(cur, ast.Name):
+        return cur.id
+    return None
+
+
+def _callable_name(node: ast.AST) -> str | None:
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return node.attr
+    return None

sym_mcp/server.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Callable, Optional
+
+try:
+    from fastmcp import FastMCP
+except ImportError:  # pragma: no cover
+
+    class FastMCP:  # type: ignore[override]
+        def __init__(self, _: str) -> None:
+            self._tools: dict[str, Callable] = {}
+
+        def tool(self, name: str):
+            def decorator(func: Callable):
+                self._tools[name] = func
+                return func
+
+            return decorator
+
+        def run(self) -> None:
+            raise RuntimeError("fastmcp 未安装，无法启动 MCP 服务。")
+
+from sym_mcp.config import Settings, load_settings
+from sym_mcp.errors.parser import (
+    parse_guard_message,
+    parse_internal_error,
+    parse_pool_error,
+    parse_traceback,
+)
+from sym_mcp.executor.pool import WorkerPool, WorkerPoolError
+from sym_mcp.security.ast_guard import validate_code
+
+LOGGER = logging.getLogger(__name__)
+
+settings: Settings = load_settings()
+logging.basicConfig(level=getattr(logging, settings.log_level.upper(), logging.INFO))
+
+mcp = FastMCP("SymPy Sandbox MCP")
+
+_POOL: Optional[WorkerPool] = None
+_POOL_INIT_LOCK = asyncio.Lock()
+
+
+async def _get_pool() -> WorkerPool:
+    global _POOL
+    if _POOL is not None:
+        return _POOL
+    async with _POOL_INIT_LOCK:
+        if _POOL is not None:
+            return _POOL
+        pool = WorkerPool(
+            size=settings.pool_size,
+            exec_timeout_sec=settings.exec_timeout_sec,
+            queue_wait_sec=settings.queue_wait_sec,
+            memory_limit_mb=settings.memory_limit_mb,
+        )
+        await pool.start()
+        _POOL = pool
+        LOGGER.info("worker pool initialized")
+        return pool
+
+
+@mcp.tool(name="sympy")
+async def sympy_tool(code: str) -> str:
+    """SymPy sandbox tool: execute Python/SymPy math code.
+
+    Safety boundaries:
+    - Only sympy/math imports and calls are allowed.
+    - System calls, file I/O, network access, and dynamic execution are blocked.
+
+    Input rules:
+    - Single argument: code (str).
+    - You must print() the final answer; otherwise out may be empty.
+    - Use multiple print() lines for multiple outputs.
+
+    Recommended workflow:
+    1) Define symbols and assumptions.
+    2) Derive/solve step by step.
+    3) Simplify intermediate expressions (simplify/factor/expand).
+    4) Print final results.
+
+    Retry guidance:
+    - E_AST_BLOCK: remove unsafe statements and keep pure math code only.
+    - E_TIMEOUT: reduce problem size, split steps, simplify before solving.
+    - E_MEMORY: reduce dimensions or avoid constructing huge objects at once.
+    """
+    guard = validate_code(code)
+    if not guard.ok:
+        parsed = parse_guard_message(guard.message, hint_level=settings.hint_level)
+        return _build_error_response(parsed.code, parsed.line, parsed.err, parsed.hint)
+
+    pool = await _get_pool()
+    try:
+        result = await pool.exec(code)
+    except WorkerPoolError as exc:
+        parsed = parse_pool_error(str(exc), hint_level=settings.hint_level)
+        return _build_error_response(parsed.code, parsed.line, parsed.err, parsed.hint)
+    except Exception as exc:
+        LOGGER.exception("unexpected pool error")
+        parsed = parse_internal_error(str(exc), hint_level=settings.hint_level)
+        return _build_error_response(parsed.code, parsed.line, parsed.err, parsed.hint)
+
+    if not result.get("ok", False):
+        parsed = parse_pool_error("worker执行失败", hint_level=settings.hint_level)
+        return _build_error_response(parsed.code, parsed.line, parsed.err, parsed.hint)
+
+    if result.get("success", False):
+        stdout = (result.get("stdout") or "").rstrip()
+        out, _ = _truncate(stdout)
+        return _json_compact({"out": out})
+
+    tb_text = result.get("traceback", "") or ""
+    parsed = parse_traceback(tb_text, hint_level=settings.hint_level)
+    return _build_error_response(parsed.code, parsed.line, parsed.err, parsed.hint)
+
+
+def main() -> None:
+    mcp.run()
+
+def _build_error_response(code: str, line: int | None, err: str, hint: str) -> str:
+    err, trunc_err = _truncate(err)
+    hint, trunc_hint = _truncate(hint)
+    if trunc_err and "truncated" not in err:
+        err = f"{err}...[truncated]"
+    if trunc_hint and "truncated" not in hint:
+        hint = f"{hint}...[truncated]"
+    return _json_compact(
+        {
+            "code": code,
+            "line": line,
+            "err": err,
+            "hint": hint,
+        }
+    )
+
+
+def _truncate(text: str) -> tuple[str, int]:
+    text = text or ""
+    max_chars = settings.max_output_chars
+    if len(text) <= max_chars:
+        return text, 0
+    return f"{text[: max_chars - 12]}...[truncated]", 1
+
+
+def _json_compact(data: dict) -> str:
+    return json.dumps(data, ensure_ascii=False, separators=(",", ":"))
+
+
+if __name__ == "__main__":
+    main()

sym_mcp-0.0.0.post1.dev3.dist-info/METADATA

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: sym-mcp
+Version: 0.0.0.post1.dev3
+Summary: SymPy sandbox MCP server based on FastMCP
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Eis4TY/Sym-MCP
+Project-URL: Repository, https://github.com/Eis4TY/Sym-MCP
+Project-URL: Issues, https://github.com/Eis4TY/Sym-MCP/issues
+Keywords: mcp,sympy,sandbox,agent,llm,math
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp>=3.0.0
+Requires-Dist: sympy>=1.13.0
+Requires-Dist: pydantic>=2.8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Dynamic: license-file
+
+# SymPy Sandbox MCP
+
+English | [中文版](README.zh.md)
+
+A production-focused MCP service that lets agents/LLMs run SymPy safely and efficiently.
+It combines AST policy checks, runtime resource limits, and prewarmed workers to deliver low-noise, parse-friendly results.
+
+## Features
+
+- Single tool: `sympy` (input only requires `code`)
+- Prewarmed worker pool to avoid repeated `import sympy`
+- Two-layer safety: AST guard + runtime resource limits
+- Compact structured JSON output for low token overhead
+- Standardized error codes for reliable auto-retry workflows
+
+## Typical Use Cases
+
+- Symbolic algebra, differentiation, integration, equation solving
+- MCP tool integration for Codex / Cursor / Claude Desktop / custom MCP clients
+- Agent workflows that need controllable failures and clean error signals
+
+## Recommended Integration (MCP client via stdio)
+
+Call example:
+
+```bash
+fastmcp call \
+  --command 'python -m sym_mcp.server' \
+  --target sympy \
+  --input-json '{"code":"import sympy as sp\\nx=sp.Symbol(\"x\")\\nprint(sp.factor(x**2-1))"}'
+```
+
+Client config (`python -m`, recommended):
+
+```json
+{
+  "mcpServers": {
+    "sympy-sandbox": {
+      "command": "python",
+      "args": ["-m", "sym_mcp.server"]
+    }
+  }
+}
+```
+
+Client config (installed as `sym-mcp`):
+
+```json
+{
+  "mcpServers": {
+    "sympy-sandbox": {
+      "command": "sym-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+Client config (`uvx`):
+
+```json
+{
+  "mcpServers": {
+    "sympy-sandbox": {
+      "command": "uvx",
+      "args": ["sym-mcp"]
+    }
+  }
+}
+```
+
+## Quick Start
+
+### 1) Requirements
+
+- Python 3.11+
+- Linux / macOS (Linux recommended for production)
+
+### 2) Install (Tsinghua mirror first)
+
+```bash
+pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -e .
+pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -e ".[dev]"
+```
+
+### 3) Run server (stdio)
+
+```bash
+python -m sym_mcp.server
+```
+
+### 4) Verify tool
+
+```bash
+fastmcp list --command 'python -m sym_mcp.server'
+```
+
+## Tool Contract
+
+### Tool name
+
+- `sympy`
+
+### Input
+
+- `code: str`
+
+Notes:
+- You must `print()` final outputs.
+- If nothing is printed, `out` may be empty.
+
+### Output (always compact JSON string)
+
+Success:
+
+```json
+{"out":"x**2/2"}
+```
+
+Failure:
+
+```json
+{"code":"E_RUNTIME","line":3,"err":"ZeroDivisionError: division by zero","hint":"Runtime error. Check variable types, division-by-zero, or undefined names near the reported line."}
+```
+
+Field definitions:
+
+- `out`: stdout text on success
+- `code`: error code
+- `line`: user code error line, or `null`
+- `err`: compact error message (traceback noise removed)
+- `hint`: fix hint (based on configured hint level)
+- If `out` / `err` / `hint` is too long, it will be truncated with `...[truncated]`
+
+## Error Codes
+
+- `E_AST_BLOCK`: blocked by AST safety policy
+- `E_SYNTAX`: syntax error
+- `E_TIMEOUT`: timeout
+- `E_MEMORY`: memory limit triggered
+- `E_RUNTIME`: general runtime error
+- `E_WORKER`: worker communication/state failure
+- `E_INTERNAL`: internal server error
+
+## Recommended Agent Prompt Rules
+
+1. Use math-only Python code.
+2. Only import `sympy` or `math`.
+3. Always `print()` final answers.
+4. For multiple outputs, use multiple `print()` lines.
+5. On failure, patch minimally near `line` and retry.
+6. For `E_TIMEOUT`, reduce scale first; for `E_MEMORY`, reduce object size/dimension; for `E_AST_BLOCK`, remove unsafe statements.
+
+Example:
+
+```python
+import sympy as sp
+x = sp.Symbol("x")
+expr = (x + 1)**5
+print(sp.expand(expr))
+```
+
+## Security Model
+
+### Before execution (AST policy)
+
+- Only `sympy` / `math` imports are allowed
+- Dangerous capabilities are blocked (`eval`, `exec`, `open`, `__import__`, etc.)
+- Dunder attribute traversal is blocked (e.g. `__class__`)
+
+### During execution (OS resource limits)
+
+- Per-task CPU time limit + timeout kill
+- Per-worker memory limit via `setrlimit`
+- Worker auto-rebuild on failure to keep server healthy
+
+## Architecture
+
+- `src/sym_mcp/server.py`: MCP entrypoint and tool registration
+- `src/sym_mcp/security/ast_guard.py`: AST validation
+- `src/sym_mcp/executor/worker_main.py`: worker loop
+- `src/sym_mcp/executor/pool.py`: async prewarmed process pool
+- `src/sym_mcp/executor/sandbox.py`: restricted execution and stdout capture
+- `src/sym_mcp/errors/parser.py`: error normalization and code mapping
+- `src/sym_mcp/config.py`: runtime configuration
+
+## Configuration (Environment Variables)
+
+- `SYMMCP_POOL_SIZE`: worker pool size, default `10`
+- `SYMMCP_EXEC_TIMEOUT_SEC`: per execution timeout (sec), default `3`
+- `SYMMCP_MEMORY_LIMIT_MB`: memory cap per worker (MB), default `150`
+- `SYMMCP_QUEUE_WAIT_SEC`: queue wait timeout (sec), default `2`
+- `SYMMCP_LOG_LEVEL`: log level, default `INFO`
+- `SYMMCP_MAX_OUTPUT_CHARS`: output truncation threshold, default `1200`
+- `SYMMCP_HINT_LEVEL`: hint level (`none/short/medium`), default `medium`
+
+## FAQ
+
+### Why is `out` empty?
+
+Most likely the code does not `print()` the final result.
+
+### Why return compact JSON string?
+
+It is easier for agents to parse reliably and reduces token cost.
+
+### Is memory limiting always stable on macOS?
+
+`setrlimit` behavior differs by OS. Linux is preferred for production.
+
+### Does it support HTTP/SSE?
+
+Current primary delivery is `stdio`. HTTP/SSE can be added later via FastMCP transport extensions.
+
+## Known Limits
+
+- This is restricted Python execution, not VM/container-grade isolation
+- Memory limit behavior is OS-dependent
+- Output is truncated at threshold, with `...[truncated]` suffix
+
+## Development
+
+### Run tests
+
+```bash
+PYTHONPATH=src pytest -q
+```
+
+### Benchmark
+
+```bash
+PYTHONPATH=src python scripts/benchmark.py --concurrency 100 --total 500
+```
+
+## Contributing
+
+- Run `PYTHONPATH=src pytest -q` before submitting PRs
+- When adding new capabilities, update:
+  - error code docs
+  - README examples
+  - related unit/integration tests
+- Publishing process: [PUBLISHING.md](./PUBLISHING.md)

sym_mcp-0.0.0.post1.dev3.dist-info/RECORD

@@ -0,0 +1,19 @@
+sym_mcp/__init__.py,sha256=cfJSdc0srnrKJnnS6OI6amaQ6TyUq2afc5g5M1vfPyg,24
+sym_mcp/__main__.py,sha256=8t_7qNzDS451pU9538_IL95boYzah6iEvNJkZPpUQRc,73
+sym_mcp/config.py,sha256=J7_FsPgXgLMBzb-HiNBeKdJatLr-s1AaBb0J5bsGXys,880
+sym_mcp/schemas.py,sha256=iw9TxgzS2pjv3QVQnlpPL2Qty7RtdkOG4oXtBCecp94,217
+sym_mcp/server.py,sha256=KgaTcFm5sjWiN8pC-C6aU2pTIQilOIsf2mS-Ybpo-Gg,4870
+sym_mcp/errors/__init__.py,sha256=DLvDGcRWqvGvtQgVphXqDn345KGV6aCDnuw14Z3vs8A,30
+sym_mcp/errors/parser.py,sha256=Mfc4CTguxJRw9zNZrNL4TJMBtNa5CgcpvJG47pFzvnI,4083
+sym_mcp/executor/__init__.py,sha256=u3n7axSA-Q_EAbGqwI0LKWT_LBol3eqb4c3r5PHMscI,42
+sym_mcp/executor/pool.py,sha256=vWUBXsSo61dTGnQVPMCJAxttpxjGuF9Rso5f6YNV8KQ,6903
+sym_mcp/executor/sandbox.py,sha256=w-soUQFxLqMhO629xgEzKAKG84LxRh6Q37fMdOaA4cI,1956
+sym_mcp/executor/worker_main.py,sha256=BgtUhwuT2Aoybn2-3hUF45FSoSoTlVOXAK7mbR0Nla8,1849
+sym_mcp/security/__init__.py,sha256=crg8OP2VqDDtBD4hSQ26UMcO221ZL_iWgz1JTyLnA7s,25
+sym_mcp/security/ast_guard.py,sha256=MwKMblKmjij4Wj-epcHw4LavIFu0I9vx665Pp6qocF4,4571
+sym_mcp-0.0.0.post1.dev3.dist-info/licenses/LICENSE,sha256=o9sdgeg7UifBr_DA96ba5IelGoYdY2WSJN8FC6G1nrs,1060
+sym_mcp-0.0.0.post1.dev3.dist-info/METADATA,sha256=8FuAlCk5q00jak5lAlsSAgr1eWfoIXJg3h_dUo-MTGo,6942
+sym_mcp-0.0.0.post1.dev3.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+sym_mcp-0.0.0.post1.dev3.dist-info/entry_points.txt,sha256=Z_o4e7ExuOKT1BI15WGdYFcehGDRmQ_jai6P2Gu6VWw,48
+sym_mcp-0.0.0.post1.dev3.dist-info/top_level.txt,sha256=N7kyUBZ3yBKUzno6Wwd45c1qDEy37nMBoI0_CByMXDg,8
+sym_mcp-0.0.0.post1.dev3.dist-info/RECORD,,

sym_mcp-0.0.0.post1.dev3.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sym_mcp-0.0.0.post1.dev3.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sym-mcp = sym_mcp.server:main

sym_mcp-0.0.0.post1.dev3.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tyy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sym_mcp-0.0.0.post1.dev3.dist-info/top_level.txt

@@ -0,0 +1 @@
+sym_mcp