[stavp-star]

Closes #47 · Part of epic #49 · Stack position 13/15. Base: deep-agent/48-subagents-prompts (#61), auto-retargets on merge.

What

deep_agent/utils_mcp.py loads a curated subset of Utils-Server tools from the Jarvis Registry gateway. I followed the registry's own deepagents sandbox (jarvis-registry/src/app/api/v1/endpoints/sandbox.py) and Utils-Server/docs/registry-integration.md.

• Connection: langchain-mcp-adapters streamable HTTP to {JARVIS_GATEWAY_URL}/mcp/{JARVIS_MCP_NAMESPACE}/ (default namespace global), with Authorization: ApiKey <JARVIS_API_KEY>, the gateway's API-key scheme.

• Allow-list and allocation. Each tool goes only to the agent that needs it:

  Agent	Utils-Server tools
  main	datetime_parse_relative_expression, text_normalize, trino_validate_spatial_expression
  value-resolver	datetime_parse_relative_expression, text_normalize, geo_create_buffer, geo_validate_geometry
  schema-scout / result-verifier	none

  Gateway names are matched after sanitising, including namespaced forms like utils__text_normalize. Write tools and trino_run_query are never exposed: all SQL stays on the guarded execute_trino_query path ([Deep Agent 3/15] Enforce read-only SQL, AST-level LIMIT and safe identifiers (#35) #52).

• Envelope: every tool is wrapped in {ok, data, error}. Gateway errors ({"error", "status_code", "response_text"}) and exceptions become EXTERNAL_TOOL_ERROR, with the hint "continue without it".

• Graceful degradation: with no URL, an unreachable gateway, or a timeout (UTILS_MCP_TIMEOUT_S, default 10 s), the agent starts without these tools and logs why. Allow-listed tools missing on the gateway (e.g. still pending approval) are logged by name.

• acreate_deep_agent() loads the tools; the CLI and deep-agent-bench use it. create_deep_agent(extra_tools=...) stays sync for tests and embedding.

Skills, scoped to what the tools actually do (checked against the Utils-Server source):

• temporal-analyst: datetime_parse_relative_expression resolves point-in-time Hebrew phrases (לפני 3 ימים, יום ראשון הבא). It returns an instant, not a period ("חודש שעבר" = one month ago) and rejects "השבוע", so the skill's period rules still build the bounds.
• spatial-analyst: trino_validate_spatial_expression checks that an expression is valid and its functions exist, and can evaluate it on one row. geo_create_buffer returns GeoJSON, used with from_geojson_geometry(...).

Dependency: langchain-mcp-adapters>=0.2,<0.3. 0.3.0 imports streamable_http_client, which needs a newer mcp SDK than the locked 1.12.4. Bumping mcp would touch the Jeen client the legacy graph uses, so that's left for a separate change.

Acceptance criteria

• Tools load via MCP at startup, with a timeout and graceful fallback (tests: disabled, connection error, timeout)
• Temporal questions use datetime_parse_relative_expression in traces; the Hebrew "this week" case returns Sunday-start bounds. Partial: the tool can't produce periods, so the Sunday bounds come from the skill ([Deep Agent 11/15] One owner per topic, fix incorrect skill guidance, lint it in CI (#40) #60). Trace evidence is pending live gateway access.
• Spatial questions run trino_validate_spatial_expression before execution (in traces). Pending live.
• Execution accuracy on temporal and spatial subsets ≥ baseline. Pending ([Deep Agent] Unit tests + offline eval harness (legacy graph vs deep agent) as the migration go/no-go gate #44 harness).
• [~] Added latency per MCP call: each wrapped call measures its own latency (debug log, plus latency_ms on gateway errors). The p50/p95 report is pending live.

Definition of done: pending (infra / registry admin)

• Provision the agent's registry identity with trino:read, geo:read, text:read, datetime:read, and approve the 5 tools in the registry
• Remove rules from skills that the tools now cover, once traces show they're used reliably

Testing

• tests/deep_agent/test_utils_mcp.py: 12 tests (connection, allocation, allow-list exclusions, de-duplication, envelope, error mapping, degradation, offered tools in-agent and per subagent)
• Full suite (excluding real-services e2e): 386 passed, 2 skipped

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: f6b0268b-9606-473c-b9ca-4b2e0ec09d5b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[benb-mafat]

approved, does it always have access? also what other tools are there why dont we use more