@cubis/foundry 0.3.32 → 0.3.34

package/mcp/powers/mcp-builder/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: mcp-builder
+description: MCP (Model Context Protocol) server building principles. Tool design, resource patterns, best practices.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# MCP Builder
+
+> Principles for building MCP servers.
+
+---
+
+## 1. MCP Overview
+
+### What is MCP?
+
+Model Context Protocol - standard for connecting AI systems with external tools and data sources.
+
+### Core Concepts
+
+| Concept | Purpose |
+|---------|---------|
+| **Tools** | Functions AI can call |
+| **Resources** | Data AI can read |
+| **Prompts** | Pre-defined prompt templates |
+
+---
+
+## 2. Server Architecture
+
+### Project Structure
+
+```
+my-mcp-server/
+├── src/
+│   └── index.ts      # Main entry
+├── package.json
+└── tsconfig.json
+```
+
+### Transport Types
+
+| Type | Use |
+|------|-----|
+| **Stdio** | Local, CLI-based |
+| **SSE** | Web-based, streaming |
+| **WebSocket** | Real-time, bidirectional |
+
+---
+
+## 3. Tool Design Principles
+
+### Good Tool Design
+
+| Principle | Description |
+|-----------|-------------|
+| Clear name | Action-oriented (get_weather, create_user) |
+| Single purpose | One thing well |
+| Validated input | Schema with types and descriptions |
+| Structured output | Predictable response format |
+
+### Input Schema Design
+
+| Field | Required? |
+|-------|-----------|
+| Type | Yes - object |
+| Properties | Define each param |
+| Required | List mandatory params |
+| Description | Human-readable |
+
+---
+
+## 4. Resource Patterns
+
+### Resource Types
+
+| Type | Use |
+|------|-----|
+| Static | Fixed data (config, docs) |
+| Dynamic | Generated on request |
+| Template | URI with parameters |
+
+### URI Patterns
+
+| Pattern | Example |
+|---------|---------|
+| Fixed | `docs://readme` |
+| Parameterized | `users://{userId}` |
+| Collection | `files://project/*` |
+
+---
+
+## 5. Error Handling
+
+### Error Types
+
+| Situation | Response |
+|-----------|----------|
+| Invalid params | Validation error message |
+| Not found | Clear "not found" |
+| Server error | Generic error, log details |
+
+### Best Practices
+
+- Return structured errors
+- Don't expose internal details
+- Log for debugging
+- Provide actionable messages
+
+---
+
+## 6. Multimodal Handling
+
+### Supported Types
+
+| Type | Encoding |
+|------|----------|
+| Text | Plain text |
+| Images | Base64 + MIME type |
+| Files | Base64 + MIME type |
+
+---
+
+## 7. Security Principles
+
+### Input Validation
+
+- Validate all tool inputs
+- Sanitize user-provided data
+- Limit resource access
+
+### API Keys
+
+- Use environment variables
+- Don't log secrets
+- Validate permissions
+
+---
+
+## 8. Configuration
+
+### Claude Desktop Config
+
+| Field | Purpose |
+|-------|---------|
+| command | Executable to run |
+| args | Command arguments |
+| env | Environment variables |
+
+---
+
+## 9. Testing
+
+### Test Categories
+
+| Type | Focus |
+|------|-------|
+| Unit | Tool logic |
+| Integration | Full server |
+| Contract | Schema validation |
+
+---
+
+## 10. Best Practices Checklist
+
+- [ ] Clear, action-oriented tool names
+- [ ] Complete input schemas with descriptions
+- [ ] Structured JSON output
+- [ ] Error handling for all cases
+- [ ] Input validation
+- [ ] Environment-based configuration
+- [ ] Logging for debugging
+
+---
+
+> **Remember:** MCP tools should be simple, focused, and well-documented. The AI relies on descriptions to use them correctly.

package/mcp/powers/mcp-developer/POWER.md

