From 2ebeec376784102cb428ea89ae5b82070d9ba075 Mon Sep 17 00:00:00 2001 From: Simon KP Date: Thu, 26 Mar 2026 01:12:15 +1100 Subject: [PATCH] chore: prepare plugin for official Anthropic marketplace submission - Reframe all descriptions to comply with Anthropic Software Directory Policy (remove financial transaction language, use monitoring/automation framing) - Add SECURITY.md with vulnerability reporting and security practices - Add CHANGELOG.md with version history (Keep a Changelog format) - Add CONTRIBUTING.md with contribution guidelines - Add CLAUDE.md at plugin root for Claude context - Add .gitignore for standard ignore patterns - Add CI validation workflow for plugin structure and JSON syntax - Add author contact info (email, url) to plugin.json and marketplace.json - Update keywords (blockchain -> smart-contracts) - Fix LICENSE copyright year to 2025-2026 - Update example use cases to use generic automation language --- .claude-plugin/marketplace.json | 8 +- .github/workflows/validate-plugin.yml | 89 +++++++++++++++++++ .gitignore | 5 ++ CHANGELOG.md | 33 +++++++ CONTRIBUTING.md | 46 ++++++++++ LICENSE | 2 +- README.md | 8 +- SECURITY.md | 40 +++++++++ plugins/keeperhub/.claude-plugin/plugin.json | 6 +- plugins/keeperhub/CLAUDE.md | 21 +++++ plugins/keeperhub/README.md | 4 +- plugins/keeperhub/commands/login.md | 2 +- .../keeperhub/skills/plugin-explorer/SKILL.md | 6 +- .../skills/template-browser/SKILL.md | 2 +- .../skills/workflow-builder/SKILL.md | 6 +- 15 files changed, 256 insertions(+), 22 deletions(-) create mode 100644 .github/workflows/validate-plugin.yml create mode 100644 .gitignore create mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md create mode 100644 plugins/keeperhub/CLAUDE.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 0355237..3b5042a 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -13,10 +13,12 @@ { "name": "keeperhub", "source": "./plugins/keeperhub", - "description": "Manage KeeperHub workflows, execute automations, and browse templates from Claude Code. Connects to KeeperHub's remote MCP server with OAuth browser authentication.", + "description": "Build and manage automation workflows from Claude Code. Monitor smart contracts, track on-chain events, configure scheduled tasks, and connect notifications across Discord, Telegram, email, and webhooks. Connects to KeeperHub's remote MCP server with OAuth browser authentication.", "version": "3.0.0", "author": { - "name": "KeeperHub" + "name": "KeeperHub", + "email": "support@keeperhub.com", + "url": "https://keeperhub.com" }, "homepage": "https://app.keeperhub.com", "repository": "https://github.com/KeeperHub/claude-plugins", @@ -26,7 +28,7 @@ "workflow", "automation", "web3", - "blockchain", + "smart-contracts", "mcp" ], "category": "automation" diff --git a/.github/workflows/validate-plugin.yml b/.github/workflows/validate-plugin.yml new file mode 100644 index 0000000..9cfb481 --- /dev/null +++ b/.github/workflows/validate-plugin.yml @@ -0,0 +1,89 @@ +name: Validate Plugin Structure + +on: + pull_request: + branches: [main] + push: + branches: [main] + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Validate JSON syntax + run: | + echo "Validating JSON files..." + errors=0 + for f in $(find . -name "*.json" -not -path "./node_modules/*"); do + if ! jq empty "$f" 2>/dev/null; then + echo "Invalid JSON: $f" + errors=$((errors + 1)) + fi + done + if [ "$errors" -gt 0 ]; then + echo "$errors JSON file(s) have syntax errors" + exit 1 + fi + echo "All JSON files valid" + + - name: Validate plugin structure + run: | + echo "Checking required files..." + errors=0 + + for plugin_dir in plugins/*/; do + name=$(basename "$plugin_dir") + echo "Validating plugin: $name" + + # Check required manifest + if [ ! -f "$plugin_dir/.claude-plugin/plugin.json" ]; then + echo " Missing: .claude-plugin/plugin.json" + errors=$((errors + 1)) + else + # Validate name field exists + plugin_name=$(jq -r '.name // empty' "$plugin_dir/.claude-plugin/plugin.json") + if [ -z "$plugin_name" ]; then + echo " Missing 'name' field in plugin.json" + errors=$((errors + 1)) + fi + fi + + # Check recommended files + [ ! -f "$plugin_dir/README.md" ] && echo " Warning: Missing README.md" + done + + # Check marketplace manifest + if [ ! -f ".claude-plugin/marketplace.json" ]; then + echo "Missing: .claude-plugin/marketplace.json" + errors=$((errors + 1)) + fi + + # Check repo-level files + [ ! -f "LICENSE" ] && echo "Warning: Missing LICENSE" + [ ! -f "README.md" ] && echo "Warning: Missing README.md" + [ ! -f "SECURITY.md" ] && echo "Warning: Missing SECURITY.md" + + if [ "$errors" -gt 0 ]; then + echo "$errors validation error(s) found" + exit 1 + fi + echo "All validations passed" + + - name: Check MCP endpoint reachability + run: | + for plugin_dir in plugins/*/; do + if [ -f "$plugin_dir/.mcp.json" ]; then + urls=$(jq -r '.. | .url? // empty' "$plugin_dir/.mcp.json" 2>/dev/null) + for url in $urls; do + echo "Checking: $url" + status=$(curl -sf -o /dev/null -w "%{http_code}" --max-time 10 "$url" 2>/dev/null || echo "000") + if [ "$status" = "000" ]; then + echo " Warning: $url is unreachable (may require auth)" + else + echo " Reachable (HTTP $status)" + fi + done + fi + done diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c79b2e4 --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +node_modules/ +.DS_Store +*.log +.env +.env.local diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..390cdd5 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,33 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [3.0.0] - 2026-03-25 + +### Added +- Remote HTTP MCP server connection (app.keeperhub.com/mcp) +- OAuth 2.0 browser-based authentication +- API key fallback for headless/CI environments +- 4 auto-invoked skills: workflow-builder, template-browser, execution-monitor, plugin-explorer +- 2 slash commands: /keeperhub:login, /keeperhub:status +- Marketplace configuration for self-hosted distribution +- CI workflow for automated marketplace registry sync + +### Changed +- Migrated from local CLI (`kh serve --mcp`) to remote HTTP MCP endpoint +- Simplified installation to single marketplace add + plugin install + +## [2.0.0] - 2026-03-01 + +### Changed +- Restructured as Claude Code plugin (from standalone MCP config) +- Added skill-based architecture with trigger routing + +## [1.0.0] - 2026-02-15 + +### Added +- Initial release as Claude Code plugin +- Basic workflow management commands diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e7b1fd7 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,46 @@ +# Contributing to KeeperHub Claude Plugins + +Thank you for your interest in contributing. This guide covers the basics. + +## Reporting Bugs + +Open a GitHub Issue with: + +- A clear, descriptive title +- Steps to reproduce the problem +- Expected vs. actual behavior +- Your environment (OS, Claude Code version) + +## Suggesting Features + +Open a GitHub Issue with the `enhancement` label. Describe the use case and why it would be valuable. + +## Submitting Pull Requests + +1. Fork the repository +2. Create a feature branch from `main` (`git checkout -b feature/your-change`) +3. Make your changes +4. Test thoroughly +5. Commit with a clear message describing the change +6. Push to your fork and open a PR against `main` + +### PR Guidelines + +- Keep changes focused and minimal +- Update documentation if your change affects usage +- Ensure any new files follow existing conventions +- One logical change per PR + +## Code Style + +- No emojis in code, comments, or documentation +- Follow existing file structure and naming conventions +- Keep plugin definitions as JSON/Markdown only (no executable code) + +## Code of Conduct + +All participants are expected to treat others with respect and professionalism. Harassment, discrimination, and disruptive behavior will not be tolerated. See the project maintainers if you have concerns. + +## Questions + +If you have questions about contributing, open a GitHub Issue or reach out at support@keeperhub.com. diff --git a/LICENSE b/LICENSE index ad0de5c..514beaa 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2025 KeeperHub +Copyright (c) 2025-2026 KeeperHub Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 4e88250..fd677a6 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Claude Code plugin marketplace by KeeperHub. ### keeperhub -Build and manage Web3 automation workflows from Claude Code. Create workflows that monitor smart contracts, execute DeFi operations, transfer tokens, and send notifications across Discord, Telegram, email, and webhooks. Connects to KeeperHub's remote MCP server with OAuth browser authentication. Includes 4 skills and 2 slash commands. +Build and manage automation workflows from Claude Code. Create workflows that monitor smart contracts, track on-chain events, run scheduled tasks, and send notifications across Discord, Telegram, email, and webhooks. Connects to KeeperHub's remote MCP server with OAuth browser authentication. Includes 4 skills and 2 slash commands. ``` /plugin install keeperhub@keeperhub-plugins @@ -31,8 +31,8 @@ After install, run `/mcp` in Claude Code and authorize the keeperhub server via - **plugin-explorer** -- discover available plugins and integrations **Example use cases:** -- "Create a workflow that monitors my Aave health factor every 15 minutes and sends a Telegram alert if it drops below 1.5" -- "Show me available workflow templates for wallet monitoring" +- "Create a workflow that monitors a smart contract event every 15 minutes and sends a Telegram alert when a specific condition is met" +- "Show me available workflow templates for on-chain event monitoring" - "Why did my last workflow execution fail? Show me the logs" - "What KeeperHub plugins and integrations are available?" -- "Set up an automation that checks ETH price hourly and sends a Discord notification when it crosses $3000" +- "Set up an automation that runs a scheduled check hourly and sends a Discord notification when a threshold is crossed" diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..3769700 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,40 @@ +# Security Policy + +## Reporting Vulnerabilities + +If you discover a security vulnerability in this project, please report it responsibly. + +- **Email**: security@keeperhub.com +- **Expected response time**: 48 hours +- **Do not** open public GitHub issues for security vulnerabilities. + +Please include a description of the vulnerability, steps to reproduce, and any relevant context. + +## Supported Versions + +| Version | Supported | +| ------- | ------------------ | +| 3.0.x | Yes | +| < 3.0 | No | + +## Security Practices + +- **HTTPS only**: All communication with the remote MCP server uses HTTPS with TLS 1.2 or higher. +- **OAuth 2.0 authentication**: The plugin uses browser-based OAuth 2.0 flows. No credentials are stored in the plugin configuration files. +- **No hardcoded secrets**: API keys and tokens are provided exclusively via environment variables. They are never committed to the repository. +- **No executable code**: This plugin consists entirely of markdown and JSON configuration files. There is no executable code to audit or exploit. +- **Server-side reviews**: The remote MCP server at `app.keeperhub.com` undergoes regular security reviews and penetration testing. + +## Scope + +### In scope + +- Plugin configuration files in this repository (markdown and JSON) +- Behavior of the MCP endpoint at `app.keeperhub.com/mcp` +- OAuth flow and token handling between Claude and the MCP server + +### Out of scope + +- The KeeperHub web application itself (report separately at security@keeperhub.com) +- Third-party dependencies or services not maintained by KeeperHub +- Claude Desktop or Claude Code client vulnerabilities (report to Anthropic) diff --git a/plugins/keeperhub/.claude-plugin/plugin.json b/plugins/keeperhub/.claude-plugin/plugin.json index a50f463..1795958 100644 --- a/plugins/keeperhub/.claude-plugin/plugin.json +++ b/plugins/keeperhub/.claude-plugin/plugin.json @@ -1,10 +1,10 @@ { "name": "keeperhub", - "description": "Manage KeeperHub workflows, execute automations, and browse templates from Claude Code. Connects to KeeperHub's remote MCP server with OAuth browser authentication.", + "description": "Build and manage automation workflows from Claude Code. Monitor smart contracts, track on-chain events, configure scheduled tasks, and connect notifications across Discord, Telegram, email, and webhooks. Connects to KeeperHub's remote MCP server with OAuth browser authentication.", "version": "3.0.0", - "author": { "name": "KeeperHub" }, + "author": { "name": "KeeperHub", "email": "support@keeperhub.com", "url": "https://keeperhub.com" }, "homepage": "https://app.keeperhub.com", "repository": "https://github.com/KeeperHub/claude-plugins", "license": "MIT", - "keywords": ["keeperhub", "workflow", "automation", "web3", "blockchain", "mcp"] + "keywords": ["keeperhub", "workflow", "automation", "web3", "smart-contracts", "mcp"] } diff --git a/plugins/keeperhub/CLAUDE.md b/plugins/keeperhub/CLAUDE.md new file mode 100644 index 0000000..1c45715 --- /dev/null +++ b/plugins/keeperhub/CLAUDE.md @@ -0,0 +1,21 @@ +# KeeperHub Plugin + +This is a Claude Code plugin that connects to KeeperHub's remote MCP server for workflow automation. + +## Architecture + +- Pure markdown and JSON plugin (no executable code) +- Connects to remote MCP server at `app.keeperhub.com/mcp` via HTTP +- Authentication via OAuth 2.0 (browser) or API key (environment variable) + +## Components + +- **Skills**: 4 auto-invoked skills for workflow building, template browsing, execution monitoring, and plugin exploration +- **Commands**: 2 slash commands for login setup and status checking +- **MCP Server**: Remote HTTP connection configured in `.mcp.json` + +## Key Patterns + +- All skills check authentication before making API calls +- Skills route to each other for out-of-scope requests +- Progressive disclosure: start simple, add complexity only when needed diff --git a/plugins/keeperhub/README.md b/plugins/keeperhub/README.md index a081a69..bb06f13 100644 --- a/plugins/keeperhub/README.md +++ b/plugins/keeperhub/README.md @@ -1,6 +1,6 @@ # KeeperHub Plugin for Claude Code -Manage KeeperHub workflows, execute automations, and browse templates directly from Claude Code. +Build and manage automation workflows from Claude Code. Monitor smart contracts, track on-chain events, configure scheduled tasks, and connect notifications across Discord, Telegram, email, and webhooks. ## Quick Start @@ -17,7 +17,7 @@ Run `/mcp` in Claude Code, find "keeperhub" in the server list, and authorize vi For headless/CI environments, set `KH_API_KEY` with an organization API key (`kh_` prefix) instead. -**3.** Try asking Claude to "create a workflow that monitors a wallet" or run `/keeperhub:status` to verify. +**3.** Try asking Claude to "create a workflow that monitors a smart contract event" or run `/keeperhub:status` to verify. ## Commands diff --git a/plugins/keeperhub/commands/login.md b/plugins/keeperhub/commands/login.md index 8b6fd86..f3ba5e8 100644 --- a/plugins/keeperhub/commands/login.md +++ b/plugins/keeperhub/commands/login.md @@ -48,7 +48,7 @@ KH_API_KEY env var set: !`[ -n "${KH_API_KEY:-}" ] && echo "YES" || echo "NO"` MCP Server: app.keeperhub.com/mcp (remote) Auth: [OAuth / API key] ``` - - Suggest trying: "Create a workflow that monitors a wallet" + - Suggest trying: "Create a workflow that monitors a smart contract event" diff --git a/plugins/keeperhub/skills/plugin-explorer/SKILL.md b/plugins/keeperhub/skills/plugin-explorer/SKILL.md index 9eab5b4..7f2bd1a 100644 --- a/plugins/keeperhub/skills/plugin-explorer/SKILL.md +++ b/plugins/keeperhub/skills/plugin-explorer/SKILL.md @@ -15,7 +15,7 @@ integrations the user already has connected. Activate when ANY of these are true: - User says "what plugins are available", "show plugins", or "list plugins" - User says "show integrations", "what integrations do I have", or "list integrations" -- User says "how do I use" followed by a plugin name (web3, discord, sendgrid, webhook) +- User says "how do I use" followed by a plugin name (notifications, discord, sendgrid, webhook) - User says "what can KeeperHub do", "what actions are available", or "what are my options" - User asks about a specific action type or capability - User wants to validate a plugin configuration before using it in a workflow @@ -38,7 +38,7 @@ Do NOT activate when: 2. **For general exploration** ("what can KeeperHub do", "what plugins"): - Use `search_plugins` to list available plugins - Present a summary: plugin name, description, number of actions - - Group by category if helpful (web3, notifications, utilities) + - Group by category if helpful (monitoring, notifications, utilities) 3. **For specific plugin details** ("how do I use web3"): - Use `get_plugin` to get full documentation @@ -48,7 +48,6 @@ Do NOT activate when: 4. **For integration status** ("what integrations do I have"): - Use `list_integrations` to show configured integrations - - For web3 users, use `get_wallet_integration` to show wallet details - Highlight which integrations are active vs. need setup - Suggest plugins that would work with existing integrations @@ -67,7 +66,6 @@ Do NOT activate when: - `get_plugin` -- get full plugin documentation - `list_action_schemas` -- list available actions and their schemas - `list_integrations` -- show configured integrations -- `get_wallet_integration` -- get wallet integration details - `validate_plugin_config` -- validate action configuration - `tools_documentation` -- get MCP tool documentation diff --git a/plugins/keeperhub/skills/template-browser/SKILL.md b/plugins/keeperhub/skills/template-browser/SKILL.md index 8d9a190..bfae18a 100644 --- a/plugins/keeperhub/skills/template-browser/SKILL.md +++ b/plugins/keeperhub/skills/template-browser/SKILL.md @@ -43,7 +43,7 @@ Do NOT activate when: 3. **Show template details** when the user picks one: - Use `get_template` to fetch full metadata - Present: name, description, what it does, required integrations, trigger type, actions involved - - Highlight any prerequisites (e.g., "requires Discord integration" or "needs a wallet configured") + - Highlight any prerequisites (e.g., "requires Discord integration" or "needs an API key configured") 4. **Deploy the template** when the user confirms: - Use `deploy_template` to create the workflow from the template diff --git a/plugins/keeperhub/skills/workflow-builder/SKILL.md b/plugins/keeperhub/skills/workflow-builder/SKILL.md index 114b45e..1cb44b0 100644 --- a/plugins/keeperhub/skills/workflow-builder/SKILL.md +++ b/plugins/keeperhub/skills/workflow-builder/SKILL.md @@ -16,11 +16,11 @@ complexity only when needed. Activate when ANY of these are true: - User says "create a workflow", "build a workflow", "make a workflow", or "new workflow" -- User wants to "monitor" a contract, wallet, token, or address +- User wants to "monitor" a contract, API endpoint, or data source - User says "set up automation", "automate", or "when X happens do Y" - User says "alert me when", "notify me when", or "watch for" -- User describes a pipeline like "transfer then notify" or "check balance and send alert" -- User mentions specific KeeperHub actions like "call contract", "send webhook", "discord notification" +- User describes a pipeline like "check status then notify" or "check condition and send alert" +- User mentions specific KeeperHub actions like "read contract", "send webhook", "discord notification"