@cubis/foundry 0.3.33 → 0.3.35

package/mcp/powers/mcp-developer/steering/typescript-sdk.md

@@ -1,350 +0,0 @@
-# TypeScript SDK Implementation
-
-## Installation
-
-```bash
-npm install @modelcontextprotocol/sdk zod
-```
-
-## Basic Server Setup
-
-```typescript
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import {
-  CallToolRequestSchema,
-  ListToolsRequestSchema,
-  ListResourcesRequestSchema,
-  ReadResourceRequestSchema,
-} from "@modelcontextprotocol/sdk/types.js";
-import { z } from "zod";
-
-// Create server instance
-const server = new Server(
-  {
-    name: "example-server",
-    version: "1.0.0",
-  },
-  {
-    capabilities: {
-      resources: {},
-      tools: {},
-      prompts: {},
-    },
-  }
-);
-
-// Handle tools/list request
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-  return {
-    tools: [
-      {
-        name: "get_weather",
-        description: "Get current weather for a location",
-        inputSchema: {
-          type: "object",
-          properties: {
-            location: {
-              type: "string",
-              description: "City name or zip code",
-            },
-            units: {
-              type: "string",
-              enum: ["celsius", "fahrenheit"],
-              default: "celsius",
-            },
-          },
-          required: ["location"],
-        },
-      },
-    ],
-  };
-});
-
-// Handle tools/call request
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  if (request.params.name === "get_weather") {
-    const location = String(request.params.arguments?.location);
-    const units = String(request.params.arguments?.units ?? "celsius");
-
-    // Your tool logic here
-    const weatherData = await fetchWeather(location, units);
-
-    return {
-      content: [
-        {
-          type: "text",
-          text: `Weather in ${location}: ${weatherData.temp}°${units === "celsius" ? "C" : "F"}`,
-        },
-      ],
-    };
-  }
-
-  throw new Error(`Unknown tool: ${request.params.name}`);
-});
-
-// Start server with stdio transport
-async function main() {
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-  console.error("MCP Server running on stdio");
-}
-
-main().catch(console.error);
-```
-
-## Resource Provider
-
-```typescript
-import {
-  ListResourcesRequestSchema,
-  ReadResourceRequestSchema,
-} from "@modelcontextprotocol/sdk/types.js";
-
-// List resources
-server.setRequestHandler(ListResourcesRequestSchema, async () => {
-  return {
-    resources: [
-      {
-        uri: "file:///config/settings.json",
-        name: "Application Settings",
-        description: "Current application configuration",
-        mimeType: "application/json",
-      },
-      {
-        uri: "db://users/schema",
-        name: "User Schema",
-        description: "Database schema for users table",
-        mimeType: "text/plain",
-      },
-    ],
-  };
-});
-
-// Read resource content
-server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-  const uri = request.params.uri;
-
-  if (uri === "file:///config/settings.json") {
-    const settings = await loadSettings();
-    return {
-      contents: [
-        {
-          uri,
-          mimeType: "application/json",
-          text: JSON.stringify(settings, null, 2),
-        },
-      ],
-    };
-  }
-
-  if (uri.startsWith("db://users/")) {
-    const schema = await getDatabaseSchema("users");
-    return {
-      contents: [
-        {
-          uri,
-          mimeType: "text/plain",
-          text: schema,
-        },
-      ],
-    };
-  }
-
-  throw new Error(`Resource not found: ${uri}`);
-});
-```
-
-## Prompt Templates
-
-```typescript
-import {
-  ListPromptsRequestSchema,
-  GetPromptRequestSchema,
-} from "@modelcontextprotocol/sdk/types.js";
-
-server.setRequestHandler(ListPromptsRequestSchema, async () => {
-  return {
-    prompts: [
-      {
-        name: "code_review",
-        description: "Generate code review comments",
-        arguments: [
-          {
-            name: "language",
-            description: "Programming language",
-            required: true,
-          },
-          {
-            name: "code",
-            description: "Code to review",
-            required: true,
-          },
-        ],
-      },
-    ],
-  };
-});
-
-server.setRequestHandler(GetPromptRequestSchema, async (request) => {
-  if (request.params.name === "code_review") {
-    const language = String(request.params.arguments?.language);
-    const code = String(request.params.arguments?.code);
-
-    return {
-      messages: [
-        {
-          role: "user",
-          content: {
-            type: "text",
-            text: `Review this ${language} code and provide feedback:\n\n${code}`,
-          },
-        },
-      ],
-    };
-  }
-
-  throw new Error(`Unknown prompt: ${request.params.name}`);
-});
-```
-
-## Input Validation with Zod
-
-```typescript
-import { z } from "zod";
-
-// Define schemas for validation
-const WeatherArgsSchema = z.object({
-  location: z.string().min(1),
-  units: z.enum(["celsius", "fahrenheit"]).default("celsius"),
-});
-
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  if (request.params.name === "get_weather") {
-    // Validate and parse arguments
-    const args = WeatherArgsSchema.parse(request.params.arguments);
-
-    const weatherData = await fetchWeather(args.location, args.units);
-
-    return {
-      content: [
-        {
-          type: "text",
-          text: `Temperature: ${weatherData.temp}°${args.units === "celsius" ? "C" : "F"}`,
-        },
-      ],
-    };
-  }
-
-  throw new Error(`Unknown tool: ${request.params.name}`);
-});
-```
-
-## Error Handling
-
-```typescript
-import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
-
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  try {
-    // Validate input
-    if (!request.params.arguments?.location) {
-      throw new McpError(
-        ErrorCode.InvalidParams,
-        "location parameter is required"
-      );
-    }
-
-    const result = await executeTool(request.params.name, request.params.arguments);
-    return { content: [{ type: "text", text: result }] };
-
-  } catch (error) {
-    if (error instanceof McpError) {
-      throw error; // Re-throw MCP errors
-    }
-
-    // Wrap other errors
-    throw new McpError(
-      ErrorCode.InternalError,
-      `Tool execution failed: ${error.message}`
-    );
-  }
-});
-```
-
-## Basic Client Setup
-
-```typescript
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-
-const client = new Client(
-  {
-    name: "example-client",
-    version: "1.0.0",
-  },
-  {
-    capabilities: {},
-  }
-);
-
-// Connect to server
-const transport = new StdioClientTransport({
-  command: "node",
-  args: ["./server.js"],
-});
-
-await client.connect(transport);
-
-// List available tools
-const toolsResponse = await client.request(
-  { method: "tools/list" },
-  ListToolsResultSchema
-);
-
-console.log("Available tools:", toolsResponse.tools);
-
-// Call a tool
-const result = await client.request(
-  {
-    method: "tools/call",
-    params: {
-      name: "get_weather",
-      arguments: { location: "San Francisco" },
-    },
-  },
-  CallToolResultSchema
-);
-
-console.log("Result:", result.content);
-```
-
-## Notifications
-
-```typescript
-// Server sends notification
-server.notification({
-  method: "notifications/resources/updated",
-  params: {
-    uri: "file:///config/settings.json",
-  },
-});
-
-// Client handles notifications
-client.setNotificationHandler((notification) => {
-  if (notification.method === "notifications/resources/updated") {
-    console.log("Resource updated:", notification.params.uri);
-  }
-});
-```
-
-## Best Practices
-
-1. **Type Safety**: Use Zod for runtime validation
-2. **Error Handling**: Always wrap errors in McpError
-3. **Async/Await**: Use async/await throughout
-4. **Logging**: Log to stderr, not stdout (stdio transport)
-5. **Cleanup**: Handle graceful shutdown
-6. **Testing**: Use unit tests with mock transports
-7. **Performance**: Cache expensive operations
-8. **Security**: Validate all inputs, sanitize outputs

package/mcp/powers/postman/POWER.md

@@ -1,243 +0,0 @@
-````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
-````