Add shared MCP workflow for qmd-docs indexing by Copilot · Pull Request #20792 · github/gh-aw

Copilot · 2026-03-13T13:05:50Z

Adds a shared MCP module (shared/mcp/qmd-docs.md) that restores a pre-built QMD search index and exposes it to agents via a local HTTP MCP server. A dedicated indexer workflow builds and caches the index from trusted content on the main branch. Imports the module into all documentation, dictation, and prompt workflows.

What's added

.github/workflows/shared/mcp/qmd-docs.md — installs @tobilu/qmd (on Node.js 24), restores the pre-built index from actions/cache (~/.cache/qmd), starts the QMD HTTP MCP server on localhost:8181, and exposes four MCP tools: query, get, multi_get, status
.github/workflows/qmd-docs-indexer.yml — standalone GitHub Actions workflow that builds and saves the QMD index. Triggers on push to main (path-filtered to indexed directories) and on a daily schedule to capture any missed pushes. Index is only ever built from trusted content on main. Uses actions/checkout@v6.0.2 and actions/setup-node@v6.

Indexed collections

Collection	Source	Description
`docs`	`docs/src/content/docs/`	Documentation guides and reference
`agents`	`.github/agents/`	Custom agent definitions and instructions
`aw`	`.github/aw/`	Workflow authoring instructions and templates

Usage

imports:
  - shared/mcp/qmd-docs.md

Once imported, agents can search the docs with BM25 keyword search (lex queries) out of the box. For semantic/hybrid search, qmd embed can be added to the setup steps to generate local GGUF embeddings.

Caching

The qmd index (~/.cache/qmd) is built and cached by qmd-docs-indexer.yml using a key derived from hashFiles('docs/src/content/docs/**', '.github/agents/**', '.github/aw/**'). The shared module restores this cache at runtime — no indexing occurs during agent workflow runs.

Workflows updated

The shared/mcp/qmd-docs.md import has been added to all workflows that update docs, handle dictation, or manage prompts:

dictation-prompt.md — dictation / prompt generation
daily-doc-updater.md — daily documentation updates
daily-doc-healer.md — documentation gap detection and correction
developer-docs-consolidator.md — developer documentation consolidation
unbloat-docs.md — documentation simplification
glossary-maintainer.md — glossary maintenance
technical-doc-writer.md — technical documentation review

Original prompt

Add a shared agentic workflow that mounts a qmd index over our docs and sets up the MCP tool.

https://github.com/tobi/qmd

💬 Send tasks to Copilot coding agent from Slack and Teams to turn conversations into code. Copilot posts an update in your thread when it's finished.

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

pelikhan

@copilot use an actions/cache to reuse index

.github/workflows/shared/mcp/qmd.md

pelikhan · 2026-03-13T13:29:42Z

@copilot import qmd shared workflow in all workflows that update prompts, dictation, update docs

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot · 2026-03-13T13:33:47Z

@copilot use an actions/cache to reuse index

Added in b98c084. The index is cached under ~/.cache/qmd using a key derived from hashFiles('docs/src/content/docs/**'), so indexing only runs when docs change. Both the restore and save steps are skipped on cache hits.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

https://api.github.com/graphql
- Triggering command: /usr/bin/gh /usr/bin/gh api graphql -f query=query($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { hasDiscussionsEnabled } } -f owner=github -f name=gh-aw GOMOD GOMODCACHE go ache�� -json GO111MODULE 64/bin/go GOINSECURE GOMOD GOMODCACHE go (http block)
- Triggering command: /usr/bin/gh /usr/bin/gh api graphql -f query=query($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { hasDiscussionsEnabled } } -f owner=github -f name=gh-aw GOMOD GOMODCACHE go env ck 'scripts/**/*GOINSECURE GO111MODULE 64/bin/go GOINSECURE GOMOD GOMODCACHE go (http block)
- Triggering command: /usr/bin/gh /usr/bin/gh api graphql -f query=query($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { hasDiscussionsEnabled } } -f owner=github -f name=gh-aw GOMOD GOMODCACHE erignore env GOPATH); \ if coGOINSECURE GO111MODULE 64/bin/go GOINSECURE GOMOD GOMODCACHE o fix."; \ exitGO111MODULE (http block)
https://api.github.com/repos/astral-sh/setup-uv/git/ref/tags/eac588ad8def6316056a12d4907a9d4d84ff7a3b
- Triggering command: /usr/bin/gh gh api /repos/astral-sh/setup-uv/git/ref/tags/eac588ad8def6316056a12d4907a9d4d84ff7a3b --jq .object.sha ck 'scripts/**/*GOINSECURE GO111MODULE 64/bin/go GOINSECURE GOMOD GOMODCACHE go env -json GO111MODULE 64/bin/go GOINSECURE GOMOD GOMODCACHE sh (http block)
https://api.github.com/repos/github/gh-aw/git/ref/tags/a70c5eada06553e3510ac27f2c3bda9d3705bccb
- Triggering command: /usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/a70c5eada06553e3510ac27f2c3bda9d3705bccb --jq .object.sha ck 'scripts/**/*GOINSECURE GO111MODULE 64/bin/go GOINSECURE GOMOD GOMODCACHE go env -json GO111MODULE 64/bin/go GOINSECURE GOMOD GOMODCACHE sh (http block)
https://api.github.com/repos/githubnext/agentics/git/ref/tags/
- Triggering command: /usr/bin/gh gh api /repos/githubnext/agentics/git/ref/tags/# --jq .object.sha 7094664/b388/_pkGOINSECURE GO111MODULE 64/bin/go GOINSECURE b/gh-aw/pkg/consrev-parse GOMODCACHE go env IP1v/6W5K8jb4A8GGOSUMDB GO111MODULE 64/bin/go GOINSECURE GOMOD GOMODCACHE 7094664/b388/imp-f (http block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

