aidevops 2.52.1

package/.agent/tools/build-mcp/api-wrapper.md

@@ -0,0 +1,445 @@
+---
+description: API wrapper pattern for REST API to MCP conversion
+mode: subagent
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  glob: true
+  grep: true
+  webfetch: true
+---
+
+# API Wrapper Pattern - REST API to MCP
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Purpose**: Template for wrapping any REST API as an MCP server
+- **Stack**: TypeScript + Bun + ElysiaJS + elysia-mcp
+- **Pattern**: One tool per API endpoint
+
+**Steps**:
+
+1. Identify API endpoints to expose
+2. Create Zod schemas for inputs
+3. Map HTTP methods to tools
+4. Handle authentication via env vars
+5. Return structured JSON responses
+
+<!-- AI-CONTEXT-END -->
+
+## Complete Template
+
+```typescript
+import { Elysia } from 'elysia';
+import { mcp } from 'elysia-mcp';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+
+// Configuration
+const API_BASE = process.env.API_BASE_URL || 'https://api.example.com';
+const API_KEY = process.env.API_KEY;
+
+if (!API_KEY) {
+  console.error('API_KEY environment variable is required');
+  process.exit(1);
+}
+
+// Helper for API requests
+async function apiRequest(
+  endpoint: string,
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE' = 'GET',
+  body?: unknown
+) {
+  const response = await fetch(`${API_BASE}${endpoint}`, {
+    method,
+    headers: {
+      'Authorization': `Bearer ${API_KEY}`,
+      'Content-Type': 'application/json',
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`API Error ${response.status}: ${error}`);
+  }
+
+  return response.json();
+}
+
+// MCP Server
+const app = new Elysia()
+  .use(
+    mcp({
+      serverInfo: {
+        name: 'example-api-mcp',
+        version: '1.0.0',
+      },
+      capabilities: {
+        tools: {},
+        resources: {},
+      },
+      setupServer: async (server: McpServer) => {
+        // LIST endpoint
+        server.tool(
+          'list_items',
+          {
+            page: z.number().optional().default(1).describe('Page number'),
+            limit: z.number().optional().default(20).describe('Items per page'),
+            filter: z.string().optional().describe('Filter query'),
+          },
+          async (args) => {
+            try {
+              const params = new URLSearchParams({
+                page: String(args.page),
+                limit: String(args.limit),
+                ...(args.filter && { filter: args.filter }),
+              });
+              const data = await apiRequest(`/items?${params}`);
+              return {
+                content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+              };
+            } catch (error) {
+              return {
+                content: [{
+                  type: 'text',
+                  text: JSON.stringify({ error: true, message: String(error) }),
+                }],
+                isError: true,
+              };
+            }
+          }
+        );
+
+        // GET endpoint
+        server.tool(
+          'get_item',
+          {
+            id: z.string().describe('Item ID'),
+          },
+          async (args) => {
+            try {
+              const data = await apiRequest(`/items/${args.id}`);
+              return {
+                content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+              };
+            } catch (error) {
+              return {
+                content: [{
+                  type: 'text',
+                  text: JSON.stringify({ error: true, message: String(error) }),
+                }],
+                isError: true,
+              };
+            }
+          }
+        );
+
+        // CREATE endpoint
+        server.tool(
+          'create_item',
+          {
+            name: z.string().describe('Item name'),
+            description: z.string().optional().describe('Item description'),
+            tags: z.array(z.string()).optional().describe('Item tags'),
+          },
+          async (args) => {
+            try {
+              const data = await apiRequest('/items', 'POST', args);
+              return {
+                content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+              };
+            } catch (error) {
+              return {
+                content: [{
+                  type: 'text',
+                  text: JSON.stringify({ error: true, message: String(error) }),
+                }],
+                isError: true,
+              };
+            }
+          }
+        );
+
+        // UPDATE endpoint
+        server.tool(
+          'update_item',
+          {
+            id: z.string().describe('Item ID'),
+            name: z.string().optional().describe('New name'),
+            description: z.string().optional().describe('New description'),
+            tags: z.array(z.string()).optional().describe('New tags'),
+          },
+          async (args) => {
+            try {
+              const { id, ...updates } = args;
+              const data = await apiRequest(`/items/${id}`, 'PUT', updates);
+              return {
+                content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+              };
+            } catch (error) {
+              return {
+                content: [{
+                  type: 'text',
+                  text: JSON.stringify({ error: true, message: String(error) }),
+                }],
+                isError: true,
+              };
+            }
+          }
+        );
+
+        // DELETE endpoint
+        server.tool(
+          'delete_item',
+          {
+            id: z.string().describe('Item ID'),
+            confirm: z.boolean().describe('Confirm deletion'),
+          },
+          async (args) => {
+            if (!args.confirm) {
+              return {
+                content: [{
+                  type: 'text',
+                  text: JSON.stringify({ error: true, message: 'Deletion not confirmed' }),
+                }],
+                isError: true,
+              };
+            }
+            try {
+              await apiRequest(`/items/${args.id}`, 'DELETE');
+              return {
+                content: [{
+                  type: 'text',
+                  text: JSON.stringify({ success: true, deleted: args.id }),
+                }],
+              };
+            } catch (error) {
+              return {
+                content: [{
+                  type: 'text',
+                  text: JSON.stringify({ error: true, message: String(error) }),
+                }],
+                isError: true,
+              };
+            }
+          }
+        );
+
+        // Expose API docs as resource
+        server.resource('API Documentation', 'resource://api-docs', async () => ({
+          contents: [{
+            uri: 'resource://api-docs',
+            mimeType: 'text/markdown',
+            text: `# Example API MCP
+
+## Available Tools
+
+- \`list_items\` - List all items with pagination
+- \`get_item\` - Get a single item by ID
+- \`create_item\` - Create a new item
+- \`update_item\` - Update an existing item
+- \`delete_item\` - Delete an item (requires confirmation)
+
+## Authentication
+
+API key is configured via \`API_KEY\` environment variable.
+`,
+          }],
+        }));
+      },
+    })
+  )
+  .listen(3000);
+
+console.log('MCP Server running on http://localhost:3000/mcp');
+```
+
+## Stdio Version (for OpenCode/Claude)
+
+```typescript
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const API_BASE = process.env.API_BASE_URL || 'https://api.example.com';
+const API_KEY = process.env.API_KEY;
+
+async function apiRequest(endpoint: string, method = 'GET', body?: unknown) {
+  const response = await fetch(`${API_BASE}${endpoint}`, {
+    method,
+    headers: {
+      'Authorization': `Bearer ${API_KEY}`,
+      'Content-Type': 'application/json',
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (!response.ok) throw new Error(`API Error ${response.status}`);
+  return response.json();
+}
+
+const server = new McpServer({
+  name: 'example-api-mcp',
+  version: '1.0.0',
+});
+
+server.tool(
+  'list_items',
+  { limit: z.number().optional().default(20) },
+  async (args) => {
+    const data = await apiRequest(`/items?limit=${args.limit}`);
+    return { content: [{ type: 'text', text: JSON.stringify(data) }] };
+  }
+);
+
+// Add more tools...
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+## OpenCode Configuration
+
+```json
+{
+  "mcp": {
+    "example-api": {
+      "type": "local",
+      "command": [
+        "/bin/bash",
+        "-c",
+        "API_KEY=$EXAMPLE_API_KEY bun run /path/to/example-api-mcp/src/index.ts"
+      ],
+      "enabled": true
+    }
+  }
+}
+```
+
+## Common API Patterns
+
+### Pagination
+
+```typescript
+server.tool(
+  'list_paginated',
+  {
+    cursor: z.string().optional().describe('Pagination cursor'),
+    limit: z.number().optional().default(50).describe('Items per page'),
+  },
+  async (args) => {
+    const params = new URLSearchParams({ limit: String(args.limit) });
+    if (args.cursor) params.set('cursor', args.cursor);
+    
+    const data = await apiRequest(`/items?${params}`);
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          items: data.items,
+          nextCursor: data.next_cursor,
+          hasMore: !!data.next_cursor,
+        }, null, 2),
+      }],
+    };
+  }
+);
+```
+
+### Search
+
+```typescript
+server.tool(
+  'search',
+  {
+    query: z.string().describe('Search query'),
+    fields: z.array(z.string()).optional().describe('Fields to search'),
+    sort: z.enum(['relevance', 'date', 'name']).optional().default('relevance'),
+  },
+  async (args) => {
+    const data = await apiRequest('/search', 'POST', {
+      q: args.query,
+      fields: args.fields,
+      sort: args.sort,
+    });
+    return {
+      content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+  }
+);
+```
+
+### Batch Operations
+
+```typescript
+server.tool(
+  'batch_update',
+  {
+    ids: z.array(z.string()).describe('Item IDs to update'),
+    updates: z.object({
+      status: z.string().optional(),
+      tags: z.array(z.string()).optional(),
+    }).describe('Updates to apply'),
+  },
+  async (args) => {
+    const results = await Promise.all(
+      args.ids.map(id => 
+        apiRequest(`/items/${id}`, 'PUT', args.updates)
+          .then(data => ({ id, success: true, data }))
+          .catch(error => ({ id, success: false, error: String(error) }))
+      )
+    );
+    return {
+      content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
+    };
+  }
+);
+```
+
+### File Upload
+
+```typescript
+server.tool(
+  'upload_file',
+  {
+    filename: z.string().describe('File name'),
+    content: z.string().describe('Base64 encoded file content'),
+    mimeType: z.string().optional().default('application/octet-stream'),
+  },
+  async (args) => {
+    const response = await fetch(`${API_BASE}/upload`, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${API_KEY}`,
+        'Content-Type': args.mimeType,
+        'X-Filename': args.filename,
+      },
+      body: Buffer.from(args.content, 'base64'),
+    });
+    const data = await response.json();
+    return {
+      content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+  }
+);
+```
+
+## Testing
+
+```bash
+# Start server
+bun run src/index.ts
+
+# Test with MCP Inspector
+npx @modelcontextprotocol/inspector
+# Connect to http://localhost:3000/mcp
+
+# Or test directly
+curl -X POST http://localhost:3000/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+```

