[UPDATE PRIMITIVE] Add MCP prompt argument completions for VS Code slash command UX

[Copilot]

📝 Update Information

Primitive Details

• Type: Prompts
• Name: All 14 workflow prompts
• Update Category: Feature Enhancement

⚠️ CRITICAL: PR SCOPE VALIDATION

✅ ALLOWED FILES:

• Server implementation files (server/src/**/*.ts)
• Updated primitive implementations
• Updated or new test files (server/test/**/*.ts)
• Extension test files (extensions/vscode/test/**/*.ts)
• Build configuration (extensions/vscode/esbuild.config.js)

🚫 FORBIDDEN FILES:

• No unrelated files included

---

🛑 MANDATORY PR VALIDATION CHECKLIST

• ONLY server implementation files are included
• NO temporary or output files are included
• NO unrelated configuration files are included
• ALL existing tests continue to pass
• NEW functionality is properly tested

---

• Impact Scope: Moderate — touches all prompt registrations but via a single wrapper function
• Breaking Changes: No
• API Compatibility: Enhanced (additive only — completion/complete responses are new)
• Performance Impact: Neutral (completions are lazy, only invoked on user keystroke)

🎯 Changes Description

Current Behavior

Workflow prompts used as VS Code Copilot Chat slash commands show raw text input fields for all parameters. Users must manually type full file paths for CodeQL queries, databases, SARIF files, etc., with zero guidance.

Updated Behavior

Prompt parameters now provide auto-complete suggestions via the MCP SDK's completable() function. VS Code shows a filtered dropdown as the user types:

• language — filters SUPPORTED_LANGUAGES by prefix
• queryPath — discovers .ql/.qlref files in workspace
• sarifPath/sarifPathA/sarifPathB — discovers .sarif/.sarif.json files
• database/databasePath — lists CodeQL database directories from CODEQL_DATABASES_BASE_DIRS and workspace
• workspaceUri/packRoot — finds directories containing codeql-pack.yml

Motivation

The VS Code MCP integration supports completion/complete for prompt arguments. The MCP SDK already ships completable() — we just weren't using it.

🔄 Before vs. After Comparison

Functionality Changes

// BEFORE: raw shape, no completions
server.prompt('explain_codeql_query', description,
  toPermissiveShape(explainCodeqlQuerySchema.shape),
  handler);

// AFTER: completable-wrapped shape — VS Code shows filtered dropdown
server.prompt('explain_codeql_query', description,
  addCompletions(toPermissiveShape(explainCodeqlQuerySchema.shape)),
  handler);

API Changes

No schema changes. addCompletions() clones each targeted field to a fresh z.string() with completable() metadata attached. Fields without registered completers pass through unchanged. The completion/complete MCP capability is automatically advertised by the SDK when any completable field exists.

Output Format Changes

New completion/complete responses:

{
  "completion": {
    "values": ["java", "javascript"],
    "hasMore": false,
    "total": 2
  }
}

🧪 Testing & Validation

Test Coverage Updates

• Existing Tests: All 1337 server tests pass (60 files), all 160 extension unit tests pass
• New Test Cases: 37 unit tests for completion providers and addCompletions utility
• Regression Tests: Existing workflow-prompts.test.ts (309 tests) validates schema consistency
• Edge Case Tests: ZodEnum handling, mutation safety, empty workspace, skipped directories

Test Results

• Unit Tests: 1337/1337 pass (server), 160/160 pass (extension)
• Integration Tests: 12 new e2e tests in mcp-completion-e2e.integration.test.ts

📋 Implementation Details

Files Modified

• New: server/src/prompts/prompt-completions.ts — completion providers + addCompletions() utility
• Modified: server/src/prompts/workflow-prompts.ts — 1 import + 14 lines: wrap each server.prompt() shape
• New: server/test/src/prompts/prompt-completions.test.ts — 37 unit tests
• New: extensions/vscode/test/suite/mcp-completion-e2e.integration.test.ts — 12 e2e tests
• Modified: extensions/vscode/esbuild.config.js — add new test entry point

Code Changes Summary

• Type Safety: cloneStringType validates input is ZodString or ZodEnum, throws on unexpected types
• Mutation Safety: addCompletions clones schemas before attaching completable() to avoid mutating shared schema constants

Dependencies

• No New Dependencies: Uses existing @modelcontextprotocol/sdk v1.29 (completable export)

🔗 References

External References

• VS Code MCP developer guide — Prompts with completions
• MCP SDK completable() API

🚀 Compatibility & Migration

Backward Compatibility

• Fully Compatible: No breaking changes. Clients that don't support completion/complete simply never call it.

API Evolution

• Enhanced Parameters: Existing parameters gain auto-complete; no parameter additions or removals
• Maintained Contracts: All prompt schemas, handlers, and validation unchanged

👥 Review Guidelines

For Reviewers

• ⚠️ SCOPE COMPLIANCE: 5 files, all directly related
• ⚠️ BACKWARD COMPATIBILITY: Zero changes to prompt handler logic or schemas
• Functionality: addCompletions() is a pure wrapper — prompt behavior unchanged
• Test Coverage: 37 new unit tests + 12 e2e tests

Testing Instructions

npm run build-and-test        # Full suite
npm test -w server             # Server tests (1337 tests)
npm run test:coverage -w extensions/vscode  # Extension unit tests (160 tests)

📊 Impact Assessment

Server Impact

• Startup Time: Negligible — addCompletions runs once during registration
• Runtime Stability: Completion callbacks are async, error-resilient (catch + empty array)
• Resource Usage: File scans capped at 50 results, 8 levels deep, skip node_modules/.git

AI Assistant Impact

• Enhanced User Experience: Users pick from dropdowns instead of typing raw paths

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• update.code.visualstudio.com
  • Triggering command: /opt/hostedtoolcache/node/24.13.0/x64/bin/node node scripts/download-vscode.js k/codeql-develop. gh ensi�� ST_VAR:-not_set} nt-mcp-server/node_modules/vitest/suppress-warnings.cjs cal/bin/echo echo ${MALICIOUSbash bash Query.ql nt-mcp-server/node_modules/vitest/dist/workers/forks.js test�� n/echo sh node_modules/.bin/bash (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Snapshot Warnings

⚠️: No snapshots were found for the head SHA 6e9f718.

Ensure that dependencies are being submitted on PR branches and consider enabling retry-on-snapshot-warnings. See the documentation for more information and troubleshooting advice.

Scanned Files

None