René's URL Explorer Experiment

Title: mcp: trim tool surface, add prompt + lifecycle, expand server_info by jeffreyaven · Pull Request #651 · stackql/stackql · GitHub

Open Graph Title: mcp: trim tool surface, add prompt + lifecycle, expand server_info by jeffreyaven · Pull Request #651 · stackql/stackql

X Title: mcp: trim tool surface, add prompt + lifecycle, expand server_info by jeffreyaven · Pull Request #651 · stackql/stackql

Description: Summary PR1 of a two-PR series prepping the MCP server for richer client integration. This PR is purely about shaping the tool surface; PR2 will add server modes, elicitation-based approval, and an audit subsystem. 11 tools (down from 18) + 1 prompt: prune placeholders/duplicates, rename the three query tools, add run_lifecycle_operation, describe_resource, describe_method. Convert prompt_write_safe_select_tool to an MCP prompt registered via Server.AddPrompt. Per-tool rendering: drop the runtime format parameter; new pkg/mcp_server/render exposes RenderTable (uniform multi-row) and RenderKV (sparse / single-record). MCP responses carry both rendered text and a typed DTO. Expanded server_info: adds sql_backend and provider_registry derived from runtime context. Drops redundant name/info. Renames Go field IsReadOnly -> ReadOnly (JSON tag is_read_only preserved). Read-only gate: run_mutation_query and run_lifecycle_operation refuse when Config.Server.IsReadOnly is true. New EnabledPrompts allowlist mirroring EnabledTools (independent). Delete orphaned pkg/presentation package - sole consumer was the removed MCP renderer. Tool surface (final) Tool Renderer Notes server_info KV now reports sql_backend, provider_registry, is_read_only list_providers Table list_services Table requires provider list_resources Table requires provider, service list_methods Table requires provider, service, resource describe_resource KV new; replaces describe_table describe_method KV new shape: {provider, service, resource, method}, always EXTENDED validate_select_query KV renamed from validate_query_json_v2 run_select_query Table renamed from query_json_v2 run_mutation_query KV renamed from exec_query_json_v2; refused in read-only run_lifecycle_operation KV new; routes through Backend.ExecQuery like mutations but distinct contract for EXEC semantics; refused in read-only Prompt: write_safe_select (static text from ExplainerPromptWriteSafeSelectTool). Tools removed greet, db_identity, query_v2, query_v3, query_validate_json_v2, list_tables_json, list_tables_json_page, describe_table, get_foreign_keys, find_relationships, prompt_write_safe_select_tool (now a prompt). Breaking changes describe_method input changed from {method_path, extended} to {provider, service, resource, method}. Always EXTENDED now. QueryResultDTO is now {rows} (the format, row_count, raw, warnings fields are gone). ValidationResultDTO is now {valid, errors} (the message field is gone). ServerInfoDTO drops name/info, adds sql_backend/provider_registry. Design notes for reviewers pkg/mcp_server package invariant preserved: zero imports from internal/... or any-sdk. All data crossing the boundary is primitive types or interfaces. The new pkg/mcp_server/render is also pure. ServerBuildInfo follows the data-carrier rule in AGENTS.md: unexported interface (serverBuildInfo), unexported implementation, single exported constructor (NewServerBuildInfo). cmd-side callers use := to bind the inferred unexported type — Go is fine with this. SQLBackend / ProviderRegistry plumbing: cmd/mcp.go decodes runtimeCtx.SQLBackendCfgRaw via dto.GetSQLBackendCfg (uses SQLDialect/DBEngine) and runtimeCtx.RegistryRaw via a small YAML probe (url then localDocRoot). Both are best-effort: empty string if the blob is missing or malformed. JSON wire compatibility: the is_read_only JSON tag is preserved on the renamed Go field so existing robot assertions continue to pass. Out of scope (PR2): no Mode enum, no classifyQuery helper, no four-mode gate logic, no req.Session.Elicit, no AuditSink, no audit middleware. The existing IsReadOnly *bool is the sole gate, wired at the two write-tool handlers. Test plan go build ./... clean go vet ./... clean golangci-lint run on ./pkg/mcp_server/..., ./internal/stackql/mcpbackend/..., ./internal/stackql/cmd/... -> 0 issues go test --tags sqlite_stackql -count=1 ./... -> all packages pass Unit tests added 13 new tests in pkg/mcp_server/tools_test.go exercise every tool end-to-end via mcp.NewInMemoryTransports: TestTool_ServerInfo_RendersKVAndStructured TestTool_ListProviders_RendersTable TestTool_ListServices_ForwardsHierarchy TestTool_DescribeResource_UsesKVRenderer TestTool_DescribeMethod_RequiresFourSegments TestTool_ValidateSelectQuery_SuccessAndFailure TestTool_RunSelectQuery_ForwardsRowLimit TestTool_RunMutation_RefusedInReadOnly TestTool_RunLifecycleOperation_PositiveAndReadOnly TestRegistration_EnabledToolsFilters TestPrompt_WriteSafeSelect_RegisteredAndReturnsCanonicalText TestPrompt_EnabledPromptsFilters Plus TestIsToolEnabled/TestIsPromptEnabled for allowlist semantics Plus four renderer tests in pkg/mcp_server/render/render_test.go Robot scenarios Renamed (tool action only) in surviving scenarios: validate_query_json_v2 -> validate_select_query query_json_v2 / query_v2 -> run_select_query exec_query_json_v2 -> run_mutation_query Updated: MCP HTTP Server Info Includes Version also asserts sql_backend + provider_registry. MCP HTTP Server Restricted Tools Allowlist keyed on server_info (fixture changed from ["greet"] to ["server_info"]). New: MCP HTTPS Describe Resource Canonical MCP HTTPS Describe Method Canonical — asserts a row with name == 'project' via list comprehension MCP HTTPS Run Lifecycle Operation Canonical — positive path against aws.transfer.servers.stop_server MCP HTTP Read Only Server Info Flag — asserts is_read_only: true against the new 9916 server MCP HTTPS Run Mutation Refused In Read Only — refusal for both write tools Start MCP Servers extended with a fifth server on 127.0.0.1:9916 with read_only: true. Removed 8 obsolete scenarios (Greet, DB Identity, Query V3, Foreign Keys, Find Relationships, Describe Table, Greeting Tool, Show Version SQL — the latter superseded by the expanded server_info). Robot suite run locally / in CI 🤖 Generated with Claude Code

Open Graph Description: Summary PR1 of a two-PR series prepping the MCP server for richer client integration. This PR is purely about shaping the tool surface; PR2 will add server modes, elicitation-based approval, and an...

X Description: Summary PR1 of a two-PR series prepping the MCP server for richer client integration. This PR is purely about shaping the tool surface; PR2 will add server modes, elicitation-based approval, and an...

Opengraph URL: https://github.com/stackql/stackql/pull/651

X: @github

direct link

Domain: github.com

Links:

Viewport: width=device-width