@amsterdamdatalabs/enact-extensions 0.1.42 → 0.1.48

package/extensions/plugin-dev/skills/mcp-integration/examples/http-server.json

@@ -1,20 +0,0 @@
-{
-  "_comment": "Example HTTP MCP server configuration for REST APIs",
-  "rest-api": {
-    "type": "http",
-    "url": "https://api.example.com/mcp",
-    "headers": {
-      "Authorization": "Bearer ${API_TOKEN}",
-      "Content-Type": "application/json",
-      "X-API-Version": "2024-01-01"
-    }
-  },
-  "internal-service": {
-    "type": "http",
-    "url": "https://api.example.com/mcp",
-    "headers": {
-      "Authorization": "Bearer ${API_TOKEN}",
-      "X-Service-Name": "claude-plugin"
-    }
-  }
-}

package/extensions/plugin-dev/skills/mcp-integration/examples/sse-server.json

@@ -1,19 +0,0 @@
-{
-  "_comment": "Example SSE MCP server configuration for hosted cloud services",
-  "asana": {
-    "type": "sse",
-    "url": "https://mcp.asana.com/sse"
-  },
-  "github": {
-    "type": "sse",
-    "url": "https://mcp.github.com/sse"
-  },
-  "custom-service": {
-    "type": "sse",
-    "url": "https://mcp.example.com/sse",
-    "headers": {
-      "X-API-Version": "v1",
-      "X-Client-ID": "${CLIENT_ID}"
-    }
-  }
-}

package/extensions/plugin-dev/skills/mcp-integration/examples/stdio-server.json

@@ -1,38 +0,0 @@
-{
-  "_comment": "Example stdio MCP server configuration for local file system access",
-  "filesystem": {
-    "command": "npx",
-    "args": [
-      "-y",
-      "@modelcontextprotocol/server-filesystem",
-      "${CLAUDE_PROJECT_DIR}"
-    ],
-    "env": {
-      "LOG_LEVEL": "info"
-    }
-  },
-  "database": {
-    "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server.js",
-    "args": [
-      "--config",
-      "${CLAUDE_PLUGIN_ROOT}/config/db.json"
-    ],
-    "env": {
-      "DATABASE_URL": "${DATABASE_URL}",
-      "DB_POOL_SIZE": "10"
-    }
-  },
-  "custom-tools": {
-    "command": "python",
-    "args": [
-      "-m",
-      "my_mcp_server",
-      "--port",
-      "8080"
-    ],
-    "env": {
-      "API_KEY": "${CUSTOM_API_KEY}",
-      "DEBUG": "false"
-    }
-  }
-}

package/extensions/plugin-dev/skills/mcp-integration/examples/ws-server.json

@@ -1,26 +0,0 @@
-{
-  "_comment": "Example WebSocket MCP server configuration for real-time bidirectional communication",
-  "realtime-service": {
-    "type": "ws",
-    "url": "wss://mcp.example.com/ws",
-    "headers": {
-      "Authorization": "Bearer ${TOKEN}"
-    }
-  },
-  "streaming-data": {
-    "type": "ws",
-    "url": "wss://stream.example.com/mcp",
-    "headers": {
-      "X-API-Key": "${API_KEY}",
-      "X-Client-ID": "${CLIENT_ID}"
-    }
-  },
-  "live-updates": {
-    "type": "ws",
-    "url": "wss://live.example.com/mcp/v1",
-    "headers": {
-      "Authorization": "Bearer ${WS_TOKEN}",
-      "X-Connection-Type": "persistent"
-    }
-  }
-}

package/extensions/plugin-dev/skills/mcp-integration/references/authentication.md