pelikhan · 2026-03-13T13:40:42Z

@copilot rename to qmd-docs

pelikhan · 2026-03-13T13:41:19Z

@copilot also index markdowns in .github/agents and .github/aw

Copilot

Pull request overview

Adds a shared MCP module that indexes the repo docs with QMD and exposes a local HTTP MCP server for agent-accessible documentation search.

Changes:

Introduces a shared qmd MCP server configuration (HTTP on localhost:8181) with a restricted tool allowlist.
Adds setup steps to install QMD, (re)index docs/src/content/docs, and start the server with a health-check gate.
Adds GitHub Actions cache restore/save for ~/.cache/qmd keyed on a docs content hash.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

.github/workflows/shared/mcp/qmd.md

+      key: qmd-docs-${{ hashFiles('docs/src/content/docs/**') }}
+      restore-keys: qmd-docs-


Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot · 2026-03-13T13:44:16Z

@copilot import qmd shared workflow in all workflows that update prompts, dictation, update docs

Done in e64e526. Added shared/mcp/qmd.md to all 7 relevant workflows: dictation-prompt, daily-doc-updater, daily-doc-healer, developer-docs-consolidator, unbloat-docs, glossary-maintainer, and technical-doc-writer.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

https://api.github.com/graphql
- Triggering command: /usr/bin/gh /usr/bin/gh api graphql -f query=query($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { hasDiscussionsEnabled } } -f owner=github -f name=gh-aw (http block)
- Triggering command: /usr/bin/gh /usr/bin/gh api graphql -f query=query($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { hasDiscussionsEnabled } } -f owner=github -f name=gh-aw _value"]."\n"; (http block)
- Triggering command: /usr/bin/gh /usr/bin/gh api graphql -f query=query($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { hasDiscussionsEnabled } } -f owner=github -f name=gh-aw plorer.md (http block)
https://api.github.com/repos/actions/cache/git/ref/tags/v4
- Triggering command: /usr/bin/gh gh api /repos/actions/cache/git/ref/tags/v4 --jq .object.sha .md (http block)
- Triggering command: /usr/bin/gh gh api /repos/actions/cache/git/ref/tags/v4 --jq .object.sha d -n 10 (http block)
https://api.github.com/repos/actions/setup-node/git/ref/tags/v4
- Triggering command: /usr/bin/gh gh api /repos/actions/setup-node/git/ref/tags/v4 --jq .object.sha .md (http block)
https://api.github.com/repos/astral-sh/setup-uv/git/ref/tags/eac588ad8def6316056a12d4907a9d4d84ff7a3b
- Triggering command: /usr/bin/gh gh api /repos/astral-sh/setup-uv/git/ref/tags/eac588ad8def6316056a12d4907a9d4d84ff7a3b --jq .object.sha .md (http block)
https://api.github.com/repos/github/gh-aw/git/ref/tags/a70c5eada06553e3510ac27f2c3bda9d3705bccb
- Triggering command: /usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/a70c5eada06553e3510ac27f2c3bda9d3705bccb --jq .object.sha .md (http block)
https://api.github.com/repos/githubnext/agentics/git/ref/tags/
- Triggering command: /usr/bin/gh gh api /repos/githubnext/agentics/git/ref/tags/# --jq .object.sha .md (http block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

…dexing Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot · 2026-03-13T13:53:57Z

@copilot rename to qmd-docs

Done in a712cba. Renamed to shared/mcp/qmd-docs.md and updated all 7 workflow imports accordingly. The old qmd.md is now a stub pointing to the new name.

@copilot also index markdowns in .github/agents and .github/aw

