Repository navigation
Description
Summary
Parent: #699. OpenAI has invited StackQL into the ChatGPT plugin directory with an expedited review, target Friday 2026-11-13. The directory validator rejects any MCP server whose tools do not declare readOnlyHint, destructiveHint and openWorldHint as explicit booleans (annotations_required), and the plugin guidelines ask for a human-readable title and a description that says when to use each tool.
This issue covers the server-side changes only (Go and markdown under pkg/mcp_server and docs). Packaging and CI are tracked in #893 and the website changes in stackql/stackql.io#305.
Current state
tools/list today (go-sdk v1.8.0: ReadOnlyHint and IdempotentHint are plain bools and always serialise, DestructiveHint and OpenWorldHint are *bool with omitempty):
| Tool | readOnlyHint | destructiveHint | openWorldHint | Source |
|---|---|---|---|---|
| server_info, list_providers, list_services, list_resources, list_methods, describe_method, validate_select_query, list_registry, query_library_search, query_library_get | true | absent | absent | derived in deriveToolAnnotations (pkg/mcp_server/gate.go) |
| run_select_query | absent (no annotations object) | absent | absent | queryGate, class unknown |
| run_mutation_query, run_lifecycle_operation | false | true | absent | registerExecQueryTool |
| pull_provider, reload_credentials | false | false | absent | explicit |
No tool sets Title.
Changes
pkg/mcp_server/gate.go:deriveToolAnnotationsreturns the full hint set for select-class tools (readOnlyHint: true,destructiveHint: false,openWorldHintper tool).openWorldHintistruefor tools that reach the network (list_registry,pull_provider,run_select_query,run_mutation_query,run_lifecycle_operation) andfalsefor tools that only read local state (server_info,list_*,describe_method,validate_select_query,query_library_*,reload_credentials).run_select_query: explicit annotationsreadOnlyHint: false,destructiveHint: false,openWorldHint: true. Keep the existing invariant that SQL-carrying tools never claim read-only; the policy gate stays the enforcement point. Confirm the gate refuses non-SELECT statements submitted through this tool before claimingdestructiveHint: false.run_mutation_query,run_lifecycle_operation,pull_provider,reload_credentials: addopenWorldHintas above; existingdestructiveHintandidempotentHintvalues unchanged.Titleon every tool (mcp.Tool.Title, go-sdk 1.8.0), sourced alongside the descriptions mastered inpkg/mcp_server/content/tools/*.mdso there is one place to edit.- Review the fifteen descriptions in
pkg/mcp_server/content/tools/*.mdagainst the OpenAI guidelines: action-oriented name, says when to use the tool, no mention of HTTP mechanics. Expect wording edits only. docs/mcp.md(annotation paragraph at about line 150): document the full hint set and theopenWorldHintrule.- Tests: update the expectations in
pkg/mcp_server/tools_test.goandpkg/mcp_server/query_library_test.go, and add one assertion that every published tool carries all three hints non-nil so the invariant cannot regress silently.
Do not change response shapes. The guidelines discourage timestamps in tool results, and run_mutation_query returns {messages, timestamp}. Leave it as is and justify it in the review notes; changing the DTO would ripple into the embedded SDKs.
Must not break
The same tools/list is consumed by every surface, so the change must be additive:
- Claude Desktop MCPB bundle (
packaging/mcpb,manifest.template.json) and the Anthropic Connector Directory submission that is already in. - Claude Code and other clients via npm
@stackql/mcp-serverand PyPIstackql-mcp-server, the OCI image, and the official MCP registry entryio.github.stackql/stackql-mcp. - Codex repo marketplace plugin (
.agents/plugins/marketplace.json). - Embedded SDKs: cargo
stackql-mcp, Go mirrorstackql/stackql-mcp-go, NuGetStackQL.Mcp. - Streamable HTTP mode with the static bearer token.
Invariants: tool names, input and output schemas and DTOs unchanged; mode semantics (safe, read_only, unsafe) untouched; annotations advisory only; no second init() in any file; no new stackql_context.py entries.
Verification: go test ./pkg/mcp_server/..., full robot suite (MCP scenarios), packaging/mcpb/scripts/smoke-test.py, packaging/openai-plugin/scripts/smoke-test.py, and a before/after diff of tools/list JSON showing only annotations and title fields changed.
Out of scope
Plugin packaging, CI and ZIP build (#893); stackql.io pages (stackql/stackql.io#305).
Activity
multiple-fixes