Address latest PR review comments

data-douser · data-douser · commit df4ce5e33183 · 2026-03-09T06:40:16.000-06:00
diff --git a/docs/ql-mcp/resources.md b/docs/ql-mcp/resources.md
@@ -4,20 +4,22 @@
 
 ## Overview
 
-The server exposes **8 static resources** and a set of **dynamic per-language resources** that supply AI assistants with CodeQL reference material. Resources are read-only and backed by `.md` files bundled with the server.
+The server exposes **10 static resources** and a set of **dynamic per-language resources** that supply AI assistants with CodeQL reference material. Resources are read-only and backed by `.md` files bundled with the server.
 
 ## Static Resources
 
-| Resource                       | URI                                         | Description                                                                       |
-| ------------------------------ | ------------------------------------------- | --------------------------------------------------------------------------------- |
-| CodeQL Query Basics            | `codeql://learning/query-basics`            | QL query writing reference: syntax, metadata, patterns, testing                   |
-| CodeQL Test-Driven Development | `codeql://learning/test-driven-development` | TDD theory and workflow for developing CodeQL queries                             |
-| CodeQL Performance Patterns    | `codeql://patterns/performance`             | Performance profiling and optimization for CodeQL queries                         |
-| CodeQL Server Overview         | `codeql://server/overview`                  | MCP server orientation guide: tools, prompts, resources, and workflows            |
-| CodeQL Server Prompts          | `codeql://server/prompts`                   | Complete reference of MCP prompts for CodeQL development workflows                |
-| CodeQL Server Queries          | `codeql://server/queries`                   | Overview of bundled tools queries: PrintAST, PrintCFG, CallGraphFrom, CallGraphTo |
-| CodeQL Server Tools            | `codeql://server/tools`                     | Complete reference of default MCP tools for CodeQL development                    |
-| CodeQL Security Templates      | `codeql://templates/security`               | Security query templates for multiple languages and vulnerability classes         |
+| Resource                       | URI                                           | Description                                                                       |
+| ------------------------------ | --------------------------------------------- | --------------------------------------------------------------------------------- |
+| CodeQL Query Basics            | `codeql://learning/query-basics`              | QL query writing reference: syntax, metadata, patterns, testing                   |
+| CodeQL Test-Driven Development | `codeql://learning/test-driven-development`   | TDD theory and workflow for developing CodeQL queries                             |
+| CodeQL Performance Patterns    | `codeql://patterns/performance`               | Performance profiling and optimization for CodeQL queries                         |
+| CodeQL Server Overview         | `codeql://server/overview`                    | MCP server orientation guide: tools, prompts, resources, and workflows            |
+| CodeQL Server Prompts          | `codeql://server/prompts`                     | Complete reference of MCP prompts for CodeQL development workflows                |
+| CodeQL Server Queries          | `codeql://server/queries`                     | Overview of bundled tools queries: PrintAST, PrintCFG, CallGraphFrom, CallGraphTo |
+| CodeQL Server Tools            | `codeql://server/tools`                       | Complete reference of default MCP tools for CodeQL development                    |
+| CodeQL Security Templates      | `codeql://templates/security`                 | Security query templates for multiple languages and vulnerability classes         |
+| CodeQL Query Unit Testing      | `codeql://guides/query-unit-testing`          | Guide for creating and running unit tests for CodeQL queries                      |
+| CodeQL Dataflow Migration      | `codeql://guides/dataflow-migration-v1-to-v2` | Guide for migrating from legacy v1 dataflow API to modern v2 module-based API     |
 
 ## Language-Specific Resources
 
