feat(mcp): add WorldQuant authentication recovery tools

backend/app/mcp_api/server.py

@@ -21,6 +21,8 @@ from ..research_access.service import ResearchAccess, ResearchError
 
 # Name, schema, business method, required scope, description. No generic arbitrary HTTP tool.
 TOOLS = {
+    "get_worldquant_connection": (c.ConnectionReference, "connection", "research:read", "读取 WorldQuant 连接状态及可选认证 job_id 的进度，不发起认证；人工验证在网页完成。"),
+    "authenticate_worldquant": (c.Authentication, "authenticate", "research:refresh", "使用服务端已保存凭据连接或重新认证 WorldQuant，返回 job_id；action=connect（默认）或人工验证后 verify。用 get_worldquant_connection 查询，不接收密码，不修改账户配置。"),
     "get_research_capabilities": (c.Empty, "capabilities", "research:read", "读取直接研究能力、完整设置 schema 和调度阻塞，不代表平台剩余额度。"),
     "search_catalog": (c.CatalogSearch, "catalog", "research:read", "分页查询指定范围的数据集或字段元数据；无缓存不等于无数据，不隐式刷新。"),
     "get_research_metadata": (c.Metadata, "metadata", "research:read", "读取范围、设置快照、算子定义或字段可用性；未知不认定通过。"),
@@ -66,7 +68,7 @@ class MCPResearchServer:
             inputSchema=schema.model_json_schema(), annotations=types.ToolAnnotations(
                 readOnlyHint=scope == "research:read", destructiveHint=method == "control",
                 idempotentHint=method in {"submit", "control"} or scope == "research:read",
-                openWorldHint=method in {"refresh", "submit", "metadata", "check_self_correlation"}))
+                openWorldHint=method in {"refresh", "submit", "metadata", "check_self_correlation", "authenticate"}))
             for name, (schema, method, scope, description) in TOOLS.items()
             if scope in principal.scopes and "research:read" in principal.scopes])
 

backend/app/research_access/contracts.py

@@ -18,6 +18,14 @@ class Empty(Contract):
     pass
 
 
+class Authentication(Contract):
+    action: Literal["connect", "verify"] = "connect"
+
+
+class ConnectionReference(Contract):
+    job_id: RunId | None = None
+
+
 class Page(Contract):
     limit: int = Field(default=25, ge=1, le=100)
     offset: int = Field(default=0, ge=0)

backend/app/research_access/service.py

@@ -17,6 +17,7 @@ from ..catalog.platform import platform_options, validate_platform_scope
 from ..catalog.research_metadata import ResearchMetadata, availability_key
 from ..catalog.service import Catalog
 from ..correlation import MIN_SAMPLES, THRESHOLD, WINDOW_YEARS
+from ..jobs import AUTH_KINDS
 from ..models import Account, Alpha, BacktestItem, Job, JobItem, ResearchRequest, SimulationAttempt, now
 from ..research.serialization import encode_snapshot
 from ..research.workspace_contracts import FieldAvailabilityInput
@@ -59,6 +60,51 @@ class ResearchAccess:
                     "platform_check": False,
                 }}
 
+    async def connection(self, args):
+        """Read bounded connection evidence; never return credentials or session cookies."""
+        account = await self.db.get(Account, self.principal.account_id)
+        if not account or account.wq_user_id != self.principal.wq_user_id:
+            raise ResearchError("ACCOUNT_MISMATCH", "平台账户绑定已变化")
+        job = None
+        if args.job_id:
+            job = await self.db.get(Job, args.job_id)
+            if not job or job.kind not in AUTH_KINDS:
+                raise ResearchError("NOT_FOUND", "认证任务不存在")
+        return {"connection_status": account.connection_status,
+                "session_authenticated": self.client.authenticated,
+                "credentials_configured": bool(account.email and account.password_encrypted),
+                "requires_human_verification": account.connection_status == "verification_required",
+                "web_url": f"{self.public_origin}/",
+                "job": {"job_id": job.id, "kind": job.kind, "status": job.status} if job else None,
+                "next_step": "需要人工验证时在网页账户连接面板完成，再调用 authenticate_worldquant(action=verify)"}
+
+    async def authenticate(self, args):
+        """Queue authentication using saved credentials, sharing the HTTP account lock.
+
+        The caller commits the job and audit together before waking the runner.
+        Human challenges remain in the browser; no password or challenge URL is exposed.
+        """
+        account = await self.db.scalar(select(Account).where(
+            Account.id == self.principal.account_id).with_for_update())
+        if not account or account.wq_user_id != self.principal.wq_user_id:
+            raise ResearchError("ACCOUNT_MISMATCH", "平台账户绑定已变化")
+        if not account.email or not account.password_encrypted:
+            raise ResearchError("CREDENTIALS_NOT_CONFIGURED", "请先在网页保存 WorldQuant 账户配置")
+        job = await self.db.scalar(select(Job).where(
+            Job.kind.in_(AUTH_KINDS), Job.status.in_(("running", "queued"))))
+        if not job:
+            # Preserve a pending challenge instead of replacing its server-side session.
+            if args.action == "connect" and account.connection_status == "verification_required":
+                raise ResearchError("VERIFICATION_REQUIRED", "请在网页完成人工验证，再调用 action=verify")
+            job = Job(id=str(uuid4()), kind=args.action, payload={}, checkpoint={})
+            self.db.add(job)
+            if args.action == "connect":
+                account.connection_status, account.connection_error = "connecting", None
+            await self.db.flush()
+        self.wake = "jobs"
+        return {"job_id": job.id, "status": job.status, "action": job.kind,
+                "read_with": "get_worldquant_connection", "web_url": f"{self.public_origin}/"}
+
     async def catalog(self, args):
         data = await Catalog(self.db).search(args.filters, args.dataset_id)
         return {**data, "scope": args.filters.model_dump(include={"region", "universe", "delay", "instrument_type"}),