Rewrite static MCP resources with actionable LLM-oriented content, rename URIs, add new resources

- Rewrite getting-started.md as MCP server orientation guide (codeql://server/overview)
- Rewrite query-basics.md as practical query writing reference (codeql://server/queries)
- Rewrite security-templates.md with multi-language templates and TDD workflow
- Rewrite performance-patterns.md with profiling tool focus
- Create server-prompts.md (codeql://server/prompts) with complete prompt reference
- Create server-tools.md (codeql://server/tools) with complete default tool reference
- Rewrite ql-test-driven-development.md as TDD theory overview with cross-links
- Register ql-test-driven-development.md as MCP resource (codeql://learning/test-driven-development)
- Update resources.ts with new imports and getters
- Update codeql-resources.ts with new URIs and 7 resource registrations
- Update resources.test.ts with tests for new resources
- Update docs/ql-mcp/resources.md and server/README.md

Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com>

Author: Copilot

docs/ql-mcp/resources.md

@@ -4,16 +4,19 @@
 
 ## Overview
 
-The server exposes **4 static learning resources** and a set of **dynamic per-language resources** that supply AI assistants with CodeQL reference material. Resources are read-only and backed by `*.prompt.md` files bundled with the server.
+The server exposes **7 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 Getting Started      | `codeql://learning/getting-started` | Comprehensive introduction to CodeQL for beginners  |
-| CodeQL Query Basics         | `codeql://learning/query-basics`    | Learn the fundamentals of writing CodeQL queries    |
-| CodeQL Security Templates   | `codeql://templates/security`       | Ready-to-use security query templates               |
-| CodeQL Performance Patterns | `codeql://patterns/performance`     | Best practices for writing efficient CodeQL queries |
+| Resource                       | URI                                         | Description                                                               |
+| ------------------------------ | ------------------------------------------- | ------------------------------------------------------------------------- |
+| 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 Query Writing Guide     | `codeql://server/queries`                   | Practical reference for writing and validating CodeQL queries             |
+| CodeQL Server Tools            | `codeql://server/tools`                     | Complete reference of default MCP tools for CodeQL development            |
+| CodeQL Test-Driven Development | `codeql://learning/test-driven-development` | TDD theory and workflow for developing CodeQL queries                     |
+| CodeQL Security Templates      | `codeql://templates/security`               | Security query templates for multiple languages and vulnerability classes |
+| CodeQL Performance Patterns    | `codeql://patterns/performance`             | Performance profiling and optimization for CodeQL queries                 |
 
 ## Language-Specific Resources
 

server/README.md

@@ -85,10 +85,12 @@ Full reference: [Prompts](https://github.com/advanced-security/codeql-developmen
 
 ### Resources
 
-Static learning materials and per-language references served to AI assistants:
+Static reference materials and per-language references served to AI assistants:
 
-- **CodeQL Getting Started** / **Query Basics** — Introductory guides
-- **Security Templates** / **Performance Patterns** — Ready-to-use templates and best practices
+- **Server Overview** / **Query Writing Guide** — MCP server orientation and query development reference
+- **Server Tools** / **Server Prompts** — Complete tool and prompt references
+- **Test-Driven Development** — TDD theory and workflow for CodeQL queries
+- **Security Templates** / **Performance Patterns** — Multi-language security templates and profiling guidance
 - **Language AST References** — For actions, cpp, csharp, go, java, javascript, python, ql, ruby
 - **Language Security Patterns** — For cpp, csharp, go, javascript, python
 

server/dist/codeql-development-mcp-server.js

@@ -12,6 +12,9 @@ import gettingStartedContent from '../resources/getting-started.md';
 import performancePatternsContent from '../resources/performance-patterns.md';
 import queryBasicsContent from '../resources/query-basics.md';
 import securityTemplatesContent from '../resources/security-templates.md';
+import serverPromptsContent from '../resources/server-prompts.md';
+import serverToolsContent from '../resources/server-tools.md';
+import testDrivenDevelopmentContent from '../resources/ql-test-driven-development.md';
 
 /**
  * Get the getting started guide content
@@ -20,6 +23,13 @@ export function getGettingStartedGuide(): string {
   return gettingStartedContent;
 }
 
+/**
+ * Get the performance patterns content
+ */
+export function getPerformancePatterns(): string {
+  return performancePatternsContent;
+}
+
 /**
  * Get the query basics guide content
  */
@@ -35,8 +45,22 @@ export function getSecurityTemplates(): string {
 }
 
 /**
- * Get the performance patterns content
+ * Get the server prompts overview content
  */
-export function getPerformancePatterns(): string {
-  return performancePatternsContent;
+export function getServerPrompts(): string {
+  return serverPromptsContent;
+}
+
+/**
+ * Get the server tools overview content
+ */
+export function getServerTools(): string {
+  return serverToolsContent;
+}
+
+/**
+ * Get the test-driven development guide content
+ */
+export function getTestDrivenDevelopment(): string {
+  return testDrivenDevelopmentContent;
 }

server/dist/codeql-development-mcp-server.js.map

@@ -1,30 +1,93 @@
-# CodeQL Getting Started Guide
+# CodeQL Development MCP Server — Getting Started
 
-## What is CodeQL?
+This resource is the primary onboarding guide for LLM clients connecting to the CodeQL Development MCP Server. It explains what the server provides, which tools and prompts are available, and how to orchestrate common workflows.
 
-CodeQL is a semantic code analysis engine that allows you to write queries to find problems in source code.
+## What This Server Does
 
-## Installation
+The CodeQL Development MCP Server wraps the CodeQL CLI and supporting utilities behind the Model Context Protocol (MCP). It exposes **tools** (executable actions), **prompts** (reusable workflow templates), and **resources** (reference material) that enable an LLM to develop, test, and analyze CodeQL queries without direct shell access.
 
-1. Download CodeQL CLI from GitHub releases
-2. Add to PATH
-3. Verify: `codeql version`
+## Available Resources
 
-## First Steps
+Read these resources via `resources/read` to deepen your understanding:
 
-### 1. Create a Database
+| URI                                         | Purpose                                   |
+| ------------------------------------------- | ----------------------------------------- |
+| `codeql://server/overview`                  | This guide — MCP server orientation       |
+| `codeql://server/queries`                   | Writing and validating CodeQL queries     |
+| `codeql://server/tools`                     | Complete default tool reference           |
+| `codeql://server/prompts`                   | Complete prompt reference                 |
+| `codeql://templates/security`               | Security query templates (multi-language) |
+| `codeql://patterns/performance`             | Performance profiling and optimization    |
+| `codeql://learning/test-driven-development` | TDD theory and workflow for CodeQL        |
+| `codeql://languages/{language}/ast`         | Language-specific AST class reference     |
+| `codeql://languages/{language}/security`    | Language-specific security patterns       |
 
-```bash
-codeql database create my-db --language=java --source-root=./src
-```
+## Quick-Start Workflows
 
-### 2. Run Analysis
+### 1. Create a New Query (TDD Approach)
 
-```bash
-codeql database analyze my-db --format=sarif --output=results.sarif
-```
+Use the `test_driven_development` prompt (or `ql_tdd_basic` / `ql_tdd_advanced`):
 
-## Resources
+1. `create_codeql_query` — scaffold query, test files, and `.qlref`
+2. `codeql_pack_install` — install pack dependencies
+3. Write test code with positive and negative cases
+4. `codeql_test_run` — run tests (expect failure initially)
+5. Implement query logic
+6. `codeql_query_compile` — validate syntax
+7. `codeql_test_run` — iterate until tests pass
+8. `codeql_test_accept` — accept correct results as baseline
 
-- [CodeQL Documentation](https://codeql.github.com/)
-- [GitHub Security Lab](https://securitylab.github.com/)
+### 2. Understand Code Structure
+
+Use the `tools_query_workflow` prompt:
+
+1. `codeql_query_run` with `queryName="PrintAST"` — visualize the AST
+2. `codeql_query_run` with `queryName="PrintCFG"` — visualize control flow
+3. `codeql_query_run` with `queryName="CallGraphFrom"` / `"CallGraphTo"` — trace call relationships
+
+### 3. Analyze Query Quality
+
+1. `codeql_database_analyze` — run queries against a database
+2. `profile_codeql_query` or `profile_codeql_query_from_logs` — analyze performance
+3. `run_query_and_summarize_false_positives` prompt — assess precision
+4. `sarif_rank_false_positives` / `sarif_rank_true_positives` prompts — rank results
+
+### 4. Iterative Development with LSP
+
+Use the `ql_lsp_iterative_development` prompt:
+
+1. `codeql_lsp_completion` — get code completions while writing QL
+2. `codeql_lsp_definition` — navigate to symbol definitions
+3. `codeql_lsp_references` — find all references to a symbol
+4. `codeql_lsp_diagnostics` — real-time syntax and semantic validation
+
+## Tool Categories
+
+The server provides **38 default tools** across these categories (see `codeql://server/tools` for the full reference):
+
+- **CodeQL CLI tools** — Database creation, query compilation, execution, result decoding, pack management
+- **LSP tools** — Code completion, go-to-definition, find references, diagnostics
+- **Query development tools** — Scaffolding, validation, profiling, quick evaluation, database registration
+
+## Prompt Categories
+
+The server provides **11 prompts** (see `codeql://server/prompts` for the full reference):
+
+- **Test-driven development** — `test_driven_development`, `ql_tdd_basic`, `ql_tdd_advanced`
+- **Code understanding** — `tools_query_workflow`, `explain_codeql_query`
+- **Iterative development** — `ql_lsp_iterative_development`
+- **Documentation and quality** — `document_codeql_query`, `run_query_and_summarize_false_positives`, `sarif_rank_false_positives`, `sarif_rank_true_positives`
+- **Workshop creation** — `workshop_creation_workflow`
+
+## Key Concepts
+
+- **CodeQL database**: A relational representation of source code created by `codeql_database_create`. All queries execute against a database.
+- **QL pack**: A directory containing `codeql-pack.yml` with query or library code. Use `codeql_pack_install` to resolve dependencies.
+- **`.qlref` file**: A test reference that points from a test directory to the query being tested.
+- **`.expected` file**: The expected output of a query test. Use `codeql_test_accept` to update it when results are correct.
+- **BQRS**: Binary Query Result Sets — the native output format of `codeql_query_run`. Decode with `codeql_bqrs_decode` or interpret with `codeql_bqrs_interpret`.
+- **SARIF**: Static Analysis Results Interchange Format — the standard output format for `codeql_database_analyze`.
+
+## Supported Languages
+
+The server supports CodeQL queries for: `actions`, `cpp`, `csharp`, `go`, `java`, `javascript`, `python`, `ruby`, `swift`.

server/src/lib/resources.ts

@@ -1,19 +1,100 @@
 # Performance Optimization Patterns
 
-## Efficient Joins
-
-```ql
-// Efficient - Proper join condition
-from Method m, MethodAccess ma
-where ma.getMethod() = m
-select m, ma
-```
-
-## Early Filtering
-
-```ql
-// Filter early for better performance
-from Expr e
-where e.getEnclosingCallable().getDeclaringType().hasName("Controller")
-  and e.getType().hasName("String")
-```
+This resource describes how to evaluate and improve the performance of CodeQL queries using the MCP server's profiling tools. Rather than prescribing generic optimization rules, it focuses on using the `profile_codeql_query_from_logs` tool and the `explain_codeql_query` prompt to make evidence-based performance improvements.
+
+## Primary Performance Tool: `profile_codeql_query_from_logs`
+
+The `profile_codeql_query_from_logs` tool is the primary means of evaluating the actual performance of a CodeQL query. It parses existing CodeQL evaluator logs into a structured performance profile without re-running the query.
+
+### Workflow
+
+1. **Run the query**: Use `codeql_query_run` with `evaluationOutput` set to a directory path. This generates evaluator log files.
+2. **Generate a log summary**: Use `codeql_generate_log_summary` to create a human-readable summary of the evaluator log.
+3. **Profile**: Use `profile_codeql_query_from_logs` to parse the evaluator log into a structured performance profile identifying expensive predicates, pipeline stages, and tuple counts.
+4. **Identify bottlenecks**: Review the profile output for predicates with high evaluation times or unexpectedly large result sets.
+5. **Refine**: Modify the query to address identified bottlenecks, then re-run and re-profile to verify improvements.
+
+Alternatively, use `profile_codeql_query` to profile a query by running it against a specific database and analyzing the resulting evaluator log in a single step.
+
+### What the Profile Shows
+
+- **Predicate evaluation times** — which predicates are the most expensive
+- **Tuple counts** — how many intermediate results each predicate produces
+- **Pipeline stages** — the internal evaluation plan chosen by the CodeQL engine
+- **RA (relational algebra) operations** — join orders, aggregation steps, and recursive evaluations
+
+## Using `explain_codeql_query` for Performance Understanding
+
+The `explain_codeql_query` prompt generates a detailed explanation of a query, including Mermaid evaluation diagrams that visualize the data flow and evaluation order. This is useful for understanding _why_ a query may be slow before profiling.
+
+## Key Performance Concepts
+
+The following concepts are relevant when interpreting profiling output. Verify these against actual profiling data rather than applying them blindly.
+
+### Large Intermediate Result Sets
+
+When a predicate produces significantly more tuples than expected, it may indicate:
+
+- Missing or insufficiently restrictive filter conditions in the `where` clause
+- A cross-product between two large relations that should be joined more tightly
+
+**How to detect**: Look for predicates in the profile output with high tuple counts relative to their expected output size.
+
+### Recursive Predicate Costs
+
+Recursive predicates (e.g., transitive closures via `+` or `*`) can be expensive when the underlying relation is large. The profiler shows iteration counts and per-iteration tuple growth.
+
+**How to detect**: Look for recursive predicates with many iterations or high per-iteration costs in the profile output.
+
+### Join Order Sensitivity
+
+The CodeQL evaluator chooses a join order for predicates in the `where` clause. In some cases, the chosen order may not be optimal.
+
+**How to detect**: Look for pipeline stages where a large intermediate result is produced before being filtered down. The profiler shows tuple counts at each stage.
+
+### Improving "Performance" — Two Dimensions
+
+The word "performance" for CodeQL queries has two meanings:
+
+1. **Runtime efficiency** — how fast the query evaluates. Addressed by reducing tuple counts, improving join orders, and simplifying recursive predicates.
+2. **Result quality** — how accurate the query's output is (precision and recall). Addressed by refining source/sink/sanitizer definitions, adding or removing filter conditions, and testing against diverse codebases.
+
+The `profile_codeql_query_from_logs` tool addresses runtime efficiency. For result quality, use the `run_query_and_summarize_false_positives` prompt and the `sarif_rank_false_positives` / `sarif_rank_true_positives` prompts.
+
+## Performance Review for GitHub Actions CodeQL Scans
+
+When reviewing CodeQL performance in the context of GitHub Actions CI/CD scans, key areas to examine include:
+
+### Code Exclusion
+
+Excluding non-essential files from analysis (vendored dependencies, generated code, test files) is one of the most impactful performance improvements. Any interpreted language or compiled language using `build-mode: none` can use a `paths-ignore` array in the CodeQL configuration file to exclude paths.
+
+### Hardware Sizing
+
+Recommended runner sizes based on lines of code:
+
+- Small (< 100K lines): 8 GB RAM, 2 cores
+- Medium (100K–1M lines): 16 GB RAM, 4–8 cores
+- Large (> 1M lines): 64 GB RAM, 8 cores
+
+### Monorepo Splitting
+
+For monorepos with multiple independent applications separated by process/network boundaries, consider splitting CodeQL scans by application. This reduces database size and enables parallel scanning via Actions matrix strategies.
+
+## Related Tools and Prompts
+
+| Tool / Prompt                                    | Purpose                                                              |
+| ------------------------------------------------ | -------------------------------------------------------------------- |
+| `profile_codeql_query`                           | Profile a query run against a database (runs the query and profiles) |
+| `profile_codeql_query_from_logs`                 | Profile from existing evaluator logs (no re-run needed)              |
+| `codeql_generate_log_summary`                    | Generate a human-readable evaluator log summary                      |
+| `codeql_query_run`                               | Execute a query (set `evaluationOutput` to capture logs)             |
+| `explain_codeql_query` prompt                    | Understand query evaluation flow with Mermaid diagrams               |
+| `run_query_and_summarize_false_positives` prompt | Assess result quality (precision)                                    |
+
+## Related Resources
+
+- `codeql://server/overview` — MCP server orientation guide
+- `codeql://server/queries` — Query structure and compilation tools
+- `codeql://server/tools` — Complete tool reference
+- `codeql://learning/test-driven-development` — TDD workflow for iterative query improvement