Repository navigation
[AskT49 SQL tool] feat(mcp): SQL analysis tools for signed-in users - #481
SylvainGravejat wants to merge 10 commits into
Conversation
client.assistantQueries wraps the user-scoped /v2/assistant_queries, /v2/assistant_views and /v2/assistant_guides endpoints through Transport.executeManual, so they share the SDK's auth, X-Account-ID, error mapping and timeout path. Calls require accountId; POST queries are not retried. These endpoints sit outside the API-key OpenAPI contract, so their response types live in the manager. Rebuilt from #436 onto current main. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Adds sql_query, describe_views, query_guide and get_query_result in a new analytics toolset. They call the Terminal49 API's assistant query, view and guide endpoints, which authorize every call. The gateway serves analytics only to signed-in (OAuth) users, and only after GET /v2/assistant_views confirms the account has SQL access. That answer is cached for a minute per credential and account; a denial hides the tools and a transient failure keeps them listed. API keys, agent tokens and the shared token never get them, and an operator allowlist without analytics turns them off. The SQL tools use a client that never retries, run identical concurrent queries once, pass the API's messages through for rejected queries and unknown topics, and stop the model on rate limits and service failures. Co-Authored-By: Alex Garcia <alex.garcia@terminal49.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Alex Garcia <alex.garcia@terminal49.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The gateway mints a new API token for each signed-in request, so the SQL access check and the duplicate-query check now key on the caller's own token; before, neither could ever hit. The access check fits within the request deadline, and SQL calls time out after 20 seconds instead of running into the function limit. The SQL length limit counts bytes, as the API does. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Drops the CSV download advice, which MCP clients can't use, and no longer promises that duplicate queries always run once. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
Shadow risk calibration
Calibration result: agreement. Shadow risk never blocks or enables merge. Keep it in observation mode until roughly 50 pull requests have human-reviewed labels, then calibrate before considering any policy use. |
…-signed-in-users-sql_query Resolve conflicts in the toolset docs, the MCP README, the record-writes gateway test and the tools/list snapshot. The snapshot is regenerated, not hand-merged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01V8cPhktNpguVMk39bAstza
Main now requires every read-only tool to be marked idempotent and keeps the server instructions under 2 KB for every toolset selection. Mark sql_query idempotent like the other read tools (clients ignore idempotentHint on read-only tools), and cut the SQL paragraph of the instructions to one pointer: the sql_query description already carries the query guidance. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01V8cPhktNpguVMk39bAstza
With main's tracking lifecycle tools, the registry now holds 38 tools. List the four analytics tools in the README and update the totals in the README and TOOLS_OVERVIEW. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01V8cPhktNpguVMk39bAstza
CodeQL flagged the plain SHA-256 of the API token in sqlScope as an insufficient password hash. The token is a high-entropy credential used only as an in-memory cache and dedup key, so follow main's credentialHash pattern in write-kit.ts and key an HMAC with it instead. The scope stays deterministic per credential, base URL and account. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01V8cPhktNpguVMk39bAstza
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 788e00e18f
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| const wait = | ||
| details && typeof details === 'object' && 'retry_after' in details | ||
| ? details.retry_after | ||
| : undefined; |
There was a problem hiding this comment.
Read the SDK's Retry-After value
When the assistant endpoint returns a 429 with the documented Retry-After header but no nonstandard retry_after body field, Transport places the delay in RateLimitError.retryAfterMs, while this branch reads only error.details.retry_after. The SQL tool therefore omits the wait time even though its response tells the model to explain it; use retryAfterMs (converted to seconds), optionally retaining the body field as a fallback.
Useful? React with 👍 / 👎.
Linear: DEV-13504
Adds read-only SQL analysis to the MCP server for signed-in users whose account has SQL access. It supersedes #436: the SDK manager is cherry-picked from it with its authorship, and most of the tool, discovery and caching code is ported from it onto the tool registry.
What it adds
Four tools in a new
analyticstoolset:query_guidedescribe_viewssql_querySELECTover theassistant_*views; returns a sample of rows and aresult_idget_query_resultWho gets the tools
usercredentials (OAuth) getanalytics. API keys, agent tokens and the shared token never do, even whenT49_MCP_TOOLSETSlists it.GET /v2/assistant_viewsconfirms the account has SQL access.T49_MCP_TOOLSETSunset, signed-in users getanalyticson top of the defaults. With it set, it must listanalytics, which makes the variable a kill switch.How the SQL calls behave
Docs
mcp/sql-queries.analyticsadded to the toolset docs.Tests
tools/sql-query.test.ts, and gateway cases intests/api-handler.test.ts.analyticsis requested.npm run agent-verifypasses. The smoke test still lists 30 tools for an API-key session.Before marking ready
Live check on a Vercel preview against staging:
The dashboard agent keeps its own SQL tools for now. Moving it to these tools, which means allowing
agentcredentials, is a separate change.🤖 Generated with Claude Code
Need help on this PR? Tag
@codesmith-botwith what you need.Fix both timeout gaps before merging so slow upstream calls return errors instead of losing the MCP response.
Fix with agent prompt
Summary
Adds four SQL analysis tools for signed-in users, with account access discovery, concurrent-query sharing, an SDK manager, and documentation.
Diagram
Reviews (1) · Last reviewed commit: "docs(mcp): add the analytics toolset to ..." · Reviewed by Greptile