@musashishao/agent-kit 1.9.0 → 1.9.1

package/.agent/skills/mcp-composition/SKILL.md

@@ -0,0 +1,362 @@
+---
+name: mcp-composition
+description: Multi-agent orchestration patterns with MCP. Pipelines, hierarchies, and agent-as-server design.
+version: "1.0.0"
+skills:
+  - mcp-builder
+  - parallel-agents
+  - ai-agents-architect
+---
+
+# 🎼 MCP Composition Patterns
+
+> Build complex multi-agent systems using MCP as the composition layer.
+
+---
+
+## Quick Reference
+
+| Pattern | Use Case |
+|---------|----------|
+| **Pipeline** | Sequential agent processing |
+| **Parallel** | Concurrent multi-agent tasks |
+| **Hierarchical** | Manager-worker orchestration |
+| **Agent-as-Server** | Expose agents as MCP tools |
+
+---
+
+## 1. Why MCP for Agent Composition?
+
+MCP provides a **standardized interface** for agents to:
+- Discover and invoke other agents
+- Share context across agent boundaries
+- Chain operations with type safety
+- Monitor and trace multi-agent flows
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Multi-Agent System                        │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│   ┌─────────┐     MCP      ┌─────────┐     MCP      ┌─────────┐
+│   │ Agent A │◄────────────►│ Agent B │◄────────────►│ Agent C │
+│   │ (Plan)  │              │ (Code)  │              │ (Review)│
+│   └─────────┘              └─────────┘              └─────────┘
+│                                                             │
+│   Each agent is both an MCP client AND an MCP server        │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Pattern: Pipeline (Sequential Chain)
+
+Agents process in sequence, each receiving output from the previous.
+
+```typescript
+// Pipeline configuration
+const pipeline = [
+  { agent: "planner", tool: "create_plan" },
+  { agent: "coder", tool: "implement_plan" },
+  { agent: "reviewer", tool: "review_code" },
+  { agent: "tester", tool: "write_tests" },
+];
+
+// Execute pipeline
+async function executePipeline(initialInput: string) {
+  let context = initialInput;
+  
+  for (const stage of pipeline) {
+    const result = await mcpClient.callTool(
+      stage.agent,
+      stage.tool,
+      { input: context }
+    );
+    
+    context = result;
+    console.log(`[${stage.agent}] completed`);
+  }
+  
+  return context;
+}
+```
+
+### When to Use
+- ✅ Linear workflows (plan → code → review)
+- ✅ Each stage depends on previous output
+- ✅ Clear handoff points
+
+### When to Avoid
+- ❌ Independent parallel tasks
+- ❌ Complex branching logic
+
+---
+
+## 3. Pattern: Parallel (Fan-Out/Fan-In)
+
+Multiple agents work simultaneously on independent tasks.
+
+```typescript
+// Parallel execution
+async function parallelAgents(input: string) {
+  const tasks = [
+    mcpClient.callTool("security-agent", "scan_vulnerabilities", { code: input }),
+    mcpClient.callTool("lint-agent", "check_style", { code: input }),
+    mcpClient.callTool("test-agent", "find_test_gaps", { code: input }),
+  ];
+  
+  // Wait for all to complete
+  const [security, lint, tests] = await Promise.all(tasks);
+  
+  // Aggregate results
+  return {
+    security: security.issues,
+    lint: lint.warnings,
+    tests: tests.gaps,
+    overall: computeScore(security, lint, tests),
+  };
+}
+```
+
+### When to Use
+- ✅ Independent analysis tasks
+- ✅ Multi-perspective review
+- ✅ Time-sensitive operations
+
+### When to Avoid
+- ❌ Sequential dependencies
+- ❌ Shared mutable state
+
+---
+
+## 4. Pattern: Hierarchical (Manager-Worker)
+
+A manager agent coordinates specialized worker agents.
+
+```typescript
+class OrchestratorAgent {
+  private workers = new Map<string, MCPClient>();
+  
+  async handle(request: string) {
+    // 1. Analyze request and plan
+    const plan = await this.plan(request);
+    
+    // 2. Delegate to workers
+    const results = await Promise.all(
+      plan.tasks.map(async (task) => {
+        const worker = this.selectWorker(task.type);
+        return worker.callTool(task.tool, task.args);
+      })
+    );
+    
+    // 3. Synthesize results
+    return this.synthesize(results);
+  }
+  
+  selectWorker(taskType: string): MCPClient {
+    const mapping = {
+      "frontend": "frontend-specialist",
+      "backend": "backend-specialist",
+      "security": "security-auditor",
+      "testing": "test-engineer",
+    };
+    return this.workers.get(mapping[taskType]);
+  }
+}
+```
+
+### When to Use
+- ✅ Complex multi-domain tasks
+- ✅ Dynamic task allocation
+- ✅ Expertise-based routing
+
+### When to Avoid
+- ❌ Simple single-domain tasks
+- ❌ When manager overhead > benefit
+
+---
+
+## 5. Agent-as-MCP-Server Pattern
+
+Expose any AI agent as an MCP server for composition.
+
+```typescript
+// Wrap agent as MCP server
+function agentToMCPServer(agent: Agent): McpServer {
+  const server = new McpServer({
+    name: agent.name,
+    version: agent.version,
+  });
+  
+  // Expose agent capabilities as tools
+  for (const capability of agent.capabilities) {
+    server.tool(
+      capability.name,
+      capability.description,
+      capability.schema,
+      async (args) => {
+        const result = await agent.execute(capability.name, args);
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      }
+    );
+  }
+  
+  // Expose agent context as resource
+  server.resource(
+    "agent-context",
+    `${agent.name}://context`,
+    async () => ({
+      contents: [{
+        uri: `${agent.name}://context`,
+        mimeType: "application/json",
+        text: JSON.stringify(agent.getContext()),
+      }]
+    })
+  );
+  
+  return server;
+}
+```
+
+### Benefits
+- 🔄 Any MCP client can invoke the agent
+- 📊 Standard observability
+- 🔐 Unified authentication
+- 🔌 Plugin architecture
+
+---
+
+## 6. Context Sharing
+
+### Shared Memory Pattern
+
+```typescript
+// Central context store (e.g., Redis)
+class SharedContext {
+  private store: Map<string, any> = new Map();
+  
+  async set(key: string, value: any, ttl?: number) {
+    this.store.set(key, { value, expires: Date.now() + (ttl || 3600000) });
+  }
+  
+  async get(key: string): Promise<any> {
+    const entry = this.store.get(key);
+    if (!entry || entry.expires < Date.now()) return null;
+    return entry.value;
+  }
+}
+
+// Usage across agents
+const context = new SharedContext();
+
+// Agent A writes
+await context.set("current_plan", { steps: [...] });
+
+// Agent B reads
+const plan = await context.get("current_plan");
+```
+
+### Context Propagation in MCP
+
+```typescript
+// Include context in tool calls
+const result = await mcpClient.callTool("coder", "implement", {
+  task: "Add login form",
+  context: {
+    project: "my-app",
+    tech_stack: ["React", "TypeScript"],
+    decisions: await context.get("decisions"),
+  }
+});
+```
+
+---
+
+## 7. Error Handling & Recovery
+
+### Retry Pattern
+
+```typescript
+async function callWithRetry(
+  agent: string, 
+  tool: string, 
+  args: any,
+  maxRetries = 3
+) {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      return await mcpClient.callTool(agent, tool, args);
+    } catch (error) {
+      if (attempt === maxRetries) throw error;
+      
+      // Exponential backoff
+      await sleep(Math.pow(2, attempt) * 1000);
+    }
+  }
+}
+```
+
+### Circuit Breaker
+
+```typescript
+class CircuitBreaker {
+  private failures = 0;
+  private lastFailure = 0;
+  private state: "closed" | "open" | "half-open" = "closed";
+  
+  async call<T>(fn: () => Promise<T>): Promise<T> {
+    if (this.state === "open") {
+      if (Date.now() - this.lastFailure > 30000) {
+        this.state = "half-open";
+      } else {
+        throw new Error("Circuit breaker open");
+      }
+    }
+    
+    try {
+      const result = await fn();
+      this.failures = 0;
+      this.state = "closed";
+      return result;
+    } catch (error) {
+      this.failures++;
+      this.lastFailure = Date.now();
+      
+      if (this.failures >= 5) {
+        this.state = "open";
+      }
+      throw error;
+    }
+  }
+}
+```
+
+---
+
+## 8. Composition Checklist
+
+### Before Building
+
+- [ ] Define clear agent responsibilities
+- [ ] Choose composition pattern
+- [ ] Design context sharing strategy
+- [ ] Plan error handling
+
+### Implementation
+
+- [ ] Wrap agents as MCP servers
+- [ ] Implement orchestration logic
+- [ ] Add retry/circuit breaker
+- [ ] Enable distributed tracing
+
+### Production
+
+- [ ] Monitor inter-agent latency
+- [ ] Set up alerts for failures
+- [ ] Document agent interactions
+- [ ] Version agent APIs
+
+---
+
+> **Key Insight:** MCP transforms the "how do agents talk to each other?" problem into a solved infrastructure concern, letting you focus on agent capabilities rather than communication protocols.

package/.agent/skills/mcp-observability/SKILL.md

@@ -0,0 +1,323 @@
+---
+name: mcp-observability
+description: OpenTelemetry integration for MCP servers. Tracing, metrics, LangSmith/Langfuse support.
+version: "1.0.0"
+skills:
+  - mcp-builder
+  - observability-patterns
+  - opentelemetry-expert
+---
+
+# 📊 MCP Observability
+
+> Comprehensive observability for MCP servers with OpenTelemetry, custom metrics, and LLM-specific tracing.
+
+---
+
+## Quick Reference
+
+| Topic | Description |
+|-------|-------------|
+| **Tracing** | Distributed traces for MCP tool calls |
+| **Metrics** | Latency, throughput, error rates |
+| **LLM Integration** | LangSmith, Langfuse, custom backends |
+
+---
+
+## 1. Why Observability for MCP?
+
+MCP servers are critical infrastructure for AI agents. Without observability:
+- 🔴 Tool failures are invisible
+- 🔴 Performance bottlenecks go unnoticed
+- 🔴 Agent behavior is a "black box"
+- 🔴 Debugging is guesswork
+
+With proper observability:
+- ✅ Every tool call is traced
+- ✅ Latency percentiles are visible
+- ✅ Error patterns are detectable
+- ✅ Agent flows are understandable
+
+---
+
+## 2. OpenTelemetry Integration
+
+### Setup
+
+```typescript
+import { initializeTracing, traceToolCall } from "./observability/otel.js";
+
+// Initialize at startup
+initializeTracing({
+  serviceName: "my-mcp-server",
+  serviceVersion: "1.0.0",
+  otlpEndpoint: "http://localhost:4318",
+});
+```
+
+### Trace Tool Calls
+
+```typescript
+server.tool("my_tool", "Description", schema, async (args) => {
+  // Automatically creates span with timing
+  return traceToolCall("my_tool", args, async () => {
+    // Tool implementation
+    const result = await doWork(args);
+    return { content: [{ type: "text", text: result }] };
+  });
+});
+```
+
+### Trace Structure
+
+```
+[TRACE: user-request-123]
+└─ [SPAN: mcp.request] 1200ms
+   ├─ [SPAN: mcp.tool.search_knowledge] 450ms
+   │  ├─ [SPAN: sync.check] 10ms
+   │  └─ [SPAN: search.execute] 430ms
+   ├─ [SPAN: mcp.tool.analyze_dependencies] 300ms
+   └─ [SPAN: mcp.tool.get_impact_zone] 400ms
+```
+
+---
+
+## 3. Metrics Collection
+
+### Key Metrics
+
+| Metric | Type | Description |
+|--------|------|-------------|
+| `mcp.tool.calls` | Counter | Total tool invocations |
+| `mcp.tool.duration` | Histogram | Tool execution time |
+| `mcp.tool.errors` | Counter | Failed tool calls |
+| `mcp.request.count` | Counter | Total MCP requests |
+| `mcp.sync.duration` | Histogram | Auto-sync execution time |
+
+### Collecting Metrics
+
+```typescript
+import { recordToolMetrics, getMetrics } from "./observability/otel.js";
+
+// Record after each tool call
+recordToolMetrics({
+  toolName: "search_knowledge",
+  duration: 450,
+  success: true,
+  inputTokens: 100,
+  outputTokens: 500,
+});
+
+// Expose metrics endpoint
+server.tool("get_metrics", "Get server metrics", {}, async () => {
+  const metrics = getMetrics();
+  return { content: [{ type: "text", text: JSON.stringify(metrics) }] };
+});
+```
+
+### Metrics Response Example
+
+```json
+{
+  "tools": {
+    "search_knowledge": {
+      "calls": 150,
+      "avgDuration": 320,
+      "p95Duration": 890,
+      "errorRate": 0.02
+    },
+    "analyze_dependencies": {
+      "calls": 45,
+      "avgDuration": 180,
+      "p95Duration": 450,
+      "errorRate": 0.0
+    }
+  },
+  "summary": {
+    "totalRequests": 195,
+    "avgDuration": 280,
+    "uptime": 86400
+  }
+}
+```
+
+---
+
+## 4. LangSmith Integration
+
+For AI-specific observability with LangChain's LangSmith:
+
+```typescript
+// Enable LangSmith tracing
+process.env.LANGCHAIN_TRACING_V2 = "true";
+process.env.LANGSMITH_API_KEY = "your-api-key";
+process.env.LANGSMITH_PROJECT = "mcp-gateway";
+
+// Traces automatically sent to LangSmith
+```
+
+### Benefits
+- View agent reasoning chains
+- See tool call sequences
+- Track LLM token usage
+- Compare prompt versions
+
+---
+
+## 5. Langfuse Integration
+
+For cost tracking and detailed LLM analytics:
+
+```typescript
+import { Langfuse } from "langfuse";
+
+const langfuse = new Langfuse({
+  publicKey: "pk-...",
+  secretKey: "sk-...",
+});
+
+// Create trace for MCP session
+const trace = langfuse.trace({
+  name: "mcp-session",
+  userId: sessionId,
+});
+
+// Track tool call
+const span = trace.span({
+  name: "tool.search_knowledge",
+  input: args,
+});
+
+// Update with result
+span.end({
+  output: result,
+  statusMessage: "success",
+});
+
+// Flush at end
+await langfuse.flush();
+```
+
+---
+
+## 6. Alerting Patterns
+
+### Critical Alerts
+
+| Condition | Threshold | Action |
+|-----------|-----------|--------|
+| Error rate > 5% | 5 minutes | PagerDuty |
+| P95 latency > 5s | 10 minutes | Slack |
+| Tool unavailable | Any | Immediate |
+
+### Warning Alerts
+
+| Condition | Threshold | Action |
+|-----------|-----------|--------|
+| Error rate > 1% | 15 minutes | Slack |
+| P95 latency > 2s | 30 minutes | Log |
+| Memory usage > 80% | 5 minutes | Scale |
+
+### Alert Configuration (Prometheus/AlertManager)
+
+```yaml
+groups:
+  - name: mcp-gateway
+    rules:
+      - alert: MCPHighErrorRate
+        expr: rate(mcp_tool_errors_total[5m]) / rate(mcp_tool_calls_total[5m]) > 0.05
+        for: 5m
+        labels:
+          severity: critical
+        annotations:
+          summary: "MCP Gateway error rate > 5%"
+          
+      - alert: MCPHighLatency
+        expr: histogram_quantile(0.95, mcp_tool_duration_seconds_bucket) > 5
+        for: 10m
+        labels:
+          severity: warning
+        annotations:
+          summary: "MCP Gateway P95 latency > 5s"
+```
+
+---
+
+## 7. Debugging with Traces
+
+### Finding Slow Tools
+
+```sql
+-- Query in Jaeger/Tempo
+SELECT 
+  resource.service.name,
+  span.name,
+  percentile(duration_ms, 95) as p95
+FROM traces
+WHERE service.name = 'mcp-gateway'
+GROUP BY span.name
+ORDER BY p95 DESC
+LIMIT 10
+```
+
+### Tracing Agent Flows
+
+```
+Agent: "Find files using authentication"
+  │
+  ├─► [MCP] search_knowledge("authentication") → 3 results
+  │
+  ├─► [MCP] analyze_dependencies("src/auth/login.ts") 
+  │     └─► imports: 5, imported_by: 12
+  │
+  └─► [MCP] get_impact_zone("src/auth/login.ts")
+        └─► affected: 12 files
+```
+
+---
+
+## 8. Best Practices
+
+### DO ✅
+
+- Trace all tool calls
+- Include input/output size in spans
+- Set meaningful span names
+- Propagate trace context
+- Sample appropriately for high volume
+
+### DON'T ❌
+
+- Log sensitive data in traces
+- Create spans for trivial operations
+- Forget to end spans (use try/finally)
+- Ignore cardinality explosion
+- Over-sample in production
+
+### Span Naming Convention
+
+```
+mcp.request              # Top-level MCP request
+mcp.tool.{name}          # Tool execution
+mcp.sync.{target}        # Sync operations
+mcp.search.{type}        # Search operations
+mcp.auth.{action}        # Authentication
+```
+
+---
+
+## 9. Production Checklist
+
+- [ ] OpenTelemetry SDK initialized
+- [ ] OTLP exporter configured
+- [ ] Sampling rate set (1.0 for dev, 0.1 for prod)
+- [ ] Service name and version set
+- [ ] Trace context propagation enabled
+- [ ] Metrics endpoint exposed
+- [ ] Alerts configured
+- [ ] Dashboard created
+- [ ] Log correlation enabled
+
+---
+
+> **Remember:** Observability is not optional for production MCP servers. The few milliseconds of tracing overhead are worth hours of debugging time saved.