new-tool

name	new-tool
description	Scaffold a new SAP Datasphere MCP tool across all four required layers (client method, business-logic function, @server.tool wrapper, example + test) following project conventions. Use when adding a new datasphere_* tool.
disable-model-invocation	true

new-tool — scaffold a SAP Datasphere MCP tool

Adding a tool to this server is a fixed 4-layer ritual. Do all four, in order, and keep the conventions in CLAUDE.md. Never skip the example or the test.

Inputs to gather first

• Tool name — datasphere_<verb> (e.g. datasphere_list_views).
• What it returns — rows (QueryResult), metadata, or a summary dict.
• Which Datasphere API — catalog vs. consumption (relational / analytical), and whether it needs a new HTTP call or can reuse an existing DatasphereClient method.
• Row-returning? — if yes, which cap applies (max_rows_preview, max_rows_query, max_rows_profile, max_rows_analytical, max_search_results).

Layer 1 — src/sap_datasphere_mcp/client.py

Only if a new HTTP call is needed. Add an async def on DatasphereClient. Rules:

• Get the token via await self.oauth.get_access_token().
• Build URL candidates from self._catalog_prefixes() or self._consumption_prefixes() — never hardcode /dwc or /datasphere. Include both URL-shape variants the way preview_asset_data / query_relational do.
• Call self._get_with_fallback(urls=..., headers=..., params=..., allow_top_fallback=...).
• Escape OData key literals: space_id.replace("'", "''").
• Return a typed model from models.py (Space, Asset, QueryResult) where it fits.
• Bump the # Version: vN header comment.

Layer 2 — module-level async def in src/sap_datasphere_mcp/tools/tasks.py

This is the business logic + guardrails layer (NOT yet the MCP wrapper). Rules:

• Honor mock_mode (use the _Mock* client path already in the file).
• Clamp any row argument with _cap_int(value, cap) and report cap_applied in meta.
• On failure return the _make_error(code, message, details) shape — keep messages short and LLM-friendly. Do not leak credentials or full tokens.
• Return plain JSON-serializable dicts/lists.

Layer 3 — @server.tool(...) wrapper inside register_tools(server) (same file)

• Add near the other @server.tool(...) registrations (~line 1700+).
• name="datasphere_<verb>", a one-line description written for an LLM caller.
• The wrapper just validates/forwards args to the Layer-2 function and returns its result.

Layer 4 — example + test

• examples/demo_mcp_<verb>.py — mirror an existing demo_mcp_*.py (they construct the server / call the tool end-to-end).
• tests/test_<area>.py — add a test that runs with DATASPHERE_MOCK_MODE set so it needs no live tenant. Mirror the closest existing test module.

Verify

pip install -e ".[dev]"   # if not already
ruff check . ; ruff format .
pytest -q

Report which files you created/edited and confirm the new tool shows up in register_tools.