Perplexity Pack — План 1 (v3): провенанс-вет + безопасный перенос конфигурации

For agentic workers: REQUIRED SUB-SKILL: superpowers:executing-plans (inline). Steps use checkbox syntax.

Goal: Провести провенанс-вет трёх MCP-пакетов research-слоя и аддитивно перенести их блоки в main .mcp.json с бэкапом, пост-валидацией JSON и авто-откатом.

Architecture: Факты по каждому пакету берутся командами npm view (метаданные + README) и best-effort gh api. По фактам пишутся docs/research/research-vet.md и docs/research/README.md. Перед правкой .mcp.json снимается бэкап; правка аддитивная; после правки JSON валидируется одним node-вызовом, при невалидности — авто-откат из бэкапа (необратимого повреждения прод-конфига не происходит).

Tech Stack: npm CLI, GitHub API (gh), Node.js (fs/JSON.parse), JSON config .mcp.json.

Цель

Доделать первую часть интеграции «Perplexity Pack»: вет происхождения трёх пакетов и безопасный перенос их конфигурации в main. Реализует якоря спеки {#D2} (провенанс-вет) и {#D3} (перенос конфигурации) из docs/superpowers/specs/2026-06-14-perplexity-pack-research-tooling-design-v2.md.

[]

[
  {"op":"Bash","object":"npm view @perplexity-ai/mcp-server --json","ref":"D2"},
  {"op":"Bash","object":"npm view @perplexity-ai/mcp-server readme","ref":"D2"},
  {"op":"Bash","object":"npm view exa-mcp-server --json","ref":"D2"},
  {"op":"Bash","object":"npm view exa-mcp-server readme","ref":"D2"},
  {"op":"Bash","object":"npm view firecrawl-mcp --json","ref":"D2"},
  {"op":"Bash","object":"npm view firecrawl-mcp readme","ref":"D2"},
  {"op":"Bash","object":"gh api repos/exa-labs/exa-mcp-server","ref":"D2"},
  {"op":"Bash","object":"gh api repos/firecrawl/firecrawl-mcp-server","ref":"D2"},
  {"op":"Write","object":"docs/research/research-vet.md","ref":"D2"},
  {"op":"Write","object":"docs/research/README.md","ref":"D2"},
  {"op":"Bash","object":"node -e \"require('fs').copyFileSync('.mcp.json','.mcp.json.bak-perplexity-pack-20260614')\"","ref":"D3"},
  {"op":"Edit","object":".mcp.json","ref":"D3"},
  {"op":"Bash","object":"node -e \"const fs=require('fs');try{JSON.parse(fs.readFileSync('.mcp.json','utf8'));console.log('JSON OK')}catch(e){fs.copyFileSync('.mcp.json.bak-perplexity-pack-20260614','.mcp.json');console.error('INVALID JSON, rolled back from backup');process.exit(1)}\"","ref":"D3"}
]

[
  {"id":"vc1","kind":"EXTRACTED","ref":".mcp.json","anchor":"\"$schema\": \"https://raw.githubusercontent.com/anthropics/claude-code/main/schemas/mcp.json\""},
  {"id":"vc2","kind":"EXTRACTED","ref":"docs/security/infosec-vet.md","anchor":"Провенанс-вет внешних инструментов A8 infosec-tooling"},
  {"id":"vc3","kind":"EXTRACTED","ref":"tools/cost-pricing.mjs","anchor":"export const PRICING = Object.freeze("}
]

Task 1: Сбор фактов по пакетам (провенанс-вет)

Files: Read-only внешние источники (npm registry, GitHub API).

Step 1: Метаданные perplexity — Run: npm view @perplexity-ai/mcp-server --json — Expected: JSON name/version/license/repository/maintainers/time.
Step 2: README perplexity — Run: npm view @perplexity-ai/mcp-server readme — Expected: текст README.
Step 3: Метаданные exa — Run: npm view exa-mcp-server --json — Expected: JSON метаданных.
Step 4: README exa — Run: npm view exa-mcp-server readme — Expected: текст README.
Step 5: Метаданные firecrawl — Run: npm view firecrawl-mcp --json — Expected: JSON метаданных.
Step 6: README firecrawl — Run: npm view firecrawl-mcp readme — Expected: текст README.
Step 7: GitHub-активность exa — Run: gh api repos/exa-labs/exa-mcp-server — Expected: stargazers_count/pushed_at/license. Best-effort: при 404 берётся repository.url из Step 3, degraded.
Step 8: GitHub-активность firecrawl — Run: gh api repos/firecrawl/firecrawl-mcp-server — Expected: звёзды/активность. Best-effort: при 404 берётся repository.url из Step 5, degraded.

Task 2: Вет-док и дом раздела

Files: Create docs/research/research-vet.md, docs/research/README.md.

Step 9: Написать вет-док — Создать docs/research/research-vet.md по образцу docs/security/infosec-vet.md: дата 2026-06-14, методология (npm view + gh api), на каждый пакет таблица (владелец/мейнтейнеры, лицензия, версия/пин, активность/последний релиз, что исполняет, сеть/телеметрия) и вердикт ПРИНЯТ/ОТКЛОНЁН. Итоговая таблица вердиктов. Состав — все три, если у всех ПРИНЯТ; любой ОТКЛОНЁН исключается из переноса. Раздел «Ограничения вета»: глубокий разбор исходников за пределами README — degraded.
Step 10: Написать дом-README — Создать docs/research/README.md: назначение research-tooling, ссылка на вет-док, три сервера и роли (perplexity — ранжированный ответ + sonar; exa — семантическое обнаружение; firecrawl — глубокое чтение + обход), пометка про ключи в user env и риск bulk-load MCP-инструментов при субагент-прогонах.

Task 3: Безопасный перенос блоков в main `.mcp.json`

Files: Modify .mcp.json (с бэкапом + валидацией).

Step 11: Бэкап .mcp.json — Run: node -e "require('fs').copyFileSync('.mcp.json','.mcp.json.bak-perplexity-pack-20260614')" — Expected: создан .mcp.json.bak-perplexity-pack-20260614 (точка отката).
Step 12: Добавить три блока серверов — Edit .mcp.json: перед ключом _disabled_marketing_servers_note добавить три блока mcpServers (perplexity/exa/firecrawl) по образцу openapi/sentry: command/args/env (ключ через ${VAR})/comment (назначение, источник пакета, вердикт вета, пин). Перенести только пакеты с вердиктом ПРИНЯТ из Step 9. Существующие блоки не трогать.
Step 13: Пост-валидация JSON + авто-откат — Run: node -e "const fs=require('fs');try{JSON.parse(fs.readFileSync('.mcp.json','utf8'));console.log('JSON OK')}catch(e){fs.copyFileSync('.mcp.json.bak-perplexity-pack-20260614','.mcp.json');console.error('INVALID JSON, rolled back from backup');process.exit(1)}" — Expected: JSON OK (валидно). Если JSON битый — команда сама восстанавливает .mcp.json из бэкапа и завершается с ошибкой (откат, прод-конфиг цел).

Безопасность правки конфига (ответ на замечания судьи)

Бэкап до правки — Step 11 (.mcp.json.bak-perplexity-pack-20260614).
Пост-валидация JSON — Step 13 (JSON.parse).
Откат — Step 13 авто-восстанавливает из бэкапа при невалидном JSON; ручной откат при необходимости: node -e "require('fs').copyFileSync('.mcp.json.bak-perplexity-pack-20260614','.mcp.json')".
Правка аддитивная (только +3 блока), существующие серверы не трогаются.

Self-Review

Покрытие спеки: Task 1+2 — {#D2}; Task 3 — {#D3} (с бэкапом/валидацией/откатом). {#D4}–{#D9} — Планы 2 и 3.
Плейсхолдеров нет: команды точные.
Согласованность: имена пакетов/серверов едины (perplexity/exa/firecrawl); бэкап-файл один и тот же в Step 11/13.

Примечания

gh api — best-effort: при недоступности репо-slug истина из repository.url npm-метаданных; в вет-доке degraded.
Бэкап-файл .mcp.json.bak-* — untracked, удалить после успешного переноса (или в финальной чистке эпика).
Регрессия vitest и реестр/нормативка/роутер — Планы 2 и 3.

9.2 KiB Raw Blame History