@@ -0,0 +1,88 @@
+````markdown
+---
+inclusion: manual
+name: mcp-developer
+description: "Use for implementing, debugging, and maintaining MCP servers/clients with SDKs, protocol compliance, transports, schemas, and security hardening."
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.0.0"
+  domain: api-architecture
+  triggers: MCP, Model Context Protocol, MCP server, MCP client, Claude integration, AI tools, context protocol, JSON-RPC
+  role: specialist
+  scope: implementation
+  output-format: code
+  related-skills: fastapi-expert, typescript-pro, security-reviewer, devops-engineer
+---
+
+# MCP Developer
+
+Senior MCP (Model Context Protocol) developer with deep expertise in building servers and clients that connect AI systems with external tools and data sources.
+
+## Role Definition
+
+You are a senior MCP developer with expertise in protocol implementation, SDK usage (TypeScript/Python), and production deployment. You build robust MCP servers that expose resources, tools, and prompts to Claude and other AI systems while maintaining security, performance, and developer experience standards.
+
+## When to Use This Skill
+
+- Building MCP servers for data source integration
+- Implementing tool functions for AI assistants
+- Creating resource providers with URI schemes
+- Setting up MCP clients for Claude integration
+- Debugging protocol compliance issues
+- Optimizing MCP performance and security
+
+## Core Workflow
+
+1. **Analyze requirements** - Identify data sources, tools needed, client apps
+2. **Design protocol** - Define resources, tools, prompts, schemas
+3. **Implement** - Build server/client with SDK, add security controls
+4. **Test** - Verify protocol compliance, performance, error handling
+5. **Deploy** - Package, configure, monitor in production
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Protocol | `references/protocol.md` | Message types, lifecycle, JSON-RPC 2.0 |
+| TypeScript SDK | `references/typescript-sdk.md` | Building servers/clients in Node.js |
+| Python SDK | `references/python-sdk.md` | Building servers/clients in Python |
+| Tools | `references/tools.md` | Tool definitions, schemas, execution |
+| Resources | `references/resources.md` | Resource providers, URIs, templates |
+
+## Constraints
+
+### MUST DO
+- Implement JSON-RPC 2.0 protocol correctly
+- Validate all inputs with schemas (Zod/Pydantic)
+- Use proper transport mechanisms (stdio/HTTP/SSE)
+- Implement comprehensive error handling
+- Add authentication and authorization
+- Log protocol messages for debugging
+- Test protocol compliance thoroughly
+- Document server capabilities
+
+### MUST NOT DO
+- Skip input validation on tool inputs
+- Expose sensitive data in resource content
+- Ignore protocol version compatibility
+- Mix synchronous code with async transports
+- Hardcode credentials or secrets
+- Return unstructured errors to clients
+- Deploy without rate limiting
+- Skip security controls
+
+## Output Templates
+
+When implementing MCP features, provide:
+1. Server/client implementation file
+2. Schema definitions (tools, resources, prompts)
+3. Configuration file (transport, auth, etc.)
+4. Brief explanation of design decisions
+
+## Knowledge Reference
+
+Model Context Protocol (MCP), JSON-RPC 2.0, TypeScript SDK (@modelcontextprotocol/sdk), Python SDK (mcp), Zod schemas, Pydantic validation, stdio transport, SSE transport, resource URIs, tool functions, prompt templates, authentication, rate limiting
+````

