Use hashtag tool refs in MCP server prompts

Author: data-douser

docs/getting-started.md

@@ -18,7 +18,7 @@ See the [VS Code Extension guide](./vscode/extension.md) for details.
 
 The `.vsix` can be downloaded from
 [GitHub Releases](https://github.com/advanced-security/codeql-development-mcp-server/releases)
-or built from source (`npm run package:vscode` at the repository root).
+or built from source (`npm run package:vsix` at the repository root).
 
 ### From npm
 

docs/vscode/extension.md

@@ -39,7 +39,7 @@ Or in VS Code: **Extensions** sidebar → `⋯` menu → **Install from VSIX…*
 From the repository root:
 
 ```bash
-npm run package:vscode
+npm run package:vsix
 code --install-extension extensions/vscode/codeql-development-mcp-server.vsix
 ```
 

extensions/vscode/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vscode-codeql-development-mcp-server",
   "displayName": "CodeQL Development MCP Server",
-  "description": "Automatically installs, configures, and manages the CodeQL Development MCP Server in VS Code.",
+  "description": "LLM-assisted development of CodeQL queries, libraries, and tests via #ql-mcp prompts, resources, and tools.",
   "version": "2.24.1",
   "publisher": "advanced-security",
   "license": "SEE LICENSE IN LICENSE",

package.json

@@ -48,7 +48,7 @@
     "test:client": "npm run test:integration:default -w client",
     "test:server": "npm run test -w server",
     "test:vscode": "npm run test -w extensions/vscode",
-    "package:vscode": "npm run clean:test-dbs &&npm run package -w extensions/vscode",
+    "package:vsix": "npm run clean:test-dbs &&npm run package -w extensions/vscode",
     "tidy": "npm run lint:fix && npm run format",
     "tidy:check": "npm run lint && npm run format:check",
     "upgrade": "npm run upgrade:node",

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

@@ -32,7 +32,7 @@ Documentation files are **siblings** to the query file (same directory).
 
 1. **No documentation exists**: Create new `QueryFileBaseName.md` file
 2. **`.md` file exists**: Update the existing markdown file
-3. **`.qhelp` file exists**: Use `codeql_generate_query-help` tool to convert to markdown, then update
+3. **`.qhelp` file exists**: Use #codeql_generate_query-help tool to convert to markdown, then update
 
 ## Workflow Checklist
 
@@ -41,39 +41,39 @@ Use the following MCP server tools to gather context before creating documentati
 ### Phase 1: Query Discovery
 
 - [ ] **Step 1: Locate query files**
-  - Tool: `find_codeql_query_files`
+  - Tool: #find_codeql_query_files
   - Parameters: `queryPath` = provided query path
   - Gather: Query source file path, existing documentation files, test files
   - Check: Does `QueryFileBaseName.md` or `QueryFileBaseName.qhelp` exist?
 
 - [ ] **Step 2: Read query metadata**
-  - Tool: `codeql_resolve_metadata`
+  - Tool: #codeql_resolve_metadata
   - Parameters: `query` = query file path
   - Gather: @name, @description, @kind, @id, @tags, @precision, @severity
 
 ### Phase 2: Convert Existing qhelp (if needed)
 
 - [ ] **Step 3: Convert qhelp to markdown** (only if `.qhelp` exists)
-  - Tool: `codeql_generate_query-help`
+  - Tool: #codeql_generate_query-help
   - Parameters: `query` = query file path, `format` = "markdown"
   - Use output as starting point for updated documentation
 
 ### Phase 3: Gather Query Context
 
 - [ ] **Step 4: Validate query structure**
-  - Tool: `validate_codeql_query`
+  - Tool: #validate_codeql_query
   - Parameters: `query` = query source code
   - Gather: Structural validation, suggestions
-  - Note: This is a heuristic check only — for full validation, use `codeql_query_compile`
+  - Note: This is a heuristic check only — for full validation, use #codeql_query_compile
 
 - [ ] **Step 5: Explore query types** (if deeper understanding needed)
-  - Tool: `codeql_lsp_definition` — navigate to class/predicate definitions
-  - Tool: `codeql_lsp_completion` — explore member predicates on types used in the query
+  - Tool: #codeql_lsp_definition — navigate to class/predicate definitions
+  - Tool: #codeql_lsp_completion — explore member predicates on types used in the query
   - Parameters: `file_path`, `line` (0-based), `character` (0-based), `workspace_uri` (pack root)
-  - Run `codeql_pack_install` first — LSP tools require resolved dependencies
+  - Run #codeql_pack_install first — LSP tools require resolved dependencies
 
 - [ ] **Step 6: Run tests** (if tests exist from Step 1)
-  - Tool: `codeql_test_run`
+  - Tool: #codeql_test_run
   - Parameters: `tests` = test directories
   - Gather: Pass/fail status, confirms query behavior
 

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

@@ -34,28 +34,28 @@ You MUST use the following MCP server tools in sequence to gather context before
 ### Phase 1: Query Discovery and Validation
 
 - [ ] **Step 1: Locate query files**
-  - Tool: `find_codeql_query_files`
+  - Tool: #find_codeql_query_files
   - Parameters: `queryPath` = provided query path
   - Gather: Query source file, test files, expected results, metadata location
   - Note: If tests exist, record the test directory path for later steps
 
 - [ ] **Step 2: Validate query structure**
-  - Tool: `validate_codeql_query`
+  - Tool: #validate_codeql_query
   - Parameters: `query` = contents of the query file
   - Gather: Structural validation results, heuristic warnings/suggestions
 
 ### Phase 2: Test Execution and Database Creation
 
 - [ ] **Step 3: Run existing tests** (if tests exist from Step 1)
-  - Tool: `codeql_test_run`
+  - Tool: #codeql_test_run
   - Parameters: `tests` = array of test directories from Step 1
   - Purpose: Ensures test database is created and current with test code
   - Gather: Test pass/fail status, test database path (`.testproj` directory)
 
 ### Phase 3: Code Structure Analysis (if test database exists)
 
 - [ ] **Step 4: Generate PrintAST output**
-  - Tool: `codeql_query_run`
+  - Tool: #codeql_query_run
   - Parameters:
     - `queryName`: `"PrintAST"`
     - `queryLanguage`: provided language
@@ -65,7 +65,7 @@ You MUST use the following MCP server tools in sequence to gather context before
   - Gather: AST hierarchy showing code structure representation
 
 - [ ] **Step 5: Generate PrintCFG output** (for key functions)
-  - Tool: `codeql_query_run`
+  - Tool: #codeql_query_run
   - Parameters:
     - `queryName`: `"PrintCFG"`
     - `queryLanguage`: provided language
@@ -77,7 +77,7 @@ You MUST use the following MCP server tools in sequence to gather context before
 ### Phase 4: Query Profiling and Evaluation Order
 
 - [ ] **Step 6: Profile the query**
-  - Tool: `profile_codeql_query`
+  - Tool: #profile_codeql_query
   - Parameters:
     - `queryPath`: the query file path
     - `database`: If `databasePath` input was provided and valid, use it; otherwise use test database from Step 3
@@ -103,11 +103,11 @@ You MUST use the following MCP server tools in sequence to gather context before
   ```
 
 - [ ] **Step 8: Quick evaluate specific predicates** (as needed)
-  - First, locate the predicate: Tool: `find_predicate_position` with `file` and `name`
-  - Then evaluate: Tool: `quick_evaluate` with `file`, `db`, and `symbol`
+  - First, locate the predicate: Tool: #find_predicate_position with `file` and `name`
+  - Then evaluate: Tool: #quick_evaluate with `file`, `db`, and `symbol`
   - Use when: You need more context on how a specific predicate or class behaves
-  - Note: `find_class_position` finds `class` definitions only, not `module` definitions
-  - Note: `find_predicate_position` returns 1-based positions; LSP tools use 0-based
+  - Note: #find_class_position finds `class` definitions only, not `module` definitions
+  - Note: #find_predicate_position returns 1-based positions; LSP tools use 0-based
 
 ### Phase 5: Generate Explanation
 

server/src/prompts/document-codeql-query.prompt.md

@@ -21,7 +21,7 @@ Thus, this prompt can be used in any environment where the query files are on di
 ## Prerequisites
 
 1. A CodeQL pack with `codeql-pack.yml` on disk
-2. Dependencies installed via `codeql_pack_install` (pointing at the pack directory)
+2. Dependencies installed via #codeql_pack_install (pointing at the pack directory)
 3. Query files saved to disk (LSP tools operate on files, not inline strings)
 
 ## Key Concept: Positions Are File Path + Line + Character
@@ -37,12 +37,12 @@ containing `codeql-pack.yml`) for import resolution to work. Without it, complet
 and definitions for imported libraries will be empty.
 
 > **Critical**: LSP line/character positions are 0-based, but `read_file`,
-> `find_predicate_position`, and `find_class_position` return 1-based positions.
+> #find_predicate_position, and #find_class_position return 1-based positions.
 > Always subtract 1 when passing their output to LSP tools.
 
 ## Step 1: Discover Available Types with Completions
 
-Use `codeql_lsp_completion` to explore what types and predicates are available at any
+Use #codeql_lsp_completion to explore what types and predicates are available at any
 position in a query file. This replaces manual documentation browsing.
 
 **Example**: To see what classes are available in a `from` clause after `import javascript`:
@@ -68,7 +68,7 @@ each with full signature and documentation.
 
 ## Step 2: Navigate to Definitions
 
-Use `codeql_lsp_definition` to find where a class, predicate, or module is defined.
+Use #codeql_lsp_definition to find where a class, predicate, or module is defined.
 This returns the file URI and line range of the definition — even into library pack
 files you haven't opened.
 
@@ -95,7 +95,7 @@ the source.
 
 ## Step 3: Find All References
 
-Use `codeql_lsp_references` to find how a symbol is used across the workspace.
+Use #codeql_lsp_references to find how a symbol is used across the workspace.
 
 ```text
 Tool: codeql_lsp_references
@@ -115,7 +115,7 @@ find real usage examples instead of guessing from documentation.
 
 ## Step 4: Locate Symbols with Position Finders
 
-Use `find_predicate_position` and `find_class_position` to locate where a specific
+Use #find_predicate_position and #find_class_position to locate where a specific
 symbol is defined in a file. These return **1-based** line/column positions.
 
 ```text
@@ -126,18 +126,18 @@ Parameters:
 Returns: { start_line: 12, start_col: 13, end_line: 12, end_col: 20 }
 ```
 
-> **Note**: `find_class_position` finds `class` definitions only — it does not find
-> `module` definitions. Use `find_predicate_position` for predicates inside modules.
+> **Note**: #find_class_position finds `class` definitions only — it does not find
+> `module` definitions. Use #find_predicate_position for predicates inside modules.
 
 **Combining with LSP tools**: To navigate to a predicate's definition in library code:
 
-1. Use `find_predicate_position` to get its 1-based position
+1. Use #find_predicate_position to get its 1-based position
 2. Subtract 1 from line/col to convert to 0-based
-3. Pass to `codeql_lsp_definition` to jump to the underlying type
+3. Pass to #codeql_lsp_definition to jump to the underlying type
 
 ## Step 5: Quick-Evaluate Individual Predicates
 
-Use `quick_evaluate` to evaluate a single predicate or class against a database
+Use #quick_evaluate to evaluate a single predicate or class against a database
 without running the full query. This is the fastest way to debug whether a predicate
 matches what you expect.
 
@@ -151,27 +151,27 @@ Parameters:
 ```
 
 The tool evaluates just that symbol (predicate or class) and returns the result path.
-Use `codeql_bqrs_decode` on the output to inspect results in CSV or JSON format.
+Use #codeql_bqrs_decode on the output to inspect results in CSV or JSON format.
 
 ## Step 6: Validate at Multiple Levels
 
 Use the right validation tool for each situation:
 
-| Tool                     | Use When                                | Input              | Resolves Imports?   |
-| ------------------------ | --------------------------------------- | ------------------ | ------------------- |
-| `validate_codeql_query`  | Quick structural check                  | Inline QL string   | No (heuristic only) |
-| `codeql_lsp_diagnostics` | Syntax/semantic validation of fragments | Inline QL string   | No                  |
-| `codeql_query_compile`   | Full compilation check                  | On-disk `.ql` file | Yes                 |
-| `codeql_test_run`        | End-to-end result validation            | Test directory     | Yes                 |
+| Tool                    | Use When                                | Input              | Resolves Imports?   |
+| ----------------------- | --------------------------------------- | ------------------ | ------------------- |
+| #validate_codeql_query  | Quick structural check                  | Inline QL string   | No (heuristic only) |
+| #codeql_lsp_diagnostics | Syntax/semantic validation of fragments | Inline QL string   | No                  |
+| #codeql_query_compile   | Full compilation check                  | On-disk `.ql` file | Yes                 |
+| #codeql_test_run        | End-to-end result validation            | Test directory     | Yes                 |
 
-**`codeql_lsp_diagnostics`** validates QL syntax and semantics for inline code snippets,
+**#codeql_lsp_diagnostics** validates QL syntax and semantics for inline code snippets,
 but **cannot resolve `import` statements** (like `import javascript`). Use it for:
 
 - Checking predicate signatures and QL syntax
 - Verifying `from`/`where`/`select` clause structure
 - Catching type errors in import-free QL fragments
 
-For queries with imports, always use `codeql_query_compile` on the saved file.
+For queries with imports, always use #codeql_query_compile on the saved file.
 
 ## Iterative Development Loop
 
@@ -202,7 +202,7 @@ This example shows the tools in action for building a JavaScript XSS query.
 ### 1. Create the query file and install dependencies
 
 Write a `.ql` file with `import javascript` and a skeleton `from`/`where`/`select`.
-Run `codeql_pack_install` on the pack directory.
+Run #codeql_pack_install on the pack directory.
 
 ### 2. Explore sink types
 
@@ -245,14 +245,14 @@ quick_evaluate(file=..., db=test.testproj, symbol="isSink")  →  inspect result
 
 ## Important Notes
 
-- **All LSP tools use 0-based positions**. `find_class_position` and
-  `find_predicate_position` return 1-based positions. Convert before combining.
+- **All LSP tools use 0-based positions**. #find_class_position and
+  #find_predicate_position return 1-based positions. Convert before combining.
 - **`workspace_uri` must be the pack root** (the directory containing
   `codeql-pack.yml`). Without it, completions and definitions will be empty.
-- **Run `codeql_pack_install` first**. LSP tools require resolved dependencies.
-- **`codeql_lsp_diagnostics` cannot resolve imports**. For `import javascript`
-  and similar, use `codeql_query_compile` on the on-disk file instead.
-- **`find_class_position` finds `class` only**, not `module` definitions.
-  Use grep or `find_predicate_position` for predicates inside modules.
-- **`codeql_lsp_references` scope** depends on `workspace_uri`. Point it at
+- **Run #codeql_pack_install first**. LSP tools require resolved dependencies.
+- **#codeql_lsp_diagnostics cannot resolve imports**. For `import javascript`
+  and similar, use #codeql_query_compile on the on-disk file instead.
+- **#find_class_position finds `class` only**, not `module` definitions.
+  Use grep or #find_predicate_position for predicates inside modules.
+- **#codeql_lsp_references scope** depends on `workspace_uri`. Point it at
   a library pack root to find usages across library code.