Skip to content

Commit 3c1d9f1

Browse files
Copilotdata-douser
Copilot
and
data-douser
authored
Restructure docs: replace tools-reference.md with ql-mcp/ primitives docs and add testing strategy (#33)
* Initial plan * Improve docs: replace tools-reference.md with ql-mcp/ docs and add testing.md - Remove docs/tools-reference.md - Add docs/ql-mcp/tools.md (34 always-on + 11 optional monitoring tools) - Add docs/ql-mcp/prompts.md (10 prompts with categories) - Add docs/ql-mcp/resources.md (4 static + per-language resources) - Add docs/testing.md (3-layer testing strategy overview) - Update README.md, getting-started.md, public.md to link to new docs Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com> * docs: clarify Layer 2 after/ directory validation behavior Address review comment: distinguish file-based tests (which diff before/ to after/) from monitoring-based tests (which generally do not diff after/ contents). --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com> Co-authored-by: Nathan Randall <data-douser@github.com>
1 parent 7093a4e commit 3c1d9f1

File tree

8 files changed

+249
-611
lines changed

8 files changed

+249
-611
lines changed

‎README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -138,7 +138,10 @@ npm install && npm run build
138138

139139
- [Public Installation Guide](docs/public.md) - Install and run without cloning the repository
140140
- [Getting Started Guide](docs/getting-started.md) - Detailed installation and setup instructions
141-
- [Tools Reference](docs/tools-reference.md) - Complete list of available MCP tools and usage examples
141+
- [Tools Reference](docs/ql-mcp/tools.md) - Complete list of available MCP tools
142+
- [Prompts Reference](docs/ql-mcp/prompts.md) - MCP prompts for CodeQL development workflows
143+
- [Resources Reference](docs/ql-mcp/resources.md) - MCP resources for CodeQL learning and reference
144+
- [Testing Strategy](docs/testing.md) - Multi-layer testing approach
142145

143146
## License
144147

‎docs/getting-started.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -104,4 +104,6 @@ Add to your `mcp.json` file:
104104

105105
## Next Steps
106106

107-
- [Tools Reference](./tools-reference.md) - Available MCP tools and usage
107+
- [Tools Reference](./ql-mcp/tools.md) - Available MCP tools
108+
- [Prompts Reference](./ql-mcp/prompts.md) - MCP prompts for CodeQL workflows
109+
- [Resources Reference](./ql-mcp/resources.md) - MCP resources for CodeQL learning

‎docs/public.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -255,8 +255,11 @@ dependencies:
255255

256256
## Further Reading
257257

258-
- [Tools Reference](./tools-reference.md) — Complete list of MCP tools and usage examples
259258
- [Getting Started (developer)](./getting-started.md) — Building from source and advanced configuration
259+
- [Testing Reference](./testing.md) — Overview of this repo's release testing strategy
260+
- [MCP Tools Reference](./ql-mcp/tools.md) — Complete list of MCP tools
261+
- [MCP Prompts Reference](./ql-mcp/prompts.md) — MCP prompts for CodeQL development workflows
262+
- [MCP Resources Reference](./ql-mcp/resources.md) — MCP resources for CodeQL learning and reference
260263
- [VS Code MCP Server Documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) — Configuring MCP servers in VS Code
261264
- [Publishing and Using CodeQL Packs](https://docs.github.com/en/code-security/tutorials/customize-code-scanning/publishing-and-using-codeql-packs) — Managing CodeQL packs with the CodeQL CLI
262265
- [Model Context Protocol](https://modelcontextprotocol.io/) — The MCP specification

‎docs/ql-mcp/prompts.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Prompts
2+
3+
> MCP prompts provided by the CodeQL Development MCP Server.
4+
5+
## Overview
6+
7+
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.
8+
9+
## Prompt Reference
10+
11+
| Prompt | Description |
12+
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
13+
| `document_codeql_query` | Create or update documentation for a CodeQL query |
14+
| `explain_codeql_query` | Generate a detailed explanation of a CodeQL query for workshop learning content |
15+
| `ql_lsp_iterative_development` | Iterative CodeQL query development using LSP tools for completion, navigation, and validation |
16+
| `ql_tdd_advanced` | Advanced test-driven CodeQL development with AST visualization, control flow, and call graph analysis |
17+
| `ql_tdd_basic` | Test-driven CodeQL query development checklist — write tests first, implement query, iterate until tests pass |
18+
| `sarif_rank_false_positives` | Analyze SARIF results to identify likely false positives in CodeQL query results |
19+
| `sarif_rank_true_positives` | Analyze SARIF results to identify likely true positives in CodeQL query results |
20+
| `test_driven_development` | Test-driven development workflow for CodeQL queries using MCP tools |
21+
| `tools_query_workflow` | Guide for using built-in tools queries (PrintAST, PrintCFG, CallGraphFrom, CallGraphTo) to understand code structure |
22+
| `workshop_creation_workflow` | Guide for creating CodeQL query development workshops from production-grade queries |
23+
24+
## Prompt Categories
25+
26+
### Test-Driven Development
27+
28+
- **`ql_tdd_basic`** — Covers the core TDD loop: write test cases, implement the query, run tests, iterate.
29+
- **`ql_tdd_advanced`** — Extends basic TDD with AST visualization, control flow graph analysis, and call graph exploration.
30+
- **`test_driven_development`** — End-to-end TDD workflow using MCP tools for each step.
31+
32+
### Code Understanding
33+
34+
- **`tools_query_workflow`** — Uses PrintAST, PrintCFG, CallGraphFrom, and CallGraphTo tool queries to explore how source code is represented in a CodeQL database.
35+
- **`explain_codeql_query`** — Produces verbal explanations and Mermaid evaluation diagrams for a given query.
36+
37+
### Iterative Development
38+
39+
- **`ql_lsp_iterative_development`** — Combines LSP completions, go-to-definition, and diagnostics for an interactive development loop.
40+
41+
### Documentation and Quality
42+
43+
- **`document_codeql_query`** — Generates standardized markdown documentation as a sibling file to a query.
44+
- **`sarif_rank_false_positives`** / **`sarif_rank_true_positives`** — Help assess query precision by ranking SARIF results.
45+
46+
### Workshop Creation
47+
48+
- **`workshop_creation_workflow`** — Guides the creation of multi-exercise workshops that teach CodeQL query development.

‎docs/ql-mcp/resources.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Resources
2+
3+
> MCP resources provided by the CodeQL Development MCP Server.
4+
5+
## Overview
6+
7+
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.
8+
9+
## Static Resources
10+
11+
| Resource | URI | Description |
12+
| --------------------------- | ----------------------------------- | --------------------------------------------------- |
13+
| CodeQL Getting Started | `codeql://learning/getting-started` | Comprehensive introduction to CodeQL for beginners |
14+
| CodeQL Query Basics | `codeql://learning/query-basics` | Learn the fundamentals of writing CodeQL queries |
15+
| CodeQL Security Templates | `codeql://templates/security` | Ready-to-use security query templates |
16+
| CodeQL Performance Patterns | `codeql://patterns/performance` | Best practices for writing efficient CodeQL queries |
17+
18+
## Language-Specific Resources
19+
20+
Each supported language can expose one or more of the following resource types under the URI pattern `codeql://languages/{language}/{type}`:
21+
22+
| Language | AST Reference | Security Patterns | Additional |
23+
| ---------- | :-----------: | :---------------: | ----------------------------------------- |
24+
| actions | ✓ | | |
25+
| cpp | ✓ | ✓ | |
26+
| csharp | ✓ | ✓ | |
27+
| go | ✓ | ✓ | dataflow, library-modeling, basic-queries |
28+
| java | ✓ | | |
29+
| javascript | ✓ | ✓ | |
30+
| python | ✓ | ✓ | |
31+
| ql | ✓ | | |
32+
| ruby | ✓ | | |
33+
34+
### Resource Types
35+
36+
- **AST Reference** (`codeql://languages/{language}/ast`) — CodeQL AST class reference for the language, describing how source constructs map to QL classes.
37+
- **Security Patterns** (`codeql://languages/{language}/security`) — Security query patterns and framework modeling guidance.
38+
- **Dataflow** (`codeql://languages/go/dataflow`) — Guide to using the CodeQL dataflow library.
39+
- **Library Modeling** (`codeql://languages/go/library-modeling`) — Guide to modeling third-party libraries for CodeQL analysis.
40+
- **Basic Queries** (`codeql://languages/go/basic-queries`) — Introductory query examples for the language.

‎docs/ql-mcp/tools.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Tools
2+
3+
> Complete reference of MCP tools provided by the CodeQL Development MCP Server.
4+
5+
## Overview
6+
7+
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)).
8+
9+
## Always-On Tools
10+
11+
### CodeQL CLI Tools
12+
13+
| Tool | Description |
14+
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
15+
| `codeql_bqrs_decode` | Decode BQRS result files to human-readable formats |
16+
| `codeql_bqrs_info` | Get metadata and information about BQRS result files |
17+
| `codeql_bqrs_interpret` | Interpret BQRS result files according to query metadata and generate output in specified formats (CSV, SARIF, graph formats) |
18+
| `codeql_database_analyze` | Run queries or query suites against CodeQL databases |
19+
| `codeql_database_create` | Create a CodeQL database from source code |
20+
| `codeql_generate_log-summary` | Create a summary of a structured JSON evaluator event log file |
21+
| `codeql_generate_query-help` | Generate query help documentation from QLDoc comments |
22+
| `codeql_pack_install` | Install CodeQL pack dependencies |
23+
| `codeql_pack_ls` | List CodeQL packs under some local directory path |
24+
| `codeql_query_compile` | Compile and validate CodeQL queries |
25+
| `codeql_query_format` | Automatically format CodeQL source code files |
26+
| `codeql_query_run` | Execute a CodeQL query against a database |
27+
| `codeql_resolve_database` | Resolve database path and validate database structure |
28+
| `codeql_resolve_languages` | List installed CodeQL extractor packs |
29+
| `codeql_resolve_library-path` | Resolve library path for CodeQL queries and libraries |
30+
| `codeql_resolve_metadata` | Resolve and return the key-value metadata pairs from a CodeQL query source file |
31+
| `codeql_resolve_qlref` | Resolve qlref files to their corresponding query files |
32+
| `codeql_resolve_queries` | List available CodeQL queries found on the local filesystem |
33+
| `codeql_resolve_tests` | Resolve the local filesystem paths of unit tests and/or queries under some base directory |
34+
| `codeql_test_accept` | Accept new test results as the expected baseline |
35+
| `codeql_test_extract` | Extract test databases for CodeQL query tests |
36+
| `codeql_test_run` | Run CodeQL query tests |
37+
38+
### Language Server Protocol (LSP) Tools
39+
40+
| Tool | Description |
41+
| ------------------------ | ----------------------------------------------------------------------------------------------- |
42+
| `codeql_lsp_completion` | Get code completions at a cursor position in a CodeQL file |
43+
| `codeql_lsp_definition` | Go to the definition of a CodeQL symbol at a given position |
44+
| `codeql_lsp_diagnostics` | Authoritative syntax and semantic validation of CodeQL (QL) code via the CodeQL Language Server |
45+
| `codeql_lsp_references` | Find all references to a CodeQL symbol at a given position |
46+
47+
### Query Development Tools
48+
49+
| Tool | Description |
50+
| ------------------------- | ------------------------------------------------------------------------------------------------------------------ |
51+
| `create_codeql_query` | Create directory structure and files for a new CodeQL query with tests |
52+
| `find_class_position` | Find the start/end line and column of a class for quick evaluation |
53+
| `find_codeql_query_files` | Find and track all files and directories related to a CodeQL query, including resolved metadata |
54+
| `find_predicate_position` | Find the start/end line and column of a predicate for quick evaluation |
55+
| `profile_codeql_query` | Profile the performance of a CodeQL query run against a specific database by analyzing the evaluator log JSON file |
56+
| `quick_evaluate` | Quick evaluate either a class or a predicate in a CodeQL query for debugging |
57+
| `register_database` | Register a CodeQL database given a local path to the database directory |
58+
| `validate_codeql_query` | Quick heuristic validation for CodeQL query structure (does not compile the query) |
59+
60+
## Optional Monitoring Tools
61+
62+
These tools are disabled by default and require opt-in. See [Monitoring and Reporting](../mcp-server-monitoring-and-reporting.md) for details.
63+
64+
### Session Management
65+
66+
| Tool | Description |
67+
| ---------------------- | ------------------------------------------------------------ |
68+
| `session_end` | End a query development session with final status |
69+
| `session_get` | Get complete details of a specific query development session |
70+
| `session_list` | List query development sessions with optional filtering |
71+
| `session_update_state` | Update the current state of a query development session |
72+
73+
### Session Analytics
74+
75+
| Tool | Description |
76+
| --------------------------------- | ---------------------------------------------------------------- |
77+
| `session_calculate_current_score` | Calculate current quality score for a session based on its state |
78+
| `session_get_call_history` | Get MCP call history for a specific session |
79+
| `session_get_score_history` | Get quality score history for a specific session |
80+
| `session_get_test_history` | Get test execution history for a specific session |
81+
82+
### Batch Operations
83+
84+
| Tool | Description |
85+
| -------------------- | ----------------------------------------------------------------------- |
86+
| `sessions_aggregate` | Generate aggregate insights from multiple sessions based on filters |
87+
| `sessions_compare` | Compare multiple query development sessions across specified dimensions |
88+
| `sessions_export` | Export session data in specified format for external analysis |

0 commit comments

Comments
 (0)