package/mcp/powers/mcp-developer/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: mcp-developer
+description: "Use for implementing, debugging, and maintaining MCP servers/clients with SDKs, protocol compliance, transports, schemas, and security hardening."
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.0.0"
+  domain: api-architecture
+  triggers: MCP, Model Context Protocol, MCP server, MCP client, Claude integration, AI tools, context protocol, JSON-RPC
+  role: specialist
+  scope: implementation
+  output-format: code
+  related-skills: fastapi-expert, typescript-pro, security-reviewer, devops-engineer
+---
+
+# MCP Developer
+
+Senior MCP (Model Context Protocol) developer with deep expertise in building servers and clients that connect AI systems with external tools and data sources.
+
+## Role Definition
+
+You are a senior MCP developer with expertise in protocol implementation, SDK usage (TypeScript/Python), and production deployment. You build robust MCP servers that expose resources, tools, and prompts to Claude and other AI systems while maintaining security, performance, and developer experience standards.
+
+## When to Use This Skill
+
+- Building MCP servers for data source integration
+- Implementing tool functions for AI assistants
+- Creating resource providers with URI schemes
+- Setting up MCP clients for Claude integration
+- Debugging protocol compliance issues
+- Optimizing MCP performance and security
+
+## Core Workflow
+
+1. **Analyze requirements** - Identify data sources, tools needed, client apps
+2. **Design protocol** - Define resources, tools, prompts, schemas
+3. **Implement** - Build server/client with SDK, add security controls
+4. **Test** - Verify protocol compliance, performance, error handling
+5. **Deploy** - Package, configure, monitor in production
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Protocol | `references/protocol.md` | Message types, lifecycle, JSON-RPC 2.0 |
+| TypeScript SDK | `references/typescript-sdk.md` | Building servers/clients in Node.js |
+| Python SDK | `references/python-sdk.md` | Building servers/clients in Python |
+| Tools | `references/tools.md` | Tool definitions, schemas, execution |
+| Resources | `references/resources.md` | Resource providers, URIs, templates |
+
+## Constraints
+
+### MUST DO
+- Implement JSON-RPC 2.0 protocol correctly
+- Validate all inputs with schemas (Zod/Pydantic)
+- Use proper transport mechanisms (stdio/HTTP/SSE)
+- Implement comprehensive error handling
+- Add authentication and authorization
+- Log protocol messages for debugging
+- Test protocol compliance thoroughly
+- Document server capabilities
+
+### MUST NOT DO
+- Skip input validation on tool inputs
+- Expose sensitive data in resource content
+- Ignore protocol version compatibility
+- Mix synchronous code with async transports
+- Hardcode credentials or secrets
+- Return unstructured errors to clients
+- Deploy without rate limiting
+- Skip security controls
+
+## Output Templates
+
+When implementing MCP features, provide:
+1. Server/client implementation file
+2. Schema definitions (tools, resources, prompts)
+3. Configuration file (transport, auth, etc.)
+4. Brief explanation of design decisions
+
+## Knowledge Reference
+
+Model Context Protocol (MCP), JSON-RPC 2.0, TypeScript SDK (@modelcontextprotocol/sdk), Python SDK (mcp), Zod schemas, Pydantic validation, stdio transport, SSE transport, resource URIs, tool functions, prompt templates, authentication, rate limiting

package/mcp/powers/postman/POWER.md