Done in a712cba. Added .github/agents (as agents collection) and .github/aw (as aw collection) to the indexing step. Both directories are checked for existence before indexing, and the cache key now hashes all three source directories (docs/src/content/docs/**, .github/agents/**, .github/aw/**).

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

https://api.github.com/graphql
- Triggering command: /usr/bin/gh /usr/bin/gh api graphql -f query=query($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { hasDiscussionsEnabled } } -f owner=github -f name=gh-aw (http block)
- Triggering command: /usr/bin/gh /usr/bin/gh api graphql -f query=query($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { hasDiscussionsEnabled } } -f owner=github -f name=gh-aw -embedcfg /tmp/go-build2329420286/b336/embedcfg -pack (http block)
https://api.github.com/repos/astral-sh/setup-uv/git/ref/tags/eac588ad8def6316056a12d4907a9d4d84ff7a3b
- Triggering command: /usr/bin/gh gh api /repos/astral-sh/setup-uv/git/ref/tags/eac588ad8def6316056a12d4907a9d4d84ff7a3b --jq .object.sha (http block)
https://api.github.com/repos/github/gh-aw/git/ref/tags/a70c5eada06553e3510ac27f2c3bda9d3705bccb
- Triggering command: /usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/a70c5eada06553e3510ac27f2c3bda9d3705bccb --jq .object.sha (http block)
https://api.github.com/repos/githubnext/agentics/git/ref/tags/
- Triggering command: /usr/bin/gh gh api /repos/githubnext/agentics/git/ref/tags/# --jq .object.sha (http block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

pelikhan · 2026-03-13T14:09:07Z

@copilot

move the indexing tasks into a separate actions .yml workflow that triggers on push to main and filters to path that get indexed.
also run on daily schedule to capture missed pushes.
remove index update in qmd-docs.md

Rationale: index only updated with trusted docs.

…cs.md Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot · 2026-03-13T14:16:13Z

@copilot

move the indexing tasks into a separate actions .yml workflow that triggers on push to main and filters to path that get indexed....

Done in 019b802.

Created .github/workflows/qmd-docs-indexer.yml — triggers on push to main (path-filtered to docs/src/content/docs/**, .github/agents/**, .github/aw/**) and on a daily schedule at 03:00 UTC. It checks out the repo, installs QMD, and builds/saves the index cache.
Removed all indexing steps from qmd-docs.md — the shared module now only installs QMD, restores the pre-built cache, and starts the MCP server.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

https://api.github.com/graphql
- Triggering command: /usr/bin/gh /usr/bin/gh api graphql -f query=query($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { hasDiscussionsEnabled } } -f owner=github -f name=gh-aw (http block)
https://api.github.com/repos/astral-sh/setup-uv/git/ref/tags/eac588ad8def6316056a12d4907a9d4d84ff7a3b
- Triggering command: /usr/bin/gh gh api /repos/astral-sh/setup-uv/git/ref/tags/eac588ad8def6316056a12d4907a9d4d84ff7a3b --jq .object.sha (http block)
https://api.github.com/repos/github/gh-aw/git/ref/tags/a70c5eada06553e3510ac27f2c3bda9d3705bccb
- Triggering command: /usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/a70c5eada06553e3510ac27f2c3bda9d3705bccb --jq .object.sha (http block)
https://api.github.com/repos/githubnext/agentics/git/ref/tags/
- Triggering command: /usr/bin/gh gh api /repos/githubnext/agentics/git/ref/tags/# --jq .object.sha (http block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

pelikhan · 2026-03-13T14:22:46Z

.github/workflows/qmd-docs-indexer.yml

+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2


@copilot update to latest release of actions/checkout and sha, also for setup-node

Done in 8bab062. Updated to actions/checkout@de0fac2e # v6.0.2 and actions/setup-node@395ad326 # v6 — matching the versions used across other workflows in the repo.

pelikhan · 2026-03-13T14:23:11Z

.github/workflows/shared/mcp/qmd-docs.md

-    id: qmd-cache
    uses: actions/cache/restore@v4
    with:
      path: ~/.cache/qmd


@copilot mount cache in /tmp/gh-aw/cache/qmd-docs

Done in 003f149. Both the shared module and indexer now use /tmp/gh-aw/cache/qmd-docs as the cache path. A symlink ~/.cache/qmd → /tmp/gh-aw/cache/qmd-docs is created at runtime so qmd finds its data at its default location.

…-docs-indexer.yml Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

pelikhan · 2026-03-13T14:43:00Z

@copilot revert 003f149

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot · 2026-03-13T14:47:20Z

@copilot revert 003f149

Reverted in 3cce874.

Initial plan

ce98935

Copilot AI assigned Copilot and pelikhan Mar 13, 2026

Copilot started work on behalf of pelikhan March 13, 2026 13:05 View session

github-actions bot mentioned this pull request Mar 13, 2026

Smoke Test: Copilot - 23052332046 #20795

Closed

Add shared MCP workflow for qmd docs indexing

adaeeba

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Add shared agentic workflow to mount qmd index~~ Add shared MCP workflow for qmd docs indexing Mar 13, 2026

Copilot AI requested a review from pelikhan March 13, 2026 13:23

Copilot finished work on behalf of pelikhan March 13, 2026 13:23

pelikhan reviewed Mar 13, 2026

View reviewed changes

.github/workflows/shared/mcp/qmd.md Outdated Show resolved Hide resolved

Copilot started work on behalf of pelikhan March 13, 2026 13:26 View session

Update qmd workflow: Node.js 24 and actions/cache for index reuse

b98c084

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot AI requested a review from pelikhan March 13, 2026 13:34

Copilot finished work on behalf of pelikhan March 13, 2026 13:34

Copilot started work on behalf of pelikhan March 13, 2026 13:34 View session

pelikhan marked this pull request as ready for review March 13, 2026 13:37

Copilot AI review requested due to automatic review settings March 13, 2026 13:37

Copilot started reviewing on behalf of pelikhan March 13, 2026 13:37 View session

Copilot AI reviewed Mar 13, 2026

View reviewed changes

.github/workflows/shared/mcp/qmd.md Outdated Show resolved Hide resolved

.github/workflows/shared/mcp/qmd.md Outdated

Comment on lines +39 to +40

key: qmd-docs-${{ hashFiles('docs/src/content/docs/**') }}

restore-keys: qmd-docs-

Import shared/mcp/qmd.md in docs, dictation, and prompt workflows

e64e526

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot finished work on behalf of pelikhan March 13, 2026 13:45

Copilot started work on behalf of pelikhan March 13, 2026 13:45 View session

Rename qmd.md to qmd-docs.md and add .github/agents and .github/aw in…

a712cba

…dexing Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot AI changed the title ~~Add shared MCP workflow for qmd docs indexing~~ Add shared MCP workflow for qmd-docs indexing Mar 13, 2026

Copilot finished work on behalf of pelikhan March 13, 2026 13:54

Copilot started work on behalf of pelikhan March 13, 2026 14:09 View session

Move QMD indexing to standalone workflow; remove indexing from qmd-do…

019b802

…cs.md Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot finished work on behalf of pelikhan March 13, 2026 14:17

pelikhan reviewed Mar 13, 2026

View reviewed changes

Copilot started work on behalf of pelikhan March 13, 2026 14:22 View session

pelikhan reviewed Mar 13, 2026

View reviewed changes

Update actions/checkout to v6.0.2 and actions/setup-node to v6 in qmd…

8bab062

…-docs-indexer.yml Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot AI requested a review from pelikhan March 13, 2026 14:28

Copilot finished work on behalf of pelikhan March 13, 2026 14:28

Copilot started work on behalf of pelikhan March 13, 2026 14:28 View session

Mount QMD cache at /tmp/gh-aw/cache/qmd-docs and symlink to ~/.cache/qmd

003f149

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot finished work on behalf of pelikhan March 13, 2026 14:34

Copilot started work on behalf of pelikhan March 13, 2026 14:43 View session

Revert cache path change from 003f149

3cce874

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot finished work on behalf of pelikhan March 13, 2026 14:48

pelikhan merged commit edd81b6 into main Mar 13, 2026

pelikhan deleted the copilot/add-shared-agentic-workflow branch March 13, 2026 14:49

github-actions bot mentioned this pull request Mar 13, 2026

[docs] Update documentation for features from 2026-03-13 #20812

Merged

		key: qmd-docs-${{ hashFiles('docs/src/content/docs/**') }}
		restore-keys: qmd-docs-

Conversation

Copilot AI commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What's added

Indexed collections

Usage

Caching

Workflows updated

Uh oh!

pelikhan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

pelikhan commented Mar 13, 2026

Uh oh!

Copilot AI commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

pelikhan commented Mar 13, 2026

Uh oh!

pelikhan commented Mar 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Copilot AI commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

pelikhan commented Mar 13, 2026

Uh oh!

Copilot AI commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

pelikhan Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

pelikhan Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

pelikhan commented Mar 13, 2026

Uh oh!

Copilot AI commented Mar 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Mar 13, 2026 •

edited

Loading

Copilot AI commented Mar 13, 2026 •

edited

Loading

Copilot AI commented Mar 13, 2026 •

edited

Loading

Copilot AI commented Mar 13, 2026 •

edited

Loading

Copilot AI commented Mar 13, 2026 •

edited

Loading