Repository navigation
docs(readme): fenced install blocks so MCP directories can parse them - #341
Merged
Merged
Conversation
aiagentslisting.com reads README.adoc raw (GitHub's /readme choice) and only recognises Markdown ``` fences. It failed "Installation method" and "Easy install", and could not find the npx package for its live checks, although the npx command and mcpServers block were both present inside AsciiDoc [source]/---- blocks. Asciidoctor accepts ``` fences natively, so the == Install section now uses them (rendering unchanged), plus a bare `npx -y` line. README.md is re-derived with the pinned toolchain (pandoc 3.10, asciidoctor 2.0.26); this also clears staleness from today's badge-table edits. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R1piD9ewX1Qqm9ciFcmPxG
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configuration
📒 Files selected for processing (2)
Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review. 📜 Recent review details⏰ Context from checks skipped due to timeout. (25)
|
| Layer / File(s) | Summary |
|---|---|
README examples and reference layout README.md, README.adoc |
README.md groups badges, adds an MCP launch command, and reformats tool, transport and environment-variable tables. README.adoc replaces AsciiDoc source-block delimiters with Markdown fences for Claude Code, Claude Desktop and runtime examples. |
Priority: ⬇️ Low
Estimated code review effort: 1 (Trivial) | ~5 minutes
Change: Other
Merge Risk: ⚪ Minimal · up to b8515
The documentation changes have no established merge-blocking issue. The derivation workflow still needs a successful run, but its reported failure has not been tied to this change.
Architecture Summary
Architecture risk: 🔵 Low · up to b8515
The change affects 2 systems.
Changed systems: README.adoc, README.md
Architecture concerns
No architecture-level concerns identified.
Review details
Systems and components
- observed — README.adoc (service) was modified; 1 changed file maps to changed impact.
- observed — README.md (service) was modified; 1 changed file maps to changed impact.
Before / after behavior
- observed — Modified behavior in README.adoc: The Claude Code CLI examples now use Markdown fences instead of an AsciiDoc
[source,bash]block; theclaude mcp addand directnpxcommands are unchanged. - observed — Modified behavior in README.adoc: The Claude Desktop configuration example now opens with a Markdown JSON fence instead of the AsciiDoc
[source,json]delimiter. - observed — Modified behavior in README.adoc: The Claude Desktop configuration example now closes with a Markdown fence instead of the AsciiDoc source-block delimiter.
- observed — Modified behavior in README.adoc: The Deno/Bun/Node command example now opens with a Markdown Bash fence instead of the AsciiDoc
[source,bash]delimiter.
🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
| Check name | Status | Explanation |
|---|---|---|
| Docstring Coverage | ✅ Passed | No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0… |
| Linked Issues check | ✅ Passed | Check skipped because no linked issues were found for this pull request. |
| Out of Scope Changes check | ✅ Passed | Check skipped because no linked issues were found for this pull request. |
| Title check | ✅ Passed | The title clearly describes the main change: using fenced install blocks so MCP directories can parse them. |
| Description check | ✅ Passed | The description covers the summary, changes, quality checklist, testing, deferred checks and screenshots. It gives relevant context for the documentation-only changes and identifies that the listing s… |
✨ Finishing Touches
🛠️ Fix failing CI checks
- Commit to this branch
- Create a new PR
- Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
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.
A rabbit reads the fenced-in lines,
And finds the launch command just right.
The badges gather in neat rows,
The tables keep their facts in sight.
With README tidied, off it goes!
Comment @coderabbitai help to get the list of available commands.
🔍 Hypatia Security ScanFindings: 114 issues detected
View findings[
{
"reason": "Job `sonarqube` in build.yml has no `timeout-minutes:` declaration. Default is 6 hours — a stuck codeload fetch or runner hang can burn budget. Add `timeout-minutes: 10` (or proportional).",
"type": "missing_timeout_minutes",
"file": ".github/workflows/build.yml",
"action": "flag",
"rule_module": "workflow_audit",
"severity": "medium",
"recipe_id": "recipe-add-workflow-timeout-minutes",
"job": "sonarqube"
},
{
"reason": "Job `triage` in label-triage.yml has no `timeout-minutes:` declaration. Default is 6 hours — a stuck codeload fetch or runner hang can burn budget. Add `timeout-minutes: 10` (or proportional).",
"type": "missing_timeout_minutes",
"file": ".github/workflows/label-triage.yml",
"action": "flag",
"rule_module": "workflow_audit",
"severity": "medium",
"recipe_id": "recipe-add-workflow-timeout-minutes",
"job": "triage"
},
{
"reason": "Job `sync` in labels.yml has no `timeout-minutes:` declaration. Default is 6 hours — a stuck codeload fetch or runner hang can burn budget. Add `timeout-minutes: 10` (or proportional).",
"type": "missing_timeout_minutes",
"file": ".github/workflows/labels.yml",
"action": "flag",
"rule_module": "workflow_audit",
"severity": "medium",
"recipe_id": "recipe-add-workflow-timeout-minutes",
"job": "sync"
},
{
"reason": "Job `deploy` in pages-deploy.yml has no `timeout-minutes:` declaration. Default is 6 hours — a stuck codeload fetch or runner hang can burn budget. Add `timeout-minutes: 10` (or proportional).",
"type": "missing_timeout_minutes",
"file": ".github/workflows/pages-deploy.yml",
"action": "flag",
"rule_module": "workflow_audit",
"severity": "medium",
"recipe_id": "recipe-add-workflow-timeout-minutes",
"job": "deploy"
},
{
"reason": "Step uses `peter-evans/repository-dispatch` with `token: ${{ secrets.FARM_DISPATCH_TOKEN }}` but has no `if: secrets.FARM_DISPATCH_TOKEN != ''` gate. On repos where the secret hasn't been propagated the action fails on every push, red-maining the repo. Add the step-level gate (or env+if pattern) so the missing-secret path is a clean skip instead of a red.",
"type": "secret_action_without_presence_gate",
"file": ".github/workflows/instant-sync.yml",
"action": "peter-evans/repository-dispatch",
"rule_module": "workflow_audit",
"severity": "high",
"fix_recipe": "add_secret_presence_gate"
},
{
"reason": "codeql.yml does not list `language: actions` in its matrix, but the repo has workflow files. CodeQL's `actions` language scans workflow YAML for injection and other CI/CD-specific weaknesses — every repo with workflows benefits. Add an entry to `matrix.include` with `language: actions` + `build-mode: none`.",
"type": "codeql_missing_actions_language",
"file": ".github/workflows/codeql.yml",
"action": "flag",
"rule_module": "workflow_audit",
"severity": "medium",
"fix_recipe": "add_codeql_actions_language"
},
{
"line": 39,
"reason": "job in .github/workflows/labels.yml references `secrets.*` but does not install `step-security/harden-runner` — review outbound-egress monitoring",
"type": "RE001",
"file": ".github/workflows/labels.yml",
"action": "report",
"rule_module": "research_extensions",
"severity": "medium"
},
{
"line": 46,
"reason": "job in .github/workflows/push-email-notify.yml references `secrets.*` but does not install `step-security/harden-runner` — review outbound-egress monitoring",
"type": "RE001",
"file": ".github/workflows/push-email-notify.yml",
"action": "report",
"rule_module": "research_extensions",
"severity": "medium"
},
{
"line": 32,
"reason": "job in .github/workflows/build.yml references `secrets.*` but does not install `step-security/harden-runner` — review outbound-egress monitoring",
"type": "RE001",
"file": ".github/workflows/build.yml",
"action": "report",
"rule_module": "research_extensions",
"severity": "medium"
},
{
"line": 44,
"reason": "job in .github/workflows/container-publish.yml references `secrets.*` but does not install `step-security/harden-runner` — review outbound-egress monitoring",
"type": "RE001",
"file": ".github/workflows/container-publish.yml",
"action": "report",
"rule_module": "research_extensions",
"severity": "medium"
}
]Powered by Hypatia Neurosymbolic CI/CD Intelligence |
3 tasks
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
|
Add Carrot credits or activate Agent usage billing to use Autopilot |
Contributor
|
✅ Coding Agent task started: View task and status The task will inspect the CI failures, validate its fix, and commit the fix to this branch automatically.
⏭️ 2 check(s) skipped — already failing on `main` (not caused by this PR)
|
9 of 14 tasks
hyperpolymath
added a commit
that referenced
this pull request
Oct 7, 2026
…box can run it (#348) ## Summary Removes the `env` block from the Claude Desktop `mcpServers` example in the README. The goal is to let aiagentslisting.com's sandbox run the npx package, so the listing's four remaining checks can be credited: **Exposes tools** (required), Verified live, Ships prompts and Ships resources. The score is currently 49/100, grade F, with 2 of 3 required checks passed. Why this is thought to be the blocker: - At 2026-10-07T06:48Z the listing held `installConfig.mcpServers.boj-server.env = {"BOJ_URL": ""}`. The scanner blanks env values, the way it would for a credential the user must supply. - The listing has `serverTools: []` and no `serverToolsCheckedAt`, so the sandbox has never run against boj-server. - The one local-stdio npx server in a 28-listing sample (`discover` pages 1–4) that the sandbox did verify is `playwright-mcp`, with `serverToolsSource: "sandbox"` and a score of 80. Its config declares no `env`. This is a hypothesis. It's confirmed only once a rescan shows `serverToolsSource: "sandbox"`. `BOJ_URL` already defaults to `http://localhost:7700` (`mcp-bridge/lib/api-clients.js:14`), so the example behaves exactly as before, and the README still says how to set the variable. Follows #341, which fixed Installation method and Easy install; both now score full marks. ## Type of change Documentation only. ## 📌 New pins Head SHA: **`e1aa8d3c998c72e5fb728859ff589bd291806696`**. This PR adds or changes no pins: no action `uses:`, `actions.lock`, lockfile or container digest changes. ## Changes - `README.adoc`: dropped the `"env": { "BOJ_URL": … }` line from the Claude Desktop JSON fence, and added one sentence saying `BOJ_URL` defaults to `http://localhost:7700` and should be set under `env` only if the backend listens elsewhere. - `README.md`: re-derived from README.adoc (ADR-004). The only differences are those two changes. ## RSR Quality Checklist ### Required - [x] Tests pass. N/A in practice: this PR changes no code, only two README files. - [x] Code is formatted. N/A: no code changed. - [x] Linter is clean. N/A: no code changed. - [x] No banned language patterns. Documentation only; no new files. - [x] No `unsafe` blocks without `// SAFETY:` comments. N/A: no code changed. - [x] No banned functions. N/A: no code changed. - [x] SPDX license headers present. Both modified files keep their existing CC-BY-SA-4.0 headers, and there are no new files. - [x] No secrets, credentials, or `.env` files included. The removed line was a localhost default, not a secret. ### As Applicable - [ ] `.machine_readable/*` updated. N/A: project state didn't change, and A2ML is retired estate-wide (D308). - [x] Documentation updated for user-facing changes. That is the whole PR. - [ ] `TOPOLOGY.md` updated. N/A: architecture didn't change. - [ ] `CHANGELOG` updated. N/A: README example only, no release. - [ ] New dependencies reviewed. N/A: no dependencies added. - [ ] ABI/FFI changes validated. N/A: ABI and FFI untouched. ## Testing - **Server unaffected by the env value.** I ran `npx -y @hyperpolymath/boj-server@latest` (0.4.7) twice, once with `BOJ_URL` unset and once with `BOJ_URL=""`, sending initialize, `tools/list`, `prompts/list` and `resources/list`. Both runs completed a clean handshake and returned **65 tools, 6 prompts and 6 resources**, with nothing but JSON-RPC on stdout. - **README.md re-derived with the pinned pipeline.** asciidoctor 2.0.26 docbook5, then pandoc 3.10 gfm, plus the SPDX/GENERATED banner. The local reducer is 1.1.2 against the pinned 1.1.1; every other line of the output is identical to the committed file. The workflow's own `norm` + `diff -q` freshness step reports **up to date**. - **After merge:** the owner clicks Rescan, then `get_listing boj-server` should show `serverToolsSource: "sandbox"` and `quality.requiredPassed: true`. Deferred non-required reds that are also red on main@960ad299: `governance` and `SonarQube`, both tracked in #338. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01P56iYjCwHmbRyfFrpyJzTC Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Lifts the boj-server listing on aiagentslisting.com from F (22/49). The scanner reads
README.adocraw, because that is the file GitHub's/readmeAPI serves. It only recognises Markdown ``` fences, so it failed Installation method (required, 15) and Easy install (12). Because it never parsed thenpxcommand, it also reported "ships no npx package for our sandbox". That left the four live checks unscored (Verified live 20, Exposes tools 15, Ships prompts 8, Ships resources 8) and capped the grade at B. The command and the `mcpServers` block were already in the README, inside AsciiDoc `[source]` / `----` blocks.📌 New pins
Head SHA: b8515b9. No pins added or changed (docs-only: no
uses:,actions.lock, lockfile or container digest touched).Changes
README.adoc,== Installsection only: the three[source,bash|json]+----blocks become```bash/```jsonfences, which Asciidoctor accepts natively, so the page renders the same. The++_++escapes inside those blocks are dropped, since they are literal within fences. Adds a barenpx -y @hyperpolymath/boj-serverline.README.mdis re-derived with the README Derive workflow's pinned toolchain (asciidoctor-reducer → asciidoctor 2.0.26 docbook5 → pandoc 3.10 gfm, plus the SPDX/GENERATED banner). This also clears staleness onmain: today's badge-table edits toREADME.adochad not been re-derived.RSR Quality Checklist
Required
asciidoctor --failure-level=WARN -b docbook5exits 0 with no warnings.unsafeblocks without// SAFETY:. N/A: no code..envfiles.As Applicable
.machine_readable/STATE/ECOSYSTEM/META. N/A: no project state, integration or architecture change.TOPOLOGY.md. N/A.Testing
main, the only change is the addednpx -yblock. The install blocks were already fenced inREADME.md, and this PR keeps them fenced there.npx -y @hyperpolymath/boj-server@latest(npm 0.4.7), sendinginitialize,tools/list,prompts/listandresources/list. stdout was pure JSON-RPC (logs went to stderr). It returned 65 tools, 6 prompts, 6 resources, so unlocking the live checks can only add points.```jsonmcpServersand```bashnpx -y …fences.Deferred red checks (pre-existing on
main, non-required)All four fail identically on
mainatcb567a42, the base of this PR:readme-derive / Derive & verify README.md: deferred to README Derive check dies at toolchain install on main (pinned standards 84355587: gem --version with multiple gems) #342. The pinned standards reusable dies atgem installbefore it compares anything. I regeneratedREADME.mdlocally with the same pinned pandoc 3.10 / asciidoctor 2.0.26 recipe (see Testing).governance / Allowlist Preflight: deferred to Three pre-existing red non-required checks on main: Allowlist Preflight (empty GH_TOKEN), Workflow security linter (duplicatewithin abi-drift.yml), SonarQube (403) #338.governance / Workflow security linter: deferred to Three pre-existing red non-required checks on main: Allowlist Preflight (empty GH_TOKEN), Workflow security linter (duplicatewithin abi-drift.yml), SonarQube (403) #338 (duplicatewithinabi-drift.yml).SonarQube: deferred to Three pre-existing red non-required checks on main: Allowlist Preflight (empty GH_TOKEN), Workflow security linter (duplicatewithin abi-drift.yml), SonarQube (403) #338.Screenshots
N/A.
🤖 Generated with Claude Code
https://claude.ai/code/session_01R1piD9ewX1Qqm9ciFcmPxG