@cubis/foundry 0.3.31 → 0.3.33

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/kotlin-pro/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: "kotlin-pro"
+description: "Use for modern Kotlin backend/mobile/shared code with Kotlin 2.3-era language tooling and production patterns."
+license: MIT
+metadata:
+  version: "1.0.0"
+  domain: "language"
+  role: "specialist"
+  stack: "kotlin"
+  baseline: "Kotlin 2.3 line (2.2.20+ compatible)"
+---
+
+# Kotlin Pro
+
+## When to use
+
+- Building Kotlin services or Android/shared modules.
+- Designing coroutine-based async flows.
+- Improving null-safety and domain model clarity.
+
+## Core workflow
+
+1. Establish target platform (JVM/Android/multiplatform).
+2. Define domain types and boundary contracts first.
+3. Implement with coroutine/flow patterns where appropriate.
+4. Validate with tests and static analysis.
+
+## Baseline standards
+
+- Keep nullability explicit; avoid forced non-null assertions.
+- Prefer immutable data models and pure transforms.
+- Use structured concurrency and clear scope ownership.
+- Keep serialization and transport models separate from domain.
+- Use dependency boundaries that support modular testing.
+
+## Avoid
+
+- Coroutine launches without lifecycle ownership.
+- Platform-specific leakage into shared/core modules.
+- Overusing extension magic that hurts readability.

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/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/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/mcp-developer/references/protocol.md

@@ -0,0 +1,244 @@
+# MCP Protocol Specification
+
+## Protocol Overview
+
+MCP is built on JSON-RPC 2.0 and enables bidirectional communication between clients (like Claude Desktop) and servers that provide resources, tools, and prompts.
+
+## Message Types
+
+### Request/Response
+
+```typescript
+// Request format
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/list",
+  "params": {}
+}
+
+// Success response
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "tools": [
+      {
+        "name": "get_weather",
+        "description": "Get weather for a location",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "location": { "type": "string" }
+          },
+          "required": ["location"]
+        }
+      }
+    ]
+  }
+}
+
+// Error response
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "error": {
+    "code": -32602,
+    "message": "Invalid params",
+    "data": { "details": "location is required" }
+  }
+}
+```
+
+### Notifications
+
+```typescript
+// Server sends notification (no response expected)
+{
+  "jsonrpc": "2.0",
+  "method": "notifications/resources/updated",
+  "params": {
+    "uri": "file:///project/data.json"
+  }
+}
+```
+
+## Connection Lifecycle
+
+```
+1. Client initiates connection (stdio/HTTP/SSE)
+2. Client sends initialize request
+   → Server responds with capabilities
+3. Client sends initialized notification
+4. Normal operation (requests/notifications)
+5. Client/server can ping for keepalive
+6. Client sends shutdown request
+7. Connection closes
+```
+
+### Initialize Handshake
+
+```typescript
+// Client initialize request
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "initialize",
+  "params": {
+    "protocolVersion": "2024-11-05",
+    "capabilities": {
+      "roots": { "listChanged": true },
+      "sampling": {}
+    },
+    "clientInfo": {
+      "name": "claude-desktop",
+      "version": "1.0.0"
+    }
+  }
+}
+
+// Server response
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "protocolVersion": "2024-11-05",
+    "capabilities": {
+      "resources": { "subscribe": true, "listChanged": true },
+      "tools": { "listChanged": true },
+      "prompts": { "listChanged": true }
+    },
+    "serverInfo": {
+      "name": "my-mcp-server",
+      "version": "1.0.0"
+    }
+  }
+}
+
+// Client sends initialized notification
+{
+  "jsonrpc": "2.0",
+  "method": "notifications/initialized"
+}
+```
+
+## Core Methods
+
+### Resources
+
+```typescript
+// List available resources
+resources/list → { resources: Resource[] }
+
+// Read resource content
+resources/read { uri: string } → { contents: ResourceContent[] }
+
+// Subscribe to resource updates (if supported)
+resources/subscribe { uri: string } → {}
+
+// Unsubscribe
+resources/unsubscribe { uri: string } → {}
+
+// Server notifies of changes
+notifications/resources/list_changed → {}
+notifications/resources/updated { uri: string } → {}
+```
+
+### Tools
+
+```typescript
+// List available tools
+tools/list → { tools: Tool[] }
+
+// Execute tool
+tools/call {
+  name: string,
+  arguments: object
+} → { content: ToolResponse[] }
+
+// Server notifies of tool changes
+notifications/tools/list_changed → {}
+```
+
+### Prompts
+
+```typescript
+// List available prompts
+prompts/list → { prompts: Prompt[] }
+
+// Get prompt with arguments
+prompts/get {
+  name: string,
+  arguments?: object
+} → { messages: PromptMessage[] }
+
+// Server notifies of prompt changes
+notifications/prompts/list_changed → {}
+```
+
+## Error Codes
+
+Standard JSON-RPC 2.0 codes plus MCP-specific:
+
+```typescript
+const ERROR_CODES = {
+  // JSON-RPC 2.0 standard
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+
+  // MCP-specific (implementation defined)
+  RESOURCE_NOT_FOUND: -32001,
+  TOOL_EXECUTION_ERROR: -32002,
+  UNAUTHORIZED: -32003,
+  RATE_LIMIT_EXCEEDED: -32004
+};
+```
+
+## Transport Mechanisms
+
+### stdio (Standard Input/Output)
+
+```typescript
+// Server reads from stdin, writes to stdout
+// Each message is newline-delimited JSON
+// Used for local integration (Claude Desktop default)
+```
+
+### HTTP with SSE (Server-Sent Events)
+
+```typescript
+// Client POSTs JSON-RPC requests to endpoint
+// Server streams responses and notifications via SSE
+// Used for remote servers
+
+POST /mcp HTTP/1.1
+Content-Type: application/json
+
+{"jsonrpc":"2.0","id":1,"method":"tools/list"}
+
+// SSE response
+GET /mcp/sse HTTP/1.1
+
+event: message
+data: {"jsonrpc":"2.0","id":1,"result":{...}}
+```
+
+## Protocol Versions
+
+Current version: `2024-11-05`
+
+Servers must declare supported version in initialize response. Clients should verify compatibility.
+
+## Best Practices
+
+1. **Validation**: Always validate params with JSON Schema
+2. **Error handling**: Return structured errors with helpful messages
+3. **Versioning**: Check protocol version in initialize
+4. **Timeouts**: Implement request timeouts (30s recommended)
+5. **Logging**: Log all protocol messages for debugging
+6. **Stateless**: Design tools/resources to be stateless
+7. **Idempotency**: Make tool calls idempotent when possible
+8. **Notifications**: Use notifications for real-time updates