Skip to content

[BUG] MCP describe_method fails for methods named list: DESCRIBE METHOD cannot parse a keyword method name #926

Closed

Description

@jeffreyaven

Summary

In v1.0.888 the MCP describe_method tool fails for every method named list, with a parser syntax error. list is the most common method name across providers, so the tool cannot describe the primary SELECT method of most resources. Passing the method name double-quoted ("list") works.

The tool sends DESCRIBE METHOD EXTENDED <provider>.<service>.<resource>.<method> with the method unquoted, and in stackql-parser v0.0.17-alpha05 the token LIST is in neither reserved_keyword nor non_reserved_keyword, so it cannot be a DESCRIBE METHOD segment.

Environment

  • stackql 1.0.888, commit f7b4116, build date 2026-11-05T00:26:03Z (from server_info)
  • MCP transport stdio, sql_backend sqlite3, mode safe, Windows
  • google provider v26.08.00446 (the latest in the public registry)

To reproduce

Call the MCP describe_method tool with:

{"provider": "google", "service": "storage", "resource": "buckets", "method": "list"}

Result:

failed to extract query results: error:  You have an error in your stackql syntax; parser error: Code: INVALID_ARGUMENT
syntax error at position 53 near 'list'

Controls, same server and provider:

  • "method": "get" returns the get contract.
  • "method": "\"list\"" (the name double-quoted) returns the list contract: project as input_required, and the output columns acl through website.

Every list method tried fails the same way, on google, oci, ovh and railway resources. This came up while verifying documentation examples against the latest providers.

Root cause

  1. At f7b4116, GetDescribeMethod builds the statement by concatenation, with the method unquoted: mcp_service_stackql.go#L191-L208. Position 53 is the end of list in DESCRIBE METHOD EXTENDED google.storage.buckets.list.
  2. In stackql-parser v0.0.17-alpha05 (pinned in go.mod):
    • The DESCRIBE METHOD rule takes four reserved_table_id segments: sql.y#L2248-L2251.
    • reserved_table_id is table_id | reserved_keyword: sql.y#L3910-L3915.
    • table_id is id_or_var | non_reserved_keyword: sql.y#L3900-L3908.
    • "list" lexes as the keyword LIST (token.go#L255). LIST is used only by REGISTRY LIST (sql.y#L886-L896) and is listed in neither keyword production, so a bare list is rejected where the rule expects an identifier. A double-quoted name lexes as an identifier, which is why the workaround works.

Status on main

e86ce1a (#909, 2026-11-13) replaced the document-backed path: describe_method now queries stackql_preview.metadata.method_fields with the method as a quoted string literal, which avoids the parser for document-backed providers. No release contains it yet (v1.0.888 is the latest).

What remains on main (c4c58ff, still pinning v0.0.17-alpha05):

  • The stackql_preview branch of GetDescribeMethod still formats an unquoted DESCRIBE METHOD: mcp_service_stackql.go#L202-L210.
  • The DESCRIBE METHOD statement itself, typed in stackql shell or passed to stackql exec, cannot name a method called list. The 1.0.888 tool fails because it sends exactly that statement.
  • A static check of the v0.0.17-alpha05 grammar finds 27 keywords in the same position, usable as neither reserved nor non-reserved identifiers: all, alter, analyze, _binary, _utf8mb4, _utf8, _latin1, cast, column, constraint, do, format, full, group_concat, list, pull, registry, release, savepoint, sql_cache, sql_calc_found_rows, sql_no_cache, stream, tree, traditional, vitess, work. A method with any of these names should hit the same error in DESCRIBE METHOD; only list was tested, and it is the one that matters most in practice.

Expected behavior

describe_method and DESCRIBE METHOD accept any method name a provider declares, including list, without quoting.

Suggested fix

  • Release fix-method-schema-discovery #909, which fixes the MCP path for document-backed providers.
  • In stackql-parser, accept LIST (and the other keywords above that can sensibly be names, such as PULL, REGISTRY, RELEASE, STREAM and FORMAT) as identifiers, for example as non_reserved_keyword, checking for conflicts with REGISTRY LIST.
  • Quote the identifiers in the stackql_preview branch of GetDescribeMethod, or route it through the same metadata query.
  • Add robot tests for DESCRIBE METHOD <provider>.<service>.<resource>.list and for the MCP describe_method tool with method set to list.

Workaround until then: pass the method name double-quoted, "list".

Activity

  1. added
    bugSomething isn't working
    goPull requests that update go code
    on Nov 15, 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

    bugSomething isn't workinggoPull 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