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

[Copilot]

📝 Update Information

Primitive Details

• Type: Resource
• Name: All static MCP resources (8 static + language-specific resources)
• Update Category: Feature Enhancement

⚠️ CRITICAL: PR SCOPE VALIDATION

• ONLY server implementation files are included
• NO temporary or output files are included
• NO unrelated configuration files are included
• ALL existing tests continue to pass
• NEW functionality is properly tested

---

• Impact Scope: Moderate — resource content, URIs, registration, and language resource delivery changed; no tool or prompt logic modified

Update Metadata

• Breaking Changes: Yes — two resource URIs renamed, one URI repurposed (see below)
• API Compatibility: Changed (URI renames + new URIs)
• Performance Impact: Neutral

🎯 Changes Description

Current Behavior

Static MCP resources contain placeholder-quality content: a generic "what is CodeQL" blurb, a 15-line QL snippet, 2 security examples, and 2 trivial performance patterns. ql-test-driven-development.md exists but is not registered as a resource. No server/tools, server/prompts, or server/queries reference resources exist. Resource filenames do not match their endpoint paths. Repo-level docs (docs/ql-mcp/tools.md, docs/ql-mcp/prompts.md) duplicate content that should have a single authoritative source. Language-specific resource files contain broken relative links to ../../../resources/cli/** paths and qlt tool references copied from the codeql-development-template repo.

Updated Behavior

8 static resources with actionable, cross-linked content written for LLM consumers. Resource filenames match their endpoint paths:

URI	File	Content
codeql://learning/query-basics	learning-query-basics.md	QL query writing reference: syntax, metadata, from/where/select, common patterns, testing conventions
codeql://learning/test-driven-development	ql-test-driven-development.md	TDD theory, AST value, cross-links to ql_tdd_* prompts
codeql://patterns/performance	performance-patterns.md	profile_codeql_query_from_logs workflow, CI/CD performance review concepts
codeql://server/overview	server-overview.md	Primary onboarding guide — tools, prompts, resources, workflows
codeql://server/prompts	server-prompts.md	Complete prompt reference (all 11 prompts)
codeql://server/queries	server-queries.md	Overview of bundled tools queries (PrintAST, PrintCFG, CallGraphFrom, CallGraphTo) with language support matrix
codeql://server/tools	server-tools.md	Complete default tool reference (38 tools, no monitoring tools)
codeql://templates/security	security-templates.md	Multi-language templates, v2 taint tracking, source/sink/sanitizer patterns

Language-specific resources (server/src/resources/languages/*.md) cleaned of all template-repo artifacts:

• Removed all qlt tool references and broken ../../../resources/cli/** relative links
• Replaced "CLI References" sections with MCP tool name references
• Fixed deprecated v1 API references (isAdditionalTaintStep → isAdditionalFlowStep)
• Fixed incomplete "Example AST Hierarchy" in java_ast.md

All resources cross-reference specific MCP tool names and prompt names for LLM discoverability. Repo-level documentation (docs/ql-mcp/tools.md and docs/ql-mcp/prompts.md) now points to the MCP resource files as the authoritative source, eliminating content duplication.

Motivation

Resources are consumed by LLMs via resources/read. The previous content provided no guidance on the MCP server's capabilities, tools, prompts, or workflows. After PR #111 ensured resources are actually available in VSIX bundles, the content needed to match. Language resource files contained broken references copied from another repository that would confuse LLM consumers.

🔄 Before vs. After Comparison

Functionality Changes

URI Changes:
BEFORE                              → AFTER
codeql://learning/getting-started   → codeql://server/overview    (renamed, file: server-overview.md)
codeql://learning/query-basics      → codeql://learning/query-basics (kept, file: learning-query-basics.md)
(not registered)                    → codeql://server/queries     (new — bundled tools queries overview)
(not registered)                    → codeql://server/prompts     (new)
(not registered)                    → codeql://server/tools       (new)
(not registered)                    → codeql://learning/test-driven-development (new registration)
codeql://templates/security         → (unchanged)
codeql://patterns/performance       → (unchanged)

File Renames:
getting-started.md        → server-overview.md
query-basics.md           → learning-query-basics.md
(new)                     → server-queries.md
(new)                     → server-prompts.md
(new)                     → server-tools.md

API Changes

// BEFORE: 4 resources, 4 getter functions
import { getGettingStartedGuide, getQueryBasicsGuide, getSecurityTemplates, getPerformancePatterns } from '../lib/resources';

// AFTER: 8 resources, 8 getter functions (alphabetically ordered)
import { getLearningQueryBasics, getPerformancePatterns, getSecurityTemplates,
  getServerOverview, getServerPrompts, getServerQueries, getServerTools,
  getTestDrivenDevelopment } from '../lib/resources';

Output Format Changes

Language security query guides now use MCP tool name references instead of broken filesystem links:

// BEFORE (broken relative links from template repo):
## CLI References
- [qlt query generate new-query](../../../resources/cli/qlt/qlt_query_generate_new-query.prompt.md)
- [codeql query format](../../../resources/cli/codeql/codeql_query_format.prompt.md)

// AFTER (MCP tool name references):
## MCP Tools for Query Development
- `codeql_query_format` — automatically format CodeQL source code files
- `codeql_query_compile` — compile and validate CodeQL queries

🧪 Testing & Validation

Test Coverage Updates

• Existing Tests: All 930 tests pass (46 files)
• New Test Cases: Tests for getServerOverview, getServerPrompts, getServerQueries, getServerTools, getTestDrivenDevelopment
• Regression Tests: Existing resource getter tests updated for renamed functions and passing
• Edge Case Tests: N/A — resources are static string returns

Validation Scenarios

1. Backward Compatibility: codeql://learning/query-basics, codeql://templates/security, and codeql://patterns/performance URIs preserved
2. New Functionality: 4 new resource endpoints return non-empty markdown content
3. Error Handling: N/A — resources are static string returns
4. Performance: Neutral — same static import mechanism

Test Results

• Unit Tests: All pass (930/930)
• Integration Tests: Pre-existing codeql_pack_install failure (credential issue, unrelated)

📋 Implementation Details

Files Modified

• Core Implementation: server/src/tools/codeql-resources.ts — 8 resource registrations
• Supporting Libraries: server/src/lib/resources.ts — 8 static imports + getter functions (alphabetically ordered)
• Tests: server/test/src/lib/resources.test.ts — 8 test cases
• Documentation: docs/ql-mcp/resources.md, docs/ql-mcp/tools.md, docs/ql-mcp/prompts.md, server/README.md
• Resources: 5 .md files in server/src/resources/ rewritten; 3 new .md files created; 2 files renamed to match endpoint paths
• Language Resources: javascript_security_query_guide.md, csharp_security_query_guide.md, python_security_query_guide.md — removed template-repo artifacts, java_ast.md — fixed incomplete section

Code Changes Summary

• Algorithm Improvements: N/A — resources are static content
• Error Handling: N/A
• Type Safety: Getter functions renamed for clarity (getGettingStartedGuide → getServerOverview, etc.)
• Input Validation: N/A
• Output Format: All resources now cross-reference tool/prompt names; language resources use MCP tool name references instead of broken filesystem links

Dependencies

• No New Dependencies: Update uses existing dependencies only

🔍 Quality Improvements

Code Quality Enhancements

• Readability: Resource filenames match endpoint paths (e.g., server-overview.md for codeql://server/overview)
• Maintainability: docs/ql-mcp/tools.md and docs/ql-mcp/prompts.md now point to MCP resource files as authoritative sources, eliminating content duplication
• Testability: Each resource getter has a dedicated test
• Reusability: N/A

🔗 References

Related Issues/PRs

• Related PRs: PR Embed MCP resource content at build time for VSIX compatibility #111 — Fixed build-time embedding so resources are available in VSIX bundles

🚀 Compatibility & Migration

Backward Compatibility

• Fully Compatible: No breaking changes
• Breaking Changes: Changes that break existing usage (detailed below)

Breaking Changes

Changes Made:

• codeql://learning/getting-started renamed to codeql://server/overview
• codeql://learning/query-basics URI preserved but file renamed from query-basics.md to learning-query-basics.md
• codeql://server/queries now serves bundled tools queries overview (not QL writing guide — that content moved to codeql://learning/query-basics)

Migration Guide:

• Update any resources/read calls using codeql://learning/getting-started to codeql://server/overview
• codeql://learning/query-basics URI is unchanged (QL writing reference)
• codeql://server/queries is a new resource for bundled tools queries (PrintAST, PrintCFG, CallGraphFrom, CallGraphTo)
• codeql://templates/security and codeql://patterns/performance URIs are unchanged

API Evolution

• Improved Responses: Richer, cross-linked resource content
• Better Error Messages: N/A
• Maintained Contracts: learning/query-basics, templates/security, and patterns/performance URIs preserved

👥 Review Guidelines

For Reviewers

• ⚠️ SCOPE COMPLIANCE: PR contains only server implementation files and repo-level docs
• ⚠️ BACKWARD COMPATIBILITY: URI renames and file renames are intentional (issue requirement + review feedback)
• Functionality: 8 resources register and return non-empty markdown
• Test Coverage: 930 tests pass
• Documentation: docs/ql-mcp/resources.md updated with 8-resource table; docs/ql-mcp/tools.md and docs/ql-mcp/prompts.md updated to reference MCP resource files as authoritative sources

Testing Instructions

npm run build-and-test    # from repo root
cd server && npm test     # unit tests only

📊 Impact Assessment

AI Assistant Impact

• Enhanced Accuracy: Resources now explain which tools/prompts to use and when; language resources no longer contain broken links or references to non-existent tools
• Better Coverage: 8 resources (up from 4) covering tools, prompts, bundled queries, TDD, and workflows
• Improved Reliability: Removed template-repo artifacts (qlt references, broken resources/cli/ links) that would confuse LLM consumers
• Enhanced User Experience: LLMs can orient themselves on first connection via codeql://server/overview; bundled tools queries documented at codeql://server/queries

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[Copilot]

Pull request overview

This PR enhances the CodeQL Development MCP Server's static resources from 4 to 8, rewriting all content as actionable, cross-linked LLM-oriented guides. It builds on PR #111 (which fixed build-time embedding) by providing substantive content for the now-working resource endpoints. The main structural changes are URI renames, file renames, three new resource files, and migration of language AST/security resource content from runtime filesystem reads to static imports embedded at build time.

Changes:

• 8 static resources (up from 4): rewritten content + new server/overview, server/prompts, server/queries, learning/test-driven-development; URI codeql://learning/getting-started → codeql://server/overview
• Language resource content moved from runtime file paths in language-types.ts to static imports (.md files under server/src/resources/languages/), eliminating loadResourceContent() and fs dependencies in language-resources.ts
• New E2E integration test (mcp-resource-e2e.integration.test.ts) verifying all resources return non-empty, non-fallback content; repo-level docs updated to point to MCP resource files as authoritative sources

Reviewed changes

Copilot reviewed 39 out of 41 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
server/src/lib/resources.ts	Replaces old getter functions with 8 new getters using static imports
server/src/tools/codeql-resources.ts	Registers all 8 static resources with updated URIs and descriptions
server/src/types/language-types.ts	Replaces file path strings with static .md imports for all language resources
server/src/resources/language-resources.ts	Removes loadResourceContent/fs in favor of pre-loaded content from language-types.ts
server/src/resources/learning-query-basics.md	New comprehensive QL query writing reference
server/src/resources/server-overview.md	New primary onboarding guide for LLM clients
server/src/resources/server-prompts.md	New complete prompt reference
server/src/resources/server-queries.md	New bundled tools queries overview (PrintAST, PrintCFG, etc.)
server/src/resources/server-tools.md	New complete tool reference (38 tools)
server/src/resources/ql-test-driven-development.md	Rewritten TDD conceptual overview (was detailed step-by-step guide)
server/src/resources/performance-patterns.md	Rewritten to focus on profiling tools workflow
server/src/resources/security-templates.md	Expanded with multi-language templates and v2 taint tracking API
server/src/resources/getting-started.md	Deleted (replaced by server-overview.md)
server/src/resources/query-basics.md	Deleted (replaced by learning-query-basics.md)
server/src/resources/languages/*.md	New language-specific AST/security .md files (previously were .prompt.md under ql/)
server/test/src/lib/resources.test.ts	Updated to test all 8 getter functions
server/test/src/resources/language-resources.test.ts	Removes fs mock, adds content handler tests
extensions/vscode/test/suite/mcp-resource-e2e.integration.test.ts	New E2E integration test for resource endpoints
extensions/vscode/esbuild.config.js	Adds new integration test file to build
docs/ql-mcp/resources.md	Updated resource table to reflect 8 resources
docs/ql-mcp/tools.md	Delegates to server-tools.md as authoritative source
docs/ql-mcp/prompts.md	Delegates to server-prompts.md as authoritative source
server/README.md	Updated resource descriptions

[Copilot]

Pull request overview

Copilot reviewed 39 out of 41 changed files in this pull request and generated 7 comments.

[Copilot]

Pull request overview

Copilot reviewed 58 out of 60 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 58 out of 60 changed files in this pull request and generated 1 comment.