store-mcp-py 0.1.0__tar.gz

store_mcp_py-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: store-mcp-py
+Version: 0.1.0
+Summary: MCP (Model Context Protocol) adapter that auto-generates tool surfaces for py-store schemas (schema-driven CRUD + sandboxed GQL query + optional ask), stdio transport
+License: MIT
+Keywords: py-store,storepy,mcp,model-context-protocol,crud,gql,ai
+Requires-Python: >=3.10
+Requires-Dist: mcp<3,>=2.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"

store_mcp_py-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "store-mcp-py"
+version = "0.1.0"
+description = "MCP (Model Context Protocol) adapter that auto-generates tool surfaces for py-store schemas (schema-driven CRUD + sandboxed GQL query + optional ask), stdio transport"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+keywords = ["py-store", "storepy", "mcp", "model-context-protocol", "crud", "gql", "ai"]
+dependencies = ["mcp>=2.2,<3"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[tool.setuptools.packages.find]
+include = ["store_mcp*"]

store_mcp_py-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

store_mcp_py-0.1.0/store_mcp/__init__.py

@@ -0,0 +1,314 @@
+"""store-mcp-py — 为 py-store 已注册 schema 自动生成 MCP 工具面。
+
+语义依据：../spec/*.md（双端 parity，改动先改 spec）。
+设计哲学：MCP 只是 GQL 的又一层 AI 客户端皮肤 —— 适配层零语义发明。
+双出口：
+    export_tools(store, opts)   → list[dict]（纯构建，零 SDK 依赖，永远可用）
+    create_server(store, opts)  → 低层 Server（装配全部守卫，不绑传输）
+    run_stdio(store, opts)      → stdio 阻塞运行（create_server + stdio_server）
+
+store 端口契约见 spec/00：query / query_one / insert / update / remove / set_context；
+元数据（list / get）走 opts.schema_module → duck(store.list/store.get) → py_store.schema；
+档位上下文 text2query（query 工具强制沙箱）取用顺序：opts["text2query"] → py_store.schema。
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+__all__ = ['export_tools', 'create_server', 'run_stdio',
+           'filter_archived', 'schema_projection', 'build_surface', 'error_of']
+
+ARCHIVE_SUFFIX = 'Deleted'
+
+
+# ── spec/01：归档表过滤（与 store-api / store-graphql / store-grpc 逐字一致）──
+
+def filter_archived(names: list[str]) -> list[str]:
+    names_set = set(names)
+    return [n for n in names
+            if not (n.endswith(ARCHIVE_SUFFIX) and n[:-len(ARCHIVE_SUFFIX)] in names_set)]
+
+
+# ── spec/01：schema 投影（fields + computes 均视为字段，与 store-graphql 对齐）──
+
+def schema_projection(defn: dict | None) -> str:
+    if not defn:
+        return ''
+    keys = list({**(defn.get('fields') or {}), **(defn.get('computes') or {})})
+    return f' {{ {", ".join(keys)} }}' if keys else ''
+
+
+def id_field_of(defn: dict | None) -> str:
+    return (defn or {}).get('idField') or '_id'
+
+
+# ── 协议面错误（spec/03 判定链的皮肤侧子集）──
+
+class SkinError(Exception):
+    def __init__(self, code: str, message: str):
+        super().__init__(message)
+        self.code = code
+
+
+def _assert_object(value: Any, field: str) -> None:
+    if not isinstance(value, dict):
+        raise SkinError('invalidBody', f'{field} 必须为 JSON 对象（数组/标量拒绝，spec/02）')
+
+
+# ── spec/03：错误判定链（类名判定跨包安全，不依赖宿主 isinstance）──
+
+def error_of(e: BaseException) -> dict:
+    name = getattr(e, 'name', None) or e.__class__.__name__
+    if name == 'SkinError':
+        return {'code': e.code, 'message': str(e)}  # type: ignore[attr-defined]
+    if name == 'AskExhausted':
+        return {'code': 'askExhausted', 'message': str(e)}
+    if name == 'PermissionError':
+        return {'code': 'permissionDenied', 'message': str(e)}
+    if name == 'ProfileViolation':
+        return {'code': 'profileBlocked', 'message': str(e)}
+    return {'code': 'planError', 'message': str(e)}
+
+
+# ── 元数据 provider（spec/00：opts.schema_module → duck → py_store.schema）──
+
+def _meta_provider(store: Any, opts: dict):
+    module = opts.get('schema_module')
+    if module is not None:
+        return module
+    if hasattr(store, 'list') and hasattr(store, 'get'):
+        return store
+    try:
+        from py_store import schema
+        return schema
+    except ImportError as e:
+        raise RuntimeError(
+            'store-mcp: 取不到 schema 元数据（store 无 list/get，且未安装 py_store）。'
+            '传 opts["schema_module"] 或安装 py-store') from e
+
+
+# ── spec/01：工具清单构建（纯 JSON Schema 直出）──
+
+def _obj(properties: dict, required: list[str]) -> dict:
+    return {'type': 'object', 'properties': properties, 'required': required}
+
+
+def model_tools(name: str, defn: dict | None, description: str | None) -> list[dict]:
+    desc = description or f'{name}（MCP 工具面，由 schema 自动生成）'
+    d = lambda s: f'{desc} — {s}'  # noqa: E731
+    return [
+        {'name': f'get_{name}', 'description': d('按 id 查单条'),
+         'inputSchema': _obj({'id': {'type': 'string', 'description': '文档 id（原样透传）'}}, ['id'])},
+        {'name': f'list_{name}', 'description': d('列表查询：q 为自模型名始的 GQL 余部（与 REST ?q= 同源），空则按 schema 投影'),
+         'inputSchema': _obj({'q': {'type': 'string', 'description': 'GQL 余部，如 "($condition: @c0) -> { name }"'},
+                              'params': {'type': 'object', 'description': 'GQL params（键 = 去掉 @ 的引用名）'}}, [])},
+        {'name': f'create_{name}', 'description': d('插入文档'),
+         'inputSchema': _obj({'body': {'type': 'object', 'description': '文档对象'}}, ['body'])},
+        {'name': f'update_{name}', 'description': d('按 id 定位后部分更新'),
+         'inputSchema': _obj({'id': {'type': 'string'},
+                              'set': {'type': 'object', 'description': '待更新字段集'}}, ['id', 'set'])},
+        {'name': f'delete_{name}', 'description': d('按 id 定位删除'),
+         'inputSchema': _obj({'id': {'type': 'string'}}, ['id'])},
+    ]
+
+
+QUERY_TOOL = {
+    'name': 'query',
+    'description': ('全局 GQL 直查（只读沙箱：强制 text2query 档，core 硬限 1000 行 / 深度 3，'
+                    '禁 route_override）。gql 为自模型名始的完整 GQL 查询串，条件值一律参数化（@key 引用，值放 params）'),
+    'inputSchema': _obj({'gql': {'type': 'string'}, 'params': {'type': 'object'}}, ['gql']),
+}
+
+ASK_TOOL = {
+    'name': 'ask',
+    'description': ('AI 问数（只读）：自然语言 → 宿主 ask() 编排（LLM 翻译 → text2query 档校验执行 → '
+                    '失败结构化回喂重试）。成功返回 {data, attempts, events}；失败显式报错（不降级、不返回空结果）'),
+    'inputSchema': _obj({'question': {'type': 'string', 'description': '自然语言问题'}}, ['question']),
+}
+
+
+def build_surface(store: Any, opts: dict):
+    """收集工具面（归档过滤 + x-mcp 注记 + ask 启用守卫）。返回 (tools, handlers)。"""
+    meta = _meta_provider(store, opts)
+    names = opts.get('resources') or filter_archived(list(meta.list()))
+    tools: list[dict] = []
+    handlers: dict[str, Any] = {}
+
+    for name in names:
+        defn = meta.get(name) if hasattr(meta, 'get') else None
+        xm = (defn or {}).get('x-mcp') or {}
+        if xm.get('hidden'):
+            continue  # spec/01 注记：模型级 hidden
+        proj = schema_projection(defn)
+        id_field = id_field_of(defn)
+        description = defn.get('description') if defn else None
+        for tool in model_tools(name, defn, description):
+            if tool['name'] in handlers:
+                raise RuntimeError(f'ERR_NAME_CONFLICT:工具名 "{tool["name"]}" 冲突（spec/01）')
+            tools.append(tool)
+            handlers[tool['name']] = _model_handler_curry(store, tool['name'], name, proj, id_field)
+
+    # spec/02：query 工具强制 text2query 档 —— 档位上下文取用顺序见模块头
+    tools.append(dict(QUERY_TOOL))
+    handlers['query'] = _query_handler(store, opts)
+
+    # spec/01：ask 仅 opts.llm 提供时注册；配 llm 缺 ctx 装配期抛错（fail-secure）
+    if opts.get('llm') is not None:
+        if opts.get('ctx') is None:
+            raise RuntimeError(
+                'store-mcp: opts["llm"] 已提供但缺 opts["ctx"] —— ask 工具需要服务端用户上下文'
+                '（如 {"userId": ..., "roles": [...]}）；ctx 属受信参数，不进任何工具入参（D5）')
+        tools.append(dict(ASK_TOOL))
+        handlers['ask'] = _ask_handler(opts)
+
+    return tools, handlers
+
+
+# ── spec/02：映射表 handler ──
+
+async def _model_handler(store, tool_name, name, proj, id_field, args):
+    verb = tool_name[:tool_name.index('_')]
+    if verb == 'get':
+        row = await store.query_one(f'{name}($condition: @c0){proj}', {'c0': {id_field: args['id']}}, None)
+        if row is None:
+            raise SkinError('notFound', f'{name} {args["id"]} not found')
+        return row
+    if verb == 'list':
+        q = args.get('q')
+        return await store.query(f'{name}{q}' if q else f'{name}{proj}', args.get('params'), None)
+    if verb == 'create':
+        _assert_object(args.get('body'), 'body')
+        return await store.insert(name, args['body'])
+    if verb == 'update':
+        _assert_object(args.get('set'), 'set')
+        return await store.update(name, {id_field: args['id']}, args['set'])
+    if verb == 'delete':
+        return await store.remove(name, {id_field: args['id']})
+    raise SkinError('planError', f'未知工具动词: {verb}')
+
+
+def _model_handler_curry(store, tool_name, name, proj, id_field):
+    async def handler(args):
+        return await _model_handler(store, tool_name, name, proj, id_field, args)
+    return handler
+
+
+def _query_handler(store, opts):
+    async def handler(args):
+        gql = args.get('gql')
+        if not isinstance(gql, str) or not gql.strip():
+            raise SkinError('invalidParam', 'gql 必须为非空字符串（自模型名始，spec/02）')
+        t2q = opts.get('text2query')
+
+        async def run():
+            # routeOverride 恒 None（D5/CWE-639）
+            return await store.query(gql, args.get('params'), None)
+
+        # 形态契约（spec/00）：与宿主逐字同形的 sync contextmanager 工厂——
+        # py_store.schema.text2query 即 `@contextmanager def text2query(): ...`
+        # （实为 `with t2q(): await run()`；回调/awaitable 形态一律不收，守卫按 callable 放行后
+        #  在此处以 with 进入——非 contextmanager 形态会在此 TypeError 显式暴露，禁静默降级）
+        if callable(t2q):
+            with t2q():
+                return await run()
+        return await run()  # 测试注入路径之外不可达：装配期已守卫
+    return handler
+
+
+def _ask_handler(opts):
+    async def handler(args):
+        question = args.get('question')
+        if not isinstance(question, str) or not question.strip():
+            raise SkinError('invalidParam', 'question 必须为非空自然语言字符串')
+        # 护栏零新增：档位/只读/回喂/硬限全在宿主 ask()；AskResult(data, attempts, events) 全量返回
+        r = await opts['host_ask'](question)
+        return {'data': r.data, 'attempts': r.attempts, 'events': r.events}
+    return handler
+
+
+# ── 双出口 ──
+
+def export_tools(store: Any, opts: dict | None = None) -> list[dict]:
+    """纯构建工具清单（零 SDK 依赖，永远可用；对齐 store-grpc export_proto 先例）。"""
+    return build_surface(store, opts or {})[0]
+
+
+def create_server(store: Any, opts: dict | None = None):
+    """装配 MCP Server（全部守卫在此，不绑传输——测试经 memory 流直连）。"""
+    opts = dict(opts or {})
+    try:
+        import mcp.types as types
+        from mcp.server.lowlevel import Server
+    except ImportError as e:
+        raise RuntimeError(
+            f'store-mcp-py 缺承载依赖 mcp（{e}）。安装：pip install "mcp>=2.2,<3"') from e
+
+    # spec/02：query 工具强制 text2query 档 —— opts["text2query"] 优先，缺省从宿主取，两者皆无 ⇒ 拒绝装配
+    if not callable(opts.get('text2query')):
+        try:
+            from py_store.schema import text2query
+            opts['text2query'] = text2query
+        except ImportError:
+            pass
+        if not callable(opts.get('text2query')):
+            raise RuntimeError(
+                'store-mcp: query 工具强制 text2query 档（spec/02），但未取得档位上下文。'
+                '安装 py-store 或传 opts["text2query"]（async 上下文管理器/装饰器，py_store.schema 导出）')
+
+    if opts.get('llm') is not None:
+        if opts.get('ctx') is None:
+            raise RuntimeError('store-mcp: opts["llm"] 已提供但缺 opts["ctx"]（fail-secure，spec/01）')
+        if not callable(opts.get('host_ask')):
+            try:
+                from py_store import ask as host_ask
+                opts['host_ask'] = lambda q: host_ask(q, llm=opts['llm'], ctx=opts['ctx'])
+            except ImportError as e:
+                raise RuntimeError(f'store-mcp: ask 工具需要宿主 py_store（{e}）。安装：pip install py-store') from e
+
+    tools, handlers = build_surface(store, opts)
+    app = Server(opts.get('name') or 'store-mcp')
+
+    async def list_tools(ctx, params):
+        return types.ListToolsResult(tools=[
+            types.Tool(name=t['name'], description=t['description'], inputSchema=t['inputSchema'])
+            for t in tools])
+
+    async def call_tool(ctx, params):
+        name = params.name
+        args = params.arguments or {}
+        try:
+            handler = handlers.get(name)
+            if handler is None:
+                raise SkinError('invalidParam', f'未知工具: {name}')
+            provider = opts.get('context_provider')
+            if provider is not None:
+                ctx = await provider(getattr(params, 'meta', None))
+                await store.set_context(ctx or None)  # 显式清除语义，spec/02
+            data = await handler(args)
+            # 成功响应不含任何 error 键（spec/03 正向断言）
+            return types.CallToolResult(content=[types.TextContent(
+                type='text', text=json.dumps(data if data is not None else None, ensure_ascii=False))])
+        except Exception as e:  # noqa: BLE001 —— 一切失败显式 isError（spec/03，禁静默失守）
+            err = error_of(e)
+            return types.CallToolResult(isError=True, content=[types.TextContent(
+                type='text', text=json.dumps(err, ensure_ascii=False))])
+
+    app.add_request_handler('tools/list', types.PaginatedRequestParams, list_tools)
+    app.add_request_handler('tools/call', types.CallToolRequestParams, call_tool)
+    return {'server': app, 'tools': tools}
+
+
+def run_stdio(store: Any, opts: dict | None = None) -> None:
+    """stdio 阻塞运行：create_server + stdio_server（对齐 node createStdioServer）。"""
+    import anyio
+    from mcp.server.stdio import stdio_server
+
+    app = create_server(store, opts)['server']
+
+    async def _main():
+        async with stdio_server() as (read_stream, write_stream):
+            await app.run(read_stream, write_stream, app.create_initialization_options())
+
+    anyio.run(_main)

store_mcp_py-0.1.0/store_mcp_py.egg-info/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: store-mcp-py
+Version: 0.1.0
+Summary: MCP (Model Context Protocol) adapter that auto-generates tool surfaces for py-store schemas (schema-driven CRUD + sandboxed GQL query + optional ask), stdio transport
+License: MIT
+Keywords: py-store,storepy,mcp,model-context-protocol,crud,gql,ai
+Requires-Python: >=3.10
+Requires-Dist: mcp<3,>=2.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"

store_mcp_py-0.1.0/store_mcp_py.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+pyproject.toml
+store_mcp/__init__.py
+store_mcp_py.egg-info/PKG-INFO
+store_mcp_py.egg-info/SOURCES.txt
+store_mcp_py.egg-info/dependency_links.txt
+store_mcp_py.egg-info/requires.txt
+store_mcp_py.egg-info/top_level.txt
+tests/test_conformance.py
+tests/test_mcp.py

store_mcp_py-0.1.0/store_mcp_py.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

store_mcp_py-0.1.0/store_mcp_py.egg-info/requires.txt

@@ -0,0 +1,4 @@
+mcp<3,>=2.2
+
+[dev]
+pytest>=8

store_mcp_py-0.1.0/store_mcp_py.egg-info/top_level.txt

@@ -0,0 +1 @@
+store_mcp

store_mcp_py-0.1.0/tests/test_conformance.py

@@ -0,0 +1,153 @@
+"""conformance 一致性测试 —— 加载 ../../conformance/cases.json（双端唯一断言事实源），
+断言值逐字取自 JSON，本文件零内联期望（改断言先改 cases.json）。"""
+
+import json
+from contextlib import contextmanager
+from pathlib import Path
+
+import anyio
+import pytest
+
+from mock_store import mock_store
+from store_mcp import create_server, filter_archived
+from test_mcp import make_session
+
+_CASES = Path(__file__).resolve().parents[2] / 'conformance' / 'cases.json'
+cases = json.loads(_CASES.read_text(encoding='utf-8'))
+
+
+def parse(result):
+    assert result.content, '必须有 content'
+    return json.loads(result.content[0].text)
+
+
+@pytest.mark.anyio
+async def test_surface_tool_names():
+    store, _ = mock_store()
+    async with await make_session(store) as s:
+        tools = (await s.list_tools()).tools
+        assert sorted(t.name for t in tools) == cases['surface']['expected_tool_names']
+        assert len(tools) == cases['surface']['expected_count']
+
+
+@pytest.mark.anyio
+async def test_get_projection_and_miss():
+    store, calls = mock_store()
+    async with await make_session(store) as s:
+        r = await s.call_tool(cases['get']['tool'], cases['get']['args'])
+        assert not r.is_error
+        assert parse(r) == cases['get']['hit_data']
+        op, q, params = calls[0]
+        assert op == cases['get']['expected_op']['py']
+        assert q == cases['get']['expected_q']
+        assert params == cases['get']['expected_params']
+
+        miss = await s.call_tool(cases['get']['tool'], cases['get']['miss_args'])
+        assert miss.is_error
+        assert parse(miss)['code'] == cases['get']['miss_code']
+
+
+@pytest.mark.anyio
+async def test_list_q_handling():
+    store, calls = mock_store()
+    async with await make_session(store) as s:
+        await s.call_tool(cases['list']['tool'], {})
+        await s.call_tool(cases['list']['tool'], cases['list']['with_q_args'])
+        assert calls[0][0] == cases['list']['empty_q_op']['py']
+        assert calls[0][1] == cases['list']['empty_q_expected']
+        assert calls[1][1] == cases['list']['with_q_expected_q']
+        assert calls[1][2] == cases['list']['with_q_expected_params']
+
+
+@pytest.mark.anyio
+async def test_create_body_validation():
+    store, calls = mock_store()
+    async with await make_session(store) as s:
+        await s.call_tool(cases['create']['tool'], cases['create']['args'])
+        op, name, body = calls[0]
+        assert op == cases['create']['expected_op']['py']
+        assert name == cases['create']['expected_q']
+        assert body == cases['create']['expected_params']
+        bad = await s.call_tool(cases['create']['tool'], cases['create']['bad_args'])
+        assert parse(bad)['code'] == cases['create']['bad_code']
+
+
+@pytest.mark.anyio
+async def test_update_and_remove_id_field():
+    store, calls = mock_store()
+    async with await make_session(store) as s:
+        await s.call_tool(cases['update']['tool'], cases['update']['args'])
+        await s.call_tool(cases['remove']['tool'], cases['remove']['args'])
+        assert calls[0][0] == cases['update']['expected_op']['py']
+        assert calls[0][1] == cases['update']['expected_q']
+        assert calls[0][2] == cases['update']['expected_params']
+        assert calls[0][3] == cases['update']['expected_set']
+        assert calls[1][0] == cases['remove']['expected_op']['py']
+        assert calls[1][2] == cases['remove']['expected_params']
+
+
+@pytest.mark.anyio
+async def test_query_profile_passthrough():
+    store, calls = mock_store()
+    entered = []
+
+    @contextmanager
+    def t2q():
+        entered.append(True)
+        yield
+
+    async with await make_session(store, text2query=t2q) as s:
+        r = await s.call_tool(cases['query']['tool'], cases['query']['args'])
+        assert not r.is_error
+        assert entered, 'query 必须在 text2query 档内执行'
+        op, q, params = calls[0]
+        assert op == cases['query']['expected_op']['py']
+        assert q == cases['query']['expected_q']
+        assert params == cases['query']['expected_params']
+
+
+@pytest.mark.anyio
+async def test_error_mappings():
+    store, _ = mock_store()
+
+    async def boom(q, params=None, route_override=None):
+        raise ValueError(cases['errors']['stable_prefix'] + '深度超限')
+
+    store.query = boom
+
+    async with await make_session(store) as s:
+        r = await s.call_tool(cases['query']['tool'], cases['query']['args'])
+        assert r.is_error
+        err = parse(r)
+        assert err['code'] == cases['errors']['plan_error_code']
+        assert cases['errors']['stable_prefix'] in err['message']
+
+    s2, _ = mock_store()
+
+    class PermissionError(Exception):  # noqa: A001 —— 模拟宿主同名异常（跨包按名判定）
+        pass
+
+    async def denied(q, params=None, route_override=None):
+        raise PermissionError('denied')
+
+    s2.query_one = denied
+    async with await make_session(s2) as s:
+        r = await s.call_tool(cases['get']['tool'], cases['get']['args'])
+        assert parse(r)['code'] == cases['errors']['permission_code']
+
+    s3, _ = mock_store()
+
+    class ProfileViolation(Exception):
+        pass
+
+    async def blocked(q, params=None, route_override=None):
+        raise ProfileViolation('blocked')
+
+    s3.query_one = blocked
+    async with await make_session(s3) as s:
+        r = await s.call_tool(cases['get']['tool'], cases['get']['args'])
+        assert parse(r)['code'] == cases['errors']['profile_code']
+
+
+def test_archive_filter_pure():
+    assert filter_archived(cases['archive_filter']['input']) == cases['archive_filter']['expected']

store_mcp_py-0.1.0/tests/test_mcp.py

@@ -0,0 +1,292 @@
+"""store-mcp-py 测试 — 全部跑在 mock store + mcp SDK memory 流上，
+零真实库、零宿主包依赖（语义一致性以 ../spec 为准；conformance/cases.json 见步骤 8）。
+
+mcp 2.x 握手只协商 legacy 版本（实测 2025-11-25）：tools/call 裸调用即可；
+add_request_handler 的 params_type 必须是 params 模型（CallToolRequestParams /
+PaginatedRequestParams），传整 Request 模型会拿 params dict 去验 id/jsonrpc 而必拒。
+"""
+
+import json
+from contextlib import contextmanager
+
+import anyio
+import pytest
+from mcp import ClientSession
+from mcp.shared.memory import create_client_server_memory_streams
+
+from mock_store import mock_store
+from store_mcp import (create_server, error_of, export_tools, filter_archived)
+
+USER_PROJ = ' { name, full }'
+
+
+async def make_session(store, **opts):
+    """起 server（后台任务组）+ 已 initialize 的 ClientSession；用 async with 组合。"""
+    if 'text2query' not in opts:
+        opts['text2query'] = _passthrough_profile
+
+    app = create_server(store, opts)['server']
+    streams = create_client_server_memory_streams()
+
+    class Ctx:
+        async def __aenter__(self):
+            self._cm = streams.__aenter__()
+            cs, ss = await self._cm
+            self._tg = anyio.create_task_group()
+            await self._tg.__aenter__()
+            self._tg.start_soon(app.run, ss[0], ss[1], app.create_initialization_options())
+            self._session = ClientSession(cs[0], cs[1])
+            await self._session.__aenter__()
+            await self._session.initialize()
+            return self._session
+
+        async def __aexit__(self, *exc):
+            await self._session.__aexit__(*exc)
+            self._tg.cancel_scope.cancel()
+            await self._tg.__aexit__(*exc)
+            await streams.__aexit__(*exc)
+
+    return Ctx()
+
+
+def parse(result):
+    assert result.content, '必须有 content'
+    return json.loads(result.content[0].text)
+
+
+# ── 1. 工具清单：归档过滤 + x-mcp hidden + query ──
+
+@pytest.mark.anyio
+async def test_tools_list():
+    store, _ = mock_store()
+    async with await make_session(store) as s:
+        tools = (await s.list_tools()).tools
+        names = sorted(t.name for t in tools)
+        assert names == sorted([
+            'create_Order', 'create_User', 'delete_Order', 'delete_User',
+            'get_Order', 'get_User', 'list_Order', 'list_User',
+            'query', 'update_Order', 'update_User'])
+        assert len(tools) == 11
+
+
+@pytest.mark.anyio
+async def test_ask_tool_registered_only_with_llm():
+    store, _ = mock_store()
+
+    async def host_ask(question):
+        class R:
+            data = [1]
+            attempts = [{'rows': 1}]
+            events = []
+        return R()
+
+    async with await make_session(store, llm='gpt', ctx={'userId': 'u1', 'roles': ['admin']},
+                                  host_ask=host_ask) as s:
+        tools = (await s.list_tools()).tools
+        assert any(t.name == 'ask' for t in tools)
+
+
+@pytest.mark.anyio
+async def test_ask_guard_missing_ctx():
+    store, _ = mock_store()
+    with pytest.raises(RuntimeError, match='缺 opts\\["ctx"\\]'):
+        create_server(store, {'llm': 'gpt', 'text2query': lambda fn: fn()})
+
+
+# ── 2. get_X ──
+
+@pytest.mark.anyio
+async def test_get_user_projection_and_hit():
+    store, calls = mock_store()
+    async with await make_session(store) as s:
+        r = await s.call_tool('get_User', {'id': 'u1'})
+        assert not r.is_error
+        assert parse(r) == {'_id': 'u1', 'name': 'Alice'}
+        op, q, params = calls[0]
+        assert op == 'query_one'
+        assert q == f'User($condition: @c0){USER_PROJ}'
+        assert params == {'c0': {'_id': 'u1'}}
+
+
+@pytest.mark.anyio
+async def test_get_user_not_found():
+    store, _ = mock_store()
+    async with await make_session(store) as s:
+        r = await s.call_tool('get_User', {'id': 'nope'})
+        assert r.is_error
+        assert parse(r)['code'] == 'notFound'
+
+
+# ── 3. list_X ──
+
+@pytest.mark.anyio
+async def test_list_user_q_handling():
+    store, calls = mock_store()
+    async with await make_session(store) as s:
+        await s.call_tool('list_User', {})
+        await s.call_tool('list_User', {'q': '($condition: @c1) -> { name }', 'params': {'c1': {'name': 'A'}}},
+                          )
+        assert calls[0][1] == f'User{USER_PROJ}'
+        assert calls[1][1] == 'User($condition: @c1) -> { name }'
+        assert calls[1][2] == {'c1': {'name': 'A'}}
+
+
+# ── 4. create / update / delete ──
+
+@pytest.mark.anyio
+async def test_create_user_body_validation():
+    store, calls = mock_store()
+    async with await make_session(store) as s:
+        r = await s.call_tool('create_User', {'body': {'name': 'Bob'}})
+        assert parse(r)['_id'] == 'n1'
+        assert calls[0] == ['insert', 'User', {'name': 'Bob'}]
+
+        bad = await s.call_tool('create_User', {'body': [1, 2]})
+        assert bad.is_error
+        assert parse(bad)['code'] == 'invalidBody'
+
+
+@pytest.mark.anyio
+async def test_update_delete_user_id_field():
+    store, calls = mock_store()
+    async with await make_session(store) as s:
+        await s.call_tool('update_User', {'id': 'u1', 'set': {'name': 'A2'}})
+        await s.call_tool('delete_User', {'id': 'u1'})
+        assert calls[0] == ['update', 'User', {'_id': 'u1'}, {'name': 'A2'}]
+        assert calls[1] == ['remove', 'User', {'_id': 'u1'}]
+
+
+# ── 5. query 工具：强制 text2query 档 ──
+
+@pytest.mark.anyio
+async def test_query_runs_in_text2query_profile():
+    store, calls = mock_store()
+    entered = []
+
+    @contextmanager
+    def t2q():
+        entered.append(True)
+        yield
+
+    async with await make_session(store, text2query=t2q) as s:
+        r = await s.call_tool('query', {'gql': 'User -> { name }', 'params': {}})
+        assert not r.is_error
+        assert entered, 'query 必须在 text2query 档内执行'
+        assert calls[0] == ['query', 'User -> { name }', {}]
+
+
+@pytest.mark.anyio
+async def test_text2query_defaults_to_host():
+    """缺省路径：本机 py-store 已装 ⇒ 从宿主 schema 模块取得 text2query，装配成功。
+
+    （与 node 侧「缺失 ⇒ 装配期抛错」用例对称互补：py 环境宿主常驻，缺失场景
+    由 create_server 守卫段的 RuntimeError 路径覆盖——opts 与宿主皆无时抛错。）
+    """
+    store, _ = mock_store()
+    r = create_server(store, {})
+    assert any(t['name'] == 'query' for t in r['tools'])
+
+
+# ── 6. 错误透传 ──
+
+@pytest.mark.anyio
+async def test_err_prefix_passthrough():
+    store, calls = mock_store()
+
+    async def boom(q, params=None, route_override=None):
+        raise ValueError('ERR_TEXT2QUERY:深度超限')
+
+    store.query = boom
+
+    async with await make_session(store) as s:
+        r = await s.call_tool('query', {'gql': 'User'})
+        assert r.is_error
+        err = parse(r)
+        assert err['code'] == 'planError'
+        assert 'ERR_TEXT2QUERY:' in err['message'], '前缀必须原样保留'
+
+
+@pytest.mark.anyio
+async def test_permission_error_mapping_by_name():
+    store, calls = mock_store()
+
+    class PermissionError(Exception):  # noqa: A001 —— 模拟宿主同名异常（跨包按名判定）
+        pass
+
+    async def denied(q, params=None, route_override=None):
+        raise PermissionError('denied')
+
+    store.query_one = denied
+    async with await make_session(store) as s:
+        r = await s.call_tool('get_User', {'id': 'u1'})
+        assert parse(r)['code'] == 'permissionDenied'
+
+
+# ── 7. context_provider ──
+
+@pytest.mark.anyio
+async def test_context_provider_explicit_clear():
+    store, calls = mock_store()
+    async def provider(_meta):
+        return None
+    async with await make_session(store, context_provider=provider) as s:
+        await s.call_tool('get_User', {'id': 'u1'})
+        assert calls[0] == ['set_context', None]
+        assert calls[1][0] == 'query_one'
+
+
+# ── 8. export_tools：纯构建零 SDK 侧效应 ──
+
+@pytest.mark.anyio
+async def test_export_tools_matches_surface():
+    store, _ = mock_store()
+    async def host_ask(question):
+        class R:
+            data = []
+            attempts = []
+            events = []
+        return R()
+    tools = export_tools(store, {'llm': 'gpt', 'ctx': {'userId': 'u1'}, 'host_ask': host_ask})
+    assert sum(1 for t in tools if t['name'] == 'ask') == 1
+    assert len(tools) == 12  # 2 模型 × 5 + query + ask
+
+
+# ── 9. 纯函数：filter_archived / error_of ──
+
+def test_filter_archived():
+    assert filter_archived(['User', 'OrderDeleted', 'Order', 'StandaloneDeleted']) == \
+        ['User', 'Order', 'StandaloneDeleted']
+
+
+def test_error_of_known_names():
+    class ProfileViolation(Exception):
+        pass
+    assert error_of(ProfileViolation('x'))['code'] == 'profileBlocked'
+    assert error_of(ValueError('boom')) == {'code': 'planError', 'message': 'boom'}
+
+
+@contextmanager
+def _passthrough_profile():
+    """mock 档位上下文——与 py_store.schema.text2query 逐字同形（@contextmanager 工厂）。"""
+    yield
+
+
+@pytest.mark.anyio
+async def test_query_host_profile_actually_enters():
+    """宿主兜底回归：opts 不注入时从 py_store.schema 取得真实 text2query
+    （@contextmanager 工厂），query 执行期档位必须**真实进入**——mock store 内
+    断言 core 判决面 get_profile()=='text2query'（此前 mock 走 async 回调形态，
+    掩盖了 `with` 包裹缺失的缺陷，本用例堵住该回归）。"""
+    from py_store.schema import get_profile
+    store, calls = mock_store()
+
+    async def spy_query(q, params=None, route_override=None):
+        calls.append(['query', q, params, get_profile()])
+        return [{'profile': get_profile()}]
+
+    store.query = spy_query
+    async with await make_session(store, text2query=False) as s:  # False ⇒ 走宿主兜底 import
+        r = await s.call_tool('query', {'gql': 'User -> { name }'}, )
+        assert not r.is_error, parse(r)
+        assert calls[0][3] == 'text2query', 'query 必须真实进入 text2query 档'
+        assert parse(r) == [{'profile': 'text2query'}]