Skip to content

Universal SEO skill for Claude Code. 26 sub-skills + 19 sub-agents covering technical SEO, E-E-A-T, schema, GEO/AEO, agent readiness (Lighthouse Agentic Browsing, WebMCP, llms.txt), backlinks, local SEO, e-commerce, international SEO, Google APIs, and PDF/Excel reporting. 9 optional extensions for live SEO data.

fix(release): address the fresh-context review of the v2.3.1 branch

Agrici Daniel52197c2d5f2e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 07aab30..bf95064 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -43,6 +43,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Fixed
+- `metadata_template.py`, added in v2.3.0, was not registered in the launcher's
+ `ALLOWED_CORE_SCRIPTS`, so `claude-seo run metadata_template.py` was refused for
+ `/seo page` and `/seo programmatic`. Registered, with a test that every script an
+ instruction file invokes is allowlisted.
+- The dataforseo, ahrefs and firecrawl PowerShell installers created `mcpServers` as
+ a hashtable, which `ConvertTo-Json` serialised as `{}` when `~/.claude.json` was
+ missing or had no `mcpServers` yet, silently dropping the server entry; they now
+ create an object. They also wrote the file with a byte-order mark on Windows
+ PowerShell 5.1, which Node's JSON parser rejects; the write is BOM-free now.
- `_run_checked` discarded a failing setup stage's stderr/stdout, so a broken
venv or pip install reported only "failed with exit code 1" with nothing
actionable. It now surfaces a bounded tail of the child's own output, pip is
diff --git a/README.md b/README.md
index 88452f4..1ab8963 100644
--- a/README.md
+++ b/README.md
@@ -340,7 +340,7 @@ Test coverage grew from 39 (v1.9.9) to 410 across the v2 line; the url_safety su
- **v2.2.5 (August 2026): reliability and Google-currency hardening.** Fixed manual-install data packaging and lxml runtime imports, hardened JSON-LD graphs and rendered-page accessibility analysis, enforced managed-runtime command references, and refreshed Google Search and Lighthouse guidance through August 25.
- **v2.2.6 (September 2026): security and hosted-install patch.** Closed a cache-path traversal and a WHOIS referral SSRF, refused the RFC 6598 range, moved the launcher to `scripts/` so the claude.ai-hosted marketplace accepts the plugin, raised dependency floors past PYSEC-2026-3940, locked the cost ledgers, and added Windows, macOS, and pip-audit CI.
- **v2.3.0 (September 2026): Google currency and community fixes.** Refreshed Google guidance through 2026-09-10 (EEA site-reputation enforcement, regional aggregator and supplier units, AI Mode travel, CrUX August), added the `CLAUDE_SEO_LOCAL_TARGETS` allowlist and proxy validation, hardened the JSON-LD hook and Unicode watermark stripping, corrected AI crawler guidance, unified `fetch_page --json`, fixed Unlighthouse flags, raised audit agent turn budgets, and landed 12 more community PRs.
-- **v2.3.1 (September 2026): agents on Opus and community follow-ups.** Five judgment-heavy agents run on Opus, Keywords Everywhere joins as a free backlinks fallback, setup failures show the failing stage's output, the remaining extension installers write `~/.claude.json` atomically, and two v2.3.0 scripts are registered with the launcher.
+- **v2.3.1 (September 2026): agents on Opus and community follow-ups.** Five judgment-heavy agents run on Opus, Keywords Everywhere joins as a free backlinks fallback, setup failures show the failing stage's output, the remaining extension installers write `~/.claude.json` atomically, and the v2.3.0 templated-metadata script is registered with the launcher.
## Limitations
diff --git a/extensions/ahrefs/install.ps1 b/extensions/ahrefs/install.ps1
index 9c1500e..2e68029 100644
--- a/extensions/ahrefs/install.ps1
+++ b/extensions/ahrefs/install.ps1
@@ -37,8 +37,8 @@ Write-Host "✓ Installed skill: $SkillTarget"
& npx --yes --package=@ahrefs/[email protected] mcp --help *> $null
# Merge ~/.claude.json.
-$settingsContent = if (Test-Path $McpConfigJson) { Get-Content $McpConfigJson -Raw | ConvertFrom-Json } else { @{} }
-if (-not $settingsContent.mcpServers) { $settingsContent | Add-Member -NotePropertyName mcpServers -NotePropertyValue @{} -Force }
+$settingsContent = if (Test-Path $McpConfigJson) { Get-Content $McpConfigJson -Raw | ConvertFrom-Json } else { [pscustomobject]@{} }
+if (-not $settingsContent.mcpServers) { $settingsContent | Add-Member -NotePropertyName mcpServers -NotePropertyValue ([pscustomobject]@{}) -Force }
$settingsContent.mcpServers | Add-Member -NotePropertyName 'ahrefs' -NotePropertyValue @{
command = 'npx'
args = @('--yes', '--package=@ahrefs/[email protected]', 'mcp')
@@ -50,7 +50,10 @@ $settingsContent.mcpServers | Add-Member -NotePropertyName 'ahrefs' -NotePropert
# -Depth 100 (not the ConvertTo-Json default of 2) so an existing
# ~/.claude.json with deeply nested config round-trips intact.
$TempConfigJson = Join-Path (Split-Path -Parent $McpConfigJson) ".claude.json.$([guid]::NewGuid().ToString('N')).tmp"
-$settingsContent | ConvertTo-Json -Depth 100 | Set-Content $TempConfigJson -Encoding UTF8
+$jsonText = $settingsContent | ConvertTo-Json -Depth 100
+# Write without a byte-order mark: on Windows PowerShell 5.1, Set-Content -Encoding UTF8
+# emits a BOM and Node's JSON.parse rejects it, which would make ~/.claude.json unreadable.
+[System.IO.File]::WriteAllText($TempConfigJson, $jsonText, (New-Object System.Text.UTF8Encoding $false))
Move-Item -Path $TempConfigJson -Destination $McpConfigJson -Force
Write-Host "Wrote mcpServers.ahrefs to $McpConfigJson"
diff --git a/extensions/dataforseo/install.ps1 b/extensions/dataforseo/install.ps1
index 783a144..d1d6925 100644
--- a/extensions/dataforseo/install.ps1
+++ b/extensions/dataforseo/install.ps1
@@ -99,8 +99,8 @@ Copy-Item -Force "$SourceDir\field-config.json" $FieldConfigPath
# Merge MCP config into ~/.claude.json
Write-Host "→ Configuring MCP server..." -ForegroundColor Yellow
-$settingsContent = if (Test-Path $McpConfigFile) { Get-Content $McpConfigFile -Raw | ConvertFrom-Json } else { @{} }
-if (-not $settingsContent.mcpServers) { $settingsContent | Add-Member -NotePropertyName mcpServers -NotePropertyValue @{} -Force }
+$settingsContent = if (Test-Path $McpConfigFile) { Get-Content $McpConfigFile -Raw | ConvertFrom-Json } else { [pscustomobject]@{} }
+if (-not $settingsContent.mcpServers) { $settingsContent | Add-Member -NotePropertyName mcpServers -NotePropertyValue ([pscustomobject]@{}) -Force }
$settingsContent.mcpServers | Add-Member -NotePropertyName 'dataforseo' -NotePropertyValue @{
command = 'npx'
args = @('-y', '[email protected]')
@@ -117,7 +117,10 @@ $settingsContent.mcpServers | Add-Member -NotePropertyName 'dataforseo' -NotePro
# -Depth 100 (not the ConvertTo-Json default of 2) so an existing
# ~/.claude.json with deeply nested config round-trips intact.
$TempConfigFile = Join-Path (Split-Path -Parent $McpConfigFile) ".claude.json.$([guid]::NewGuid().ToString('N')).tmp"
-$settingsContent | ConvertTo-Json -Depth 100 | Set-Content $TempConfigFile -Encoding UTF8
+$jsonText = $settingsContent | ConvertTo-Json -Depth 100
+# Write without a byte-order mark: on Windows PowerShell 5.1, Set-Content -Encoding UTF8
+# emits a BOM and Node's JSON.parse rejects it, which would make ~/.claude.json unreadable.
+[System.IO.File]::WriteAllText($TempConfigFile, $jsonText, (New-Object System.Text.UTF8Encoding $false))
Move-Item -Path $TempConfigFile -Destination $McpConfigFile -Force
# Restrict the credential-bearing settings file to the current user only.
try {
diff --git a/extensions/firecrawl/install.ps1 b/extensions/firecrawl/install.ps1
index 39c1939..ea21cd3 100644
--- a/extensions/firecrawl/install.ps1
+++ b/extensions/firecrawl/install.ps1
@@ -69,8 +69,8 @@ Copy-Item "$SourceDir\skills\seo-firecrawl\SKILL.md" "$SkillDir\SKILL.md" -Force
# Configure MCP server
Write-Host "=> Configuring MCP server..." -ForegroundColor Yellow
-$settingsContent = if (Test-Path $McpConfigFile) { Get-Content $McpConfigFile -Raw | ConvertFrom-Json } else { @{} }
-if (-not $settingsContent.mcpServers) { $settingsContent | Add-Member -NotePropertyName mcpServers -NotePropertyValue @{} -Force }
+$settingsContent = if (Test-Path $McpConfigFile) { Get-Content $McpConfigFile -Raw | ConvertFrom-Json } else { [pscustomobject]@{} }
+if (-not $settingsContent.mcpServers) { $settingsContent | Add-Member -NotePropertyName mcpServers -NotePropertyValue ([pscustomobject]@{}) -Force }
$settingsContent.mcpServers | Add-Member -NotePropertyName 'firecrawl-mcp' -NotePropertyValue @{
command = 'npx'
args = @('-y', '[email protected]')
@@ -82,7 +82,10 @@ $settingsContent.mcpServers | Add-Member -NotePropertyName 'firecrawl-mcp' -Note
# -Depth 100 (not the ConvertTo-Json default of 2, or the previous 10) so an
# existing ~/.claude.json with deeply nested config round-trips intact.
$TempConfigFile = Join-Path (Split-Path -Parent $McpConfigFile) ".claude.json.$([guid]::NewGuid().ToString('N')).tmp"
-$settingsContent | ConvertTo-Json -Depth 100 | Set-Content $TempConfigFile -Encoding UTF8
+$jsonText = $settingsContent | ConvertTo-Json -Depth 100
+# Write without a byte-order mark: on Windows PowerShell 5.1, Set-Content -Encoding UTF8
+# emits a BOM and Node's JSON.parse rejects it, which would make ~/.claude.json unreadable.
+[System.IO.File]::WriteAllText($TempConfigFile, $jsonText, (New-Object System.Text.UTF8Encoding $false))
Move-Item -Path $TempConfigFile -Destination $McpConfigFile -Force
# Restrict the credential-bearing settings file to the current user only.
try {
diff --git a/extensions/firecrawl/uninstall.ps1 b/extensions/firecrawl/uninstall.ps1
index b7f6700..d24b1c6 100644
--- a/extensions/firecrawl/uninstall.ps1
+++ b/extensions/firecrawl/uninstall.ps1
@@ -23,7 +23,10 @@ if (Test-Path $McpConfigFile) {
# 10) so an existing ~/.claude.json with deeply nested config
# round-trips intact.
$TempConfigFile = Join-Path (Split-Path -Parent $McpConfigFile) ".claude.json.$([guid]::NewGuid().ToString('N')).tmp"
- $settings | ConvertTo-Json -Depth 100 | Set-Content $TempConfigFile -Encoding UTF8
+ $jsonText = $settings | ConvertTo-Json -Depth 100
+# Write without a byte-order mark: on Windows PowerShell 5.1, Set-Content -Encoding UTF8
+# emits a BOM and Node's JSON.parse rejects it, which would make ~/.claude.json unreadable.
+[System.IO.File]::WriteAllText($TempConfigFile, $jsonText, (New-Object System.Text.UTF8Encoding $false))
Move-Item -Path $TempConfigFile -Destination $McpConfigFile -Force
Write-Host "v Removed MCP server from ~/.claude.json" -ForegroundColor Green
}
diff --git a/scripts/keywordseverywhere_api.py b/scripts/keywordseverywhere_api.py
index 87a7fb2..f982cd3 100644
--- a/scripts/keywordseverywhere_api.py
+++ b/scripts/keywordseverywhere_api.py
@@ -93,6 +93,10 @@ def get_rank(domains: list, api_key: str) -> dict:
try:
err_body = response.json()
err_msg = err_body.get("message") or err_body.get("error") or response.text
+
+ # Never echo the key back through an upstream error body.
+
+ err_msg = str(err_msg).replace(api_key, "<redacted>")[:500]
except ValueError:
err_msg = response.text or f"HTTP {response.status_code}"
return {
diff --git a/scripts/runtime.py b/scripts/runtime.py
index ffac8ee..6d1b011 100755
--- a/scripts/runtime.py
+++ b/scripts/runtime.py
@@ -205,6 +205,9 @@ def _home_pattern(home: str) -> re.Pattern[str]:
# once nested) and Windows tools mix drive-letter case, so match the home
# directory by its segments rather than by the exact string.
parts = [re.escape(part) for part in re.split(r"[\\/]+", home) if part]
+ if not parts:
+ # A root home directory would otherwise redact every path separator.
+ return re.compile(r"(?!x)x")
pattern = r"[\\/]+".join(parts)
if home[:1] in ("\\", "/"):
pattern = r"[\\/]+" + pattern
@@ -223,8 +226,8 @@ def _redact(text: str) -> str:
return text
-def _tail(text: str, limit: int = 30) -> str:
- lines = [line.rstrip() for line in text.splitlines() if line.strip()]
+def _tail(text: str, limit: int = 30, width: int = 400) -> str:
+ lines = [line.rstrip()[:width] for line in text.splitlines() if line.strip()]
return "\n".join(f" {line}" for line in lines[-limit:])
diff --git a/tests/test_firecrawl_install_atomic_write.py b/tests/test_firecrawl_install_atomic_write.py
index a4054cd..19a7444 100644
--- a/tests/test_firecrawl_install_atomic_write.py
+++ b/tests/test_firecrawl_install_atomic_write.py
@@ -41,8 +41,11 @@ def test_ps1_writes_mcp_config_atomically(rel: str, variables: tuple[str, str])
)
# The final Set-Content must target the temp file, not the real config
# path directly, so a crash mid-write cannot leave it truncated.
- assert f"Set-Content {temp_var} -Encoding UTF8" in text
- assert f"Set-Content {config_var} -Encoding UTF8" not in text
+ assert f"[System.IO.File]::WriteAllText({temp_var}, $jsonText, (New-Object System.Text.UTF8Encoding $false))" in text, (
+ f"{rel}: the temp file must be written without a BOM"
+ )
+ assert "Set-Content" not in text or f"Set-Content {config_var}" not in text
+ assert "[pscustomobject]@{}" in text, f"{rel}: mcpServers must be created as an object, not a hashtable"
@pytest.mark.parametrize("rel", WRITERS.keys())
diff --git a/tests/test_keywordseverywhere_api.py b/tests/test_keywordseverywhere_api.py
index 41d5605..f954404 100644
--- a/tests/test_keywordseverywhere_api.py
+++ b/tests/test_keywordseverywhere_api.py
@@ -128,3 +128,20 @@ def test_main_rejects_batches_over_100_domains_without_a_network_call(
err = capsys.readouterr().err
assert "101" in err
assert "max 100" in err
+
+
+def test_upstream_error_body_never_echoes_the_key(monkeypatch):
+ """A 500 whose body repeats the key must not leak it into the result."""
+ import keywordseverywhere_api as ke
+
+ class _Resp:
+ status_code = 500
+ text = "upstream error: API-OPR opr_live_SECRET123 rejected"
+
+ def json(self):
+ raise ValueError("not json")
+
+ monkeypatch.setattr(ke, "safe_requests_get", lambda *a, **k: _Resp())
+ result = ke.get_rank(["example.com"], api_key="opr_live_SECRET123")
+ assert "opr_live_SECRET123" not in str(result)
+ assert "<redacted>" in str(result.get("error", ""))