diff --git a/CHANGELOG.md b/CHANGELOG.md index a3ab005..ba70d48 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -241,6 +241,26 @@ Catalogue additions from the 2026-11-09 candidate review. - `docs/CATALOG.md`, `docs/RESEARCH.md`, and both READMEs were updated in the same change. +Catalogue additions from the 2026-11-10 candidate review. + +- One installable skill: `OthmanAdi/planning-with-files` — plans, progress and + findings kept in `.planning/`, per-turn plan re-injection against context rot, + recovery after `/clear` or compaction, and a deterministic completion gate. + The pinned `skills/planning-with-files` archive was downloaded and SHA-256 + verified; nothing was installed. +- Three reference-only entries: `nextlevelbuilder/ui-ux-pro-max-skill`, the + design-intelligence skill whose local style, palette, typography and UX data + is queried by Python scripts and delivered through a per-client generator CLI, + recorded in `framework-best-practices`; `agentskills/agentskills`, the Agent + Skills specification plus the `skills-ref` reference validator, recorded in + `skill-ecosystem`; and `ArcadeAI/arcade-mcp`, the Python MCP server framework + (`pip install arcade-mcp`), recorded in `build-mcp` next to `fastmcp` and the + official `mcp-python-sdk`. +- The catalog now holds 107 entries: 48 installable resources (23 skills, 6 rule + packs, 17 MCP servers, and 2 LSP bridges) and 59 references. +- `docs/CATALOG.md`, `docs/RESEARCH.md`, `docs/LSP.md`, and both READMEs were + updated in the same change. + ## npm shell 0.1.1 — 2026-10-28 - Honor HTTP/HTTPS proxy environment variables for GitHub runtime downloads, diff --git a/README.md b/README.md index a59c7b9..9890f22 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ Find useful, established GitHub projects for AI assisted development, then insta The installer is written in Python, with a dedicated Python toolkit. The collection also serves web and general software development across **Claude Code, Codex, Cursor, VS Code Copilot, and OpenCode**. -The repository catalog includes **103 entries**: **47 installable resources** (22 skills, 6 rule packs, 17 MCP servers, and 2 LSP bridges) and **56 references** (agent-lsp, mcpls, lspyx, 11 native language servers, and 42 other tools). Choose from **11 profiles** across **5 coding agents**. Repository `main` may include unreleased additions; `apd list --json` reports the catalog in your installed runtime. +The repository catalog includes **107 entries**: **48 installable resources** (23 skills, 6 rule packs, 17 MCP servers, and 2 LSP bridges) and **59 references** (agent-lsp, mcpls, lspyx, 11 native language servers, and 45 other tools). Choose from **11 profiles** across **5 coding agents**. Repository `main` may include unreleased additions; `apd list --json` reports the catalog in your installed runtime. ## Contents @@ -120,7 +120,7 @@ Browse the [curated catalog](docs/CATALOG.md) for project descriptions, upstream | [Reticle](https://github.com/reticlehq/reticle) | MCP-driven verification of the running web app in a real browser, returning verdicts with the `file:line` behind them. | | [Hippo](https://github.com/kitfunso/hippo-memory) | MCP long-term memory for coding agents from a local store that strengthens recalled memories and decays stale ones. | -Also explore [Ripwire](https://github.com/redhat-et/ripwire), [Graphify](https://github.com/Graphify-Labs/graphify), [CodeBoarding](https://github.com/CodeBoarding/CodeBoarding), [MCP Context Forge](https://github.com/IBM/mcp-context-forge), [Ruler](https://github.com/intellectronica/ruler), [Open Code Review](https://github.com/alibaba/open-code-review), [MCP Inspector](https://github.com/modelcontextprotocol/inspector), [MCP Toolbox for Databases](https://github.com/googleapis/mcp-toolbox), [OpenSpec](https://github.com/Fission-AI/OpenSpec), [Spec Kit](https://github.com/github/spec-kit), [GitHub MCP](https://github.com/github/github-mcp-server), [uv](https://github.com/astral-sh/uv), [Ruff](https://github.com/astral-sh/ruff), [Tombi](https://github.com/tombi-toml/tombi), and security scanners in the [full reference collection](docs/CATALOG.md). +Also explore [Ripwire](https://github.com/redhat-et/ripwire), [Graphify](https://github.com/Graphify-Labs/graphify), [CodeBoarding](https://github.com/CodeBoarding/CodeBoarding), [UI/UX Pro Max](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill), [Agent Skills specification](https://github.com/agentskills/agentskills), [MCP Context Forge](https://github.com/IBM/mcp-context-forge), [Ruler](https://github.com/intellectronica/ruler), [Open Code Review](https://github.com/alibaba/open-code-review), [MCP Inspector](https://github.com/modelcontextprotocol/inspector), [MCP Toolbox for Databases](https://github.com/googleapis/mcp-toolbox), [OpenSpec](https://github.com/Fission-AI/OpenSpec), [Spec Kit](https://github.com/github/spec-kit), [GitHub MCP](https://github.com/github/github-mcp-server), [uv](https://github.com/astral-sh/uv), [Ruff](https://github.com/astral-sh/ruff), [Tombi](https://github.com/tombi-toml/tombi), and security scanners in the [full reference collection](docs/CATALOG.md). Entries marked **installable** have a recipe in this release. Entries without an install recipe are references, with installation managed by their upstream projects. `lsp` includes the installable Serena and lsp-mcp-server bridges plus standalone language-server references, including Tombi for TOML project configuration. diff --git a/README.zh-CN.md b/README.zh-CN.md index a7c47d0..5847aa5 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -17,7 +17,7 @@ 安装器使用 Python 编写，并提供 Python 开发预设；整个集合也覆盖 Web 和通用软件开发。目前支持 **Claude Code、Codex、Cursor、VS Code Copilot 和 OpenCode**。 -仓库目录收录 **103 个条目**：**47 个可安装资源**（22 个 skills、6 套规则、17 个 MCP servers、2 个 LSP 桥接），以及 **56 个参考条目**（agent-lsp、mcpls、lspyx、11 个原生语言服务、42 个其他工具）。提供 **11 种预设、5 种 coding agent** 适配。`main` 可能包含尚未发版的新增项，`apd list --json` 显示已安装 runtime 实际包含的工具目录。 +仓库目录收录 **107 个条目**：**48 个可安装资源**（23 个 skills、6 套规则、17 个 MCP servers、2 个 LSP 桥接），以及 **59 个参考条目**（agent-lsp、mcpls、lspyx、11 个原生语言服务、45 个其他工具）。提供 **11 种预设、5 种 coding agent** 适配。`main` 可能包含尚未发版的新增项，`apd list --json` 显示已安装 runtime 实际包含的工具目录。 ## 目录 @@ -119,7 +119,7 @@ apd runtime update # 立即检查稳定 runtime 通道 | [Reticle](https://github.com/reticlehq/reticle) | 通过 MCP 在真实浏览器中验证运行中的应用，给出结论与对应的 `file:line`。 | | [Hippo](https://github.com/kitfunso/hippo-memory) | 通过 MCP 为 coding agent 提供本地长期记忆，常用记忆会强化、过期记忆会衰减。 | -[完整参考集合](docs/CATALOG.md) 还收录了 [Ripwire](https://github.com/redhat-et/ripwire)、[Graphify](https://github.com/Graphify-Labs/graphify)、[CodeBoarding](https://github.com/CodeBoarding/CodeBoarding)、[MCP Context Forge](https://github.com/IBM/mcp-context-forge)、[Ruler](https://github.com/intellectronica/ruler)、[Open Code Review](https://github.com/alibaba/open-code-review)、[MCP Inspector](https://github.com/modelcontextprotocol/inspector)、[MCP Toolbox for Databases](https://github.com/googleapis/mcp-toolbox)、[OpenSpec](https://github.com/Fission-AI/OpenSpec)、[Spec Kit](https://github.com/github/spec-kit)、[GitHub MCP](https://github.com/github/github-mcp-server)、[uv](https://github.com/astral-sh/uv)、[Ruff](https://github.com/astral-sh/ruff)、[Tombi](https://github.com/tombi-toml/tombi) 和安全扫描工具。 +[完整参考集合](docs/CATALOG.md) 还收录了 [Ripwire](https://github.com/redhat-et/ripwire)、[Graphify](https://github.com/Graphify-Labs/graphify)、[CodeBoarding](https://github.com/CodeBoarding/CodeBoarding)、[UI/UX Pro Max](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill)、[Agent Skills 规范](https://github.com/agentskills/agentskills)、[MCP Context Forge](https://github.com/IBM/mcp-context-forge)、[Ruler](https://github.com/intellectronica/ruler)、[Open Code Review](https://github.com/alibaba/open-code-review)、[MCP Inspector](https://github.com/modelcontextprotocol/inspector)、[MCP Toolbox for Databases](https://github.com/googleapis/mcp-toolbox)、[OpenSpec](https://github.com/Fission-AI/OpenSpec)、[Spec Kit](https://github.com/github/spec-kit)、[GitHub MCP](https://github.com/github/github-mcp-server)、[uv](https://github.com/astral-sh/uv)、[Ruff](https://github.com/astral-sh/ruff)、[Tombi](https://github.com/tombi-toml/tombi) 和安全扫描工具。 标记为 **installable** 的条目已提供安装配方；没有安装配方的条目作为参考，由上游项目负责安装。`lsp` 分类同时包含可安装的 Serena 与 lsp-mcp-server 桥接，以及独立语言服务参考（含用于 TOML 项目配置的 Tombi）。 diff --git a/docs/CATALOG.md b/docs/CATALOG.md index 49c77ad..0b86b72 100644 --- a/docs/CATALOG.md +++ b/docs/CATALOG.md @@ -1,6 +1,6 @@ # Curated catalog / 精选目录 -Reviewed **2026-11-09**, catalog schema **2**. **103 entries**, with **47 installable/configurable integrations** and **56 reference-only tools**. The installable set contains 22 skills, 6 rule packs, 17 MCP servers, and 2 MCP-to-LSP bridges. The 16 LSP entries comprise the two installable bridges (Serena, lsp-mcp-server), the three reference-only bridges (agent-lsp, mcpls, lspyx), and 11 standalone language-server references. +Reviewed **2026-11-10**, catalog schema **2**. **107 entries**, with **48 installable/configurable integrations** and **59 reference-only tools**. The installable set contains 23 skills, 6 rule packs, 17 MCP servers, and 2 MCP-to-LSP bridges. The 16 LSP entries comprise the two installable bridges (Serena, lsp-mcp-server), the three reference-only bridges (agent-lsp, mcpls, lspyx), and 11 standalone language-server references. Stars are dated repository-level snapshots, not scores for individual skills or rules. Multiple entries from ECC, Superpowers, agent-skills, or another monorepo share the same repository evidence. The executable source of truth is [`catalog.json`](../src/awesome_python_dev/data/catalog.json); every entry records its source, license, review date, and installation status. @@ -51,6 +51,7 @@ Profiles select relevant tools instead of loading every available rule and frame | [`open-code-review`](https://github.com/alibaba/open-code-review) | Run an AI review over a diff with deterministic analysis pipelines plus a tuned review model, with matching agent skills and plugins. | Reference only | 49,294 | Apache-2.0 | | [`graphify`](https://github.com/Graphify-Labs/graphify) | Build a local, deterministic knowledge graph of a repository, its docs, SQL schemas and configuration, and answer architecture, dependency and change-impact questions through a coding-agent skill with no vector store. | Reference only | 142,432 | Apache-2.0 | | [`brooks-lint`](https://github.com/hyhmrright/brooks-lint) | Six review modes for architecture decay, technical debt, test weakness, and remediation, using book-derived risk codes and a 0-100 health score, packaged for fourteen coding agents. | Reference only | 1,561 | MIT | +| [`planning-with-files`](https://github.com/OthmanAdi/planning-with-files/tree/2362ca385ad74f061aa0e7b73f56543a4b7e6df2/skills/planning-with-files) | Keep the plan in files instead of context: `.planning/` plan, progress and findings documents, per-turn re-injection against context rot, session recovery after `/clear` or compaction, and a deterministic completion gate. | Install skill | 27,973 | MIT | ## Python, languages, and framework practices @@ -67,6 +68,7 @@ Profiles select relevant tools instead of loading every available rule and frame | [`backend-patterns`](https://github.com/affaan-m/ECC/tree/25278e7d7b6cf6e6a4e7a6c8e10f14ff22f0eb5b/skills/backend-patterns) | Node.js, Express, and Next.js API architecture, data access, caching, and observability. | Install skill | 290,505 | MIT | | [`springboot-patterns`](https://github.com/affaan-m/ECC/tree/25278e7d7b6cf6e6a4e7a6c8e10f14ff22f0eb5b/skills/springboot-patterns) | Spring Boot REST layers, transactional services, repositories, caching, and production defaults. | Install skill | 290,505 | MIT | | [`golang-patterns`](https://github.com/affaan-m/ECC/tree/25278e7d7b6cf6e6a4e7a6c8e10f14ff22f0eb5b/skills/golang-patterns) | Idiomatic Go errors, interfaces, concurrency, package organization, and resource lifecycle patterns. | Install skill | 290,505 | MIT | +| [`ui-ux-pro-max`](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) | Query a local design database for a UI task — 80 styles, 192 palettes, 74 font pairings, 120 UX guidelines and per-stack reasoning rules for 22 stacks — and produce a project design system instead of a generic palette. | Reference only | 147,361 | MIT | ## Security review and scanning @@ -166,6 +168,7 @@ Profiles select relevant tools instead of loading every available rule and frame | [`cross-code-organizer`](https://github.com/mcpware/cross-code-organizer) | Inventory what each coding agent will actually load — configuration, memories, skills, and MCP servers — edit those files in place, and scan MCP tool descriptions for poisoning. | Reference only | 386 | MIT | | [`skillsaw`](https://github.com/stbenjam/skillsaw) | Lint, autofix and baseline the skills, plugin manifests, hooks and instruction files a coding agent loads across the major agent ecosystems. | Reference only | 71 | Apache-2.0 | | [`agents-cli`](https://github.com/google/agents-cli) | Seven Agent Skills plus a CLI for building, evaluating, deploying, observing and publishing ADK agents on Google Cloud. | Reference only | 6,315 | Apache-2.0 | +| [`agent-skills-spec`](https://github.com/agentskills/agentskills) | The Agent Skills specification plus `skills-ref`, the Python reference validator that checks a skill directory and renders the properties and prompt block a client would load. | Reference only | 27,113 | Apache-2.0 | ## Python project toolchain @@ -187,6 +190,7 @@ Profiles select relevant tools instead of loading every available rule and frame | [`fastmcp`](https://github.com/jlowin/fastmcp) | Build Python MCP servers and clients with a high-level API. | Reference only | 28,217 | Apache-2.0 | | [`mcp-python-sdk`](https://github.com/modelcontextprotocol/python-sdk) | Official Python SDK for implementing MCP servers and clients. | Reference only | 24,684 | MIT | | [`mcp-inspector`](https://github.com/modelcontextprotocol/inspector) | Launch, inspect, and call any MCP server from a web UI, TUI, or CLI while developing or debugging an integration. | Reference only | 11,216 | MIT and Apache-2.0 (relicensing in progress) | +| [`arcade-mcp`](https://github.com/ArcadeAI/arcade-mcp) | Build Python MCP servers with decorator tools, resources, prompts, sampling and elicitation, framework-owned OAuth, and an `arcade-mcp` CLI for scaffolding, running and deploying servers. | Reference only | 1,088 | MIT | ## Source pins and installation boundaries @@ -198,6 +202,7 @@ Skill and rule archives are pinned to full commits and verified against a record | [wshobson/agents](https://github.com/wshobson/agents/tree/0874a27b17a22e2b7c2e2bcd725768e0803cad06) | `0874a27b17a22e2b7c2e2bcd725768e0803cad06` | `468c5d32d4a24ea9629c7713d209bbb46cf462ac487d3bc442414aec4ed54c43` | | [affaan-m/ECC](https://github.com/affaan-m/ECC/tree/25278e7d7b6cf6e6a4e7a6c8e10f14ff22f0eb5b) | `25278e7d7b6cf6e6a4e7a6c8e10f14ff22f0eb5b` | `7979cc21e2093aed6218fa1709373eff5eb8641b0c0a5128c68db91bbedd7bb1` | | [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills/tree/aeac41d4d005999432bb7312f7ff06383a91d59d) | `aeac41d4d005999432bb7312f7ff06383a91d59d` | `0211a580aab7d45c73886d6f96d2f0679416119b4f9add08b6ceea5c0c15fbf1` | +| [OthmanAdi/planning-with-files](https://github.com/OthmanAdi/planning-with-files/tree/2362ca385ad74f061aa0e7b73f56543a4b7e6df2) | `2362ca385ad74f061aa0e7b73f56543a4b7e6df2` | `cf60990c520c8f5d6fff876524450ce67172ad8ce785213a9bc50dbb06ac2227` | | Service | Pinned launcher | Runtime / setup | | --- | --- | --- | @@ -277,6 +282,11 @@ Skill and rule archives are pinned to full commits and verified against a record - [`elephant-goldfish`](https://github.com/google/elephant-goldfish-model) is a plugin rather than a single skill, which is why it has no recipe: ten reviewer prompts live in `agents/`, and the shipped skills (`skills/egm-*/SKILL.md`, mirrored under `distributions/claude/skills/` for `bootstrap`, `brainstorm`, `draft`, `review`, `review-loop`, `resolve` and `drift-report`) read the repository-level prompts and standards. Upstream states the constraint itself: "Install the complete plugin so its skills can read the reviewer prompts and document standards." It ships per-harness manifests and rule files for Claude Code (`.claude-plugin/`), Codex (`.codex-plugin/`), Cursor (`.cursor-plugin/` plus `rules/egm.mdc`), Copilot (`com.github.copilot/`), Antigravity/Gemini (`.agents/`, `.gemini/`) and a generic `.plugin/`, with per-client setup in `docs/` (`harnesses.md`, `claude.md`, `codex.md`, `cursor.md`, `copilot.md`, `opencode.md`); the Claude route is `claude plugin marketplace add google/elephant-goldfish-model` then `claude plugin install egm@egm`. It is recorded in `spec-driven-development` next to `openspec`, `spec-kit` and `spec-kitty` for a different lever: instead of generating and gating specification documents, it runs an agent ensemble that drafts a design and then attacks it, and reports drift afterwards. Repository metadata, the README, the plugin manifests, the `agents/` and skills trees, `AI_POLICY.md` and the Apache-2.0 `LICENSE` were read in this pass; nothing was installed and no plugin, agent or skill was activated. - [`lspyx`](https://github.com/iyazerski/lspyx) covers the one gap left in `lsp-bridge`: `serena` and `lsp-mcp-server` bridge to configured language servers, `agent-lsp` orchestrates several, and `mcpls` bridges Rust, Python and Go - none of them is Python-only and none reports through `ty`. `lspyx mcp serve` answers definition, references, outline, diagnostics and rename-preview queries from `ty` plus Ruff with a per-workspace daemon (`src/daemon/`, `src/mcp/`, `src/lsp/rename.rs`), and the CLI exposes the same answers; setup is `brew install iyazerski/tap/lspyx`, `cargo install lspyx --locked` or `install.sh`, with `ty` and Ruff in the project `.venv` or on `PATH`, and `lspyx doctor` checking the result. There is no registry package the installer can own, so it stays reference-only like the other two bridges. Caveat worth weighing: 0 stars observed on 2026-11-09 - the least-adopted entry recorded here - about seven months old, single-maintainer, MIT-licensed, with eight tagged releases (latest v0.6.0, 2026-11-07); re-check it at the next review and drop it if the lane stays unserved. Nothing was installed and no MCP session was started. +- [`planning-with-files`](https://github.com/OthmanAdi/planning-with-files) is the first installable skill here whose state lives in files rather than in context: `.planning/-/` holds the plan, its progress and its findings, the active plan is re-injected every turn so it survives context rot, the skill rebuilds the plan after `/clear` or compaction, and `scripts/check-complete.sh` gates completion with a SHA-256 attestation of the plan text it injected. The recipe copies the pinned `skills/planning-with-files` subtree (`SKILL.md`, `scripts/` with bash, PowerShell and Python implementations, `templates/`, `evals/`, `examples.md`, `plan-inventory.md`, `reference.md`), and every path in `SKILL.md` resolves inside that directory (`${CLAUDE_SKILL_DIR}`, `$PWF_SKILL_DIR`, `./scripts/...`, no `../` escapes), so the installed skill is self-contained; the Claude Code and Codex hooks it needs are declared in the skill's own frontmatter, which those clients read from the installed file, so `apd` owns the files while hook registration stays upstream. Upstream additionally ships an npm launcher, plugin-marketplace entries and an `npx skills` route for 60+ agents; this entry deliberately pins the commit archive only. Evidence read in this pass: repository metadata, README, the `skills/` tree at the pinned commit, `SKILL.md`, the `scripts/`, `templates/` and `evals/` listings, and the downloaded archive (24,950,981 bytes, SHA-256 verified, 37 files under the subtree, `LICENSE` at the archive root copied as `license_path`). Nothing was installed and no agent session was started. +- [`ui-ux-pro-max`](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) covers the Web half of this catalog's remit from the design side: it answers style, palette, typography, icon, motion and UX-guideline questions from a local data set of 39 CSV/JSON files (3,103,749 bytes) under `.claude/skills/ui-ux-pro-max/data/`, covering 22 stacks, through `scripts/search.py` and `design_system.py`, which need only a Python 3 standard library and make no network calls, and it can emit a project design system instead of a palette. It is reference-only on purpose: upstream delivers it through a per-client generator (`npm install -g ui-ux-pro-max-cli`, `uipro init --ai `, also `npx`, with `update`/`uninstall`/`--dry-run` and a Claude Code marketplace route) and its README says to always use that CLI, so the repository tree is the generator's source template rather than the installed layout; the commands inside `SKILL.md` are anchored to `${CLAUDE_PLUGIN_ROOT}/.claude/skills/ui-ux-pro-max/scripts/search.py`, which a bare commit-archive copy would not reproduce. That, plus the CLI owning activation and updates, is why no pinned recipe is claimed and the entry sits next to `skillsaw` and `graphify` as a reference. MIT license at the repository root (`skill.json` also declares MIT). Evidence read in this pass: repository metadata, README (install and troubleshooting sections, including the pre-v2.5.1 symlink packaging note), `skill.json` 2.15.0, the `.claude/skills/` trees at commit `4f2dbb67`, `SKILL.md` and its path references. Nothing was installed and no client files were generated. +- [`agent-skills-spec`](https://github.com/agentskills/agentskills) is the normative document behind the `skill` kind used throughout this catalog: `docs/specification.mdx` defines the `SKILL.md` frontmatter (`name`, `description`, optional `license`, `allowed-tools` and `metadata`), the directory layout and the progressive-disclosure rules that the skill recipes here follow, and `skills-ref/` is the Python reference implementation (`skills-ref validate `, `read-properties`, `to-prompt`; importable API under `src/`, tests alongside, PyPI release 0.1.1, Python >=3.11). It is recorded as a reference next to `anthropics/skills` and `agents-cli` because it is not a tool this installer puts into a client project — it is what a skill is checked against, so there is no pinned recipe. Upstream marks `skills-ref` as demonstration-only rather than production tooling, which is the caveat recorded with the entry; the specification itself is the reason the entry is useful. Evidence read in this pass: repository metadata, README, the `docs/` and `skills-ref/` trees, `skills-ref/README.md`, `skills-ref/pyproject.toml` and the PyPI release metadata. Nothing was installed and no skill was validated with it. +- [`arcade-mcp`](https://github.com/ArcadeAI/arcade-mcp) is the third entry in the `build-mcp` lane next to `fastmcp` and the official `mcp-python-sdk`, and the most widely deployed of the three (its README attributes 7,500+ tools across 81 hosted MCP servers to it): a decorator API covering tools, resources, prompts, sampling, elicitation, progress and logging, `requires_auth=` declarations that let the framework own OAuth and token refresh, and an `arcade-mcp` CLI for scaffolding, running and deploying servers. It stays reference-only for the same reason as `fastmcp`: it is a Python library (monorepo layout with `libs/arcade-core`, `libs/arcade-mcp-server`, `libs/arcade-cli`, `libs/arcade-evals`, `libs/arcade-serve` and `examples/mcp_servers/`) installed inside a server project rather than an agent-side MCP server the installer can configure by launching a command, so there is no pinned recipe; `pip install arcade-mcp` resolves PyPI 1.17.6 (Python >=3.10) and the server package publishes separately as `arcade-mcp-server` 1.33.0. MIT license. Evidence read in this pass: repository metadata, README (framework highlights and install sections), the `libs/` and `examples/` trees, and the PyPI metadata for both packages. Nothing was installed and no server was started. + MCP package/source pins identify the top-level server revision. npm/uv and upstream language-server managers may resolve additional dependencies at launch; this is not a hermetic runtime lock. ## Selection, verification, and maintenance diff --git a/docs/LSP.md b/docs/LSP.md index 5cebf21..8f91658 100644 --- a/docs/LSP.md +++ b/docs/LSP.md @@ -130,7 +130,7 @@ Select the intended scan scope and reviewed rule sets, pin dependencies in the p ## Verification recorded for this recipe -On 2026-11-09, the `squirrelscan` MCP entry added that day was launched through its pinned command from a temporary project and completed MCP `initialize` and `tools/list` with 15 tools discovered ([research evidence](RESEARCH.md#mcp-protocol-smoke-results)); no `tools/call` request was issued, so no site was audited, no report was written, and no account was used. The `pipelock`, `elephant-goldfish`, and `lspyx` references added the same day were recorded from repository metadata, upstream documentation, package metadata, and license files only: no proxy was started and no policy was loaded, no traffic was intercepted, no plugin, agent, or skill was activated, and no language-server startup or MCP session was run for `lspyx`. On 2026-11-06, the `misata` MCP entry added that day was launched through its pinned command from a temporary project and completed MCP `initialize` and `tools/list` with 15 tools discovered ([research evidence](RESEARCH.md#mcp-protocol-smoke-results)); no `tools/call` request was issued, so no dataset was generated, no certificate was re-verified, and no database was seeded. The `agnix`, `skillspector`, and `brooks-lint` references added the same day were recorded from repository metadata, upstream documentation, package metadata, and license files only: no lint run or `--fix`, no scan, no installer, and no editor or MCP session was started. On 2026-11-02, the `roam-code`, `orm-lens`, and `lsp-mcp-server` entries added that day were launched through their pinned commands from a temporary project and completed MCP `initialize` and `tools/list` with 17, 13, and 29 tools discovered ([research evidence](RESEARCH.md#mcp-protocol-smoke-results)); no `tools/call` request was issued, so no codebase was indexed, no Django or SQLAlchemy project was analysed, and no language server was driven. The `ai-rulez` entry added the same day stays a reference: its npm and PyPI packages are installers for a native binary, and the wrapper's own download did not finish in the smoke window, so no MCP session was started. On 2026-11-01, the `repomix` MCP entry added that day passed the same launch check with six tools discovered, while `pyrefly`, `osv-scanner`, and `deptry` were added from repository metadata, upstream documentation, and license files only: no language-server startup, editor configuration, scan, or MCP session was run for those three references. On 2026-10-29, `mcpls` was added from repository metadata, the upstream documentation book, license files, and release v0.8.0 only: no language-server startup, editor configuration, or MCP session was run. The `code-review-graph` and `mcp-tools-py` MCP entries added the same day were launched through the pinned commands and completed `initialize` and `tools/list`; see [research evidence](RESEARCH.md#mcp-protocol-smoke-results). On 2026-10-30, the `fallow` MCP entry added that day passed the same launch check with 43 tools discovered, while `chunkhound` was recorded as a reference after its pinned command failed to complete `initialize` in a fresh project within the smoke window. On 2026-10-28, `ty` and `agent-lsp` were added from repository metadata, upstream documentation, and license files only: no language-server startup, editor configuration, or MCP session was run for either entry. On 2026-10-27, the exact pinned Serena command completed MCP `initialize` and `tools/list` on macOS with Python 3.13 in a temporary Python project, using an isolated `SERENA_HOME`. Startup and tool discovery took about 35 seconds. It exposed 22 tools, including `find_symbol`, `find_referencing_symbols`, and `get_diagnostics_for_file`. +On 2026-11-10, no MCP or language-server entry was added or changed: the `planning-with-files` skill added that day had its pinned archive downloaded and SHA-256 verified but was not installed, and the `ui-ux-pro-max`, `agent-skills-spec` and `arcade-mcp` references added the same day were recorded from repository metadata, upstream documentation, package metadata and license files only, so no client files were generated, no skill was validated and no MCP server was started. On 2026-11-09, the `squirrelscan` MCP entry added that day was launched through its pinned command from a temporary project and completed MCP `initialize` and `tools/list` with 15 tools discovered ([research evidence](RESEARCH.md#mcp-protocol-smoke-results)); no `tools/call` request was issued, so no site was audited, no report was written, and no account was used. The `pipelock`, `elephant-goldfish`, and `lspyx` references added the same day were recorded from repository metadata, upstream documentation, package metadata, and license files only: no proxy was started and no policy was loaded, no traffic was intercepted, no plugin, agent, or skill was activated, and no language-server startup or MCP session was run for `lspyx`. On 2026-11-06, the `misata` MCP entry added that day was launched through its pinned command from a temporary project and completed MCP `initialize` and `tools/list` with 15 tools discovered ([research evidence](RESEARCH.md#mcp-protocol-smoke-results)); no `tools/call` request was issued, so no dataset was generated, no certificate was re-verified, and no database was seeded. The `agnix`, `skillspector`, and `brooks-lint` references added the same day were recorded from repository metadata, upstream documentation, package metadata, and license files only: no lint run or `--fix`, no scan, no installer, and no editor or MCP session was started. On 2026-11-02, the `roam-code`, `orm-lens`, and `lsp-mcp-server` entries added that day were launched through their pinned commands from a temporary project and completed MCP `initialize` and `tools/list` with 17, 13, and 29 tools discovered ([research evidence](RESEARCH.md#mcp-protocol-smoke-results)); no `tools/call` request was issued, so no codebase was indexed, no Django or SQLAlchemy project was analysed, and no language server was driven. The `ai-rulez` entry added the same day stays a reference: its npm and PyPI packages are installers for a native binary, and the wrapper's own download did not finish in the smoke window, so no MCP session was started. On 2026-11-01, the `repomix` MCP entry added that day passed the same launch check with six tools discovered, while `pyrefly`, `osv-scanner`, and `deptry` were added from repository metadata, upstream documentation, and license files only: no language-server startup, editor configuration, scan, or MCP session was run for those three references. On 2026-10-29, `mcpls` was added from repository metadata, the upstream documentation book, license files, and release v0.8.0 only: no language-server startup, editor configuration, or MCP session was run. The `code-review-graph` and `mcp-tools-py` MCP entries added the same day were launched through the pinned commands and completed `initialize` and `tools/list`; see [research evidence](RESEARCH.md#mcp-protocol-smoke-results). On 2026-10-30, the `fallow` MCP entry added that day passed the same launch check with 43 tools discovered, while `chunkhound` was recorded as a reference after its pinned command failed to complete `initialize` in a fresh project within the smoke window. On 2026-10-28, `ty` and `agent-lsp` were added from repository metadata, upstream documentation, and license files only: no language-server startup, editor configuration, or MCP session was run for either entry. On 2026-10-27, the exact pinned Serena command completed MCP `initialize` and `tools/list` on macOS with Python 3.13 in a temporary Python project, using an isolated `SERENA_HOME`. Startup and tool discovery took about 35 seconds. It exposed 22 tools, including `find_symbol`, `find_referencing_symbols`, and `get_diagnostics_for_file`. The check made no `tools/call` requests and ended before language-server initialization completed. It verifies the package launch and MCP discovery path, not symbol correctness, every programming language, every operating system, or integration inside all five agent applications. @@ -140,4 +140,4 @@ The check made no `tools/call` requests and ended before language-server initial `apd list --kind lsp` 可查看 Serena、lsp-mcp-server 与独立语言服务。后者需按各自官方指南安装，再由编辑器或其他原生 LSP 客户端加载。OpenCode 原生 `lsp` 设置与 MCP 桥接是两条独立路径；本工具保留你的设置，不自动开启原生 LSP。 -已验证 Serena 的 MCP 握手和工具列表，尚未执行符号操作或逐一验证所有 agent 界面。项目移动后需核对生成配置中的绝对路径；Serena 自己创建的缓存和项目状态不由 `apd remove` 清理。lsp-mcp-server 不自带语言服务：需自行安装（Python 用 python-lsp-server 提供的 `pylsp`）并在项目内配置 `.lsp-mcp.json`，它只是把已有语言服务接到 agent。2026-11-02 新增的 roam-code、orm-lens、lsp-mcp-server 也通过了握手与工具列表检查（分别 17、13、29 个工具），但没有调用任何工具。2026-11-06 新增的 `misata`（Python 合成测试数据 MCP）通过握手与工具列表检查（15 个工具），未调用任何工具；同期的 `agnix`（agent 配置 lint / LSP）、`skillspector`（技能与 MCP 安全扫描）、`brooks-lint`（六种代码审查模式）仅按仓库元数据、上游文档与许可证收录，未运行安装器、扫描或语言服务。 2026-11-09 新增的 `squirrelscan`（网站审计 MCP）通过握手与工具列表检查（15 个工具），未调用任何工具、未审计任何站点；同期的 `pipelock`（出网与 MCP 策略网关）、`elephant-goldfish`（多 harness 设计评审插件）、`lspyx`（Python 专用 ty+Ruff 桥接）仅按仓库元数据、上游文档与许可证收录，未运行安装器、代理、插件或语言服务。 +已验证 Serena 的 MCP 握手和工具列表，尚未执行符号操作或逐一验证所有 agent 界面。项目移动后需核对生成配置中的绝对路径；Serena 自己创建的缓存和项目状态不由 `apd remove` 清理。lsp-mcp-server 不自带语言服务：需自行安装（Python 用 python-lsp-server 提供的 `pylsp`）并在项目内配置 `.lsp-mcp.json`，它只是把已有语言服务接到 agent。2026-11-02 新增的 roam-code、orm-lens、lsp-mcp-server 也通过了握手与工具列表检查（分别 17、13、29 个工具），但没有调用任何工具。2026-11-06 新增的 `misata`（Python 合成测试数据 MCP）通过握手与工具列表检查（15 个工具），未调用任何工具；同期的 `agnix`（agent 配置 lint / LSP）、`skillspector`（技能与 MCP 安全扫描）、`brooks-lint`（六种代码审查模式）仅按仓库元数据、上游文档与许可证收录，未运行安装器、扫描或语言服务。 2026-11-09 新增的 `squirrelscan`（网站审计 MCP）通过握手与工具列表检查（15 个工具），未调用任何工具、未审计任何站点；同期的 `pipelock`（出网与 MCP 策略网关）、`elephant-goldfish`（多 harness 设计评审插件）、`lspyx`（Python 专用 ty+Ruff 桥接）仅按仓库元数据、上游文档与许可证收录，未运行安装器、代理、插件或语言服务。 2026-11-10 新增的 `planning-with-files`（把计划、进度与发现写进 `.planning/` 文件的 skill）只下载并校验了固定归档的 SHA-256，未安装、未启动 agent 会话；同期的 `ui-ux-pro-max`（本地设计数据 skill，经生成器 CLI 交付）、`agent-skills-spec`（Agent Skills 规范与 `skills-ref` 校验器）、`arcade-mcp`（Python MCP 框架）仅按仓库元数据、上游文档与许可证收录，未生成客户端文件、未运行校验、未启动 MCP 会话。 diff --git a/docs/RESEARCH.md b/docs/RESEARCH.md index 6ccb007..a6aa62e 100644 --- a/docs/RESEARCH.md +++ b/docs/RESEARCH.md @@ -1,6 +1,6 @@ # Research and provenance -Research date: **2026-11-09**. Repository metadata was fetched with `gh api repos//`; package versions came from the npm and PyPI registries. The manifest records the snapshot date, repository stars, latest push timestamp, license, and source links. Stars belong to whole repositories: the 22 skill entries come from four upstream repositories, and the six ECC rule packs share the ECC repository snapshot. A high star count is not an independent quality score for every skill or rule. +Research date: **2026-11-10**. Repository metadata was fetched with `gh api repos//`; package versions came from the npm and PyPI registries. The manifest records the snapshot date, repository stars, latest push timestamp, license, and source links. Stars belong to whole repositories: the 23 skill entries come from five upstream repositories, and the six ECC rule packs share the ECC repository snapshot. A high star count is not an independent quality score for every skill or rule. ## Patterns adopted @@ -150,6 +150,22 @@ A second daily pass over recently active coding-agent skills, MCP servers and Py One entry was executed in this pass - the pinned `squirrelscan` launcher, through the repository smoke script - and only to protocol negotiation, so no site was audited, no report was written and no MCP tool was called. The three references were recorded from repository metadata, upstream documentation, package metadata and license files only: nothing was installed, no plugin, agent or skill was activated, no proxy or policy was loaded, no traffic was intercepted and no MCP session was started. +## Candidate review on 2026-11-10 + +A third daily pass over recently active coding-agent skills, MCP servers and Python/web tooling added four entries after de-duplication against the previous 103: one installable skill (`OthmanAdi/planning-with-files`) and three reference-only entries (`nextlevelbuilder/ui-ux-pro-max-skill`, `agentskills/agentskills`, `ArcadeAI/arcade-mcp`). + +`planning-with-files` is the first installable skill here whose state lives in files rather than in context: `.planning/-/` holds the plan, its progress and its findings, the active plan is re-injected every turn so it survives context rot, the skill rebuilds the plan after `/clear` or compaction, and `scripts/check-complete.sh` gates completion with a SHA-256 attestation of the plan text it injected. It is also the only candidate in this pass whose delivered unit is a single self-contained subtree, so it takes a commit-pinned archive recipe: the archive was downloaded from `codeload.github.com` at `2362ca385ad74f061aa0e7b73f56543a4b7e6df2` (24,950,981 bytes, SHA-256 `cf60990c520c8f5d6fff876524450ce67172ad8ce785213a9bc50dbb06ac2227`, 37 files under the subtree), but it was not installed and no agent session was started, so no hook registration, plan re-injection or completion gate was exercised. + +`ui-ux-pro-max` covers the Web half of this catalog's remit from the design side: it answers style, palette, typography, icon, motion and UX-guideline questions from a local data set of 39 CSV/JSON files (3,103,749 bytes) under `.claude/skills/ui-ux-pro-max/data/`, spanning 22 stacks, through `scripts/search.py` and `design_system.py`, which need only a Python 3 standard library and make no network calls. It stays reference-only because upstream delivers it through a per-client generator (`npm install -g ui-ux-pro-max-cli`, then `uipro init --ai `, with `update`, `uninstall`, `--dry-run`, an `npx` route and a Claude Code marketplace route) and its README says to always use that CLI, so the repository tree is the generator's source template rather than the installed layout; the commands inside `SKILL.md` are anchored to `${CLAUDE_PLUGIN_ROOT}/.claude/skills/ui-ux-pro-max/scripts/search.py`, which a bare archive copy would not reproduce. MIT license; `skill.json` declares version 2.15.0 and the tree read here was commit `4f2dbb67e64969a9a30ab00742f2d55d66ddec2b`. + +`agent-skills-spec` is the normative document behind the `skill` kind used throughout this catalog: `docs/specification.mdx` defines the `SKILL.md` frontmatter (`name`, `description`, optional `license`, `allowed-tools`, `metadata`), the directory layout and the progressive-disclosure rules the recipes here follow, and `skills-ref/` is the Python reference implementation (`skills-ref validate `, `read-properties`, `to-prompt`; importable API under `src/`, tests alongside, PyPI release 0.1.1, Python >=3.11). It is recorded next to `anthropics/skills` and `agents-cli` as what a skill is checked against rather than as something to install, with the upstream caveat that `skills-ref` is demonstration-only rather than production tooling. + +`arcade-mcp` joins `fastmcp` and `mcp-python-sdk` in `build-mcp` as the third Python MCP framework, and the most widely deployed of the three (its README attributes 7,500+ tools across 81 hosted MCP servers to it): a decorator API covering tools, resources, prompts, sampling, elicitation, progress and logging, `requires_auth=` declarations that let the framework own OAuth and token refresh, and an `arcade-mcp` CLI for scaffolding, running and deploying servers. It is reference-only for the same reason as `fastmcp` — it is a Python library (monorepo with `libs/arcade-core`, `libs/arcade-mcp-server`, `libs/arcade-cli`, `libs/arcade-evals`, `libs/arcade-serve`, plus `examples/mcp_servers/`) installed inside a server project (`pip install arcade-mcp`, PyPI 1.17.6, Python >=3.10; the server package publishes separately as `arcade-mcp-server` 1.33.0) rather than an agent-side server this installer can register. + +Rejected candidates in this pass were unpublished, unlicensed, or below the adoption bar: `DadBodgeOff/drift` (793 stars, MIT, TypeScript, last pushed 2026-11-01) detects repository conventions for agents but says in its own README that nothing is published to npm yet and that the beta route is a Rust build from source; `bobnewton87/pro-debugger` (0 stars, no license file detected, last pushed 2026-02-24) and `bugounet/pdb-mcp` (0 stars, MIT, last pushed 2026-06-29) are Python debugger MCP servers below the adoption bar for a lane already served by the harness's own debugger; and `yzhao062/agent-style` (740 stars, no SPDX license detectable from repository metadata, last pushed 2026-10-27) is a writing-style rule pack whose license clarity does not meet the admission criteria. + +No entry was executed in this pass. The one installable addition was verified by downloading and hashing its pinned archive, and the three references were recorded from repository metadata, upstream documentation, package metadata and license files only: nothing was installed, no skill was validated, no client files were generated, and no MCP server was started. + ## Installable upstream evidence | Item | Evidence checked | Result | @@ -158,6 +174,7 @@ One entry was executed in this pass - the pinned `squirrelscan` launcher, throug | Python skills | [Pinned Python development skills](https://github.com/wshobson/agents/tree/0874a27b17a22e2b7c2e2bcd725768e0803cad06/plugins/python-development/skills), [upstream skill installation guidance](https://github.com/wshobson/agents/blob/main/docs/harnesses.md), complete archive | Testing and packaging each include `references/details.md` and `references/advanced-patterns.md`. These files must be copied with `SKILL.md`. | | ECC skills and rules | [Pinned source tree](https://github.com/affaan-m/ECC/tree/25278e7d7b6cf6e6a4e7a6c8e10f14ff22f0eb5b), repository metadata, MIT license, downloaded archive | Fifteen native skill directories and six explicit rule selections were checked. Selected paths are regular files/directories; skill frontmatter names match their IDs. Archive SHA-256 and size limits were verified. See [migration evidence](ECC-MIGRATION.md). | | agent-skills | [Pinned source tree](https://github.com/addyosmani/agent-skills/tree/aeac41d4d005999432bb7312f7ff06383a91d59d/skills), repository metadata, root `LICENSE` (MIT), complete downloaded archive | Both selected directories exist at the pin and contain a single `SKILL.md`; the skill directories hold no scripts or auxiliary files to copy. Archive SHA-256 `0211a580aab7…` recorded in the manifest. The collection's plugin manifests and hooks are out of scope for this installation. | +| planning-with-files skill | [Pinned source tree](https://github.com/OthmanAdi/planning-with-files/tree/2362ca385ad74f061aa0e7b73f56543a4b7e6df2/skills/planning-with-files), repository metadata, root `LICENSE` (MIT), complete downloaded archive | The selected directory exists at the pin with 37 entries (`SKILL.md`, `scripts/`, `templates/`, `evals/`, `examples.md`, `plan-inventory.md`, `reference.md`), and every path `SKILL.md` refers to resolves inside that directory. Archive SHA-256 `cf60990c520c…` recorded in the manifest. Nothing was installed and no agent session was started. | | Serena | [v2.1.0 release](https://github.com/oraios/serena/releases/tag/v2.1.0), [pinned package metadata](https://github.com/oraios/serena/blob/5e4f5cd173c7ff3eed37ee3f1de6c266b937c5dc/pyproject.toml), [component licensing](https://github.com/oraios/serena/blob/5e4f5cd173c7ff3eed37ee3f1de6c266b937c5dc/LICENSE), [server configuration](https://oraios.github.io/serena/02-usage/020_running.html) | v2.1.0 pinned to full commit; Python 3.13 selected explicitly. Generic project context, LSP backend, individual tool interface; dashboard/browser/GUI opening disabled. MCP startup and discovery of 22 tools verified; symbol calls were not exercised. | | Context7 | [MCP package README](https://github.com/upstash/context7/blob/master/packages/mcp/README.md), [client configuration](https://context7.com/docs/resources/all-clients), [npm version metadata](https://registry.npmjs.org/@upstash%2fcontext7-mcp/4.4.4) | Published stdio package `4.4.4`; Node.js `>=20.18.1`. The package README describes optional API keys for higher limits/private repositories. Hosted service behavior can change independently of the package pin. | | Playwright MCP | [Official README](https://github.com/microsoft/playwright-mcp), [npm version metadata](https://registry.npmjs.org/@playwright%2fmcp/0.0.83) | Published stdio package `0.0.83`; Node.js `>=18`. Browser installation is a separate prerequisite. | @@ -175,7 +192,7 @@ One entry was executed in this pass - the pinned `squirrelscan` launcher, throug | Reticle MCP | [Client configuration](https://github.com/reticlehq/reticle/blob/main/README.md), [installer](https://github.com/reticlehq/reticle/blob/main/install/install.sh), [framework guides](https://github.com/reticlehq/reticle/blob/main/docs/frameworks.mdx), [npm version metadata](https://registry.npmjs.org/@reticlehq%2fserver/3.9.0), [license](https://github.com/reticlehq/reticle/blob/main/LICENSE) | Published `3.9.0`; npm declares Node.js `>=20.11`, the `reticle` binary, and an optional Playwright peer. Upstream documents `npx @reticlehq/server@ mcp` for a client that already exists, and a one-line installer or `reticle setup mcp` for a machine-level setup that also appends instruction blocks and a prompt hook. Verdicts are computed locally; anonymous usage counts are on by default, and prompt upload requires linking the project. | | Mustel MCP | [Repository README](https://github.com/mustel-py/mustel/blob/main/README.md), [package metadata](https://github.com/mustel-py/mustel/blob/main/pyproject.toml), [PyPI version metadata](https://pypi.org/project/mustel/0.3.4/), [license](https://github.com/mustel-py/mustel/blob/main/LICENSE) | Published `0.3.4`; `pyproject.toml` declares Python `>=3.10` and leaves `mcp` uncapped (`mcp>=1.0.0`), so the launcher pins `--python 3.12` and `--with mcp<2`. Upstream documents `mustel serve` as the stdio server and lists five MCP tools (`review`, `review_file`, `get_code_map`, `env`, `bootstrap`), which matches what the smoke check discovered. The README is the source for the dual dev/audit mode switch (`CI`, `GITHUB_ACTIONS`, `PRE_COMMIT`), the stat-based cache, the 1,500-token `get_code_map` claim, Jupyter `.ipynb` parsing, and the `bootstrap` behaviour that rewrites IDE configuration, `.cursorrules`/`.windsurfrules` and git pre-commit hooks - none of which this recipe performs. | -The three skill/rule source archives were downloaded from `codeload.github.com` at full 40-character commits. Their SHA-256 values in the manifest were computed from the downloaded bytes. Serena instead uses an explicit Git source revision through uvx. Skill and original rule contents are upstream third-party material; catalog descriptions, selection notes, and disclosed rule adaptations are authored for this project. No upstream archive is vendored into this repository. +The five skill/rule source archives were downloaded from `codeload.github.com` at full 40-character commits. Their SHA-256 values in the manifest were computed from the downloaded bytes. Serena instead uses an explicit Git source revision through uvx. Skill and original rule contents are upstream third-party material; catalog descriptions, selection notes, and disclosed rule adaptations are authored for this project. No upstream archive is vendored into this repository. | Squirrelscan MCP | [Repository README](https://github.com/squirrelscan/squirrelscan/blob/main/README.md), [CLI `mcp` command](https://github.com/squirrelscan/squirrelscan/blob/main/apps/cli/src/cli/commands/mcp.ts), [npm package](https://www.npmjs.com/package/squirrelscan/v/0.0.173), [license](https://github.com/squirrelscan/squirrelscan/blob/main/LICENSE) | Published `0.0.173`; the package declares Node.js `>=18` and one `squirrel` binary whose `mcp` subcommand starts the local stdio server, which is exactly what the smoke check launched. Upstream also documents a hosted HTTP endpoint (`https://mcp.squirrelscan.com/mcp`) and a plugin-marketplace route, both outside this recipe, and report, publish and comment scopes need the user's own account. Nothing was audited: no site was fetched, no report was written and no MCP tool was called. | ## Why some tools are reference-only diff --git a/src/awesome_python_dev/data/catalog.json b/src/awesome_python_dev/data/catalog.json index 0c1aa10..1535d82 100644 --- a/src/awesome_python_dev/data/catalog.json +++ b/src/awesome_python_dev/data/catalog.json @@ -1,6 +1,6 @@ { "schema_version": 2, - "reviewed_at": "2026-11-09", + "reviewed_at": "2026-11-10", "tools": [ { "id": "systematic-debugging", @@ -2803,6 +2803,118 @@ "notes": "A Python-specific bridge in `lsp-bridge`, next to the general bridges (`serena`, `lsp-mcp-server`, `agent-lsp`, `mcpls`). The difference is the semantic backend: instead of driving pyright's language server it answers go-to-definition, references, outline, diagnostics and rename-preview queries through `ty`, Astral's type checker, plus Ruff, behind one small stdio MCP server with a per-workspace daemon (`src/daemon/`, `src/lsp/rename.rs`, `src/mcp/*`), and the same answers are available from the CLI. Launch is `lspyx mcp serve` (`claude mcp add --scope user lspyx -- lspyx mcp serve`), it needs `ty` and Ruff in the project `.venv` or on `PATH` (`lspyx doctor` checks the setup), and it is distributed as a Rust binary through `brew install iyazerski/tap/lspyx`, `cargo install lspyx --locked` or an install script - so, like `mcpls` and `agent-lsp`, there is no pinned registry package the installer could own, and the pair of external tools it depends on is another reason the entry stays reference-only. Evidence read in this pass: repository metadata, README, tags, the `src/` tree, eight tagged releases with eight binary assets each (latest v0.6.0, 2026-11-07) and the MIT license. Caveat worth weighing before adopting it: it is a young, single-maintainer project with 0 stars observed on 2026-11-09, recorded because the Python semantic-navigation lane has no other bridge and its ty/Ruff backend is unrepresented in this catalog. Nothing was installed and no MCP session was started.", "repository": "iyazerski/lspyx", "stars": 0 + }, + { + "archived": false, + "category": "engineering-skills", + "checked_at": "2026-11-10", + "description": "File-based planning skill for coding agents: crash-proof markdown plans on disk, session recovery after /clear or compaction, per-turn plan re-injection against context rot, and a deterministic completion gate, installed from a pinned archive.", + "evidence": [ + "https://api.github.com/repos/OthmanAdi/planning-with-files", + "https://github.com/OthmanAdi/planning-with-files/blob/master/README.md", + "https://github.com/OthmanAdi/planning-with-files/tree/master/skills/planning-with-files", + "https://github.com/OthmanAdi/planning-with-files/blob/master/skills/planning-with-files/SKILL.md", + "https://github.com/OthmanAdi/planning-with-files/blob/master/skills/planning-with-files/scripts/init-session.sh", + "https://github.com/OthmanAdi/planning-with-files/blob/master/skills/planning-with-files/templates/task_plan.md", + "https://codeload.github.com/OthmanAdi/planning-with-files/tar.gz/2362ca385ad74f061aa0e7b73f56543a4b7e6df2", + "https://github.com/OthmanAdi/planning-with-files/blob/master/LICENSE" + ], + "homepage": "https://github.com/OthmanAdi/planning-with-files", + "id": "planning-with-files", + "install": { + "url": "https://codeload.github.com/OthmanAdi/planning-with-files/tar.gz/2362ca385ad74f061aa0e7b73f56543a4b7e6df2", + "sha256": "cf60990c520c8f5d6fff876524450ce67172ad8ce785213a9bc50dbb06ac2227", + "ref": "2362ca385ad74f061aa0e7b73f56543a4b7e6df2", + "type": "skill", + "subdir": "skills/planning-with-files", + "license_path": "LICENSE" + }, + "kind": "skill", + "last_pushed_at": "2026-11-07T11:24:31Z", + "license": "MIT", + "name": "planning-with-files", + "notes": "Adds the persistent-plan lane to `engineering-skills`, next to the one-shot planning skills already there: instead of a single plan document the skill keeps `.planning/-/task_plan.md`, `progress.md` and `findings.md` on disk, re-injects the active plan every turn against context rot, recovers the plan after `/clear` or compaction, and gates completion with `scripts/check-complete.sh` (plus a SHA-256 attestation of the plan it injected). The recipe copies the archived `skills/planning-with-files` subtree from the pinned commit `2362ca38` - `SKILL.md`, `scripts/` (bash, PowerShell and Python implementations), `templates/`, `evals/`, `examples.md`, `plan-inventory.md`, `reference.md` - so the installed skill is self-contained: every path in `SKILL.md` is relative to the skill directory (`${CLAUDE_SKILL_DIR}`, `$PWF_SKILL_DIR`, `./scripts/...`) with no `../` escapes, and the Claude Code/Codex hooks it needs are declared in the skill's own frontmatter, which the clients read from the installed file. Upstream additionally ships an npm launcher, plugin-marketplace entries and an `npx skills` path for 60+ agents; this entry deliberately pins only the commit archive. Evidence read in this pass: repository metadata, README, the `skills/` tree at the pinned commit, `SKILL.md`, the `scripts/`, `templates/` and `evals/` listings, and the downloaded archive (24,950,981 bytes, SHA-256 verified, 37 files under the skill subtree, `LICENSE` at the archive root copied as `license_path`). Nothing was installed and no agent session was started.", + "repository": "OthmanAdi/planning-with-files", + "stars": 27973 + }, + { + "archived": false, + "category": "framework-best-practices", + "checked_at": "2026-11-10", + "description": "Design-intelligence skill for building UI/UX in web and app projects: 80 styles, 192 palettes, 74 font pairings, 120 UX guidelines and 25 chart types in local CSV data, queried with Python scripts through a per-client CLI installer.", + "evidence": [ + "https://api.github.com/repos/nextlevelbuilder/ui-ux-pro-max-skill", + "https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/blob/main/README.md", + "https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/blob/main/skill.json", + "https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/tree/main/.claude/skills/ui-ux-pro-max", + "https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/blob/main/.claude/skills/ui-ux-pro-max/SKILL.md", + "https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/blob/main/.claude/skills/ui-ux-pro-max/scripts/search.py", + "https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/blob/main/.claude/skills/ui-ux-pro-max/references/quick-reference.md", + "https://www.npmjs.com/package/ui-ux-pro-max-cli", + "https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/blob/main/LICENSE" + ], + "homepage": "https://uupm.cc", + "id": "ui-ux-pro-max", + "install": null, + "kind": "reference", + "last_pushed_at": "2026-11-07T19:05:11Z", + "license": "MIT", + "name": "UI/UX Pro Max", + "notes": "The Web-side counterpart of the Python-focused skills in this catalog: a design-intelligence skill that answers style, palette, typography, icon, motion and UX-guideline questions from 3.1 MB of local CSV/JSON data (39 files, 3,103,749 bytes under `.claude/skills/ui-ux-pro-max/data/`, 22 tech stacks) through `scripts/search.py` and `design_system.py`, which need only a Python 3 standard library and make no network calls. Recorded reference-only on purpose. Upstream ships a per-client generator (`npm install -g ui-ux-pro-max-cli`, `uipro init --ai claude`, also `npx ... init --ai `, with `update`/`uninstall`/`--dry-run` subcommands and a Claude Code marketplace path), and its README says to *always* use the CLI; the repository tree is the CLI's source template rather than the installed layout, and the commands inside `SKILL.md` are anchored to `${CLAUDE_PLUGIN_ROOT}/.claude/skills/ui-ux-pro-max/scripts/search.py`, so a bare commit-archive copy would not reproduce it. That, plus the CLI's own activation and update path, is why no pinned recipe is claimed and the entry stays next to `skillsaw` and `graphify` as a reference. License MIT (`LICENSE` at the repository root; `skill.json` also declares MIT). Evidence read in this pass: repository metadata, README (install and troubleshooting sections, including the pre-v2.5.1 symlink packaging note), `skill.json` 2.15.0, the `.claude/skills/` and `.claude/skills/ui-ux-pro-max` trees at commit `4f2dbb67`, `SKILL.md` and its path references. Nothing was installed and no client files were generated.", + "repository": "nextlevelbuilder/ui-ux-pro-max-skill", + "stars": 147361 + }, + { + "archived": false, + "category": "skill-ecosystem", + "checked_at": "2026-11-10", + "description": "The Agent Skills specification plus skills-ref, the Python reference implementation that validates a skill directory, reads its properties and renders the available-skills prompt block.", + "evidence": [ + "https://api.github.com/repos/agentskills/agentskills", + "https://agentskills.io", + "https://github.com/agentskills/agentskills/blob/main/docs/specification.mdx", + "https://github.com/agentskills/agentskills/blob/main/skills-ref/README.md", + "https://github.com/agentskills/agentskills/blob/main/skills-ref/pyproject.toml", + "https://github.com/agentskills/agentskills/tree/main/skills-ref/src", + "https://pypi.org/project/skills-ref/", + "https://github.com/agentskills/agentskills/blob/main/LICENSE" + ], + "homepage": "https://agentskills.io", + "id": "agent-skills-spec", + "install": null, + "kind": "reference", + "last_pushed_at": "2026-11-04T19:47:27Z", + "license": "Apache-2.0", + "name": "Agent Skills specification", + "notes": "The normative document behind the `skill` kind in this catalog: `docs/specification.mdx` defines the `SKILL.md` frontmatter (`name`, `description`, optional `license`/`allowed-tools`/`metadata`), the directory layout and the progressive-disclosure rules that the `skill` recipes here follow, and `skills-ref/` is the Python reference implementation (`skills-ref validate `, `read-properties `, `to-prompt ...`; importable API in `src/`, tests alongside, PyPI release 0.1.1, Python >=3.11, Apache-2.0). Recorded as a reference next to `anthropics/skills` and `agents-cli`: it is not a tool this installer puts into a client project, it is what to check a skill against, so there is no pinned recipe. Upstream marks `skills-ref` as demonstration-only rather than production tooling, which is recorded here as a caveat; the specification itself is what makes the entry useful. Evidence read in this pass: repository metadata, README, the `docs/` and `skills-ref/` trees, `skills-ref/README.md`, `skills-ref/pyproject.toml` and the PyPI release metadata. Nothing was installed and no skill was validated with it.", + "repository": "agentskills/agentskills", + "stars": 27113 + }, + { + "archived": false, + "category": "build-mcp", + "checked_at": "2026-11-10", + "description": "Open-source Python framework for building MCP servers and tools: decorator API over the full MCP spec (tools, resources, prompts, sampling, elicitation), authorization hooks, and an arcade-mcp CLI for scaffolding and running servers.", + "evidence": [ + "https://api.github.com/repos/ArcadeAI/arcade-mcp", + "https://github.com/ArcadeAI/arcade-mcp/blob/main/README.md", + "https://github.com/ArcadeAI/arcade-mcp/tree/main/libs", + "https://github.com/ArcadeAI/arcade-mcp/blob/main/libs/arcade-mcp-server/pyproject.toml", + "https://github.com/ArcadeAI/arcade-mcp/tree/main/examples/mcp_servers", + "https://pypi.org/project/arcade-mcp/", + "https://docs.arcade.dev", + "https://github.com/ArcadeAI/arcade-mcp/blob/main/LICENSE" + ], + "homepage": "https://docs.arcade.dev", + "id": "arcade-mcp", + "install": null, + "kind": "reference", + "last_pushed_at": "2026-11-09T21:03:13Z", + "license": "MIT", + "name": "Arcade MCP", + "notes": "Third entry in the `build-mcp` lane next to `fastmcp` and the official `mcp-python-sdk`, and the most widely deployed of the three (the README attributes 7,500+ prebuilt tools across 81 hosted MCP servers to it): a decorator API covering tools, resources, prompts, sampling, elicitation, progress and logging, `requires_auth=` declarations that let the framework own OAuth and token refresh, a vendor-neutral client story, and the `arcade-mcp` CLI for scaffolding, running and deploying servers. It is reference-only for the same reason as `fastmcp`: it is a Python library (`pyproject.toml`, monorepo `libs/arcade-core`, `libs/arcade-mcp-server`, `libs/arcade-cli`, `libs/arcade-evals`, `libs/arcade-serve`, `examples/mcp_servers/`) installed as a dependency inside a server project, not an agent-side MCP server this installer can configure by launching a command, so there is no pinned recipe; `pip install arcade-mcp` resolves PyPI 1.17.6 (Python >=3.10) and the server package publishes separately as `arcade-mcp-server` 1.33.0. MIT license. Evidence read in this pass: repository metadata, README (framework highlights and install sections), the `libs/` and `examples/` trees, and the PyPI metadata for both packages. Nothing was installed and no server was started.", + "repository": "ArcadeAI/arcade-mcp", + "stars": 1088 } ], "profiles": {