diff --git a/extensions/vscode/test/suite/mcp-resource-e2e.integration.test.ts b/extensions/vscode/test/suite/mcp-resource-e2e.integration.test.ts
@@ -108,7 +108,7 @@ suite('MCP Resource Integration Tests', () => {
     const response = await client.listResources();
     const staticUris = response.resources
       .map(r => r.uri)
-      .filter(uri => uri.startsWith('codeql://server/') || uri.startsWith('codeql://templates/') || uri.startsWith('codeql://patterns/') || uri.startsWith('codeql://learning/'));
+      .filter(uri => uri.startsWith('codeql://server/') || uri.startsWith('codeql://templates/') || uri.startsWith('codeql://patterns/') || uri.startsWith('codeql://learning/') || uri.startsWith('codeql://guides/'));
 
     assert.ok(staticUris.length > 0, 'Should have at least one static resource');
 
diff --git a/server/dist/codeql-development-mcp-server.js b/server/dist/codeql-development-mcp-server.js
diff --git a/server/dist/codeql-development-mcp-server.js.map b/server/dist/codeql-development-mcp-server.js.map
diff --git a/server/src/resources/codeql-query-unit-testing.md b/server/src/resources/codeql-query-unit-testing.md
@@ -6,7 +6,7 @@ Guide for creating and running unit tests for CodeQL queries. For the broader TD
 
 There is no one single way to arrange CodeQL unit tests, though there are some commonalities.
 
-For a recommended setup that uses separate "qlpacks" for CodeQL queries versus tests, a given CodeQL query and associated unit test may be layed out on the filesystem like:
+For a recommended setup that uses separate "qlpacks" for CodeQL queries versus tests, a given CodeQL query and associated unit test may be laid out on the filesystem like:
 
 ```text
 <query-pack-root>/<optional-queries-subdir>/{QueryName}/
diff --git a/server/src/resources/languages/actions_ast.md b/server/src/resources/languages/actions_ast.md
@@ -191,5 +191,5 @@ ExpressionImpl (expressions like ${{ inputs.name }})
 
 This repo contains a variant of the open-source `PrintAst.ql` query for `actions` language, with modifications for local testing:
 
-- [local actions PrintAst.ql query](../src/PrintAST/PrintAST.ql)
-- [local actions PrintAst.expected results](../test/PrintAST/PrintAST.expected)
+- Use the `codeql_query_run` tool with `queryName="PrintAST"` and `language="actions"` to run the bundled PrintAST query
+- Use the `codeql_test_run` tool to run the PrintAST test and compare against expected results
diff --git a/server/src/resources/languages/cpp_ast.md b/server/src/resources/languages/cpp_ast.md
@@ -251,8 +251,8 @@ Expression hierarchy with full type and conversion tracking
 
 This repo contains a variant of the open-source `PrintAst.ql` query for `cpp` language, with modifications for local testing:
 
-- [local cpp PrintAst.ql query](../src/PrintAST/PrintAST.ql)
-- [local cpp PrintAst.expected results](../test/PrintAST/PrintAST.expected)
+- Use the `codeql_query_run` tool with `queryName="PrintAST"` and `language="cpp"` to run the bundled PrintAST query
+- Use the `codeql_test_run` tool to run the PrintAST test and compare against expected results
 
 ## Expected test results for open-source `PrintAst.ql` query
 
diff --git a/server/src/resources/languages/csharp_ast.md b/server/src/resources/languages/csharp_ast.md
@@ -113,8 +113,8 @@ Based on the C# PrintAst.expected test results, here are the core CodeQL AST cla
 
 This repo contains a variant of the open-source `PrintAst.ql` query for `csharp` language, with modifications for local testing:
 
-- [local csharp PrintAst.ql query](../src/PrintAST/PrintAST.ql)
-- [local csharp PrintAst.expected results](../test/PrintAST/PrintAST.expected)
+- Use the `codeql_query_run` tool with `queryName="PrintAST"` and `language="csharp"` to run the bundled PrintAST query
+- Use the `codeql_test_run` tool to run the PrintAST test and compare against expected results
 
 ## Expected test results for open-source `PrintAst.ql` query
 
diff --git a/server/src/resources/languages/go_ast.md b/server/src/resources/languages/go_ast.md
@@ -285,8 +285,8 @@ select call
 
 This repo contains a variant of the open-source `PrintAst.ql` query for `go` language, with modifications for local testing:
 
-- [local go PrintAst.ql query](../src/PrintAST/PrintAST.ql)
-- [local go PrintAst.expected results](../test/PrintAST/PrintAST.expected)
+- Use the `codeql_query_run` tool with `queryName="PrintAST"` and `language="go"` to run the bundled PrintAST query
+- Use the `codeql_test_run` tool to run the PrintAST test and compare against expected results
 
 ## Expected test results for open-source `PrintAst.ql` query
 
diff --git a/server/src/resources/languages/java_ast.md b/server/src/resources/languages/java_ast.md
@@ -243,8 +243,8 @@ Use `PrintAST` on your test code to see the exact hierarchy for your specific so
 
 This repo contains a variant of the open-source `PrintAst.ql` query for `java` language, with modifications for local testing:
 
-- [local java PrintAst.ql query](../src/PrintAST/PrintAST.ql)
-- [local java PrintAst.expected results](../test/PrintAST/PrintAST.expected)
+- Use the `codeql_query_run` tool with `queryName="PrintAST"` and `language="java"` to run the bundled PrintAST query
+- Use the `codeql_test_run` tool to run the PrintAST test and compare against expected results
 
 ## Expected test results for open-source `PrintAst.ql` query
 
diff --git a/server/src/resources/languages/javascript_ast.md b/server/src/resources/languages/javascript_ast.md
@@ -185,8 +185,8 @@ Based on comprehensive analysis of CodeQL's JavaScript test results from GitHub,
 
 This repo contains a variant of the open-source `PrintAst.ql` query for `javascript` language, with modifications for local testing:
 
-- [local javascript PrintAst.ql query](../src/PrintAST/PrintAST.ql)
-- [local javascript PrintAst.expected results](../test/PrintAST/PrintAST.expected)
+- Use the `codeql_query_run` tool with `queryName="PrintAST"` and `language="javascript"` to run the bundled PrintAST query
+- Use the `codeql_test_run` tool to run the PrintAST test and compare against expected results
 
 ## Expected test results for open-source `PrintAst.ql` query
 
diff --git a/server/src/resources/languages/python_ast.md b/server/src/resources/languages/python_ast.md
@@ -4,8 +4,8 @@
 
 This repo contains a variant of the open-source `PrintAst.ql` query for `python` language, with modifications for local testing:
 
-- [local python PrintAst.ql query](../src/PrintAST/PrintAST.ql)
-- [local python PrintAst.expected results](../test/PrintAST/PrintAST.expected)
+- Use the `codeql_query_run` tool with `queryName="PrintAST"` and `language="python"` to run the bundled PrintAST query
+- Use the `codeql_test_run` tool to run the PrintAST test and compare against expected results
 
 ## CodeQL's core AST classes for `python` language
 
diff --git a/server/src/resources/languages/ruby_ast.md b/server/src/resources/languages/ruby_ast.md
@@ -208,8 +208,8 @@ Based on comprehensive analysis of GitHub CodeQL Ruby AST test results
 
 This repo contains a variant of the open-source `PrintAst.ql` query for `ruby` language, with modifications for local testing:
 
-- [local ruby PrintAst.ql query](../src/PrintAST/PrintAST.ql)
-- [local ruby PrintAst.expected results](../test/PrintAST/PrintAST.expected)
+- Use the `codeql_query_run` tool with `queryName="PrintAST"` and `language="ruby"` to run the bundled PrintAST query
+- Use the `codeql_test_run` tool to run the PrintAST test and compare against expected results
 
 ## Expected test results for open-source `PrintAst.ql` query
 
diff --git a/server/src/resources/server-overview.md b/server/src/resources/server-overview.md
@@ -10,18 +10,20 @@ The CodeQL Development MCP Server wraps the CodeQL CLI and supporting utilities
 
 Read these resources via `resources/read` to deepen your understanding:
 
-| URI                                         | Purpose                                             |
-| ------------------------------------------- | --------------------------------------------------- |
-| `codeql://server/overview`                  | This guide — MCP server orientation                 |
-| `codeql://server/queries`                   | Bundled tools queries (PrintAST, PrintCFG, etc.)    |
-| `codeql://server/tools`                     | Complete default tool reference                     |
-| `codeql://server/prompts`                   | Complete prompt reference                           |
-| `codeql://learning/query-basics`            | QL query writing reference (syntax, metadata, etc.) |
-| `codeql://learning/test-driven-development` | TDD theory and workflow for CodeQL                  |
-| `codeql://templates/security`               | Security query templates (multi-language)           |
-| `codeql://patterns/performance`             | Performance profiling and optimization              |
-| `codeql://languages/{language}/ast`         | Language-specific AST class reference               |
-| `codeql://languages/{language}/security`    | Language-specific security patterns                 |
+| URI                                           | Purpose                                             |
+| --------------------------------------------- | --------------------------------------------------- |
+| `codeql://server/overview`                    | This guide — MCP server orientation                 |
+| `codeql://server/queries`                     | Bundled tools queries (PrintAST, PrintCFG, etc.)    |
+| `codeql://server/tools`                       | Complete default tool reference                     |
+| `codeql://server/prompts`                     | Complete prompt reference                           |
+| `codeql://learning/query-basics`              | QL query writing reference (syntax, metadata, etc.) |
+| `codeql://learning/test-driven-development`   | TDD theory and workflow for CodeQL                  |
+| `codeql://templates/security`                 | Security query templates (multi-language)           |
+| `codeql://patterns/performance`               | Performance profiling and optimization              |
+| `codeql://guides/query-unit-testing`          | Guide for creating and running CodeQL query tests   |
+| `codeql://guides/dataflow-migration-v1-to-v2` | Migrating from v1 to v2 dataflow API                |
+| `codeql://languages/{language}/ast`           | Language-specific AST class reference               |
+| `codeql://languages/{language}/security`      | Language-specific security patterns                 |
 
 ## Quick-Start Workflows
 
