-
Notifications
You must be signed in to change notification settings - Fork 2
Restructure docs: replace tools-reference.md with ql-mcp/ primitives docs and add testing strategy #33
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.
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
Merged
Restructure docs: replace tools-reference.md with ql-mcp/ primitives docs and add testing strategy #33
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| # Prompts | ||
|
|
||
| > MCP prompts provided by the CodeQL Development MCP Server. | ||
|
|
||
| ## Overview | ||
|
|
||
| The server provides **10 prompts** that guide AI assistants through common CodeQL development workflows. Each prompt is backed by a `*.prompt.md` file containing structured instructions. | ||
|
|
||
| ## Prompt Reference | ||
|
|
||
| | 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 | | ||
| | `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. | ||
| - **`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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,40 @@ | ||
| # Resources | ||
|
|
||
| > MCP resources provided by the CodeQL Development MCP Server. | ||
|
|
||
| ## 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. | ||
|
|
||
| ## 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 | | ||
|
|
||
| ## Language-Specific Resources | ||
|
|
||
| Each supported language can expose one or more of the following resource types under the URI pattern `codeql://languages/{language}/{type}`: | ||
|
|
||
| | Language | AST Reference | Security Patterns | Additional | | ||
| | ---------- | :-----------: | :---------------: | ----------------------------------------- | | ||
| | actions | ✓ | | | | ||
| | cpp | ✓ | ✓ | | | ||
| | csharp | ✓ | ✓ | | | ||
| | go | ✓ | ✓ | dataflow, library-modeling, basic-queries | | ||
| | java | ✓ | | | | ||
| | javascript | ✓ | ✓ | | | ||
| | python | ✓ | ✓ | | | ||
| | ql | ✓ | | | | ||
| | ruby | ✓ | | | | ||
|
|
||
| ### Resource Types | ||
|
|
||
| - **AST Reference** (`codeql://languages/{language}/ast`) — CodeQL AST class reference for the language, describing how source constructs map to QL classes. | ||
| - **Security Patterns** (`codeql://languages/{language}/security`) — Security query patterns and framework modeling guidance. | ||
| - **Dataflow** (`codeql://languages/go/dataflow`) — Guide to using the CodeQL dataflow library. | ||
| - **Library Modeling** (`codeql://languages/go/library-modeling`) — Guide to modeling third-party libraries for CodeQL analysis. | ||
| - **Basic Queries** (`codeql://languages/go/basic-queries`) — Introductory query examples for the language. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,88 @@ | ||
| # Tools | ||
|
|
||
| > Complete reference of MCP tools provided by the CodeQL Development MCP Server. | ||
|
|
||
| ## Overview | ||
|
|
||
| The server exposes **34 always-on tools** and **11 optional monitoring tools**. Always-on tools are available in every session; monitoring tools require explicit opt-in (see [Monitoring and Reporting](../mcp-server-monitoring-and-reporting.md)). | ||
|
|
||
| ## Always-On Tools | ||
|
|
||
| ### CodeQL CLI Tools | ||
|
|
||
| | Tool | Description | | ||
| | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | ||
| | `codeql_bqrs_decode` | Decode BQRS result files to human-readable formats | | ||
| | `codeql_bqrs_info` | Get metadata and information about BQRS result files | | ||
| | `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 | | ||
| | `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 | | ||
|
|
||
| ### 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 | ||
|
|
||
| | 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 | | ||
| | `profile_codeql_query` | Profile the performance of a CodeQL query run against a specific database by analyzing the evaluator log JSON file | | ||
| | `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) | | ||
|
|
||
| ## Optional Monitoring Tools | ||
|
|
||
| These tools are disabled by default and require opt-in. See [Monitoring and Reporting](../mcp-server-monitoring-and-reporting.md) for details. | ||
|
|
||
| ### Session Management | ||
|
|
||
| | Tool | Description | | ||
| | ---------------------- | ------------------------------------------------------------ | | ||
| | `session_end` | End a query development session with final status | | ||
| | `session_get` | Get complete details of a specific query development session | | ||
| | `session_list` | List query development sessions with optional filtering | | ||
| | `session_update_state` | Update the current state of a query development session | | ||
|
|
||
| ### Session Analytics | ||
|
|
||
| | Tool | Description | | ||
| | --------------------------------- | ---------------------------------------------------------------- | | ||
| | `session_calculate_current_score` | Calculate current quality score for a session based on its state | | ||
| | `session_get_call_history` | Get MCP call history for a specific session | | ||
| | `session_get_score_history` | Get quality score history for a specific session | | ||
| | `session_get_test_history` | Get test execution history for a specific session | | ||
|
|
||
| ### Batch Operations | ||
|
|
||
| | Tool | Description | | ||
| | -------------------- | ----------------------------------------------------------------------- | | ||
| | `sessions_aggregate` | Generate aggregate insights from multiple sessions based on filters | | ||
| | `sessions_compare` | Compare multiple query development sessions across specified dimensions | | ||
| | `sessions_export` | Export session data in specified format for external analysis | |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.