Repository navigation
Unit 3: Distillery and Serena MCP infrastructure - #12
Conversation
Unit 3 of the issue-native SDD suite. Makes two MCP servers available to the SDD agents as configuration, not hardcoded literals. - shared/sdd-mcp-distillery.md: importable fragment declaring the Distillery MCP server over HTTP transport with OAuth; documents the search, find_similar, relations, recall tools; endpoint and OAuth credentials read from repo or org variables and secrets; queries scoped via the project filter to this repository's own content. - shared/sdd-mcp-serena.md: importable fragment declaring the Serena MCP server over the checked-out working tree; pins no language; degrades gracefully to text-level file reading when no language server exists. - .github/workflows/distillery-sync.md: scheduled daily agentic workflow that ingests docs/specs/, decisions/, and issues and PRs via gh-sync. - .github/workflows/mcp-smoke.md: workflow_dispatch smoke test that resolves both MCP servers and returns a result from each. - docs/sdd/mcp-tools.md: MCP tooling reference and dispatch procedure, added to the mkdocs nav. Neither fragment carries a literal hostname, org slug, bot name, or absolute path. gh aw compile reports 0 errors. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
📝 WalkthroughSummary by CodeRabbit
WalkthroughThis PR introduces two Model Context Protocol server configurations (Distillery and Serena) and integrates them into two GitHub Actions workflows: distillery-sync for scheduled knowledge syncing, and mcp-smoke for manual integration testing. It includes shared MCP configuration fragments, complete workflow definitions with activation/agent/conclusion/safe-outputs orchestration, comprehensive design documentation, and updated site navigation. ChangesMCP Servers and Workflows
Sequence DiagramssequenceDiagram
participant Cron
participant Activation
participant Agent
participant Distillery
participant Conclusion
participant SafeOutputs
Cron->>Activation: trigger daily
Activation->>Activation: setup gh-aw, validate secrets
Activation->>Activation: build/render agent prompt
Activation->>Agent: upload activation artifacts
Agent->>Agent: restore artifacts, install Copilot CLI
Agent->>Distillery: query search/recall tools (MCP)
Distillery->>Agent: return semantic results
Agent->>Agent: run within AWF firewall sandbox
Agent->>Agent: redact logs, upload agent artifacts
Conclusion->>Conclusion: check agent outcome
Conclusion->>Conclusion: report failures if configured
SafeOutputs->>SafeOutputs: process and upload safe output items
sequenceDiagram
participant Manual
participant Activation
participant Agent
participant Gateway
participant Distillery as Distillery MCP
participant Serena as Serena MCP
participant CopilotCLI as Copilot CLI
participant Conclusion
Manual->>Activation: workflow_dispatch
Activation->>Activation: setup gh-aw, validate secrets
Activation->>Agent: upload activation artifacts
Agent->>Agent: restore artifacts, install Copilot/AWF
Agent->>Gateway: start MCP gateway (HTTP/container)
Gateway->>Distillery: expose via guard policy
Gateway->>Serena: expose via guard policy
Agent->>CopilotCLI: mount MCP servers as CLIs
CopilotCLI->>Distillery: call search tool
CopilotCLI->>Serena: call symbol/project tools
CopilotCLI->>CopilotCLI: execute within AWF firewall
Agent->>Agent: stop gateway, redact logs
Agent->>Agent: upload agent artifacts
Conclusion->>Conclusion: check outcomes, handle failures
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related issues
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
norrietaylor
left a comment
There was a problem hiding this comment.
Review: Unit 3 (Distillery and Serena MCP infrastructure)
Verdict: minor-only. All six Unit 3 requirements (R3.1 to R3.6) are met, the diff compiles clean (gh aw compile: 3 workflows, 0 errors), markdownlint is clean, lock files are byte-identical to a fresh recompile (no hand-editing), and no private literals or em dashes appear in hand-authored files. The two accepted deviations (workflow sources at .github/workflows/, inline MCP declarations rather than imports:) are implemented soundly. The findings below are all Minor or Nit; none block merge.
Spec compliance
All requirements verified against the diff:
- R3.1:
shared/sdd-mcp-distillery.mddeclares HTTP transport, OAuth viaAuthorization: Bearer, documentssearch/find_similar/relations/recall, endpoint and credential asvars/secretsexpressions. Met. - R3.2: project scoping documented as mandatory with the
projectfilter; "An agent that cannot scope a query does not run the query" is a strong, testable rule. Met. - R3.3:
distillery-sync.mdis a daily-cron agentic workflow ingestingdocs/specs/,decisions/, and issues/PRs viagh-sync. Met. - R3.4:
shared/sdd-mcp-serena.mddeclaresoraios/serenaover the working tree, pins no language, documents graceful degradation. Met. - R3.5: no literal hostname, org slug, bot name, or absolute path in either fragment; verified. Met.
- R3.6:
mcp-smoke.mdis aworkflow_dispatchworkflow resolving both servers;docs/sdd/mcp-tools.mddocuments the dispatch procedure and is inmkdocs.ymlnav. Met.
Proof artifacts (fragment files exist and pass leak-scan; gh aw compile succeeds with both MCP declarations) are present or achievable.
Minor
-
Source docs claim "opens no issue" but the compiled workflow grants
issues: writeand acreate_issuetool..github/workflows/distillery-sync.md:46states "adds no comment, opens no issue, and opens no pull request";.github/workflows/mcp-smoke.md:53makes the same claim. Neither source declares asafe-outputs:block, so gh-aw injects its defaultcreate_issuesafe-output:distillery-sync.lock.ymlandmcp-smoke.lock.ymlboth compile asafe_outputsjob withissues: writeand hand the agent acreate_issuetool ({"create_issue":{"labels":[...],"max":1,...}}). The prose and the compiled grant disagree. This is gh-aw default behavior also present in the already-mergedsample.lock.yml, so it is not newly introduced, but these two sources are the first to assert the opposite in prose. Fix: either declare an explicit emptysafe-outputs: {}(or whatever gh-aw's suppress form is) so the read-only claim and theissues:permission match, or soften the prose to acknowledge the default error-reporting issue path. The first is better for least privilege: a read-only smoke/sync workflow should not carryissues: write. -
Serena working-tree mount is
:rwin the read-only smoke test..github/workflows/mcp-smoke.md:25mounts${GITHUB_WORKSPACE}:${GITHUB_WORKSPACE}:rwwhile the smoke test'sallowedlist is read-only only (activate_project,find_symbol,get_project_structure). For an install-verification smoke run,:rois sufficient and tighter (least privilege,shared/principles.mdsurgical-changes). The shared fragmentsdd-mcp-serena.md:32correctly keeps:rwbecause executing agents need symbol edits; the smoke test does not. Fix: change the smoke test mount to:ro.
Nit
vars.DISTILLERY_MCP_URLflows into the firewallallowDomainslist verbatim. In both lock files the gh-aw firewall config embeds${{ vars.DISTILLERY_MCP_URL }}as an allowed domain. If an operator sets that variable to a full URL (https://host/path) rather than a bare hostname, the firewall allowlist entry may not match as intended. Not a defect in this PR (it is gh-aw's handling of anmcp-servers.url), but worth a one-line note indocs/sdd/mcp-tools.mdthatDISTILLERY_MCP_URLshould be set so its host component is resolvable, so an operator does not misconfigure it.
Notes (no action needed)
- The two accepted deviations are handled cleanly: the fragments carry valid
mcp-servers:frontmatter and the inline declarations in the two workflows are consistent with the fragments, so Unit 4's relocation will be a move plus animports:swap, not a rewrite. engine: copilotis consistent across all three workflow sources and matches the mergedsample.md.- The "untrusted input" framing in both fragments (
sdd-mcp-distillery.md:70-75,sdd-mcp-serena.md:85-89) is a good, spec-aligned addition (Security Considerations: "MCP outputs are untrusted input"). DISTILLERY_OAUTH_TOKENis referenced only as asecrets.expression and is in the firewall--exclude-envlist in the lock files; secret handling is sound.
mcp-smoke's Serena tools (activate_project, find_symbol, get_project_structure) are all read-only, so the working-tree mount needs no write access. Addresses a least-privilege finding from the PR #12 review. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Units 2 and 3 both added an SDD nav entry. Resolved into one SDD section listing both the pipeline guide and the MCP tools page. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (1)
shared/sdd-mcp-serena.md (1)
20-20: ⚡ Quick winPin the Serena image to an immutable version (tag+digest) for workflow reproducibility.
Using
:latestmakes workflow behavior non-deterministic across runs. Pin to a specific version and digest (e.g.,ghcr.io/github/serena-mcp-server:v1.x.x@sha256:...) from the GitHub Container Registry to keep MCP behavior reproducible and auditable.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@shared/sdd-mcp-serena.md` at line 20, Replace the floating image tag "ghcr.io/github/serena-mcp-server:latest" with an immutable tag+digest (for example "ghcr.io/github/serena-mcp-server:vX.Y.Z@sha256:...") so the container reference in the container field is pinned and reproducible; locate the container: "ghcr.io/github/serena-mcp-server:latest" line in the shared/sdd-mcp-serena.md file and update it to the specific release tag and its sha256 digest obtained from the GitHub Container Registry.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/workflows/distillery-sync.md:
- Around line 43-45: Reword the “read-only” claim for gh-sync or remove the
workflow's issue-creation paths: locate references to gh-sync and the workflow’s
failure-reporting/issue-write steps (the compiled workflow paths that create or
report an issue on failure) and either disable those issue-creation/reporting
steps or change the markdown text to say the run is read-only for content
changes but may report failures to GitHub (i.e., clarify it does not modify
repository content like issues/PRs only if issue-creation is removed; otherwise
explicitly state failure-reporting issues may be created).
- Around line 49-60: The workflow currently calls gh-sync without explicitly
passing the Distillery project, leaving project selection to inference; update
the gh-sync invocation(s) that process docs/specs/, decisions/, issues and pull
requests to include the explicit project variable (vars.DISTILLERY_PROJECT) so
the sync is deterministic; ensure the repository is derived from the workflow
context (github.repository or github.repository_owner/github.event) and passed
as the scope to gh-sync as before, and add a short summary log that references
vars.DISTILLERY_PROJECT when reporting counts of spec files, decision files,
issues, and pull requests ingested/refreshed.
In @.github/workflows/mcp-smoke.md:
- Around line 49-52: The workflow requires distillery.search to be scoped by a
project but does not provide a concrete slug; update the workflow to supply a
deterministic project slug (e.g., set vars.DISTILLERY_PROJECT) or use a known
source such as the repository slug (github.repository) when calling
distillery.search; specifically, ensure the action that invokes
distillery.search references the chosen variable (vars.DISTILLERY_PROJECT or
github.repository) so the project filter is always populated and the smoke test
queries the intended project.
- Around line 61-62: The README/description line "This workflow is read-only. It
posts no comment, opens no issue, and opens no pull request." is inaccurate
because the compiled workflow still contains issue-write failure/reporting
paths; update the workflow description or the workflow logic: either
remove/disable the failure-reporting steps that create issues/comments/PRs (the
steps that run on error and call issue/comment/PR actions), or edit the sentence
to narrow it (e.g., "This workflow is read-only except for optional
failure-reporting paths that may open issues or post comments"). Locate the
failure-reporting steps by searching for actions that create issues/comments/PRs
and the description text in the workflow and make the corresponding change.
---
Nitpick comments:
In `@shared/sdd-mcp-serena.md`:
- Line 20: Replace the floating image tag
"ghcr.io/github/serena-mcp-server:latest" with an immutable tag+digest (for
example "ghcr.io/github/serena-mcp-server:vX.Y.Z@sha256:...") so the container
reference in the container field is pinned and reproducible; locate the
container: "ghcr.io/github/serena-mcp-server:latest" line in the
shared/sdd-mcp-serena.md file and update it to the specific release tag and its
sha256 digest obtained from the GitHub Container Registry.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: e1fce270-d44f-4411-b34a-a8dc73ef9d78
📒 Files selected for processing (8)
.github/workflows/distillery-sync.lock.yml.github/workflows/distillery-sync.md.github/workflows/mcp-smoke.lock.yml.github/workflows/mcp-smoke.mddocs/sdd/mcp-tools.mdmkdocs.ymlshared/sdd-mcp-distillery.mdshared/sdd-mcp-serena.md
| `gh-sync` is incremental: it indexes new and changed content and leaves | ||
| unchanged content alone. The run is read-only with respect to GitHub; it adds | ||
| no comment, opens no issue, and opens no pull request. |
There was a problem hiding this comment.
“Read-only” wording conflicts with actual workflow behavior.
This text says no issue is opened, but the compiled workflow has issue-write failure/reporting paths. Either disable failure issue creation or reword this section to avoid a false guarantee.
🧰 Tools
🪛 LanguageTool
[style] ~44-~44: ‘with respect to’ might be wordy. Consider a shorter alternative.
Context: ...ged content alone. The run is read-only with respect to GitHub; it adds no comment, opens no is...
(EN_WORDINESS_PREMIUM_WITH_RESPECT_TO)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.github/workflows/distillery-sync.md around lines 43 - 45, Reword the
“read-only” claim for gh-sync or remove the workflow's issue-creation paths:
locate references to gh-sync and the workflow’s failure-reporting/issue-write
steps (the compiled workflow paths that create or report an issue on failure)
and either disable those issue-creation/reporting steps or change the markdown
text to say the run is read-only for content changes but may report failures to
GitHub (i.e., clarify it does not modify repository content like issues/PRs only
if issue-creation is removed; otherwise explicitly state failure-reporting
issues may be created).
| All ingested content is filed under this repository's own Distillery project | ||
| (the configured project slug). The store may be shared, so this workflow | ||
| ingests only this repository's content and files it under this repository's | ||
| project. It never ingests, reads, or writes another project's content. | ||
|
|
||
| ## Procedure | ||
|
|
||
| 1. Determine the repository from the workflow context. | ||
| 2. Call `gh-sync` for the `docs/specs/` path, the `decisions/` path, and this | ||
| repository's issues and pull requests, scoped to this repository's project. | ||
| 3. Log a short summary: how many spec files, decision files, issues, and pull | ||
| requests were ingested or refreshed. |
There was a problem hiding this comment.
Make Distillery project scoping explicit and deterministic.
This workflow requires project-scoped gh-sync, but it never references vars.DISTILLERY_PROJECT, so project selection is left to inference. That can ingest into the wrong Distillery project.
🔧 Suggested patch
## Procedure
1. Determine the repository from the workflow context.
-2. Call `gh-sync` for the `docs/specs/` path, the `decisions/` path, and this
- repository's issues and pull requests, scoped to this repository's project.
+2. Resolve the Distillery project slug from `${{ vars.DISTILLERY_PROJECT }}`.
+3. Call `gh-sync` for the `docs/specs/` path, the `decisions/` path, and this
+ repository's issues and pull requests, with a mandatory `project` filter set
+ to that slug.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.github/workflows/distillery-sync.md around lines 49 - 60, The workflow
currently calls gh-sync without explicitly passing the Distillery project,
leaving project selection to inference; update the gh-sync invocation(s) that
process docs/specs/, decisions/, issues and pull requests to include the
explicit project variable (vars.DISTILLERY_PROJECT) so the sync is
deterministic; ensure the repository is derived from the workflow context
(github.repository or github.repository_owner/github.event) and passed as the
scope to gh-sync as before, and add a short summary log that references
vars.DISTILLERY_PROJECT when reporting counts of spec files, decision files,
issues, and pull requests ingested/refreshed.
| 1. **Distillery.** Call the Distillery `search` tool with a short query (for | ||
| example, the repository name or a term from a known spec), scoped to this | ||
| repository's project via the `project` filter. Confirm the call returns a | ||
| result set. |
There was a problem hiding this comment.
Project filter requirement needs an explicit slug source.
You require distillery.search to be scoped by project, but this workflow does not expose vars.DISTILLERY_PROJECT. Without a concrete slug source, the smoke test can query the wrong project and give misleading pass/fail results.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.github/workflows/mcp-smoke.md around lines 49 - 52, The workflow requires
distillery.search to be scoped by a project but does not provide a concrete
slug; update the workflow to supply a deterministic project slug (e.g., set
vars.DISTILLERY_PROJECT) or use a known source such as the repository slug
(github.repository) when calling distillery.search; specifically, ensure the
action that invokes distillery.search references the chosen variable
(vars.DISTILLERY_PROJECT or github.repository) so the project filter is always
populated and the smoke test queries the intended project.
| This workflow is read-only. It posts no comment, opens no issue, and opens no | ||
| pull request. |
There was a problem hiding this comment.
Read-only claim is not strictly true in the generated workflow.
The compiled workflow contains issue-write failure/reporting paths, so “opens no issue” is inaccurate as written. Please either disable that path or narrow this claim.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.github/workflows/mcp-smoke.md around lines 61 - 62, The README/description
line "This workflow is read-only. It posts no comment, opens no issue, and opens
no pull request." is inaccurate because the compiled workflow still contains
issue-write failure/reporting paths; update the workflow description or the
workflow logic: either remove/disable the failure-reporting steps that create
issues/comments/PRs (the steps that run on error and call issue/comment/PR
actions), or edit the sentence to narrow it (e.g., "This workflow is read-only
except for optional failure-reporting paths that may open issues or post
comments"). Locate the failure-reporting steps by searching for actions that
create issues/comments/PRs and the description text in the workflow and make the
corresponding change.
Implements Unit 3 of the issue-native SDD suite (
docs/specs/01-spec-issue-native-sdd): shared MCP infrastructure for the SDD agents, configured not hardcoded.Closes #3
What each requirement delivers
shared/sdd-mcp-distillery.md: importable fragment declaring the Distillery MCP server over HTTP transport, authenticated via OAuth. Documents thesearch,find_similar,relations, andrecalltools. The endpoint, OAuth credential, and project slug are read from repo or org variables and secrets (vars.DISTILLERY_MCP_URL,secrets.DISTILLERY_OAUTH_TOKEN,vars.DISTILLERY_PROJECT); no endpoint or org slug is a literal.sdd-*Distillery query must be scoped via theprojectfilter to this repository's own ingested content, so a shared store cannot leak unrelated or private knowledge into public artifacts. Scoping is documented as mandatory..github/workflows/distillery-sync.md: scheduled (schedule: daily) agentic workflow that ingests this repo'sdocs/specs/,decisions/, and issues and PRs into Distillery via thegh-synctool.shared/sdd-mcp-serena.md: importable fragment declaring the Serena MCP server (oraios/serena) over the checked-out working tree. Pins no language (the language-server set is resolved at install time) and states graceful degradation to text-level file reading when no language server exists for the stack.GITHUB_WORKSPACE..github/workflows/mcp-smoke.md: aworkflow_dispatchsmoke workflow that resolves both MCP servers and returns one result from each, for install verification.docs/sdd/mcp-tools.mddocuments the MCP tooling and the dispatch procedure, and is added to themkdocs.ymlnav.Deviations from the spec's literal paths
The spec's "Affected areas" places SDD workflow sources under
workflows/.gh aw compileonly processes.github/workflows/*.md(the task anticipated this). The two gh-aw workflow sources are therefore placed at.github/workflows/distillery-sync.mdand.github/workflows/mcp-smoke.mdso they genuinely compile.gh-aw's import resolver rejects any import path outside
.github/for security, so a workflow cannot import a repo-rootshared/*.mdfragment. The two MCP fragments are delivered atshared/per the R3.1/R3.4 deliverable text and matching the existing Unit 1 fragments; they contain valid gh-awmcp-servers:frontmatter. Because they cannot yet be imported from a.github/-rooted workflow,distillery-syncandmcp-smokedeclare their MCP servers inline (consistent with the fragments) rather than viaimports:. Wiring theshared/directory into thesdd-*agents as imports is Unit 4's concern; that unit will resolve the directory location for the wholeshared/tree.Security review (gh-aw strict-mode)
gh aw compilestrict mode flagged one new restricted secret:DISTILLERY_OAUTH_TOKEN. It is the OAuth bearer token for the Distillery HTTP MCP endpoint, referenced only as${{ secrets.DISTILLERY_OAUTH_TOKEN }}in theAuthorizationheader of the Distillery MCP server declaration. It is never logged and never written as a literal. No new actions were added; the existing pinned action set is reused. The change was approved into the gh-aw manifest withgh aw compile --approve.Verification
gh aw compile: 3 workflows, 0 errors, 0 warnings. Both MCP server declarations compile; configuration expressions are preserved (no literals in the.lock.yml).npx markdownlint-cli2 "**/*.md": 0 errors.mkdocs build --strict: builds clean..lock.ymlfiles are committed as gh-aw produced them (the repo standard exempts toolchain-generated lock files; the already-mergedsample.lock.ymlcarries the same gh-aw-generated content).🤖 Generated with Claude Code