aidevops 2.52.1 → 2.53.2

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

@@ -1,632 +0,0 @@
----
-description: MCP server patterns for tools, resources, and prompts
-mode: subagent
-tools:
-  read: true
-  write: true
-  edit: true
-  bash: true
-  glob: true
-  grep: true
-  webfetch: true
----
-
-# MCP Server Patterns - Tools, Resources, Prompts
-
-<!-- AI-CONTEXT-START -->
-
-## Quick Reference
-
-- **Purpose**: Patterns for registering MCP tools, resources, and prompts
-- **Validation**: Always use Zod schemas with `.describe()`
-- **SDK**: `@modelcontextprotocol/sdk` + `elysia-mcp`
-
-**Pattern Types**:
-
-| Type | Purpose | Naming Pattern | Example |
-|------|---------|----------------|---------|
-| Tool | Execute actions, call APIs | `verb_noun` | `get_user`, `create_item` |
-| Resource | Expose data/files | `protocol://path` | `config://settings` |
-| Prompt | Reusable prompt templates | `action` or `action_context` | `summarize`, `code_review` |
-
-**Tool Naming Quick Reference**:
-
-| Verb | Use Case | Examples |
-|------|----------|----------|
-| `get` | Single item by ID | `get_user`, `get_config` |
-| `list` | Multiple items | `list_users`, `list_files` |
-| `search` | Query with filters | `search_docs`, `search_logs` |
-| `create` | New resource | `create_user`, `create_project` |
-| `update` | Modify existing | `update_user`, `update_settings` |
-| `delete` | Remove resource | `delete_user`, `delete_file` |
-
-<!-- AI-CONTEXT-END -->
-
-## Tool Patterns
-
-### Basic Tool
-
-```typescript
-import { z } from 'zod';
-
-server.tool(
-  'greet',
-  {
-    name: z.string().describe('Name to greet'),
-  },
-  async (args) => ({
-    content: [{ type: 'text', text: `Hello, ${args.name}!` }],
-  })
-);
-```
-
-### Tool with Optional Parameters
-
-```typescript
-server.tool(
-  'search',
-  {
-    query: z.string().describe('Search query'),
-    limit: z.number().optional().default(10).describe('Max results'),
-    offset: z.number().optional().default(0).describe('Result offset'),
-  },
-  async (args) => {
-    const results = await performSearch(args.query, args.limit, args.offset);
-    return {
-      content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
-    };
-  }
-);
-```
-
-### Tool with Enum Validation
-
-```typescript
-server.tool(
-  'set_status',
-  {
-    status: z.enum(['active', 'inactive', 'pending']).describe('New status'),
-    reason: z.string().optional().describe('Reason for change'),
-  },
-  async (args) => {
-    await updateStatus(args.status, args.reason);
-    return {
-      content: [{ type: 'text', text: `Status updated to: ${args.status}` }],
-    };
-  }
-);
-```
-
-### Tool with Complex Input
-
-```typescript
-const AddressSchema = z.object({
-  street: z.string(),
-  city: z.string(),
-  country: z.string(),
-  postal: z.string().optional(),
-});
-
-server.tool(
-  'create_contact',
-  {
-    name: z.string().describe('Contact name'),
-    email: z.string().email().describe('Email address'),
-    phone: z.string().optional().describe('Phone number'),
-    address: AddressSchema.optional().describe('Mailing address'),
-  },
-  async (args) => {
-    const contact = await createContact(args);
-    return {
-      content: [{ type: 'text', text: JSON.stringify(contact) }],
-    };
-  }
-);
-```
-
-### Tool with Structured Output
-
-```typescript
-server.registerTool(
-  'calculate',
-  {
-    title: 'Calculator',
-    description: 'Perform mathematical calculations',
-    inputSchema: {
-      expression: z.string().describe('Math expression to evaluate'),
-    },
-    outputSchema: {
-      result: z.number(),
-      expression: z.string(),
-      timestamp: z.string(),
-    },
-  },
-  async ({ expression }) => {
-    const result = evaluate(expression);
-    const output = {
-      result,
-      expression,
-      timestamp: new Date().toISOString(),
-    };
-    return {
-      content: [{ type: 'text', text: JSON.stringify(output) }],
-      structuredContent: output,
-    };
-  }
-);
-```
-
-### Tool with Error Handling
-
-```typescript
-server.tool(
-  'fetch_data',
-  {
-    url: z.string().url().describe('URL to fetch'),
-  },
-  async (args) => {
-    try {
-      const response = await fetch(args.url);
-      if (!response.ok) {
-        return {
-          content: [{
-            type: 'text',
-            text: JSON.stringify({
-              error: true,
-              status: response.status,
-              message: `HTTP ${response.status}: ${response.statusText}`,
-            }),
-          }],
-          isError: true,
-        };
-      }
-      const data = await response.json();
-      return {
-        content: [{ type: 'text', text: JSON.stringify(data) }],
-      };
-    } catch (error) {
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({
-            error: true,
-            message: error instanceof Error ? error.message : 'Unknown error',
-          }),
-        }],
-        isError: true,
-      };
-    }
-  }
-);
-```
-
-## Resource Patterns
-
-### Static Resource
-
-```typescript
-server.resource('README', 'resource://readme', async () => ({
-  contents: [{
-    uri: 'resource://readme',
-    mimeType: 'text/markdown',
-    text: '# My MCP Server\n\nThis server provides...',
-  }],
-}));
-```
-
-### Dynamic Resource
-
-```typescript
-server.resource('Config', 'resource://config', async () => {
-  const config = await loadConfig();
-  return {
-    contents: [{
-      uri: 'resource://config',
-      mimeType: 'application/json',
-      text: JSON.stringify(config, null, 2),
-    }],
-  };
-});
-```
-
-### File Resource
-
-```typescript
-import { readFile } from 'fs/promises';
-
-server.resource('Schema', 'file://schema.json', async () => {
-  const content = await readFile('./schema.json', 'utf-8');
-  return {
-    contents: [{
-      uri: 'file://schema.json',
-      mimeType: 'application/json',
-      text: content,
-    }],
-  };
-});
-```
-
-### Resource with Parameters
-
-```typescript
-// Register a resource template
-server.resource(
-  'User Profile',
-  'resource://user/{id}',
-  async (uri) => {
-    const id = uri.pathname.split('/').pop();
-    const user = await getUser(id);
-    return {
-      contents: [{
-        uri: uri.href,
-        mimeType: 'application/json',
-        text: JSON.stringify(user),
-      }],
-    };
-  }
-);
-```
-
-### Binary Resource
-
-```typescript
-server.resource('Logo', 'resource://logo.png', async () => {
-  const buffer = await readFile('./logo.png');
-  return {
-    contents: [{
-      uri: 'resource://logo.png',
-      mimeType: 'image/png',
-      blob: buffer.toString('base64'),
-    }],
-  };
-});
-```
-
-## Prompt Patterns
-
-### Simple Prompt
-
-```typescript
-server.prompt(
-  'summarize',
-  'Summarize the given text',
-  {
-    text: z.string().describe('Text to summarize'),
-  },
-  async (args) => ({
-    description: 'Text summarization prompt',
-    messages: [{
-      role: 'user',
-      content: { type: 'text', text: `Please summarize:\n\n${args.text}` },
-    }],
-  })
-);
-```
-
-### Prompt with System Message
-
-```typescript
-server.prompt(
-  'code_review',
-  'Review code for issues',
-  {
-    code: z.string().describe('Code to review'),
-    language: z.string().optional().describe('Programming language'),
-  },
-  async (args) => ({
-    description: 'Code review prompt',
-    messages: [
-      {
-        role: 'system',
-        content: {
-          type: 'text',
-          text: 'You are an expert code reviewer. Focus on security, performance, and maintainability.',
-        },
-      },
-      {
-        role: 'user',
-        content: {
-          type: 'text',
-          text: `Review this ${args.language || 'code'}:\n\n\`\`\`${args.language || ''}\n${args.code}\n\`\`\``,
-        },
-      },
-    ],
-  })
-);
-```
-
-### Prompt with Context
-
-```typescript
-server.prompt(
-  'analyze_with_context',
-  'Analyze data with additional context',
-  {
-    data: z.string().describe('Data to analyze'),
-    context: z.string().optional().describe('Additional context'),
-    focus: z.enum(['performance', 'security', 'quality']).describe('Analysis focus'),
-  },
-  async (args) => ({
-    description: `${args.focus} analysis prompt`,
-    messages: [
-      ...(args.context ? [{
-        role: 'system' as const,
-        content: { type: 'text' as const, text: args.context },
-      }] : []),
-      {
-        role: 'user',
-        content: {
-          type: 'text',
-          text: `Analyze the following with focus on ${args.focus}:\n\n${args.data}`,
-        },
-      },
-    ],
-  })
-);
-```
-
-## Tool Naming Conventions
-
-AI assistants select tools based on names and descriptions. Follow these conventions for optimal discoverability:
-
-### Naming Pattern: `verb_noun`
-
-```text
-Format: {action}_{resource}
-Examples: get_user, list_items, create_order, delete_file, search_documents
-```
-
-| Verb | When to Use | Examples |
-|------|-------------|----------|
-| `get` | Retrieve single item by ID | `get_user`, `get_order`, `get_config` |
-| `list` | Retrieve multiple items | `list_users`, `list_orders`, `list_files` |
-| `search` | Query with filters | `search_documents`, `search_logs` |
-| `create` | Create new resource | `create_user`, `create_project` |
-| `update` | Modify existing resource | `update_user`, `update_settings` |
-| `delete` | Remove resource | `delete_user`, `delete_file` |
-| `validate` | Check validity | `validate_email`, `validate_config` |
-| `convert` | Transform format | `convert_currency`, `convert_image` |
-| `send` | Transmit data | `send_email`, `send_notification` |
-| `run` | Execute process | `run_build`, `run_tests` |
-
-### Naming Anti-Patterns
-
-```typescript
-// BAD: Vague or generic names
-'do_thing'        // What thing?
-'process'         // Process what?
-'handle_data'     // Too generic
-'execute'         // Execute what?
-
-// BAD: Inconsistent casing
-'getUser'         // Use snake_case, not camelCase
-'Get_User'        // Inconsistent capitalization
-'GET_USER'        // All caps
-
-// BAD: Redundant prefixes
-'tool_get_user'   // "tool_" prefix is redundant
-'mcp_list_items'  // "mcp_" prefix is redundant
-
-// GOOD: Clear, consistent, descriptive
-'get_user'
-'list_items'
-'search_documents'
-'create_order'
-```
-
-### Compound Actions
-
-For complex operations, use descriptive compound names:
-
-```typescript
-// Multi-step operations
-'get_user_with_orders'    // Returns user + their orders
-'list_active_sessions'    // Filtered list
-'search_and_replace'      // Combined action
-
-// Domain-specific operations
-'deploy_to_production'
-'sync_inventory'
-'generate_report'
-'export_to_csv'
-```
-
-## Tool Description Guidelines
-
-Descriptions are critical for AI assistants to understand when and how to use tools.
-
-### Description Structure
-
-Every tool description should answer:
-
-1. **What** - What does this tool do?
-2. **When** - When should an AI use this tool?
-3. **Input** - What inputs are required/optional?
-4. **Output** - What does it return?
-5. **Side Effects** - Does it modify state?
-
-### Description Template
-
-```typescript
-server.tool(
-  'create_user',
-  // Description should be 1-2 sentences covering purpose and key behavior
-  'Creates a new user account with the specified details. Returns the created user object with generated ID.',
-  {
-    email: z.string().email().describe('User email address (must be unique)'),
-    name: z.string().describe('Full name of the user'),
-    role: z.enum(['admin', 'user', 'guest']).optional().describe('User role (default: user)'),
-  },
-  async (args) => { /* ... */ }
-);
-```
-
-### Good vs Bad Descriptions
-
-```typescript
-// BAD: Too vague
-server.tool('get_data', 'Gets data', { /* ... */ });
-
-// BAD: Missing key information
-server.tool('delete_user', 'Deletes a user', { /* ... */ });
-// Missing: What happens to user's data? Is this reversible?
-
-// BAD: Too technical, not AI-friendly
-server.tool('query_db', 'Executes SELECT * FROM users WHERE id = ?', { /* ... */ });
-
-// GOOD: Clear purpose, behavior, and constraints
-server.tool(
-  'get_user',
-  'Retrieves a user by their unique ID. Returns user profile including name, email, and role. Returns null if user not found.',
-  { id: z.string().uuid().describe('Unique user identifier (UUID format)') }
-);
-
-// GOOD: Explains side effects
-server.tool(
-  'delete_user',
-  'Permanently deletes a user account and all associated data. This action cannot be undone. Requires admin privileges.',
-  { id: z.string().uuid().describe('User ID to delete') }
-);
-
-// GOOD: Explains when to use
-server.tool(
-  'search_documents',
-  'Full-text search across all documents. Use this when looking for documents by content rather than by ID. Supports wildcards and phrase matching.',
-  {
-    query: z.string().describe('Search query (supports * wildcards and "exact phrases")'),
-    limit: z.number().optional().default(20).describe('Maximum results to return'),
-  }
-);
-```
-
-### Parameter Description Best Practices
-
-```typescript
-// BAD: No description
-query: z.string()
-
-// BAD: Redundant description
-query: z.string().describe('Query')
-
-// BAD: Missing constraints
-limit: z.number().describe('Limit')
-
-// GOOD: Explains purpose and constraints
-query: z.string().describe('Search query - supports wildcards (*) and exact phrases ("...")')
-
-// GOOD: Includes valid values
-status: z.enum(['pending', 'active', 'completed']).describe('Filter by status')
-
-// GOOD: Explains defaults and ranges
-limit: z.number().min(1).max(100).optional().default(20)
-  .describe('Results per page (1-100, default: 20)')
-
-// GOOD: Explains format requirements
-date: z.string().describe('Date in ISO 8601 format (YYYY-MM-DD)')
-
-// GOOD: Explains relationships
-user_id: z.string().uuid().describe('ID of the user who owns this resource')
-```
-
-### Indicating Side Effects
-
-Always document if a tool modifies state:
-
-```typescript
-// Read-only tool - no side effects
-server.tool(
-  'get_user',
-  'Retrieves user details. Read-only operation.',
-  { /* ... */ }
-);
-
-// Write operation - has side effects
-server.tool(
-  'update_user',
-  'Updates user profile fields. Modifies the user record in the database.',
-  { /* ... */ }
-);
-
-// Destructive operation - irreversible
-server.tool(
-  'delete_user',
-  'Permanently deletes user and all data. IRREVERSIBLE. Requires confirmation.',
-  { /* ... */ }
-);
-
-// External side effects
-server.tool(
-  'send_email',
-  'Sends an email to the specified recipient. Cannot be undone once sent.',
-  { /* ... */ }
-);
-```
-
-## Best Practices
-
-### 1. Always Describe Parameters
-
-```typescript
-// Good
-query: z.string().describe('Search query to find matching items')
-
-// Bad
-query: z.string()
-```
-
-### 2. Use Specific Types
-
-```typescript
-// Good
-email: z.string().email().describe('User email address')
-url: z.string().url().describe('Webhook URL')
-count: z.number().int().positive().describe('Number of items')
-
-// Bad
-email: z.string()
-url: z.string()
-count: z.number()
-```
-
-### 3. Provide Defaults for Optional Parameters
-
-```typescript
-// Good
-limit: z.number().optional().default(20).describe('Max results (default: 20)')
-
-// Okay but less clear
-limit: z.number().optional().describe('Max results')
-```
-
-### 4. Return Structured JSON
-
-```typescript
-// Good - structured, parseable
-return {
-  content: [{
-    type: 'text',
-    text: JSON.stringify({ success: true, data: result }, null, 2),
-  }],
-};
-
-// Bad - unstructured text
-return {
-  content: [{ type: 'text', text: `Success! Got ${result.length} items` }],
-};
-```
-
-### 5. Handle Errors Gracefully
-
-```typescript
-// Good - structured error
-return {
-  content: [{
-    type: 'text',
-    text: JSON.stringify({ error: true, code: 'NOT_FOUND', message: 'Item not found' }),
-  }],
-  isError: true,
-};
-
-// Bad - throws exception
-throw new Error('Item not found');
-```