axiom-coding-agent-setup 1.0.0 → 1.0.1

package/.agents/skills/mcp-builder/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: mcp-builder
+description: Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services. Use when building MCP servers to integrate external APIs or services, in Python (FastMCP) or Node/TypeScript (MCP SDK).
+---
+
+# MCP Server Development Guide
+
+## Overview
+
+Create MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. The quality of an MCP server is measured by how well it enables LLMs to accomplish real-world tasks.
+
+---
+
+## When to Use This Skill
+
+- Building integrations between LLMs and external APIs
+- Creating tools that Claude/opencode can use to access services
+- Wrapping third-party services (GitHub, Notion, databases, etc.)
+- Building internal tools for your team
+
+---
+
+## High-Level Workflow
+
+### Phase 1: Deep Research and Planning
+
+**API Coverage vs. Workflow Tools:**
+Balance comprehensive API endpoint coverage with specialized workflow tools. When uncertain, prioritize comprehensive API coverage.
+
+**Tool Naming:**
+- Use clear, descriptive names
+- Consistent prefixes: `github_create_issue`, `github_list_repos`
+- Action-oriented naming
+
+**Context Management:**
+- Return focused, relevant data
+- Support filtering/pagination
+- Concise tool descriptions
+
+### Phase 2: Implementation
+
+**Recommended Stack:**
+- **Language**: TypeScript (excellent SDK support, static typing)
+- **Transport**: Streamable HTTP for remote, stdio for local
+
+**For TypeScript:**
+- MCP TypeScript SDK: `@modelcontextprotocol/sdk`
+- Use Zod for input validation
+- Define output schemas for structured responses
+
+**For Python:**
+- FastMCP framework: `fastmcp`
+- Use Pydantic for input validation
+
+### Phase 3: Testing
+
+- Test with MCP Inspector: `npx @modelcontextprotocol/inspector`
+- Verify each tool works as expected
+- Test error handling paths
+
+---
+
+## TypeScript Implementation
+
+### Project Setup
+
+```bash
+mkdir my-mcp-server
+cd my-mcp-server
+npm init -y
+npm install @modelcontextprotocol/sdk zod
+npm install -D @types/node typescript
+```
+
+### Basic Server Structure
+
+```typescript
+// src/index.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+
+// Define input schemas
+const SearchSchema = z.object({
+  query: z.string().describe("Search query string"),
+  limit: z.number().optional().default(10).describe("Max results to return"),
+});
+
+// Create server
+const server = new Server(
+  {
+    name: "my-api-server",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "search_items",
+        description: "Search for items in the system",
+        inputSchema: {
+          type: "object",
+          properties: {
+            query: {
+              type: "string",
+              description: "Search query string",
+            },
+            limit: {
+              type: "number",
+              description: "Max results to return",
+              default: 10,
+            },
+          },
+          required: ["query"],
+        },
+      },
+    ],
+  };
+});
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  if (name === "search_items") {
+    const parsed = SearchSchema.safeParse(args);
+    if (!parsed.success) {
+      throw new Error(`Invalid arguments: ${parsed.error.message}`);
+    }
+
+    // Implement your search logic here
+    const results = await searchItems(parsed.data.query, parsed.data.limit);
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(results, null, 2),
+        },
+      ],
+    };
+  }
+
+  throw new Error(`Unknown tool: ${name}`);
+});
+
+// Start server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch(console.error);
+```
+
+---
+
+## Python Implementation (FastMCP)
+
+### Project Setup
+
+```bash
+mkdir my-mcp-server
+cd my-mcp-server
+python -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
+pip install fastmcp
+```
+
+### Basic Server Structure
+
+```python
+# server.py
+from fastmcp import FastMCP
+from pydantic import BaseModel, Field
+from typing import Optional
+
+# Create MCP server
+mcp = FastMCP("my-api-server")
+
+# Define input model
+class SearchInput(BaseModel):
+    query: str = Field(description="Search query string")
+    limit: Optional[int] = Field(default=10, description="Max results to return")
+
+# Define tool
+@mcp.tool()
+async def search_items(query: str, limit: int = 10) -> str:
+    """
+    Search for items in the system.
+    
+    Args:
+        query: Search query string
+        limit: Maximum number of results to return
+    
+    Returns:
+        JSON string with search results
+    """
+    # Implement your search logic
+    results = await perform_search(query, limit)
+    return json.dumps(results, indent=2)
+
+# Add more tools...
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+---
+
+## Best Practices
+
+### Tool Design
+
+1. **Clear Descriptions**: Write descriptions as if explaining to a junior developer
+2. **Actionable Errors**: Error messages should suggest how to fix the issue
+3. **Consistent Naming**: Use verb_noun pattern (e.g., `create_issue`, `list_repos`)
+4. **Input Validation**: Always validate and sanitize inputs
+5. **Pagination**: Support pagination for list operations
+
+### Error Handling
+
+```typescript
+// Good error message
+throw new Error(
+  `Repository "${repo}" not found. ` +
+  `Check the repository name and ensure you have access. ` +
+  `Format: owner/repo-name`
+);
+
+// Bad error message
+throw new Error("Not found");
+```
+
+### Response Format
+
+```typescript
+// Return structured data when possible
+return {
+  content: [
+    {
+      type: "text",
+      text: JSON.stringify({
+        success: true,
+        data: results,
+        count: results.length,
+      }, null, 2),
+    },
+  ],
+};
+```
+
+---
+
+## Testing with MCP Inspector
+
+```bash
+# Install inspector globally
+npm install -g @modelcontextprotocol/inspector
+
+# Run your server with inspector
+mcp-inspector node build/index.js
+
+# For Python
+mcp-inspector python server.py
+```
+
+The inspector provides:
+- Interactive tool testing
+- Request/response inspection
+- Error debugging
+
+---
+
+## Resources
+
+- **MCP Specification**: https://modelcontextprotocol.io/
+- **TypeScript SDK**: https://github.com/modelcontextprotocol/typescript-sdk
+- **Python SDK**: https://github.com/modelcontextprotocol/python-sdk
+- **FastMCP**: https://github.com/jlowin/fastmcp

package/.agents/skills/n8n-patterns/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: n8n-workflow-patterns
+description: Best practices and patterns for building production-ready n8n workflows. Use when designing, building, or debugging n8n automation workflows.
+---
+
+# n8n Workflow Patterns Guide
+
+## Overview
+
+n8n is a workflow automation platform that connects apps and services. This skill covers patterns for building maintainable, reliable, and scalable workflows.
+
+---
+
+## When to Use This Skill
+
+- Designing new n8n workflows
+- Refactoring existing workflows for better reliability
+- Debugging failing workflows
+- Building integrations between services
+- Creating scheduled automation
+
+---
+
+## Core Principles
+
+### 1. Workflow Design Patterns
+
+**Single Responsibility**
+Each workflow should do one thing well. Complex automations should be split into multiple workflows connected via:
+- Execute Workflow node
+- Webhook triggers
+- n8n API
+
+**Fail-Fast and Loud**
+- Use Error Trigger workflows for centralized error handling
+- Never silently swallow errors
+- Send notifications on failures
+
+**Idempotency**
+Design workflows to be safely re-runnable:
+- Check if action already performed before doing it
+- Use deduplication keys
+- Handle duplicate webhook calls gracefully
+
+### 2. Node Patterns
+
+**HTTP Request Node**
+```
+Best Practices:
+- Always set timeout (default 5 min is often too long)
+- Handle 4xx and 5xx errors explicitly
+- Use pagination for large datasets
+- Implement retry logic for transient failures
+```
+
+**Code Node**
+```javascript
+// Good: Input validation
+const input = $input.first().json;
+if (!input.email) {
+  throw new Error('Email is required');
+}
+
+// Good: Error handling with context
+try {
+  const result = await someAsyncOperation();
+  return [{ json: result }];
+} catch (error) {
+  // Log context for debugging
+  console.error('Operation failed:', { input: input.id, error: error.message });
+  throw error;
+}
+```
+
+**Function Node (Legacy)**
+Prefer Code Node over Function Node in new workflows.
+
+### 3. Data Handling
+
+**Passing Data Between Nodes**
+```javascript
+// Access previous node data
+const items = $input.all();
+const firstItem = $input.first().json;
+
+// Reference specific node output
+const data = $('Node Name').first().json;
+```
+
+**Transforming Data**
+```javascript
+// Map over items
+const results = items.map(item => ({
+  json: {
+    id: item.json.id,
+    name: item.json.name.toUpperCase(),
+    processed: true,
+  }
+}));
+return results;
+```
+
+### 4. Error Handling
+
+**Try-Catch Pattern**
+```javascript
+try {
+  // Risky operation
+  const result = await riskyCall();
+  return [{ json: { success: true, data: result } }];
+} catch (error) {
+  // Return error in structured format
+  return [{
+    json: {
+      success: false,
+      error: error.message,
+      timestamp: new Date().toISOString(),
+    }
+  }];
+}
+```
+
+**Error Workflow**
+Create a dedicated workflow for error handling:
+- Trigger: Error Trigger node
+- Actions: Log to database, send Slack/email notification, retry logic
+
+### 5. Credential Management
+
+**Security Best Practices**
+- Never hardcode credentials in Code nodes
+- Always use n8n credential system
+- Rotate credentials regularly
+- Use least-privilege access for service accounts
+
+**Custom Credentials**
+For custom APIs, create a generic credential type or use HTTP Request node with OAuth.
+
+---
+
+## Workflow Architecture Patterns
+
+### Pattern 1: Webhook Receiver
+```
+Webhook Node → Validation → Processing → Response
+                    ↓
+              Error Handler
+```
+
+Use for: Real-time integrations, external service callbacks
+
+### Pattern 2: Scheduled Job
+```
+Schedule Trigger → Data Fetch → Transform → Action → Notification
+```
+
+Use for: Daily reports, data sync, cleanup tasks
+
+### Pattern 3: Event-Driven Chain
+```
+Trigger → Filter → Enrich → Route → Multiple Actions
+                              ↙      ↓      ↘
+                           Action1 Action2 Action3
+```
+
+Use for: Complex automation with conditional branches
+
+### Pattern 4: Workflow Orchestration
+```
+Main Workflow → Execute Workflow (Sub-workflow 1)
+            → Execute Workflow (Sub-workflow 2)
+            → Aggregate Results
+```
+
+Use for: Complex multi-step processes, reusable components
+
+---
+
+## Debugging Workflows
+
+### Enable Execution Logging
+```
+Settings → Log Execution → Enable
+```
+
+### Use Debug Nodes
+Insert Set nodes to inspect data at specific points:
+```javascript
+// Debug node output
+{
+  "debug_stage": "after_api_call",
+  "raw_response": $input.first().json,
+  "item_count": $input.all().length
+}
+```
+
+### Common Issues
+
+**Issue: Data not passing between nodes**
+- Check if previous node outputs items
+- Verify item structure matches expected input
+- Use Code node to inspect `$input`
+
+**Issue: Workflow times out**
+- Add pagination for large datasets
+- Use Split In Batches node
+- Consider splitting into multiple workflows
+
+**Issue: Rate limiting**
+- Add Wait nodes between API calls
+- Implement exponential backoff
+- Use queue-based processing
+
+---
+
+## Performance Optimization
+
+### Batch Processing
+```
+Split In Batches (100 items/batch) → Process → Wait 1s → Loop
+```
+
+### Parallel Processing
+```
+                    → Process A
+Split → Route       → Process B
+                    → Process C
+```
+
+### Caching
+Use the Static Data feature to cache:
+- Access tokens
+- Reference data
+- Configuration
+
+---
+
+## Code Node Utilities
+
+### Common Helpers
+```javascript
+// Date formatting
+const now = new Date().toISOString();
+const formatted = new Date().toLocaleDateString('en-US');
+
+// Generate unique ID
+const id = Date.now().toString(36) + Math.random().toString(36).substr(2);
+
+// Sleep function
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+
+// Retry wrapper
+async function withRetry(fn, maxAttempts = 3) {
+  for (let i = 0; i < maxAttempts; i++) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (i === maxAttempts - 1) throw error;
+      await sleep(1000 * (i + 1)); // Exponential backoff
+    }
+  }
+}
+```
+
+---
+
+## Resources
+
+- **n8n Docs**: https://docs.n8n.io/
+- **Workflow Templates**: https://n8n.io/workflows
+- **Community Forum**: https://community.n8n.io/
+- **Node Reference**: https://docs.n8n.io/integrations/builtin/