用途：从 MCP 客户端操作用户浏览器中已打开的 Graphistry 可视化会话，包括查看图模式、运行 GFQL 查询、创建带颜色的集合，使用户在浏览器中看到更新。
区分两个同名服务：Viz MCP（https://<graphistry-host>/mcp）用于读写用户已打开的图，是会话级服务，即本技能；PyGraphistry MCP（github.com/graphistry/graphistry-mcp）用于从零构建并上传新可视化，属 Hub 级，与本技能无关。任务若起点是用户正在查看的图，用 Viz MCP；起点是 DataFrame 或文件，用 PyGraphistry MCP 或 pygraphistry 技能。
连接：POST /mcp 上的 Streamable HTTP。tools/call 需在 Authorization 头携带凭证，initialize 与 tools/list 不需要。支持两种凭证，推荐个人密钥（不过期，长期运行的智能体不会中途 401）：个人密钥 key_id:key，可用 Authorization: Bearer <key_id>:<key> 或 PersonalKey <key_id>:<key>；查看者 JWT 约一小时过期。个人密钥在账户页 /users/personal/key/ 创建。initialize 返回 Mcp-Session-Id 响应头，后续每次请求需作为 mcp-session-id 头回传，与工具接收的 Graphistry 会话 session_id 不同；传输会话闲置 5 分钟后过期，返回 404 时应重新 initialize 重试。服务器当前协议版本 2024-11-05。
会话模型：除 list_sessions 外，工具都需要 session_id 指向活跃会话。客户端不能创建会话，会话因用户在浏览器中打开图而存在，用 list_sessions 发现。只传用户给定的会话；list_sessions 只返回裸 id，无法区分，用户开两个图时自行发现可能答错图。只有所有者可变更，凭证用户必须是持有该会话浏览器的用户，否则集合工具返回 403；非所有者若可访问底层数据集，读取仍可成功。标签页关闭即无会话，返回 410；list_sessions 可能返回 [] 而会话仍存活，空不等于无会话。其他状态：403 Talk2Graph 未启用（不可重试）、503 权益检查不可用（可重试）、504 工具调用超时（可重试）、400 缺 mcp-session-id、404 未知或过期 mcp-session-id（需重新 initialize）。
工具面：读取类有 list_sessions、get_session_info(session_id)、query_graph(session_id, gfql_operations, 可选 output_type/format)、list_collections(session_id)；变更类会改变用户所见，有 create_collection(session_id, name, gfql_operations, node_color 或 palette 之一)、update_collection、delete_collection、reorder_collections、reset_collections。query_graph 在表达式命名列时最多返回 50 行，未命名时 20 行；create_collection 最多保留 10 个集合，同名替换，30 秒内相同调用返回缓存结果；list_collections 只报告本 MCP 会话创建的集合。gfql_operations 是 JSON 编码字符串而非嵌套对象；order 按从上到下列集合 id，首个渲染在最上层；update_collection 省略字段即保持不变，勿传 null。
GFQL 传输：作为 JSON 字符串发送，需要 Node、Edge、Call、Let、Ref 等操作类型。Edge 会遍历并返回匹配的关系子图，不投影单一端点类型；每步行管道步骤（rows、group_by、order_by、limit）都是 Call；Let 与 Ref 作为顶层对象传递，不包裹在数组中。query_graph 也接受一个只读 Cypher 字符串。
静默失败情形：某些写法返回 success: true 但结果错误或为空，零行不能证明真实为零。filter_nodes_by_dict/filter_edges_by_dict 只匹配精确存储值，谓词对象不匹配任何内容。IP 内外部属性为派生属性，需先检查实际 IP 列；除非数据集另有说明，RFC1918 IPv4（10/8、172.16/12、192.168/16）、回环、链路本地、未指定、组播及共享 CGNAT（100.64/10）视为非外部，IPv6 同理；文档保留示例地址 198.51.100.0/24 与 203.0.113.0/24 不是 RFC1918 内网地址。两个图过滤器要放在 rows 之前。where_rows 中 filter_dict 只匹配精确值，比较需用 expr。
会显式报错的情形：rows 默认 table 为 nodes，按边列分组须加 {"table": "edges"}；Edge 的 direction 必须是 forward、reverse、undirected 之一，both 无效；裸的 rows/group_by/order_by/limit 无效，须包在 Call 中；谓词类型名区分大小写（GT 可用，gt 失败）；create_collection 只接受 JSON GFQL，Cypher 仅 query_graph 接受；create_collection 拒绝不再标识图节点的表达式（分组、投影掉 id、重命名或删除 id、读取边表），也拒绝按社区列排序，拒绝信息会指明修复方式。若因服务无法求值而拒绝，应报告失败而非改写重试。
工作流：list_sessions 找活跃会话 → get_session_info 获取模式（列表截断时括号内为真实总数，列缺失不等于不存在；unavailable 视为检查失败）→ 过滤前先检查存储值，比较区分大小写 → 用 query_graph 验证表达式 → 原样复用已验证 JSON 调用 create_collection 并报告匹配数（计数不可得时报告“applied, count unavailable”）。
决策：图已打开且任务是查询或重新着色时用本技能；GFQL 以 Python AST 对象或笔记本中 g.gfql() 编写时转 pygraphistry-gfql；构建或上传图转 pygraphistry；认证、上传与数据集端点转 graphistry-rest-api。
安全：凭证放环境变量，绝不硬编码；凭证放 Authorization 头，不放 URL 查询参数，也不放入模型上下文的工具参数。变更工具对用户可见，仅当用户要求改变可视化时才创建、更新或删除集合。