@@ -1,601 +0,0 @@
-# MCP Authentication Patterns
-
-Complete guide to authentication methods for MCP servers in Claude Code plugins.
-
-## Overview
-
-MCP servers support multiple authentication methods depending on the server type and service requirements. Choose the method that best matches your use case and security requirements.
-
-## OAuth (Automatic)
-
-### How It Works
-
-Claude Code automatically handles the complete OAuth 2.0 flow (with PKCE) for SSE and HTTP servers:
-
-1. User attempts to use MCP tool
-2. Claude Code detects authentication is needed
-3. Initiates OAuth 2.0 Authorization Code flow with PKCE (Proof Key for Code Exchange)
-4. Opens browser for OAuth consent
-5. User authorizes in browser
-6. Claude Code exchanges the authorization code for tokens
-7. Tokens stored securely by Claude Code
-8. Automatic token refresh using refresh tokens
-
-PKCE provides additional security for public clients by preventing authorization code interception attacks. Claude Code also supports pre-configured OAuth credentials for MCP servers that provide them.
-
-### Configuration
-
-```json
-{
-  "service": {
-    "type": "sse",
-    "url": "https://mcp.example.com/sse"
-  }
-}
-```
-
-No additional auth configuration needed! Claude Code handles everything.
-
-### Supported Services
-
-**Known OAuth-enabled MCP servers:**
-
-- Asana: `https://mcp.asana.com/sse`
-- GitHub (when available)
-- Google services (when available)
-- Custom OAuth servers
-
-### OAuth Scopes
-
-OAuth scopes are determined by the MCP server. Users see required scopes during the consent flow.
-
-**Document required scopes in your README:**
-
-```markdown
-## Authentication
-
-This plugin requires the following Asana permissions:
-
-- Read tasks and projects
-- Create and update tasks
-- Access workspace data
-```
-
-### Token Storage
-
-Tokens are stored securely by Claude Code:
-
-- Not accessible to plugins
-- Encrypted at rest
-- Automatic refresh
-- Cleared on sign-out
-
-### Troubleshooting OAuth
-
-**Authentication loop:**
-
-- Clear cached tokens (sign out and sign in)
-- Check OAuth redirect URLs
-- Verify server OAuth configuration
-
-**Scope issues:**
-
-- User may need to re-authorize for new scopes
-- Check server documentation for required scopes
-
-**Token expiration:**
-
-- Claude Code auto-refreshes
-- If refresh fails, prompts re-authentication
-
-## CLI OAuth Setup
-
-For MCP servers requiring OAuth 2.0, use CLI flags to pre-configure credentials:
-
-```bash
-claude mcp add --transport http my-service https://api.example.com/mcp \
-  --client-id "your-client-id" \
-  --client-secret \
-  --callback-port 8080
-```
-
-- `--client-id` — OAuth client ID
-- `--client-secret` — prompts for secret (hidden input); or set `MCP_CLIENT_SECRET` env var
-- `--callback-port` — local port for OAuth callback (default varies by server)
-
-For interactive OAuth setup, use the `/mcp` command within Claude Code to authenticate via browser.
-
-## Token-Based Authentication
-
-### Bearer Tokens
-
-Most common for HTTP and WebSocket servers.
-
-**Configuration:**
-
-```json
-{
-  "api": {
-    "type": "http",
-    "url": "https://api.example.com/mcp",
-    "headers": {
-      "Authorization": "Bearer ${API_TOKEN}"
-    }
-  }
-}
-```
-
-**Environment variable:**
-
-```bash
-export API_TOKEN="your-secret-token-here"
-```
-
-### API Keys
-
-Alternative to Bearer tokens, often in custom headers.
-
-**Configuration:**
-
-```json
-{
-  "api": {
-    "type": "http",
-    "url": "https://api.example.com/mcp",
-    "headers": {
-      "X-API-Key": "${API_KEY}",
-      "X-API-Secret": "${API_SECRET}"
-    }
-  }
-}
-```
-
-### Custom Headers
-
-Services may use custom authentication headers.
-
-**Configuration:**
-
-```json
-{
-  "service": {
-    "type": "sse",
-    "url": "https://mcp.example.com/sse",
-    "headers": {
-      "X-Auth-Token": "${AUTH_TOKEN}",
-      "X-User-ID": "${USER_ID}",
-      "X-Tenant-ID": "${TENANT_ID}"
-    }
-  }
-}
-```
-
-### Documenting Token Requirements
-
-Always document in your README:
-
-```markdown
-## Setup
-
-### Required Environment Variables
-
-Set these environment variables before using the plugin:
-
-\`\`\`bash
-export API_TOKEN="your-token-here"
-export API_SECRET="your-secret-here"
-\`\`\`
-
-### Obtaining Tokens
-
-1. Visit https://api.example.com/tokens
-2. Create a new API token
-3. Copy the token and secret
-4. Set environment variables as shown above
-
-### Token Permissions
-
-The API token needs the following permissions:
-
-- Read access to resources
-- Write access for creating items
-- Delete access (optional, for cleanup operations)
-  \`\`\`
-```
-
-## Environment Variable Authentication (stdio)
-
-### Passing Credentials to Server
-
-For stdio servers, pass credentials via environment variables:
-
-```json
-{
-  "database": {
-    "command": "python",
-    "args": ["-m", "mcp_server_db"],
-    "env": {
-      "DATABASE_URL": "${DATABASE_URL}",
-      "DB_USER": "${DB_USER}",
-      "DB_PASSWORD": "${DB_PASSWORD}"
-    }
-  }
-}
-```
-
-### User Environment Variables
-
-```bash
-# User sets these in their shell
-export DATABASE_URL="postgresql://localhost/mydb"
-export DB_USER="myuser"
-export DB_PASSWORD="mypassword"
-```
-
-### Documentation Template
-
-```markdown
-## Database Configuration
-
-Set these environment variables:
-
-\`\`\`bash
-export DATABASE_URL="postgresql://host:port/database"
-export DB_USER="username"
-export DB_PASSWORD="password"
-\`\`\`
-
-Or create a `.env` file (add to `.gitignore`):
-
-\`\`\`
-DATABASE_URL=postgresql://localhost:5432/mydb
-DB_USER=myuser
-DB_PASSWORD=mypassword
-\`\`\`
-
-Load with: \`source .env\` or \`export $(cat .env | xargs)\`
-\`\`\`
-```
-
-## Dynamic Headers
-
-### Headers Helper Script
-
-For tokens that change or expire, use a helper script:
-
-```json
-{
-  "api": {
-    "type": "sse",
-    "url": "https://api.example.com",
-    "headersHelper": "${CLAUDE_PLUGIN_ROOT}/scripts/get-headers.sh"
-  }
-}
-```
-
-**Script (get-headers.sh):**
-
-```bash
-#!/bin/bash
-# Generate dynamic authentication headers
-
-# Fetch fresh token
-TOKEN=$(get-fresh-token-from-somewhere)
-
-# Output JSON headers
-cat <<EOF
-{
-  "Authorization": "Bearer $TOKEN",
-  "X-Timestamp": "$(date -Iseconds)"
-}
-EOF
-```
-
-### Use Cases for Dynamic Headers
-
-- Short-lived tokens that need refresh
-- Tokens with HMAC signatures
-- Time-based authentication
-- Dynamic tenant/workspace selection
-
-## Security Best Practices
-
-### DO
-
-✅ **Use environment variables:**
-
-```json
-{
-  "headers": {
-    "Authorization": "Bearer ${API_TOKEN}"
-  }
-}
-```
-
-✅ **Document required variables in README**
-
-✅ **Use HTTPS/WSS always**
-
-✅ **Implement token rotation**
-
-✅ **Store tokens securely (env vars, not files)**
-
-✅ **Let OAuth handle authentication when available**
-
-### DON'T
-
-❌ **Hardcode tokens:**
-
-```json
-{
-  "headers": {
-    "Authorization": "Bearer sk-abc123..." // NEVER!
-  }
-}
-```
-
-❌ **Commit tokens to git**
-
-❌ **Share tokens in documentation**
-
-❌ **Use HTTP instead of HTTPS**
-
-❌ **Store tokens in plugin files**
-
-❌ **Log tokens or sensitive headers**
-
-## Multi-Tenancy Patterns
-
-### Workspace/Tenant Selection
-
-**Via environment variable:**
-
-```json
-{
-  "api": {
-    "type": "http",
-    "url": "https://api.example.com/mcp",
-    "headers": {
-      "Authorization": "Bearer ${API_TOKEN}",
-      "X-Workspace-ID": "${WORKSPACE_ID}"
-    }
-  }
-}
-```
-
-**Via URL:**
-
-```json
-{
-  "api": {
-    "type": "http",
-    "url": "https://${TENANT_ID}.api.example.com/mcp"
-  }
-}
-```
-
-### Per-User Configuration
-
-Users set their own workspace:
-
-```bash
-export WORKSPACE_ID="my-workspace-123"
-export TENANT_ID="my-company"
-```
-
-## Authentication Troubleshooting
-
-### Common Issues
-
-**401 Unauthorized:**
-
-- Check token is set correctly
-- Verify token hasn't expired
-- Check token has required permissions
-- Ensure header format is correct
-
-**403 Forbidden:**
-
-- Token valid but lacks permissions
-- Check scope/permissions
-- Verify workspace/tenant ID
-- May need admin approval
-
-**Token not found:**
-
-```bash
-# Check environment variable is set
-echo $API_TOKEN
-
-# If empty, set it
-export API_TOKEN="your-token"
-```
-
-**Token in wrong format:**
-
-```json
-// Correct
-"Authorization": "Bearer sk-abc123"
-
-// Wrong
-"Authorization": "sk-abc123"
-```
-
-### Debugging Authentication
-
-**Enable debug mode:**
-
-```bash
-claude --debug
-```
-
-Look for:
-
-- Authentication header values (sanitized)
-- OAuth flow progress
-- Token refresh attempts
-- Authentication errors
-
-**Test authentication separately:**
-
-```bash
-# Test HTTP endpoint
-curl -H "Authorization: Bearer $API_TOKEN" \
-     https://api.example.com/mcp/health
-
-# Should return 200 OK
-```
-
-## Migration Patterns
-
-### From Hardcoded to Environment Variables
-
-**Before:**
-
-```json
-{
-  "headers": {
-    "Authorization": "Bearer sk-hardcoded-token"
-  }
-}
-```
-
-**After:**
-
-```json
-{
-  "headers": {
-    "Authorization": "Bearer ${API_TOKEN}"
-  }
-}
-```
-
-**Migration steps:**
-
-1. Add environment variable to plugin README
-2. Update configuration to use ${VAR}
-3. Test with variable set
-4. Remove hardcoded value
-5. Commit changes
-
-### From Basic Auth to OAuth
-
-**Before:**
-
-```json
-{
-  "headers": {
-    "Authorization": "Basic ${BASE64_CREDENTIALS}"
-  }
-}
-```
-
-**After:**
-
-```json
-{
-  "type": "sse",
-  "url": "https://mcp.example.com/sse"
-}
-```
-
-**Benefits:**
-
-- Better security
-- No credential management
-- Automatic token refresh
-- Scoped permissions
-
-## Advanced Authentication
-
-### Mutual TLS (mTLS)
-
-Some enterprise services require client certificates.
-
-**Not directly supported in MCP configuration.**
-
-**Workaround:** Wrap in stdio server that handles mTLS:
-
-```json
-{
-  "secure-api": {
-    "command": "${CLAUDE_PLUGIN_ROOT}/servers/mtls-wrapper",
-    "args": ["--cert", "${CLIENT_CERT}", "--key", "${CLIENT_KEY}"],
-    "env": {
-      "API_URL": "https://secure.example.com"
-    }
-  }
-}
-```
-
-### JWT Tokens
-
-Generate JWT tokens dynamically with headers helper:
-
-```bash
-#!/bin/bash
-# generate-jwt.sh
-
-# Generate JWT (using library or API call)
-JWT=$(generate-jwt-token)
-
-echo "{\"Authorization\": \"Bearer $JWT\"}"
-```
-
-```json
-{
-  "headersHelper": "${CLAUDE_PLUGIN_ROOT}/scripts/generate-jwt.sh"
-}
-```
-
-### HMAC Signatures
-
-For APIs requiring request signing:
-
-```bash
-#!/bin/bash
-# generate-hmac.sh
-
-TIMESTAMP=$(date -Iseconds)
-SIGNATURE=$(echo -n "$TIMESTAMP" | openssl dgst -sha256 -hmac "$SECRET_KEY" | cut -d' ' -f2)
-
-cat <<EOF
-{
-  "X-Timestamp": "$TIMESTAMP",
-  "X-Signature": "$SIGNATURE",
-  "X-API-Key": "$API_KEY"
-}
-EOF
-```
-
-## Best Practices Summary
-
-### For Plugin Developers
-
-1. **Prefer OAuth** when service supports it
-2. **Use environment variables** for tokens
-3. **Document all required variables** in README
-4. **Provide setup instructions** with examples
-5. **Never commit credentials**
-6. **Use HTTPS/WSS only**
-7. **Test authentication thoroughly**
-
-### For Plugin Users
-
-1. **Set environment variables** before using plugin
-2. **Keep tokens secure** and private
-3. **Rotate tokens regularly**
-4. **Use different tokens** for dev/prod
-5. **Don't commit .env files** to git
-6. **Review OAuth scopes** before authorizing
-
-## Conclusion
-
-Choose the authentication method that matches your MCP server's requirements:
-
-- **OAuth** for cloud services (easiest for users)
-- **Bearer tokens** for API services
-- **Environment variables** for stdio servers
-- **Dynamic headers** for complex auth flows
-
-Always prioritize security and provide clear setup documentation for users.