package/.agent/tools/build-mcp/build-mcp.md

@@ -0,0 +1,240 @@
+---
+name: build-mcp
+description: MCP server development - building Model Context Protocol servers and tools
+mode: subagent
+---
+
+# Build-MCP - MCP Server Development Agent
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Purpose**: Build MCP servers with TypeScript + Bun + ElysiaJS
+- **Stack**: `@modelcontextprotocol/sdk` + `elysia-mcp` + Zod
+- **Starter**: `bun create https://github.com/kerlos/elysia-mcp-starter`
+- **Inspector**: `npx @modelcontextprotocol/inspector`
+
+**Quick Start**:
+
+```bash
+bun create https://github.com/kerlos/elysia-mcp-starter my-mcp
+cd my-mcp && bun install && bun run dev
+npx @modelcontextprotocol/inspector  # Connect to http://localhost:3000/mcp
+```
+
+**Subagents** (in this folder):
+
+| Subagent | When to Read |
+|----------|--------------|
+| `server-patterns.md` | Registering tools, resources, prompts |
+| `transports.md` | Configuring stdio, HTTP, SSE |
+| `deployment.md` | Adding MCP to AI assistants |
+| `api-wrapper.md` | Wrapping REST APIs as MCP |
+
+**Related Agents**:
+- `@code-standards` for linting TypeScript
+- `tools/context/context7.md` for MCP SDK docs
+
+**Git Workflow**:
+- Branch strategy: `workflows/branch.md`
+- Git operations: `tools/git.md`
+
+**Testing**: Use OpenCode CLI to test new MCPs without restarting TUI:
+
+```bash
+opencode run "Test [mcp] tools" --agent Build+
+```
+
+See `tools/opencode/opencode.md` for CLI testing patterns.
+
+**MCPs to Enable**: context7, augment-context-engine, repomix
+
+<!-- AI-CONTEXT-END -->
+
+## Why TypeScript + Bun + ElysiaJS?
+
+| Criterion | Why This Stack |
+|-----------|----------------|
+| **Robustness** | Official MCP SDK, Zod validation, full spec compliance |
+| **Speed** | Bun is 3-4x faster than Node.js |
+| **Maintainability** | End-to-end type safety, auto-generated OpenAPI docs |
+| **Future-Proof** | Anthropic-backed spec, growing ecosystem |
+
+## Project Structure
+
+```text
+my-mcp/
+├── src/
+│   ├── index.ts          # Server entry point
+│   ├── tools/            # Tool implementations
+│   ├── resources/        # Resource handlers
+│   └── prompts/          # Prompt templates
+├── package.json
+├── tsconfig.json
+└── bunfig.toml
+```
+
+## Core Patterns
+
+See `build-mcp/server-patterns.md` for complete tool, resource, and prompt registration patterns.
+
+**Minimal tool example**:
+
+```typescript
+server.tool(
+  'get_data',
+  { query: z.string().describe('Search query') },
+  async (args) => ({
+    content: [{ type: 'text', text: JSON.stringify(await fetchData(args.query)) }],
+  })
+);
+```
+
+## Transport Selection
+
+| Transport | Use Case |
+|-----------|----------|
+| stdio | Local dev, AI assistant spawns process |
+| StreamableHTTP | Production HTTP servers |
+| SSE | Legacy compatibility only |
+
+See `build-mcp/transports.md` for complete transport configuration.
+
+## Testing & Debugging
+
+```bash
+npx @modelcontextprotocol/inspector  # Connect to http://localhost:3000/mcp
+```
+
+Use `console.error()` for logging (stdout is MCP protocol).
+
+## Deployment
+
+See `build-mcp/deployment.md` for all AI assistant configurations.
+
+**OpenCode** (`~/.config/opencode/opencode.json`):
+
+```json
+{
+  "mcp": {
+    "my-mcp": {
+      "type": "local",
+      "command": ["bun", "run", "/path/to/my-mcp/src/index.ts"],
+      "enabled": true
+    }
+  }
+}
+```
+
+**Claude Code**: `claude mcp add my-mcp bun run /path/to/my-mcp/src/index.ts`
+
+## AI-Friendly Tool Design
+
+See `build-mcp/server-patterns.md` for complete naming conventions.
+
+**Key rules**:
+- Name: `verb_noun` pattern (`get_user`, `list_items`, `create_order`)
+- Description: What it does, when to use, what it returns, side effects
+- Parameters: Always use `.describe()` with constraints
+
+```typescript
+// Good
+server.tool(
+  'get_user',
+  'Retrieves user by ID. Returns profile or null if not found.',
+  { id: z.string().uuid().describe('User ID (UUID format)') }
+);
+```
+
+## Common Patterns (Not Yet in Subagents)
+
+These patterns are frequently needed but not yet documented in subagents:
+
+### Authentication
+
+```typescript
+// API Key from environment
+const API_KEY = process.env.API_KEY;
+if (!API_KEY) throw new Error('API_KEY required');
+
+// OAuth token refresh (implement in your auth module)
+async function getAccessToken(): Promise<string> {
+  // Check cache, refresh if expired
+}
+```
+
+### Rate Limiting
+
+```typescript
+import { Ratelimit } from '@upstash/ratelimit';
+import { Redis } from '@upstash/redis';
+
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(10, '10 s'),
+});
+
+// In tool handler
+const { success } = await ratelimit.limit(identifier);
+if (!success) return { content: [{ type: 'text', text: 'Rate limited' }], isError: true };
+```
+
+### Retry Logic
+
+```typescript
+async function withRetry<T>(fn: () => Promise<T>, retries = 3): Promise<T> {
+  for (let i = 0; i < retries; i++) {
+    try { return await fn(); }
+    catch (e) { if (i === retries - 1) throw e; await sleep(1000 * 2 ** i); }
+  }
+  throw new Error('Unreachable');
+}
+```
+
+## Quality Standards
+
+1. **Validation**: Zod schemas with `.describe()`
+2. **Errors**: Return structured JSON in content, set `isError: true`
+3. **Logging**: `console.error()` only (stdout is protocol)
+4. **Types**: Export input/output types
+
+Run `@code-standards` before committing TypeScript.
+
+## References
+
+Use Context7 MCP for current documentation:
+- MCP SDK: `resolve library-id for @modelcontextprotocol/sdk`
+- ElysiaJS: `resolve library-id for elysia`
+- Bun: `resolve library-id for bun`
+
+## Oh-My-OpenCode Integration
+
+When oh-my-opencode is installed, leverage these specialized agents for enhanced MCP development:
+
+| OmO Agent | When to Use | Example |
+|-----------|-------------|---------|
+| `@oracle` | MCP architecture, API design, debugging strategy | "Ask @oracle to review this MCP tool structure" |
+| `@librarian` | Find MCP examples, SDK patterns, similar implementations | "Ask @librarian for MCP tool registration examples" |
+| `@frontend-ui-ux-engineer` | If MCP has web UI components | "Ask @frontend-ui-ux-engineer to build the MCP dashboard" |
+
+**MCP Development Workflow Enhancement**:
+
+```text
+1. Design → @oracle reviews API structure
+2. Patterns → @librarian finds SDK examples
+3. Implement → Build-MCP creates server
+4. Test → MCP Inspector validates
+5. Deploy → Configure in AI assistants
+```
+
+**LSP Tools for TypeScript MCP Development**:
+
+When oh-my-opencode is installed, use LSP tools for better TypeScript development:
+- `lsp_goto_definition` - Navigate to MCP SDK types
+- `lsp_find_references` - Find all tool usages
+- `lsp_rename` - Safely rename tools across codebase
+- `lsp_diagnostics` - Catch TypeScript errors before runtime
+
+**Note**: These agents require [oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode) plugin.
+See `tools/opencode/oh-my-opencode.md` for installation.