mirror of
https://github.com/anthropics/claude-plugins-official.git
synced 2026-06-20 00:24:58 +00:00
Compare commits
1 Commits
update-cod
...
mnowicki/a
| Author | SHA1 | Date | |
|---|---|---|---|
|
7a6098a70d |
@@ -7,22 +7,6 @@
|
||||
"email": "support@anthropic.com"
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
"name": "42crunch-api-security-testing",
|
||||
"description": "Automate API security directly in Claude Code with 42Crunch - automatically audit OpenAPI specs, detect vulnerabilities aligned with OWASP API Security risks (including BOLA/BFLA), and apply AI-powered fixes. Designed for AI-assisted development workflows, it provides continuous guardrails through an audit->scan->remediate->validate loop, ensuring APIs meet enterprise security standards before deployment.",
|
||||
"author": {
|
||||
"name": "42Crunch"
|
||||
},
|
||||
"category": "security",
|
||||
"source": {
|
||||
"source": "git-subdir",
|
||||
"url": "https://github.com/42Crunch-AI/claude-plugins.git",
|
||||
"path": "plugins/api-security-testing",
|
||||
"ref": "v1.0.1",
|
||||
"sha": "56273e0e20762d76640838300a7431c4260cad32"
|
||||
},
|
||||
"homepage": "https://42crunch.com"
|
||||
},
|
||||
{
|
||||
"name": "adlc",
|
||||
"description": "Agentforce Agent Development Life Cycle — author, discover, scaffold, deploy, test, and optimize .agent files",
|
||||
@@ -33,21 +17,6 @@
|
||||
},
|
||||
"homepage": "https://github.com/SalesforceAIResearch/agentforce-adlc"
|
||||
},
|
||||
{
|
||||
"name": "adobe-for-creativity",
|
||||
"description": "Harness Adobe's creative AI-powered tools to edit images, automate design workflows, and bring creative visions to life — from background removal to vectorization and professional retouching.",
|
||||
"author": {
|
||||
"name": "Adobe"
|
||||
},
|
||||
"category": "design",
|
||||
"source": {
|
||||
"source": "git-subdir",
|
||||
"url": "https://github.com/adobe/skills.git",
|
||||
"path": "plugins/creative-cloud/adobe-for-creativity",
|
||||
"ref": "main"
|
||||
},
|
||||
"homepage": "https://github.com/adobe/skills/tree/main/plugins/creative-cloud/adobe-for-creativity"
|
||||
},
|
||||
{
|
||||
"name": "adspirer-ads-agent",
|
||||
"description": "Cross-platform ad management for Google Ads, Meta Ads, TikTok Ads, and LinkedIn Ads. 91 tools for keyword research, campaign creation, performance analysis, and budget optimization.",
|
||||
@@ -102,20 +71,6 @@
|
||||
},
|
||||
"homepage": "https://github.com/AikidoSec/aikido-claude-plugin"
|
||||
},
|
||||
{
|
||||
"name": "aiven",
|
||||
"description": "Easily deploy managed PostgreSQL, Kafka, OpenSearch, Clickhouse, and other databases, streaming, and apps through Aiven. Free tier available, up and running in minutes.",
|
||||
"author": {
|
||||
"name": "Aiven"
|
||||
},
|
||||
"category": "database",
|
||||
"source": {
|
||||
"source": "github",
|
||||
"repo": "aiven/aiven-ai-plugins",
|
||||
"commit": "d2a7697b53826588d0faf795f39d2aa2362330da"
|
||||
},
|
||||
"homepage": "https://aiven.io"
|
||||
},
|
||||
{
|
||||
"name": "alloydb",
|
||||
"description": "Create, connect, and interact with an AlloyDB for PostgreSQL database and data.",
|
||||
@@ -268,22 +223,6 @@
|
||||
},
|
||||
"homepage": "https://github.com/awslabs/agent-plugins"
|
||||
},
|
||||
{
|
||||
"name": "aws-dev-toolkit",
|
||||
"description": "AWS development toolkit — 34 skills, 11 agents, and 3 MCP servers for building, migrating, and performing architecture reviews on AWS.",
|
||||
"author": {
|
||||
"name": "aws-samples"
|
||||
},
|
||||
"category": "development",
|
||||
"source": {
|
||||
"source": "git-subdir",
|
||||
"url": "https://github.com/aws-samples/sample-claude-code-plugins-for-startups.git",
|
||||
"path": "plugins/aws-dev-toolkit",
|
||||
"ref": "main",
|
||||
"sha": "ddea7fdd605b42ed3900374815f358a2d4600db5"
|
||||
},
|
||||
"homepage": "https://github.com/aws-samples/sample-claude-code-plugins-for-startups"
|
||||
},
|
||||
{
|
||||
"name": "aws-serverless",
|
||||
"description": "Design, build, deploy, test, and debug serverless applications with AWS Serverless services.",
|
||||
@@ -524,9 +463,9 @@
|
||||
"category": "productivity",
|
||||
"source": {
|
||||
"source": "url",
|
||||
"url": "https://github.com/coderabbitai/skills.git"
|
||||
"url": "https://github.com/coderabbitai/claude-plugin.git"
|
||||
},
|
||||
"homepage": "https://github.com/coderabbitai/skills"
|
||||
"homepage": "https://github.com/coderabbitai/claude-plugin.git"
|
||||
},
|
||||
{
|
||||
"name": "commit-commands",
|
||||
@@ -628,20 +567,6 @@
|
||||
},
|
||||
"homepage": "https://www.datadoghq.com/"
|
||||
},
|
||||
{
|
||||
"name": "datarobot-agent-skills",
|
||||
"description": "DataRobot skills for AI/ML workflows — model training, deployment, predictions, feature engineering, monitoring, explainability, data preparation, App Framework CI/CD, and external agent monitoring.",
|
||||
"author": {
|
||||
"name": "DataRobot"
|
||||
},
|
||||
"category": "development",
|
||||
"source": {
|
||||
"source": "url",
|
||||
"url": "https://github.com/datarobot-oss/datarobot-agent-skills.git",
|
||||
"sha": "b3e8fd33d7c36592c802359026c15f3e067a0646"
|
||||
},
|
||||
"homepage": "https://datarobot.com"
|
||||
},
|
||||
{
|
||||
"name": "dataverse",
|
||||
"description": "Agent skills for building on, analyzing, and managing Microsoft Dataverse — with Dataverse MCP, PAC CLI, and Python SDK.",
|
||||
@@ -824,20 +749,6 @@
|
||||
"category": "development",
|
||||
"homepage": "https://github.com/anthropics/claude-plugins-public/tree/main/plugins/frontend-design"
|
||||
},
|
||||
{
|
||||
"name": "fullstory",
|
||||
"description": "Connect Claude to Fullstory to query behavioral analytics, session replays, and customer experience insights.",
|
||||
"author": {
|
||||
"name": "Fullstory"
|
||||
},
|
||||
"category": "monitoring",
|
||||
"source": {
|
||||
"source": "github",
|
||||
"repo": "fullstorydev/fullstory-skills",
|
||||
"commit": "1ec5865e7ab1449f9a0859d164c4b6a8c53b6e2f"
|
||||
},
|
||||
"homepage": "https://www.fullstory.com"
|
||||
},
|
||||
{
|
||||
"name": "github",
|
||||
"description": "Official GitHub MCP server for repository management. Create issues, manage pull requests, review code, search repositories, and interact with GitHub's full API directly from Claude Code.",
|
||||
@@ -960,21 +871,6 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "jfrog",
|
||||
"description": "Use the JFrog Platform from Claude Code: Artifactory repos and artifacts, security findings and exposures, Catalog package safety and downloads, workflows across the SDLC, and platform administration.",
|
||||
"author": {
|
||||
"name": "JFrog Ltd.",
|
||||
"url": "https://jfrog.com"
|
||||
},
|
||||
"category": "security",
|
||||
"source": {
|
||||
"source": "github",
|
||||
"repo": "jfrog/claude-plugin",
|
||||
"commit": "761921eaa12b845beba1688d699a2d45091dfe83"
|
||||
},
|
||||
"homepage": "https://jfrog.com"
|
||||
},
|
||||
{
|
||||
"name": "kotlin-lsp",
|
||||
"description": "Kotlin language server for code intelligence",
|
||||
@@ -1070,21 +966,6 @@
|
||||
},
|
||||
"homepage": "https://github.com/Shopify/liquid-skills/tree/main/plugins/liquid-skills"
|
||||
},
|
||||
{
|
||||
"name": "logfire",
|
||||
"description": "Add Logfire observability to Python applications with auto-instrumentation for FastAPI, httpx, asyncpg, SQLAlchemy, and more",
|
||||
"author": {
|
||||
"name": "Pydantic"
|
||||
},
|
||||
"category": "monitoring",
|
||||
"source": {
|
||||
"source": "git-subdir",
|
||||
"url": "https://github.com/pydantic/skills.git",
|
||||
"path": "plugins/logfire",
|
||||
"ref": "main"
|
||||
},
|
||||
"homepage": "https://github.com/pydantic/skills/tree/main/plugins/logfire"
|
||||
},
|
||||
{
|
||||
"name": "lua-lsp",
|
||||
"description": "Lua language server for code intelligence",
|
||||
@@ -1105,6 +986,17 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "managed-agents",
|
||||
"description": "Development kit for building on Claude Managed Agents",
|
||||
"author": {
|
||||
"name": "Anthropic",
|
||||
"email": "support@anthropic.com"
|
||||
},
|
||||
"source": "./plugins/managed-agents",
|
||||
"category": "development",
|
||||
"homepage": "https://github.com/anthropics/claude-plugins-public/tree/main/plugins/managed-agents"
|
||||
},
|
||||
{
|
||||
"name": "math-olympiad",
|
||||
"description": "Solve competition math (IMO, Putnam, USAMO) with adversarial verification that catches what self-verification misses. Fresh-context verifiers attack proofs with specific failure patterns. Calibrated abstention over bluffing.",
|
||||
@@ -1474,34 +1366,6 @@
|
||||
},
|
||||
"homepage": "https://www.qt.io/"
|
||||
},
|
||||
{
|
||||
"name": "quarkus-agent",
|
||||
"description": "MCP server for AI coding agents to create, manage, and interact with Quarkus applications. Provides tools for project scaffolding, dev mode lifecycle, extension skills, Dev MCP proxy, and documentation search.",
|
||||
"author": {
|
||||
"name": "Quarkus"
|
||||
},
|
||||
"category": "development",
|
||||
"source": {
|
||||
"source": "url",
|
||||
"url": "https://github.com/quarkusio/quarkus-agent-mcp.git"
|
||||
},
|
||||
"homepage": "https://quarkus.io"
|
||||
},
|
||||
{
|
||||
"name": "rails-query",
|
||||
"description": "Run read-only database queries against a Ruby on Rails 8.2+ app's database via `rails query` — ActiveRecord or SQL, schema/model introspection, EXPLAIN, pagination, and remote execution via Kamal.",
|
||||
"author": {
|
||||
"name": "Lewis Buckley",
|
||||
"url": "https://github.com/lewispb"
|
||||
},
|
||||
"category": "development",
|
||||
"source": {
|
||||
"source": "github",
|
||||
"repo": "lewispb/rails-query-skill",
|
||||
"commit": "0f53fa861089e1f46097db9a92aea311f340c355"
|
||||
},
|
||||
"homepage": "https://github.com/lewispb/rails-query-skill"
|
||||
},
|
||||
{
|
||||
"name": "railway",
|
||||
"description": "Deploy and manage apps, databases, and infrastructure on Railway. Covers project setup, deploys, environment configuration, networking, troubleshooting, and monitoring.",
|
||||
@@ -1943,20 +1807,6 @@
|
||||
},
|
||||
"homepage": "https://github.com/UI5/plugins-claude"
|
||||
},
|
||||
{
|
||||
"name": "vanta-mcp-plugin",
|
||||
"description": "The Vanta plugin connects Claude Code to Vanta's security and compliance platform through the Vanta MCP server. It combines Vanta's test-specific remediation intelligence with your local repository context to help you fix compliance failures faster.",
|
||||
"author": {
|
||||
"name": "Vanta"
|
||||
},
|
||||
"category": "security",
|
||||
"source": {
|
||||
"source": "url",
|
||||
"url": "https://github.com/VantaInc/vanta-mcp-plugin.git",
|
||||
"sha": "46e5bebf0484f08fc4a3c4054437cf5ec06298c9"
|
||||
},
|
||||
"homepage": "https://help.vanta.com/en/articles/14094979-connecting-to-vanta-mcp#h_887ce3f337"
|
||||
},
|
||||
{
|
||||
"name": "vercel",
|
||||
"description": "Vercel deployment platform integration. Manage deployments, check build status, access logs, configure domains, and control your frontend infrastructure directly from Claude Code.",
|
||||
|
||||
15
.github/workflows/validate-frontmatter.yml
vendored
15
.github/workflows/validate-frontmatter.yml
vendored
@@ -9,10 +9,6 @@ on:
|
||||
|
||||
jobs:
|
||||
validate:
|
||||
# Fork PRs are auto-closed by close-external-prs.yml, so skip validation
|
||||
# for them entirely. This also prevents untrusted filenames from forks
|
||||
# from ever reaching the shell steps below.
|
||||
if: github.event.pull_request.head.repo.full_name == github.repository
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
@@ -24,19 +20,16 @@ jobs:
|
||||
|
||||
- name: Get changed frontmatter files
|
||||
id: changed
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
PR_NUMBER: ${{ github.event.pull_request.number }}
|
||||
run: |
|
||||
# Use diff-filter=AMRC to exclude deleted files (D) - only Added, Modified, Renamed, Copied
|
||||
FILES=$(gh pr diff "$PR_NUMBER" --name-only --diff-filter=AMRC | grep -E '(agents/.*\.md|skills/.*/SKILL\.md|commands/.*\.md)$' || true)
|
||||
FILES=$(gh pr diff ${{ github.event.pull_request.number }} --name-only --diff-filter=AMRC | grep -E '(agents/.*\.md|skills/.*/SKILL\.md|commands/.*\.md)$' || true)
|
||||
echo "files<<EOF" >> "$GITHUB_OUTPUT"
|
||||
echo "$FILES" >> "$GITHUB_OUTPUT"
|
||||
echo "EOF" >> "$GITHUB_OUTPUT"
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
|
||||
- name: Validate frontmatter
|
||||
if: steps.changed.outputs.files != ''
|
||||
env:
|
||||
FILES: ${{ steps.changed.outputs.files }}
|
||||
run: |
|
||||
printf '%s\n' "$FILES" | xargs bun .github/scripts/validate-frontmatter.ts
|
||||
echo "${{ steps.changed.outputs.files }}" | xargs bun .github/scripts/validate-frontmatter.ts
|
||||
|
||||
8
plugins/managed-agents/.claude-plugin/plugin.json
Normal file
8
plugins/managed-agents/.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"name": "managed-agents",
|
||||
"description": "Claude Managed Agents Development Plugin",
|
||||
"author": {
|
||||
"name": "Anthropic",
|
||||
"email": "support@anthropic.com"
|
||||
}
|
||||
}
|
||||
202
plugins/managed-agents/LICENSE
Normal file
202
plugins/managed-agents/LICENSE
Normal file
@@ -0,0 +1,202 @@
|
||||
|
||||
Apache License
|
||||
Version 2.0, January 2004
|
||||
http://www.apache.org/licenses/
|
||||
|
||||
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||
|
||||
1. Definitions.
|
||||
|
||||
"License" shall mean the terms and conditions for use, reproduction,
|
||||
and distribution as defined by Sections 1 through 9 of this document.
|
||||
|
||||
"Licensor" shall mean the copyright owner or entity authorized by
|
||||
the copyright owner that is granting the License.
|
||||
|
||||
"Legal Entity" shall mean the union of the acting entity and all
|
||||
other entities that control, are controlled by, or are under common
|
||||
control with that entity. For the purposes of this definition,
|
||||
"control" means (i) the power, direct or indirect, to cause the
|
||||
direction or management of such entity, whether by contract or
|
||||
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||
|
||||
"You" (or "Your") shall mean an individual or Legal Entity
|
||||
exercising permissions granted by this License.
|
||||
|
||||
"Source" form shall mean the preferred form for making modifications,
|
||||
including but not limited to software source code, documentation
|
||||
source, and configuration files.
|
||||
|
||||
"Object" form shall mean any form resulting from mechanical
|
||||
transformation or translation of a Source form, including but
|
||||
not limited to compiled object code, generated documentation,
|
||||
and conversions to other media types.
|
||||
|
||||
"Work" shall mean the work of authorship, whether in Source or
|
||||
Object form, made available under the License, as indicated by a
|
||||
copyright notice that is included in or attached to the work
|
||||
(an example is provided in the Appendix below).
|
||||
|
||||
"Derivative Works" shall mean any work, whether in Source or Object
|
||||
form, that is based on (or derived from) the Work and for which the
|
||||
editorial revisions, annotations, elaborations, or other modifications
|
||||
represent, as a whole, an original work of authorship. For the purposes
|
||||
of this License, Derivative Works shall not include works that remain
|
||||
separable from, or merely link (or bind by name) to the interfaces of,
|
||||
the Work and Derivative Works thereof.
|
||||
|
||||
"Contribution" shall mean any work of authorship, including
|
||||
the original version of the Work and any modifications or additions
|
||||
to that Work or Derivative Works thereof, that is intentionally
|
||||
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||
or by an individual or Legal Entity authorized to submit on behalf of
|
||||
the copyright owner. For the purposes of this definition, "submitted"
|
||||
means any form of electronic, verbal, or written communication sent
|
||||
to the Licensor or its representatives, including but not limited to
|
||||
communication on electronic mailing lists, source code control systems,
|
||||
and issue tracking systems that are managed by, or on behalf of, the
|
||||
Licensor for the purpose of discussing and improving the Work, but
|
||||
excluding communication that is conspicuously marked or otherwise
|
||||
designated in writing by the copyright owner as "Not a Contribution."
|
||||
|
||||
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||
on behalf of whom a Contribution has been received by Licensor and
|
||||
subsequently incorporated within the Work.
|
||||
|
||||
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
copyright license to reproduce, prepare Derivative Works of,
|
||||
publicly display, publicly perform, sublicense, and distribute the
|
||||
Work and such Derivative Works in Source or Object form.
|
||||
|
||||
3. Grant of Patent License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
(except as stated in this section) patent license to make, have made,
|
||||
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||
where such license applies only to those patent claims licensable
|
||||
by such Contributor that are necessarily infringed by their
|
||||
Contribution(s) alone or by combination of their Contribution(s)
|
||||
with the Work to which such Contribution(s) was submitted. If You
|
||||
institute patent litigation against any entity (including a
|
||||
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||
or a Contribution incorporated within the Work constitutes direct
|
||||
or contributory patent infringement, then any patent licenses
|
||||
granted to You under this License for that Work shall terminate
|
||||
as of the date such litigation is filed.
|
||||
|
||||
4. Redistribution. You may reproduce and distribute copies of the
|
||||
Work or Derivative Works thereof in any medium, with or without
|
||||
modifications, and in Source or Object form, provided that You
|
||||
meet the following conditions:
|
||||
|
||||
(a) You must give any other recipients of the Work or
|
||||
Derivative Works a copy of this License; and
|
||||
|
||||
(b) You must cause any modified files to carry prominent notices
|
||||
stating that You changed the files; and
|
||||
|
||||
(c) You must retain, in the Source form of any Derivative Works
|
||||
that You distribute, all copyright, patent, trademark, and
|
||||
attribution notices from the Source form of the Work,
|
||||
excluding those notices that do not pertain to any part of
|
||||
the Derivative Works; and
|
||||
|
||||
(d) If the Work includes a "NOTICE" text file as part of its
|
||||
distribution, then any Derivative Works that You distribute must
|
||||
include a readable copy of the attribution notices contained
|
||||
within such NOTICE file, excluding those notices that do not
|
||||
pertain to any part of the Derivative Works, in at least one
|
||||
of the following places: within a NOTICE text file distributed
|
||||
as part of the Derivative Works; within the Source form or
|
||||
documentation, if provided along with the Derivative Works; or,
|
||||
within a display generated by the Derivative Works, if and
|
||||
wherever such third-party notices normally appear. The contents
|
||||
of the NOTICE file are for informational purposes only and
|
||||
do not modify the License. You may add Your own attribution
|
||||
notices within Derivative Works that You distribute, alongside
|
||||
or as an addendum to the NOTICE text from the Work, provided
|
||||
that such additional attribution notices cannot be construed
|
||||
as modifying the License.
|
||||
|
||||
You may add Your own copyright statement to Your modifications and
|
||||
may provide additional or different license terms and conditions
|
||||
for use, reproduction, or distribution of Your modifications, or
|
||||
for any such Derivative Works as a whole, provided Your use,
|
||||
reproduction, and distribution of the Work otherwise complies with
|
||||
the conditions stated in this License.
|
||||
|
||||
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||
any Contribution intentionally submitted for inclusion in the Work
|
||||
by You to the Licensor shall be under the terms and conditions of
|
||||
this License, without any additional terms or conditions.
|
||||
Notwithstanding the above, nothing herein shall supersede or modify
|
||||
the terms of any separate license agreement you may have executed
|
||||
with Licensor regarding such Contributions.
|
||||
|
||||
6. Trademarks. This License does not grant permission to use the trade
|
||||
names, trademarks, service marks, or product names of the Licensor,
|
||||
except as required for reasonable and customary use in describing the
|
||||
origin of the Work and reproducing the content of the NOTICE file.
|
||||
|
||||
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||
agreed to in writing, Licensor provides the Work (and each
|
||||
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
implied, including, without limitation, any warranties or conditions
|
||||
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||
appropriateness of using or redistributing the Work and assume any
|
||||
risks associated with Your exercise of permissions under this License.
|
||||
|
||||
8. Limitation of Liability. In no event and under no legal theory,
|
||||
whether in tort (including negligence), contract, or otherwise,
|
||||
unless required by applicable law (such as deliberate and grossly
|
||||
negligent acts) or agreed to in writing, shall any Contributor be
|
||||
liable to You for damages, including any direct, indirect, special,
|
||||
incidental, or consequential damages of any character arising as a
|
||||
result of this License or out of the use or inability to use the
|
||||
Work (including but not limited to damages for loss of goodwill,
|
||||
work stoppage, computer failure or malfunction, or any and all
|
||||
other commercial damages or losses), even if such Contributor
|
||||
has been advised of the possibility of such damages.
|
||||
|
||||
9. Accepting Warranty or Additional Liability. While redistributing
|
||||
the Work or Derivative Works thereof, You may choose to offer,
|
||||
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||
or other liability obligations and/or rights consistent with this
|
||||
License. However, in accepting such obligations, You may act only
|
||||
on Your own behalf and on Your sole responsibility, not on behalf
|
||||
of any other Contributor, and only if You agree to indemnify,
|
||||
defend, and hold each Contributor harmless for any liability
|
||||
incurred by, or claims asserted against, such Contributor by reason
|
||||
of your accepting any such warranty or additional liability.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
|
||||
APPENDIX: How to apply the Apache License to your work.
|
||||
|
||||
To apply the Apache License to your work, attach the following
|
||||
boilerplate notice, with the fields enclosed by brackets "[]"
|
||||
replaced with your own identifying information. (Don't include
|
||||
the brackets!) The text should be enclosed in the appropriate
|
||||
comment syntax for the file format. We also recommend that a
|
||||
file or class name and description of purpose be included on the
|
||||
same "printed page" as the copyright notice for easier
|
||||
identification within third-party archives.
|
||||
|
||||
Copyright [yyyy] [name of copyright owner]
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
39
plugins/managed-agents/README.md
Normal file
39
plugins/managed-agents/README.md
Normal file
@@ -0,0 +1,39 @@
|
||||
# Claude Managed Agents Development Plugin
|
||||
|
||||
A plugin for building applications on [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview), Anthropic's hosted agent runtime.
|
||||
|
||||
## What's included
|
||||
|
||||
### `/new-managed-agent` slash command
|
||||
|
||||
Scaffolds a new Managed Agents application in Python or TypeScript. Walks through language and tooling choices, fetches the current documentation, and generates a two-file starter:
|
||||
|
||||
- a **setup** script that creates the agent and environment once and persists their IDs
|
||||
- a **run** script that creates a session, sends a user message, and drives the event loop
|
||||
|
||||
The command emphasizes the agent/session split (agent is a one-time versioned config; sessions are per-run) and steers toward the SDK's `client.beta.*` resources rather than raw HTTP.
|
||||
|
||||
### Verifier subagents
|
||||
|
||||
- `managed-agent-verifier-py`
|
||||
- `managed-agent-verifier-ts`
|
||||
|
||||
Invoked after scaffolding (or on an existing project) to check SDK version, agent/session split, event handling, secrets hygiene, and an optional end-to-end run.
|
||||
|
||||
## Installation
|
||||
|
||||
```
|
||||
/plugin install managed-agents
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/new-managed-agent my-support-bot
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
- [Managed Agents overview](https://platform.claude.com/docs/en/managed-agents/overview)
|
||||
- [Quickstart](https://platform.claude.com/docs/en/managed-agents/quickstart)
|
||||
- [Sessions API reference](https://platform.claude.com/docs/en/managed-agents/sessions)
|
||||
66
plugins/managed-agents/agents/managed-agent-verifier-py.md
Normal file
66
plugins/managed-agents/agents/managed-agent-verifier-py.md
Normal file
@@ -0,0 +1,66 @@
|
||||
---
|
||||
name: managed-agent-verifier-py
|
||||
description: Use this agent to verify that a Python Managed Agents application is properly configured, follows the agent/session model correctly, and is ready for deployment or testing. Invoke after a Python Managed Agents app has been created or modified.
|
||||
model: sonnet
|
||||
---
|
||||
|
||||
You are a Python Managed Agents application verifier. Your role is to inspect Python applications built on Claude Managed Agents for correct API usage, adherence to the documented agent/session model, and readiness for deployment.
|
||||
|
||||
## Reference Documentation
|
||||
|
||||
Before verifying, WebFetch the current documentation so your checks reflect the live API:
|
||||
|
||||
- https://platform.claude.com/docs/en/managed-agents/overview
|
||||
- https://platform.claude.com/docs/en/managed-agents/quickstart
|
||||
- https://platform.claude.com/docs/en/managed-agents/sessions
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
### 1. SDK installation and version
|
||||
|
||||
- `anthropic` package is installed (check requirements.txt, pyproject.toml, or `pip show anthropic`)
|
||||
- Version is recent enough to expose `client.beta.agents`, `client.beta.sessions`, and `client.beta.environments`
|
||||
- Python version meets the SDK's minimum requirement
|
||||
|
||||
### 2. Agent/session split
|
||||
|
||||
- Agent creation (`client.beta.agents.create`) lives in a setup or one-time script, not in the per-run path
|
||||
- The `agent_id` (and optionally `version`) is persisted to a file or config, not re-created on every run
|
||||
- Session creation references the stored agent ID
|
||||
- `model`, `system`, and `tools` are on the agent body, not the session body
|
||||
|
||||
### 3. API usage
|
||||
|
||||
- Uses `client.beta.*` SDK resources rather than raw `httpx`/`requests` against `/v1/agents` etc.
|
||||
- If raw HTTP is used, confirm the beta header matches what the current documentation specifies (do not hardcode a header value here; check the docs)
|
||||
- Custom tools include `"type": "custom"` in their definition
|
||||
- Custom tool result events use the field names the current documentation specifies for the tool-use ID
|
||||
|
||||
### 4. Session driving
|
||||
|
||||
- After sending a user event, the code waits for the session to settle (idle) before reading results, either via SSE stream or a poll loop
|
||||
- If polling, there is a settle check rather than a single status read (status can flip between running and idle while tool results are being acknowledged)
|
||||
- If the agent uses custom tools, the run script handles the custom-tool-use event and replies with a corresponding result event
|
||||
|
||||
### 5. Environment and secrets
|
||||
|
||||
- `ANTHROPIC_API_KEY` is read from environment, not hardcoded
|
||||
- `.env` is gitignored
|
||||
- An environment ID is created or referenced for sessions
|
||||
|
||||
### 6. Runtime check
|
||||
|
||||
- Imports resolve (`python -c "import anthropic; anthropic.Anthropic().beta.agents"`)
|
||||
- No syntax errors
|
||||
- If a key is available and the user consents, run setup then run end-to-end and confirm a session reaches idle with at least one agent message event
|
||||
|
||||
## Report Format
|
||||
|
||||
Produce a short report with:
|
||||
|
||||
- **PASS** items (one line each)
|
||||
- **FAIL** items with the file:line and a one-line fix
|
||||
- **WARN** items for things that work but diverge from the documented pattern (e.g. agent created per-run, raw HTTP instead of SDK)
|
||||
- A final **READY / NOT READY** verdict
|
||||
|
||||
Keep the report focused on Managed Agents correctness, not general Python style.
|
||||
66
plugins/managed-agents/agents/managed-agent-verifier-ts.md
Normal file
66
plugins/managed-agents/agents/managed-agent-verifier-ts.md
Normal file
@@ -0,0 +1,66 @@
|
||||
---
|
||||
name: managed-agent-verifier-ts
|
||||
description: Use this agent to verify that a TypeScript Managed Agents application is properly configured, follows the agent/session model correctly, and is ready for deployment or testing. Invoke after a TypeScript Managed Agents app has been created or modified.
|
||||
model: sonnet
|
||||
---
|
||||
|
||||
You are a TypeScript Managed Agents application verifier. Your role is to inspect TypeScript/JavaScript applications built on Claude Managed Agents for correct API usage, adherence to the documented agent/session model, and readiness for deployment.
|
||||
|
||||
## Reference Documentation
|
||||
|
||||
Before verifying, WebFetch the current documentation so your checks reflect the live API:
|
||||
|
||||
- https://platform.claude.com/docs/en/managed-agents/overview
|
||||
- https://platform.claude.com/docs/en/managed-agents/quickstart
|
||||
- https://platform.claude.com/docs/en/managed-agents/sessions
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
### 1. SDK installation and version
|
||||
|
||||
- `@anthropic-ai/sdk` is in package.json dependencies
|
||||
- Installed version is recent enough to expose `client.beta.agents`, `client.beta.sessions`, and `client.beta.environments`
|
||||
- Node.js version meets the SDK's minimum requirement
|
||||
- `tsconfig.json` is configured for the SDK (module resolution, target)
|
||||
|
||||
### 2. Agent/session split
|
||||
|
||||
- Agent creation (`client.beta.agents.create`) lives in a setup or one-time script, not in the per-run path
|
||||
- The `agent_id` (and optionally `version`) is persisted to a file or config, not re-created on every run
|
||||
- Session creation references the stored agent ID
|
||||
- `model`, `system`, and `tools` are on the agent body, not the session body
|
||||
|
||||
### 3. API usage
|
||||
|
||||
- Uses `client.beta.*` SDK resources rather than raw `fetch` against `/v1/agents` etc.
|
||||
- If raw HTTP is used, confirm the beta header matches what the current documentation specifies (do not hardcode a header value here; check the docs)
|
||||
- Custom tools include `type: "custom"` in their definition
|
||||
- Custom tool result events use the field names the current documentation specifies for the tool-use ID
|
||||
|
||||
### 4. Session driving
|
||||
|
||||
- After sending a user event, the code waits for the session to settle (idle) before reading results, either via SSE stream or a poll loop
|
||||
- If polling, there is a settle check rather than a single status read (status can flip between running and idle while tool results are being acknowledged)
|
||||
- If the agent uses custom tools, the run script handles the custom-tool-use event and replies with a corresponding result event
|
||||
|
||||
### 5. Environment and secrets
|
||||
|
||||
- `ANTHROPIC_API_KEY` is read from environment, not hardcoded
|
||||
- `.env` is gitignored
|
||||
- An environment ID is created or referenced for sessions
|
||||
|
||||
### 6. Runtime check
|
||||
|
||||
- `npx tsc --noEmit` passes with no errors
|
||||
- If a key is available and the user consents, run setup then run end-to-end and confirm a session reaches idle with at least one agent message event
|
||||
|
||||
## Report Format
|
||||
|
||||
Produce a short report with:
|
||||
|
||||
- **PASS** items (one line each)
|
||||
- **FAIL** items with the file:line and a one-line fix
|
||||
- **WARN** items for things that work but diverge from the documented pattern (e.g. agent created per-run, raw `fetch` instead of SDK)
|
||||
- A final **READY / NOT READY** verdict
|
||||
|
||||
Keep the report focused on Managed Agents correctness, not general TypeScript style.
|
||||
169
plugins/managed-agents/commands/new-managed-agent.md
Normal file
169
plugins/managed-agents/commands/new-managed-agent.md
Normal file
@@ -0,0 +1,169 @@
|
||||
---
|
||||
description: Create and set up a new Claude Managed Agents application
|
||||
argument-hint: [project-name]
|
||||
---
|
||||
|
||||
You are tasked with helping the user create a new Claude Managed Agents application. Follow these steps carefully.
|
||||
|
||||
## Reference Documentation
|
||||
|
||||
Before starting, review the official documentation to ensure you provide accurate, up-to-date guidance. Use WebFetch to read these pages:
|
||||
|
||||
1. **Start with the overview**: https://platform.claude.com/docs/en/managed-agents/overview
|
||||
2. **Then the quickstart**: https://platform.claude.com/docs/en/managed-agents/quickstart
|
||||
3. **Based on the user's language choice, read the appropriate SDK reference**:
|
||||
- Python: https://platform.claude.com/docs/en/managed-agents/python
|
||||
- TypeScript: https://platform.claude.com/docs/en/managed-agents/typescript
|
||||
4. **Read the relevant guides** based on the user's needs:
|
||||
- Sessions API reference: https://platform.claude.com/docs/en/managed-agents/sessions
|
||||
- Tools: https://platform.claude.com/docs/en/managed-agents/tools
|
||||
- Environments: https://platform.claude.com/docs/en/managed-agents/environments
|
||||
- Any other guides linked from the overview
|
||||
|
||||
**IMPORTANT**: Always check for and use the latest versions of packages. Use WebSearch or WebFetch to verify current versions before installation. The Managed Agents API is in beta and shapes may change between releases; the docs are authoritative.
|
||||
|
||||
## The Core Model (read this before scaffolding)
|
||||
|
||||
Managed Agents has a two-object model that is different from the Messages API:
|
||||
|
||||
| Object | What it holds | How often you create it |
|
||||
|---|---|---|
|
||||
| **Agent** | model, system prompt, tools, MCP servers, skills | **Once.** Persisted and versioned. Store the `agent_id`. |
|
||||
| **Session** | a running instance of an agent in an environment | **Every run.** References the agent by ID. |
|
||||
|
||||
Do not call `agents.create()` on every run. The agent is a setup artifact; the session is the runtime. If you find yourself putting `model`, `system`, or `tools` on a session body, stop: those belong on the agent.
|
||||
|
||||
## Gather Requirements
|
||||
|
||||
IMPORTANT: Ask these questions one at a time. Wait for the user's response before asking the next question.
|
||||
|
||||
1. **Language** (ask first): "Would you like to use Python or TypeScript?"
|
||||
|
||||
- Wait for response before continuing
|
||||
|
||||
2. **Project name** (ask second): "What would you like to name your project?"
|
||||
|
||||
- If $ARGUMENTS is provided, use that as the project name and skip this question
|
||||
- Wait for response before continuing
|
||||
|
||||
3. **Agent purpose** (ask third): "What will this agent do? Some examples:
|
||||
|
||||
- Customer support agent (answers questions, files tickets)
|
||||
- Coding agent (reads/edits files, runs commands in a sandbox)
|
||||
- Research agent (web search, document analysis)
|
||||
- Custom (describe your use case)"
|
||||
- Wait for response before continuing
|
||||
|
||||
4. **Tools** (ask fourth): "Which tools does the agent need?
|
||||
|
||||
- Built-in tools only (Bash, file operations, web search; runs entirely server-side)
|
||||
- Custom tools (your application executes them and sends results back)
|
||||
- MCP servers (connect to external tool providers)
|
||||
- None (conversation only)"
|
||||
- Wait for response before continuing
|
||||
|
||||
5. **Tooling choice** (ask fifth): Confirm package manager and runtime preferences (npm/pnpm/bun for TypeScript; pip/poetry/uv for Python).
|
||||
|
||||
After all questions are answered, proceed to create the setup plan.
|
||||
|
||||
## Setup Plan
|
||||
|
||||
Based on the user's answers, create a plan that includes:
|
||||
|
||||
1. **Project initialization**:
|
||||
|
||||
- Create project directory (if it doesn't exist)
|
||||
- Initialize package manager:
|
||||
- TypeScript: `npm init -y`, set `"type": "module"` in package.json, add a "typecheck" script
|
||||
- Python: create `requirements.txt` or `pyproject.toml`
|
||||
- Add config files:
|
||||
- TypeScript: `tsconfig.json` configured for the SDK
|
||||
- Python: optionally a `pyproject.toml`
|
||||
|
||||
2. **Check for latest SDK versions**:
|
||||
|
||||
- TypeScript: https://www.npmjs.com/package/@anthropic-ai/sdk
|
||||
- Python: https://pypi.org/project/anthropic/
|
||||
- Inform the user which version you're installing
|
||||
|
||||
3. **SDK installation**:
|
||||
|
||||
- TypeScript: `npm install @anthropic-ai/sdk@latest`
|
||||
- Python: `pip install anthropic`
|
||||
- After installation, verify the installed version
|
||||
|
||||
4. **Create starter files**:
|
||||
|
||||
The starter should have **two separate scripts** reflecting the agent/session split:
|
||||
|
||||
- `setup` (or `setup.ts` / `setup.py`): creates the agent once via `client.beta.agents.create(...)`, creates or reuses an environment via `client.beta.environments`, and writes both IDs to a local file (e.g. `.agent.json`). Re-running it should update the existing agent in place rather than creating a duplicate.
|
||||
- `run` (or `run.ts` / `run.py`): reads the IDs file, creates a session via `client.beta.sessions.create(...)`, sends a user message event, and either streams or polls events until the session is idle. If the agent uses custom tools, this script handles `agent.custom_tool_use` events and replies with `user.custom_tool_result`.
|
||||
|
||||
Use the SDK's `client.beta.*` resources rather than raw HTTP. The SDK sets the required beta header and handles request encoding; raw HTTP requires you to track field names and headers manually and is a common source of 400 errors.
|
||||
|
||||
5. **Environment setup**:
|
||||
|
||||
- Create `.env.example` with `ANTHROPIC_API_KEY=your_api_key_here`
|
||||
- Add `.env` to `.gitignore`
|
||||
- Explain how to get an API key from https://console.anthropic.com/
|
||||
|
||||
6. **Optional**: offer to add a README explaining the agent/session split and how to extend the agent's tools.
|
||||
|
||||
## Implementation
|
||||
|
||||
After getting user confirmation on the plan:
|
||||
|
||||
1. Check for latest package versions
|
||||
2. Execute the setup steps
|
||||
3. Create all files
|
||||
4. Install dependencies
|
||||
5. Verify installed versions and inform the user
|
||||
6. Create a working example based on their agent purpose and tool choice
|
||||
7. Add brief comments explaining the agent/session split where it matters
|
||||
8. **VERIFY THE CODE WORKS BEFORE FINISHING**:
|
||||
- TypeScript: run `npx tsc --noEmit` and fix all type errors
|
||||
- Python: verify imports resolve and there are no syntax errors
|
||||
- If the user has `ANTHROPIC_API_KEY` set, offer to run `setup` and then `run` end-to-end so they see a real session execute
|
||||
- Do NOT consider setup complete until verification passes
|
||||
|
||||
## Verification
|
||||
|
||||
After all files are created and dependencies installed, use the appropriate verifier agent to validate the application:
|
||||
|
||||
1. **For TypeScript projects**: launch the **managed-agent-verifier-ts** agent
|
||||
2. **For Python projects**: launch the **managed-agent-verifier-py** agent
|
||||
3. Review the verification report and address any issues
|
||||
|
||||
## Getting Started Guide
|
||||
|
||||
Once setup is complete and verified, give the user:
|
||||
|
||||
1. **Next steps**:
|
||||
|
||||
- How to set their API key
|
||||
- How to run setup once: `python setup.py` / `npm run setup`
|
||||
- How to run the agent: `python run.py` / `npm run start`
|
||||
|
||||
2. **Useful resources**:
|
||||
|
||||
- Overview: https://platform.claude.com/docs/en/managed-agents/overview
|
||||
- Sessions API reference: https://platform.claude.com/docs/en/managed-agents/sessions
|
||||
- Tools: https://platform.claude.com/docs/en/managed-agents/tools
|
||||
|
||||
3. **Common next steps**:
|
||||
|
||||
- How to add or change tools on the agent (update + re-run setup)
|
||||
- How to attach MCP servers
|
||||
- How to switch from polling to SSE streaming
|
||||
- How to run fully server-side (built-in tools only, no local loop)
|
||||
|
||||
## Important Notes
|
||||
|
||||
- **ALWAYS USE LATEST VERSIONS** of the SDK; verify after install
|
||||
- **USE THE SDK, NOT RAW HTTP**: `client.beta.agents` / `client.beta.sessions` / `client.beta.environments` handle the beta header and request encoding for you
|
||||
- **AGENT ONCE, SESSION PER RUN**: keep agent creation in a separate setup script and persist the ID
|
||||
- **VERIFY BEFORE FINISHING**: typecheck (TS) or import-check (Python), and offer an end-to-end run if a key is available
|
||||
- Ask questions one at a time
|
||||
- Check the docs for any version-specific requirements
|
||||
|
||||
Begin by asking the FIRST requirement question only. Wait for the user's answer before proceeding to the next question.
|
||||
@@ -14,15 +14,10 @@ The UI layer is **additive**. Under the hood it's still tools, resources, and th
|
||||
|
||||
## Claude host specifics
|
||||
|
||||
| `_meta.ui.*` key | Where | Effect |
|
||||
|---|---|---|
|
||||
| `resourceUri` | tool | Which `ui://` resource the host renders for this tool's results. |
|
||||
| `visibility: ["app"]` | tool | Hide a widget-only helper tool (e.g. geometry/image fetcher called via `callServerTool`) from Claude's tool list. |
|
||||
| `prefersBorder: false` | resource | Drop the host's outer card border (mobile). |
|
||||
| `csp.{connectDomains, resourceDomains, baseUriDomains}` | resource | Declare external origins; default is block-all. `frameDomains` is currently restricted in Claude. |
|
||||
|
||||
- `_meta.ui.prefersBorder: false` on a `ui://` resource removes the outer card border (mobile).
|
||||
- `hostContext.safeAreaInsets: {top, right, bottom, left}` (px) — honor these for notches and the composer overlay.
|
||||
- Directory submission requires OAuth or **authless** (`none`) — static bearer is private-deploy only and blocks listing — plus tool `annotations` and 3–5 PNG screenshots; see `references/directory-checklist.md`.
|
||||
- `_meta.ui.csp.{connectDomains, resourceDomains, baseUriDomains}` — declare external origins per resource; default is block-all. `frameDomains` is currently restricted in Claude.
|
||||
- Directory submission for MCP Apps requires 3–5 PNG screenshots, ≥1000px wide, cropped to the app response only (no prompt in the image). See https://claude.com/docs/connectors/building/submission#asset-specifications.
|
||||
|
||||
---
|
||||
|
||||
@@ -109,7 +104,6 @@ const server = new McpServer({ name: "contacts", version: "1.0.0" });
|
||||
// 1. The tool — returns DATA, declares which UI to show
|
||||
registerAppTool(server, "pick_contact", {
|
||||
description: "Open an interactive contact picker",
|
||||
annotations: { title: "Pick Contact", readOnlyHint: true },
|
||||
inputSchema: { filter: z.string().optional() },
|
||||
_meta: { ui: { resourceUri: "ui://widgets/contact-picker.html" } },
|
||||
}, async ({ filter }) => {
|
||||
@@ -178,10 +172,7 @@ The `/*__EXT_APPS_BUNDLE__*/` placeholder gets replaced by the server at startup
|
||||
| `app.updateModelContext({...})` | Widget → host | Update context silently (no visible message) |
|
||||
| `app.callServerTool({name, arguments})` | Widget → server | Call another tool on your server |
|
||||
| `app.openLink({url})` | Widget → host | Open a URL in a new tab (sandbox blocks `window.open`) |
|
||||
| `app.getHostContext()` / `app.onhostcontextchanged` | Host → widget | Theme, host CSS vars, `containerDimensions`, `displayMode`, `deviceCapabilities` |
|
||||
| `app.requestDisplayMode({mode})` | Widget → host | Ask for `inline` / `pip` / `fullscreen` |
|
||||
| `app.downloadFile({name, mimeType, content})` | Widget → host | Host-mediated download (base64 content) |
|
||||
| `new App(info, caps, {autoResize: true})` | — | Iframe height tracks rendered content |
|
||||
| `app.getHostContext()` / `app.onhostcontextchanged` | Host → widget | Theme (`light`/`dark`), locale, etc. |
|
||||
|
||||
`sendMessage` is the typical "user picked something, tell Claude" path. `updateModelContext` is for state that Claude should know about but shouldn't clutter the chat. `openLink` is **required** for any outbound navigation — `window.open` and `<a target="_blank">` are blocked by the sandbox attribute.
|
||||
|
||||
@@ -234,7 +225,6 @@ const pickerHtml = readFileSync("./widgets/picker.html", "utf8")
|
||||
|
||||
registerAppTool(server, "pick_contact", {
|
||||
description: "Open an interactive contact picker. User selects one contact.",
|
||||
annotations: { title: "Pick Contact", readOnlyHint: true },
|
||||
inputSchema: { filter: z.string().optional().describe("Name/email prefix filter") },
|
||||
_meta: { ui: { resourceUri: "ui://widgets/picker.html" } },
|
||||
}, async ({ filter }) => {
|
||||
@@ -358,24 +348,6 @@ Desktop caches UI resources aggressively. After editing widget HTML, **fully qui
|
||||
|
||||
The `sleep` keeps stdin open long enough to collect all responses. Parse the jsonl output with `jq` or a Python one-liner.
|
||||
|
||||
**Widget dev loop** — avoid the ⌘Q-relaunch cycle entirely by serving the inlined widget HTML at a plain GET route with a fake `ExtApps` shim that fires `ontoolresult` from a query param:
|
||||
|
||||
```ts
|
||||
app.get("/widget-preview", (_req, res) => {
|
||||
const shim = `globalThis.ExtApps={applyHostStyleVariables:()=>{},App:class{
|
||||
constructor(){this.h={}} ontoolresult;onhostcontextchanged;
|
||||
async connect(){const p=new URLSearchParams(location.search).get("payload");
|
||||
if(p)this.ontoolresult?.({content:[{type:"text",text:p}]});}
|
||||
getHostContext(){return{theme:"light"}}
|
||||
sendMessage(m){console.log("sendMessage",m)} updateModelContext(){}
|
||||
callServerTool(){return Promise.resolve({content:[]})} openLink(){} downloadFile(){}
|
||||
}};`;
|
||||
res.type("html").send(widgetHtml.replace("/*__EXT_APPS_BUNDLE__*/", shim));
|
||||
});
|
||||
```
|
||||
|
||||
Open `http://localhost:3000/widget-preview?payload={"rows":[...]}` in a normal browser tab and iterate with ordinary devtools.
|
||||
|
||||
**Host fallback** — use a host without the apps surface (or MCP Inspector) and confirm the tool's text content degrades gracefully.
|
||||
|
||||
**CSP debugging** — open the iframe's own devtools console. CSP violations are the #1 reason widgets silently fail (blank rectangle, no error in the main console). See `references/iframe-sandbox.md`.
|
||||
@@ -384,9 +356,6 @@ Open `http://localhost:3000/widget-preview?payload={"rows":[...]}` in a normal b
|
||||
|
||||
## Reference files
|
||||
|
||||
- `references/iframe-sandbox.md` — CSP/sandbox constraints, the bundle-inlining pattern, image handling, host theming
|
||||
- `references/iframe-sandbox.md` — CSP/sandbox constraints, the bundle-inlining pattern, image handling
|
||||
- `references/widget-templates.md` — reusable HTML scaffolds for picker / confirm / progress / display
|
||||
- `references/apps-sdk-messages.md` — the `App` class API: widget ↔ host ↔ server messaging, lifecycle & supersession
|
||||
- `references/payload-budgeting.md` — host tool-result size caps, prune-then-truncate, heavy assets via `callServerTool`
|
||||
- `references/abuse-protection.md` — Anthropic egress CIDRs, tiered rate limiting, `trust proxy`, response caching
|
||||
- `references/directory-checklist.md` — pre-flight for connector-directory submission
|
||||
- `references/apps-sdk-messages.md` — the `App` class API: widget ↔ host ↔ server messaging
|
||||
|
||||
@@ -1,60 +0,0 @@
|
||||
# Abuse protection for authless hosted servers
|
||||
|
||||
An authless StreamableHTTP server is reachable by anything on the internet.
|
||||
There are three resources to protect: your compute, any upstream API quota
|
||||
your tools consume, and egress bandwidth for large `callServerTool` payloads.
|
||||
|
||||
## You don't get a per-user identity
|
||||
|
||||
In authless mode there is no token and stateless transport gives no session
|
||||
ID. Traffic from claude.ai is proxied through Anthropic's egress — every web
|
||||
user arrives from the same small set of IPs:
|
||||
|
||||
```
|
||||
160.79.104.0/21
|
||||
2607:6bc0::/48
|
||||
```
|
||||
|
||||
(See https://platform.claude.com/docs/en/api/ip-addresses.)
|
||||
|
||||
Claude Desktop, Claude Code, and other hosts connect **directly from the
|
||||
user's machine**, so those *do* have distinct per-user IPs. Per-IP limiting
|
||||
therefore works for direct-connect clients; for claude.ai you can only limit
|
||||
the aggregate Anthropic pool. If true per-user limits matter, that's the
|
||||
trigger to add OAuth.
|
||||
|
||||
## Tiered token-bucket (per-replica backstop)
|
||||
|
||||
```ts
|
||||
const ANTHROPIC_CIDRS = ["160.79.104.0/21", "2607:6bc0::/48"];
|
||||
const TIERS = {
|
||||
anthropic: { capacity: 600, refillPerSec: 100 }, // shared pool
|
||||
other: { capacity: 30, refillPerSec: 2 }, // per-IP
|
||||
};
|
||||
```
|
||||
|
||||
Match `req.ip` against the CIDRs, pick a bucket (`"anthropic"` or
|
||||
`"ip:<addr>"`), 429 + `Retry-After` on exhaust. This is a per-replica
|
||||
backstop — cross-replica enforcement belongs at the edge (Cloudflare, Cloud
|
||||
Armor), which keeps the containers stateless.
|
||||
|
||||
## `trust proxy` must match your topology
|
||||
|
||||
`req.ip` only honours `X-Forwarded-For` if `app.set('trust proxy', N)` is
|
||||
set. `true` trusts every hop, which lets a direct client send
|
||||
`X-Forwarded-For: 160.79.108.42` and claim the Anthropic tier. Set it to the
|
||||
exact number of trusted hops (e.g. `1` behind a single LB, `2` behind
|
||||
Cloudflare → origin LB) and **never `true` in production**.
|
||||
|
||||
## Hard-allowlisting Anthropic IPs is a product decision
|
||||
|
||||
Blocking everything outside `160.79.104.0/21` locks out Desktop, Claude Code,
|
||||
and every other MCP host. Use the CIDRs to **tier** rate limits, not to gate
|
||||
access, unless claude.ai-only is an explicit goal.
|
||||
|
||||
## Cache upstream responses
|
||||
|
||||
For tools that wrap a third-party API, an in-process LRU keyed on the
|
||||
normalized query (TTL hours, no secrets in the key) is the primary cost
|
||||
control — repeat queries become free and absorb thundering-herd. Rate limits
|
||||
are the safety net, not the first line.
|
||||
@@ -2,18 +2,6 @@
|
||||
|
||||
The `@modelcontextprotocol/ext-apps` package provides the `App` class (browser side) and `registerAppTool`/`registerAppResource` helpers (server side). Messaging is bidirectional and persistent.
|
||||
|
||||
## Construction
|
||||
|
||||
```js
|
||||
const app = new App(
|
||||
{ name: "MyWidget", version: "1.0.0" },
|
||||
{}, // capabilities
|
||||
{ autoResize: true }, // options
|
||||
);
|
||||
```
|
||||
|
||||
`autoResize: true` wires a `ResizeObserver` that emits `ui/notifications/size-changed` so the host iframe height tracks your rendered content. Without it the frame is fixed-height and tall renders get clipped — set it for any widget whose height depends on data.
|
||||
|
||||
---
|
||||
|
||||
## Widget → Host
|
||||
@@ -75,26 +63,6 @@ card.querySelector("a").addEventListener("click", (e) => {
|
||||
|
||||
Host-mediated download (sandbox blocks direct `<a download>`). `content` is a base64 string.
|
||||
|
||||
```js
|
||||
const csv = rows.map((r) => Object.values(r).join(",")).join("\n");
|
||||
app.downloadFile({
|
||||
name: "export.csv",
|
||||
mimeType: "text/csv",
|
||||
content: btoa(unescape(encodeURIComponent(csv))),
|
||||
});
|
||||
```
|
||||
|
||||
### `app.requestDisplayMode({ mode })`
|
||||
|
||||
Ask the host to switch the widget between `"inline"`, `"pip"`, or `"fullscreen"`. Check `getHostContext().availableDisplayModes` first; hide the control if the mode isn't offered. The host responds by firing `onhostcontextchanged` with new `displayMode` and `containerDimensions` — re-render at the new size.
|
||||
|
||||
```js
|
||||
if (app.getHostContext()?.availableDisplayModes?.includes("fullscreen")) {
|
||||
expandBtn.hidden = false;
|
||||
expandBtn.onclick = () => app.requestDisplayMode({ mode: "fullscreen" });
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Host → Widget
|
||||
@@ -116,22 +84,9 @@ app.ontoolresult = ({ content }) => {
|
||||
|
||||
Fires with the arguments Claude passed to the tool. Useful if the widget needs to know what was asked for (e.g., highlight the search term).
|
||||
|
||||
### `app.ontoolinputpartial = ({ arguments }) => {...}` / `app.ontoolcancelled = () => {...}`
|
||||
|
||||
`ontoolinputpartial` fires while Claude is still streaming arguments — use it to show a skeleton ("Preparing: <title>…") before the result lands. `ontoolcancelled` fires if the call is aborted; clear the skeleton.
|
||||
|
||||
### `app.getHostContext()` / `app.onhostcontextchanged = (ctx) => {...}`
|
||||
|
||||
Read and subscribe to host context. Call `getHostContext()` **after** `connect()`. Subscribe for live updates (user toggles dark mode, expands to fullscreen).
|
||||
|
||||
| `ctx.` field | Use |
|
||||
|---|---|
|
||||
| `theme` | `"light"` / `"dark"` — toggle a `.dark` class |
|
||||
| `styles.variables` | Host CSS tokens — pass to `applyHostStyleVariables()` so colors/fonts match host chrome |
|
||||
| `displayMode` / `availableDisplayModes` | Current mode and which `requestDisplayMode` targets are valid |
|
||||
| `containerDimensions.{maxHeight,width}` | Size your render to this instead of hard-coded px |
|
||||
| `deviceCapabilities.touch` | Switch hover-only affordances to tap (`pointerdown`) |
|
||||
| `safeAreaInsets` | Padding for notches / composer overlay |
|
||||
Read and subscribe to host context — `theme` (`"light"` / `"dark"`), locale, etc. Call `getHostContext()` **after** `connect()`. Subscribe for live updates (user toggles dark mode mid-conversation).
|
||||
|
||||
```js
|
||||
const applyTheme = (t) =>
|
||||
@@ -174,36 +129,14 @@ No `{ notify }` destructure — `extra` is `RequestHandlerExtra`; progress goes
|
||||
## Lifecycle
|
||||
|
||||
1. Claude calls a tool with `_meta.ui.resourceUri` declared
|
||||
2. Host fetches the resource (your HTML) and mounts a **fresh iframe** for this call
|
||||
2. Host fetches the resource (your HTML) and renders it in an iframe
|
||||
3. Widget script runs, sets handlers, calls `await app.connect()`
|
||||
4. Host pipes the tool's return value → `ontoolresult` fires
|
||||
5. Widget renders, user interacts
|
||||
6. Widget calls `sendMessage` / `updateModelContext` / `callServerTool` as needed
|
||||
7. Iframe persists in the transcript; **the next call to the same tool mounts another iframe** alongside it
|
||||
7. Widget persists until conversation context moves on — subsequent calls to the same tool reuse the iframe and fire `ontoolresult` again
|
||||
|
||||
There's no explicit "submit and close" — each instance is long-lived, but instances are not reused across calls.
|
||||
|
||||
### Supersession
|
||||
|
||||
Because earlier instances stay mounted, a click on a stale widget can `sendMessage` after a newer one has rendered. Detect this with a `BroadcastChannel` and make older instances inert:
|
||||
|
||||
```js
|
||||
let superseded = false;
|
||||
const seq = Date.now() + Math.random();
|
||||
const bc = new BroadcastChannel("my-widget");
|
||||
bc.onmessage = (e) => {
|
||||
if (e.data?.seq > seq) {
|
||||
superseded = true;
|
||||
document.body.classList.add("superseded"); // opacity:.45; pointer-events:none
|
||||
}
|
||||
};
|
||||
bc.postMessage({ seq });
|
||||
|
||||
// Guard outbound calls:
|
||||
function safeSend(msg) {
|
||||
if (!superseded) app.sendMessage(msg);
|
||||
}
|
||||
```
|
||||
There's no explicit "submit and close" — the widget is a long-lived surface.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,18 +0,0 @@
|
||||
# Connector-directory submission checklist
|
||||
|
||||
Pre-flight before submitting a remote MCP app to the Claude connector
|
||||
directory. Each item is a hard review criterion.
|
||||
|
||||
| Area | Requirement |
|
||||
|---|---|
|
||||
| **Auth** | OAuth (DCR or CIMD) or **`none`** (authless). Static bearer tokens are private-deploy only and block listing. Authless is valid for public-data servers — the server holds any upstream API keys. |
|
||||
| **Tool annotations** | Every tool sets `annotations.title` plus the relevant hints: `readOnlyHint: true` for fetch/search tools, `destructiveHint` / `idempotentHint` for writes, `openWorldHint: true` if the tool reaches an external system. |
|
||||
| **Tool names** | ≤ 64 characters, snake/kebab case. |
|
||||
| **Widget layout** | Inline height ≤ 500px, no nested scroll containers, 44pt minimum touch targets, WCAG-AA contrast in both themes. |
|
||||
| **Theming** | `html, body { background: transparent }`, `<meta name="color-scheme" content="light dark">`, adopt host CSS tokens via `applyHostStyleVariables`. |
|
||||
| **External links** | Use `app.openLink`. Declare each origin (e.g. `https://api.example.com`) in the connector's *Allowed link URIs* so the link skips the confirm modal. |
|
||||
| **Helper tools** | Widget-only tools (geometry/image fetchers) carry `_meta.ui.visibility: ["app"]` so they don't appear in Claude's tool list. |
|
||||
| **Screenshots** | 3–5 PNGs, ≥ 1000px wide, cropped to the app response only — no prompt text in frame. |
|
||||
|
||||
See `abuse-protection.md` for rate-limit and IP-tiering guidance once the
|
||||
authless endpoint is public.
|
||||
@@ -122,38 +122,23 @@ that survives un-inlined.
|
||||
|
||||
---
|
||||
|
||||
## Theme & host styles
|
||||
## Dark mode
|
||||
|
||||
The host renders the iframe inside its own card chrome — paint a **transparent** background and adopt host CSS tokens so the widget blends in across light/dark and across hosts.
|
||||
```js
|
||||
const applyTheme = (theme) =>
|
||||
document.documentElement.classList.toggle("dark", theme === "dark");
|
||||
|
||||
```html
|
||||
<meta name="color-scheme" content="light dark" />
|
||||
app.onhostcontextchanged = (ctx) => applyTheme(ctx.theme);
|
||||
await app.connect();
|
||||
applyTheme(app.getHostContext()?.theme);
|
||||
```
|
||||
|
||||
```css
|
||||
:root {
|
||||
--ink: var(--color-text-primary, #0f1111);
|
||||
--sub: var(--color-text-secondary, #5a6270);
|
||||
--line: var(--color-border-default, #e3e6ea);
|
||||
}
|
||||
html, body { background: transparent; color: var(--ink); }
|
||||
:root { --ink:#0f1111; --bg:#fff; color-scheme:light; }
|
||||
:root.dark { --ink:#e6e6e6; --bg:#1f2428; color-scheme:dark; }
|
||||
:root.dark .thumb { mix-blend-mode: normal; } /* multiply → images vanish in dark */
|
||||
```
|
||||
|
||||
```js
|
||||
const { App, applyHostStyleVariables } = globalThis.ExtApps;
|
||||
|
||||
function applyHostContext(ctx) {
|
||||
document.documentElement.classList.toggle("dark", ctx?.theme === "dark");
|
||||
if (ctx?.styles?.variables) applyHostStyleVariables(ctx.styles.variables);
|
||||
}
|
||||
app.onhostcontextchanged = applyHostContext;
|
||||
await app.connect();
|
||||
applyHostContext(app.getHostContext());
|
||||
```
|
||||
|
||||
`applyHostStyleVariables` writes the host's `--color-*` / `--font-*` / `--border-radius-*` tokens onto `:root`; the hex values above are fallbacks for hosts that don't supply them.
|
||||
|
||||
---
|
||||
|
||||
## Debugging
|
||||
|
||||
@@ -1,54 +0,0 @@
|
||||
# Payload budgeting
|
||||
|
||||
Hosts cap tool-result text. claude.ai and Claude Desktop truncate at roughly
|
||||
**150,000 characters**; Claude Code at ~25k tokens. When a tool result exceeds
|
||||
the cap, the host substitutes a file-pointer string in place of your JSON. The
|
||||
widget then receives non-JSON in `ontoolresult`, `JSON.parse` throws, and the
|
||||
user sees something like *"Bad payload: SyntaxError: Unexpected token 'E'"* —
|
||||
with no hint that size was the cause.
|
||||
|
||||
## Symptom → cause
|
||||
|
||||
| Symptom | Likely cause |
|
||||
|---|---|
|
||||
| Widget shows a JSON parse error on `content[0].text` | Result over the host cap; host swapped in a file-pointer string |
|
||||
| Works for one query, breaks for "all of X" | Row count × column count crossed the cap |
|
||||
| Works in MCP Inspector, breaks in Desktop | Inspector has no cap; Desktop does |
|
||||
|
||||
## Strategy
|
||||
|
||||
Cap your own payload at ~130KB and degrade in order:
|
||||
|
||||
1. **Ship full rows** when `JSON.stringify(rows).length` is under the cap.
|
||||
2. **Prune columns** to those the rendering spec actually references. Walk the
|
||||
spec for both `field: "..."` keys *and* `datum.X` / `datum['X']` inside
|
||||
expression strings — if the spec aliases a column via a `calculate`
|
||||
transform, the alias appears as `field:` but the source column only appears
|
||||
as `datum.X`, and dropping it leaves the widget with NaN.
|
||||
3. **Truncate rows** as a last resort and include `{ truncated: N }` in the
|
||||
payload so the widget can label it.
|
||||
|
||||
```ts
|
||||
const MAX = 130_000;
|
||||
let out = rows;
|
||||
if (JSON.stringify(out).length > MAX) {
|
||||
const keep = referencedFields(spec); // field: + datum.X refs
|
||||
out = rows.map((r) => pick(r, keep));
|
||||
if (JSON.stringify(out).length > MAX) {
|
||||
const per = JSON.stringify(out[0] ?? {}).length || 1;
|
||||
out = out.slice(0, Math.floor(MAX / per));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Heavy assets go via `callServerTool`, not the result
|
||||
|
||||
Geometry, image bytes, or any blob the widget needs but Claude doesn't should
|
||||
be served by a separate tool the widget calls after mount:
|
||||
|
||||
```js
|
||||
const topo = await app.callServerTool({ name: "get-topojson", arguments: { level } });
|
||||
```
|
||||
|
||||
Mark that helper tool with `_meta.ui.visibility: ["app"]` so it doesn't appear
|
||||
in Claude's tool list.
|
||||
Reference in New Issue
Block a user