@@ -0,0 +1,243 @@
+````markdown
+---
+inclusion: manual
+name: "postman"
+description: "Automate API testing and collection management with Postman - create workspaces, collections, environments, and run tests programmatically"
+---
+
+
+# Onboarding
+
+Before proceeding, validate that the user has completed the following steps before using this power.
+
+## Step 1
+
+Generate and maintain `cbx_config.json` as the only Postman configuration source (workspace: `./cbx_config.json`, global: `~/.cbx/cbx_config.json`). Use named profiles in `postman.profiles` and choose `postman.activeProfileName`. Use env-first authentication by default: keep `apiKey` as `null`, set `apiKeyEnvVar` to `POSTMAN_API_KEY` (or another profile alias), and read the key from environment variables. Only store `apiKey` inline when the user explicitly requests file-based key storage. Keep workspace selection in the active profile `workspaceId` (`null` when unknown).
+
+## Step 2
+
+Create a hook that runs anytime the source code or configuration file has been changed. Save the hook in .kiro/hooks/hookname.kiro.hook. Example hook format. Please update the patterns to match the project's file structure.
+
+```json
+{
+  "enabled": true,
+  "name": "API Postman Testing",
+  "description": "Monitors API source code changes across multiple programming languages and automatically runs Postman collection tests to validate functionality",
+  "version": "1",
+  "when": {
+    "type": "fileEdited",
+    "patterns": [
+      "*.js",
+      "*.ts",
+      "*.py",
+      "*.java",
+      "*.cs",
+      "*.go", 
+      "*.rs",
+      "*.php",
+      "*.rb",
+      "*.kt",
+      "*.swift",
+      "*.scala",
+      "package.json",
+      "requirements.txt",
+      "Pipfile",
+      "pom.xml",
+      "build.gradle",
+      "*.csproj",
+      "go.mod",
+      "Cargo.toml",
+      "composer.json",
+      "Gemfile",
+      "build.sbt",
+      "openapi.yaml",
+      "openapi.yml",
+      "swagger.yaml",
+      "swagger.yml",
+      "api.yaml",
+      "api.yml"
+    ]
+  },
+  "then": {
+    "type": "askAgent",
+    "prompt": "API source code or configuration has been modified. Please retrieve the contents of the .postman.json file. If the file does not exist or is empty, create a Postman collection for the API. If it exists, get the collection ID and run the collection, showing me the results and propose fixes for any errors found."
+  }
+}
+```
+# Overview
+
+Automate API testing and collection management with Postman. Create workspaces, collections, environments, and run tests programmatically.
+
+**Authentication**: Env-first via `cbx_config.json` + profile env alias (default `POSTMAN_API_KEY`); inline `apiKey` is optional.
+
+## Available MCP Servers
+
+### postman
+**Package:** `@postman/postman-mcp-server`
+**Connection:** SSE-based MCP server
+**Authentication:** Postman API key via Bearer token
+**Mode:** Minimal (40 essential tools) - Default configuration
+**Endpoint:** https://mcp.postman.com/minimal
+
+**Note:** This power connects to Postman's hosted MCP server via SSE. To enable Full mode (112 tools) for advanced collaboration and enterprise features, change the URL to `https://mcp.postman.com/full`.
+
+**Available Tools (40 in Minimal Mode):**
+
+**Workspace Management:**
+- `createWorkspace` - Create a new workspace
+- `getWorkspace` - Get workspace details
+- `getWorkspaces` - List all accessible workspaces
+- `updateWorkspace` - Update workspace properties
+
+**Collection Management:**
+- `createCollection` - Create a new API collection
+- `getCollection` - Get detailed collection information
+- `getCollections` - List all collections in a workspace
+- `putCollection` - Replace/update entire collection
+- `duplicateCollection` - Create a copy of a collection
+- `createCollectionRequest` - Add a request to a collection
+- `createCollectionResponse` - Add a response example to a request
+
+**Environment Management:**
+- `createEnvironment` - Create a new environment
+- `getEnvironment` - Get environment details
+- `getEnvironments` - List all environments
+- `putEnvironment` - Replace/update entire environment
+
+**Mock Server Management:**
+- `createMock` - Create a mock server
+- `getMock` - Get mock server details
+- `getMocks` - List all mock servers
+- `updateMock` - Update mock server configuration
+- `publishMock` - Make mock server public
+
+**API Specification Management:**
+- `createSpec` - Create a new API specification
+- `getSpec` - Get specification details
+- `getAllSpecs` - List all specifications
+- `getSpecDefinition` - Get complete spec definition
+- `updateSpecProperties` - Update spec metadata
+- `createSpecFile` - Add a file to a spec
+- `getSpecFile` - Get a specific spec file
+- `getSpecFiles` - List all files in a spec
+- `updateSpecFile` - Update a spec file
+
+**Code Generation & Sync:**
+- `generateCollection` - Generate collection from API spec
+- `generateSpecFromCollection` - Generate spec from collection
+- `getGeneratedCollectionSpecs` - Get specs generated from a collection
+- `getSpecCollections` - Get collections generated from a spec
+- `syncCollectionWithSpec` - Sync collection with its spec
+- `syncSpecWithCollection` - Sync spec with its collection
+
+**Testing & Execution:**
+- `runCollection` - Execute a collection with automated tests
+
+**User & Metadata:**
+- `getAuthenticatedUser` - Get current user information
+- `getTaggedEntities` - Get entities by tag
+- `getStatusOfAnAsyncApiTask` - Check async task status
+- `getEnabledTools` - List available tools by mode
+
+## Tool Usage Examples
+
+```javascript
+// Create workspace
+mcp_postman_createWorkspace({
+  "workspace": { "name": "My API Project", "type": "personal" }
+})
+
+// Create collection
+mcp_postman_createCollection({
+  "workspace": "workspace-id",
+  "collection": {
+    "info": {
+      "name": "User API",
+      "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
+    }
+  }
+})
+
+// Create environment
+mcp_postman_createEnvironment({
+  "workspace": "workspace-id",
+  "environment": {
+    "name": "Local",
+    "values": [
+      { "key": "base_url", "value": "http://localhost:3000", "enabled": true }
+    ]
+  }
+})
+
+// Run collection
+mcp_postman_runCollection({
+  "collectionId": "collection-id",
+  "environmentId": "environment-id"
+})
+```
+
+## Workflows
+
+**Project Setup:**
+```javascript
+const { workspace } = await mcp_postman_createWorkspace({ "workspace": { "name": "Project", "type": "personal" }})
+const { collection } = await mcp_postman_createCollection({ "workspace": workspace.id, "collection": { "info": { "name": "API", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }}})
+const { environment } = await mcp_postman_createEnvironment({ "workspace": workspace.id, "environment": { "name": "Local", "values": [{ "key": "base_url", "value": "http://localhost:3000", "enabled": true }]}})
+// Save IDs to .postman.json
+```
+
+**Generate from OpenAPI:**
+```javascript
+const { spec } = await mcp_postman_createSpec({ "workspaceId": "workspace-id", "name": "API Spec", "type": "OPENAPI:3.0", "files": [{ "path": "openapi.yaml", "content": "..." }]})
+const result = await mcp_postman_generateCollection({ "specId": spec.id, "elementType": "collection", "name": "Generated Collection" })
+```
+
+**Automated Testing:**
+```javascript
+const { workspaces } = await mcp_postman_getWorkspaces()
+const { collections } = await mcp_postman_getCollections({ "workspace": workspaces[0].id })
+const { environments } = await mcp_postman_getEnvironments({ "workspace": workspaces[0].id })
+for (const collection of collections) {
+  await mcp_postman_runCollection({ "collectionId": collection.uid, "environmentId": environments[0]?.id })
+}
+```
+
+## Best Practices
+
+- Store workspace/collection/environment IDs in `.postman.json`
+- Use environment variables for different contexts (local/staging/production)
+- Add post-request test scripts for validation
+- Organize requests in folders
+- Run collections before deployment
+- Ensure API server is running before tests
+
+## Troubleshooting
+
+**"Collection not found"**: Call `getCollections` to verify ID and permissions
+
+**"Environment not found"**: Call `getEnvironments` with correct workspace ID
+
+**Test failures**: Verify API server running, check environment variables (base_url, api_key), review test scripts
+
+**"Invalid API key"**: Generate new key at postman.com Settings → API Keys, verify permissions
+
+## Configuration
+
+**MCP Configuration (Minimal mode - 40 tools):**
+```json
+{
+  "mcpServers": {
+    "postman": {
+      "url": "https://mcp.postman.com/minimal",
+      "headers": {
+        "Authorization": "Bearer ${POSTMAN_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+**Full mode (112 tools):** Change URL to `https://mcp.postman.com/full`
+
+**API Key Permissions:** Workspace management, collection read/write, environment read/write, collection runs
+````