Skip to content

Explicit MCP tool annotations and titles for the ChatGPT plugin directory submission #892

Closed

Description

@jeffreyaven

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: deriveToolAnnotations returns the full hint set for select-class tools (readOnlyHint: true, destructiveHint: false, openWorldHint per tool). openWorldHint is true for tools that reach the network (list_registry, pull_provider, run_select_query, run_mutation_query, run_lifecycle_operation) and false for tools that only read local state (server_info, list_*, describe_method, validate_select_query, query_library_*, reload_credentials).
  • run_select_query: explicit annotations readOnlyHint: 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 claiming destructiveHint: false.
  • run_mutation_query, run_lifecycle_operation, pull_provider, reload_credentials: add openWorldHint as above; existing destructiveHint and idempotentHint values unchanged.
  • Title on every tool (mcp.Tool.Title, go-sdk 1.8.0), sourced alongside the descriptions mastered in pkg/mcp_server/content/tools/*.md so there is one place to edit.
  • Review the fifteen descriptions in pkg/mcp_server/content/tools/*.md against 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 the openWorldHint rule.
  • Tests: update the expectations in pkg/mcp_server/tools_test.go and pkg/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-server and PyPI stackql-mcp-server, the OCI image, and the official MCP registry entry io.github.stackql/stackql-mcp.
  • Codex repo marketplace plugin (.agents/plugins/marketplace.json).
  • Embedded SDKs: cargo stackql-mcp, Go mirror stackql/stackql-mcp-go, NuGet StackQL.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

  1. added
    enhancementNew feature or request
    goPull requests that update go code
    on Nov 4, 2026
  2. added a commit that references this issue on Nov 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestgoPull requests that update go code

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions