Skip to content

[UPDATE PRIMITIVE] Rewrite static MCP resources as actionable LLM-oriented guides #113

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
data-douser merged 10 commits into from
Mar 9, 2026
Merged

[UPDATE PRIMITIVE] Rewrite static MCP resources as actionable LLM-oriented guides #113

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
91a5a4a
Initial plan
Copilot Mar 8, 2026
5e19d95
Rewrite static MCP resources with actionable LLM-oriented content, re…
Copilot Mar 8, 2026
0d3f529
Fix tool name inconsistency: use codeql_generate_log-summary (with hy…
Copilot Mar 8, 2026
1d75bfb
Address latest PR review comments
data-douser Mar 9, 2026
3efcd64
Update docs to fix/remove tool counts
data-douser Mar 9, 2026
32166dc
Remove qlt refs, broken cli links, fix deprecated API names, fix impo…
Copilot Mar 9, 2026
113def9
Cleanup language-specific security query guides
data-douser Mar 9, 2026
f9bee7f
Migrate .github/skills/** as MCP server resources (#116)
data-douser Mar 9, 2026
df4ce5e
Address latest PR review comments
data-douser Mar 9, 2026
7392972
Merge branch 'main' into copilot/rewrite-mcp-resources-guides
data-douser Mar 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 2 additions & 41 deletions docs/ql-mcp/prompts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,45 +6,6 @@

The server provides **11 prompts** that guide AI assistants through common CodeQL development workflows. Each prompt is backed by a `*.prompt.md` file containing structured instructions.

## Prompt Reference
> **Authoritative reference**: The MCP-served resource at `codeql://server/prompts` ([`server/src/resources/server-prompts.md`](../../server/src/resources/server-prompts.md)) is the canonical documentation for prompts. Update that file when adding, removing, or changing any prompt.

| Prompt | Description |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `document_codeql_query` | Create or update documentation for a CodeQL query |
| `explain_codeql_query` | Generate a detailed explanation of a CodeQL query for workshop learning content |
| `ql_lsp_iterative_development` | Iterative CodeQL query development using LSP tools for completion, navigation, and validation |
| `ql_tdd_advanced` | Advanced test-driven CodeQL development with AST visualization, control flow, and call graph analysis |
| `ql_tdd_basic` | Test-driven CodeQL query development checklist — write tests first, implement query, iterate until tests pass |
| `run_query_and_summarize_false_positives` | Run a CodeQL query and summarize its false positives |
| `sarif_rank_false_positives` | Analyze SARIF results to identify likely false positives in CodeQL query results |
| `sarif_rank_true_positives` | Analyze SARIF results to identify likely true positives in CodeQL query results |
| `test_driven_development` | Test-driven development workflow for CodeQL queries using MCP tools |
| `tools_query_workflow` | Guide for using built-in tools queries (PrintAST, PrintCFG, CallGraphFrom, CallGraphTo) to understand code structure |
| `workshop_creation_workflow` | Guide for creating CodeQL query development workshops from production-grade queries |

## Prompt Categories

### Test-Driven Development

- **`ql_tdd_basic`** — Covers the core TDD loop: write test cases, implement the query, run tests, iterate.
- **`ql_tdd_advanced`** — Extends basic TDD with AST visualization, control flow graph analysis, and call graph exploration.
- **`test_driven_development`** — End-to-end TDD workflow using MCP tools for each step.

### Code Understanding

- **`tools_query_workflow`** — Uses PrintAST, PrintCFG, CallGraphFrom, and CallGraphTo tool queries to explore how source code is represented in a CodeQL database.
- **`explain_codeql_query`** — Produces verbal explanations and Mermaid evaluation diagrams for a given query.

### Iterative Development

- **`ql_lsp_iterative_development`** — Combines LSP completions, go-to-definition, and diagnostics for an interactive development loop.

### Documentation and Quality

- **`document_codeql_query`** — Generates standardized markdown documentation as a sibling file to a query.
- **`run_query_and_summarize_false_positives`** — Runs a CodeQL query on a database and groups results into false-positive categories by root cause.
- **`sarif_rank_false_positives`** / **`sarif_rank_true_positives`** — Help assess query precision by ranking SARIF results.

### Workshop Creation

- **`workshop_creation_workflow`** — Guides the creation of multi-exercise workshops that teach CodeQL query development.
For the complete prompt reference (all 11 prompts with descriptions and categories), see [`server/src/resources/server-prompts.md`](../../server/src/resources/server-prompts.md).
18 changes: 11 additions & 7 deletions docs/ql-mcp/resources.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,20 @@

## 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 **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.

## 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 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 |
Comment thread
data-douser marked this conversation as resolved.
Outdated

## Language-Specific Resources

Expand Down
55 changes: 3 additions & 52 deletions docs/ql-mcp/tools.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,60 +6,11 @@

The server exposes **38 default tools** and **11 opt-in monitoring tools**. Default tools are registered on startup; monitoring tools require explicit opt-in (see [Monitoring and Reporting](../mcp-server-monitoring-and-reporting.md)). Users control which tools are enabled in their MCP client configuration.

## Default Tools

### CodeQL CLI Tools

| Tool | Description |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `codeql_bqrs_decode` | Decode BQRS result files to human-readable formats (text, csv, json). Supports `--result-set`, `--rows` for pagination |
| `codeql_bqrs_info` | Get metadata about BQRS result files: result sets, column types, row counts. Supports `--format=json` and pagination offsets |
| `codeql_bqrs_interpret` | Interpret BQRS result files according to query metadata and generate output in specified formats (CSV, SARIF, graph formats) |
| `codeql_database_analyze` | Run queries or query suites against CodeQL databases. Produces evaluator logs, BQRS, and SARIF output |
| `codeql_database_create` | Create a CodeQL database from source code |
| `codeql_generate_log-summary` | Create a summary of a structured JSON evaluator event log file |
| `codeql_generate_query-help` | Generate query help documentation from QLDoc comments |
| `codeql_pack_install` | Install CodeQL pack dependencies |
| `codeql_pack_ls` | List CodeQL packs under some local directory path |
| `codeql_query_compile` | Compile and validate CodeQL queries |
| `codeql_query_format` | Automatically format CodeQL source code files |
| `codeql_query_run` | Execute a CodeQL query against a database |
| `codeql_resolve_database` | Resolve database path and validate database structure |
| `codeql_resolve_languages` | List installed CodeQL extractor packs |
| `codeql_resolve_library-path` | Resolve library path for CodeQL queries and libraries |
| `codeql_resolve_metadata` | Resolve and return the key-value metadata pairs from a CodeQL query source file |
| `codeql_resolve_qlref` | Resolve qlref files to their corresponding query files |
| `codeql_resolve_queries` | List available CodeQL queries found on the local filesystem |
| `codeql_resolve_tests` | Resolve the local filesystem paths of unit tests and/or queries under some base directory |
| `codeql_test_accept` | Accept new test results as the expected baseline |
| `codeql_test_extract` | Extract test databases for CodeQL query tests |
| `codeql_test_run` | Run CodeQL query tests |
> **Authoritative reference**: The MCP-served resource at `codeql://server/tools` ([`server/src/resources/server-tools.md`](../../server/src/resources/server-tools.md)) is the canonical documentation for default tools. Update that file when adding, removing, or changing any default tool.

### Language Server Protocol (LSP) Tools

| Tool | Description |
| ------------------------ | ----------------------------------------------------------------------------------------------- |
| `codeql_lsp_completion` | Get code completions at a cursor position in a CodeQL file |
| `codeql_lsp_definition` | Go to the definition of a CodeQL symbol at a given position |
| `codeql_lsp_diagnostics` | Authoritative syntax and semantic validation of CodeQL (QL) code via the CodeQL Language Server |
| `codeql_lsp_references` | Find all references to a CodeQL symbol at a given position |

### Query Development Tools
## Default Tools

| Tool | Description |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `create_codeql_query` | Create directory structure and files for a new CodeQL query with tests |
| `find_class_position` | Find the start/end line and column of a class for quick evaluation |
| `find_codeql_query_files` | Find and track all files and directories related to a CodeQL query, including resolved metadata |
| `find_predicate_position` | Find the start/end line and column of a predicate for quick evaluation |
| `list_codeql_databases` | List CodeQL databases discovered in configured base directories (`CODEQL_DATABASES_BASE_DIRS`). Filter by language |
| `list_mrva_run_results` | List MRVA (Multi-Repository Variant Analysis) run results with per-repo details (`CODEQL_MRVA_RUN_RESULTS_DIRS`) |
| `list_query_run_results` | List query run result directories with artifact inventory. Filter by `queryName`, `language`, or `queryPath` |
| `profile_codeql_query` | Profile the performance of a CodeQL query run against a specific database by analyzing the evaluator log JSON file |
| `profile_codeql_query_from_logs` | Parse existing CodeQL evaluator logs into a performance profile without re-running the query |
| `quick_evaluate` | Quick evaluate either a class or a predicate in a CodeQL query for debugging |
| `register_database` | Register a CodeQL database given a local path to the database directory |
| `validate_codeql_query` | Quick heuristic validation for CodeQL query structure (does not compile the query) |
For the complete default tools reference (CodeQL CLI tools, LSP tools, query development tools, common workflows, and input conventions), see [`server/src/resources/server-tools.md`](../../server/src/resources/server-tools.md).

## Optional Monitoring Tools

Expand Down
1 change: 1 addition & 0 deletions extensions/vscode/esbuild.config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ const testSuiteConfig = {
'test/suite/index.ts',
'test/suite/bridge.integration.test.ts',
'test/suite/extension.integration.test.ts',
'test/suite/mcp-resource-e2e.integration.test.ts',
'test/suite/mcp-server.integration.test.ts',
'test/suite/mcp-tool-e2e.integration.test.ts',
'test/suite/workspace-scenario.integration.test.ts',
Expand Down
Loading