codingbuddy-rules 4.5.0 → 5.1.0

package/.ai-rules/skills/mcp-builder/examples/resource-example.ts

@@ -0,0 +1,233 @@
+/**
+ * MCP Resource Implementation Example
+ *
+ * Demonstrates a complete Resource handler following the MCP specification.
+ * Resources are read-only data exposed via URI that the AI can read.
+ *
+ * Key patterns:
+ * - URI-based addressing with scheme://path convention
+ * - Resource templates for dynamic URIs
+ * - List + Read separation
+ * - Proper MIME type handling
+ */
+
+import { Injectable } from '@nestjs/common';
+
+// --- 1. Define Static Resources ---
+
+export const staticResources = [
+  {
+    uri: 'config://project',
+    name: 'Project Configuration',
+    description: 'Current project settings including tech stack, conventions, and build config',
+    mimeType: 'application/json',
+  },
+  {
+    uri: 'docs://changelog',
+    name: 'Changelog',
+    description: 'Project changelog with recent changes and version history',
+    mimeType: 'text/markdown',
+  },
+];
+
+// --- 2. Define Resource Templates (Dynamic URIs) ---
+
+export const resourceTemplates = [
+  {
+    uriTemplate: 'rules://{ruleName}',
+    name: 'AI Rule',
+    description: 'Retrieve a specific AI coding rule by name (e.g., "core", "project")',
+    mimeType: 'text/markdown',
+  },
+  {
+    uriTemplate: 'agents://{agentName}',
+    name: 'Agent Definition',
+    description: 'Retrieve a specialist agent definition by name (e.g., "solution-architect")',
+    mimeType: 'application/json',
+  },
+  {
+    uriTemplate: 'skills://{skillName}',
+    name: 'Skill Content',
+    description: 'Retrieve a skill definition by name (e.g., "mcp-builder", "api-design")',
+    mimeType: 'text/markdown',
+  },
+];
+
+// --- 3. Result Types ---
+
+interface ResourceContent {
+  uri: string;
+  mimeType: string;
+  text: string;
+}
+
+// --- 4. Implement the Resource Handler ---
+
+@Injectable()
+export class ResourceHandler {
+  constructor(
+    private readonly rulesService: RulesService,
+    private readonly agentsService: AgentsService,
+    private readonly configService: ConfigService,
+  ) {}
+
+  /**
+   * List all available resources (static + dynamic discovered).
+   * Called by MCP client via resources/list.
+   */
+  async listResources(): Promise<typeof staticResources> {
+    // Static resources are always available
+    const resources = [...staticResources];
+
+    // Dynamically discover available rules
+    const ruleNames = await this.rulesService.listRuleNames();
+    for (const name of ruleNames) {
+      resources.push({
+        uri: `rules://${name}`,
+        name: `Rule: ${name}`,
+        description: `AI coding rule: ${name}`,
+        mimeType: 'text/markdown',
+      });
+    }
+
+    return resources;
+  }
+
+  /**
+   * Read a specific resource by URI.
+   * Called by MCP client via resources/read.
+   */
+  async readResource(uri: string): Promise<ResourceContent> {
+    // Parse the URI scheme and path
+    const match = uri.match(/^(\w+):\/\/(.+)$/);
+    if (!match) {
+      throw new ResourceNotFoundError(`Invalid resource URI format: ${uri}`);
+    }
+
+    const [, scheme, path] = match;
+
+    switch (scheme) {
+      case 'config':
+        return this.readConfig(uri, path);
+      case 'docs':
+        return this.readDocs(uri, path);
+      case 'rules':
+        return this.readRule(uri, path);
+      case 'agents':
+        return this.readAgent(uri, path);
+      case 'skills':
+        return this.readSkill(uri, path);
+      default:
+        throw new ResourceNotFoundError(`Unknown resource scheme: ${scheme}`);
+    }
+  }
+
+  private async readConfig(uri: string, path: string): Promise<ResourceContent> {
+    if (path !== 'project') {
+      throw new ResourceNotFoundError(`Unknown config resource: ${path}`);
+    }
+
+    const config = await this.configService.getProjectConfig();
+    return {
+      uri,
+      mimeType: 'application/json',
+      text: JSON.stringify(config, null, 2),
+    };
+  }
+
+  private async readDocs(uri: string, path: string): Promise<ResourceContent> {
+    if (path !== 'changelog') {
+      throw new ResourceNotFoundError(`Unknown docs resource: ${path}`);
+    }
+
+    const changelog = await this.rulesService.readFile('CHANGELOG.md');
+    return {
+      uri,
+      mimeType: 'text/markdown',
+      text: changelog,
+    };
+  }
+
+  private async readRule(uri: string, ruleName: string): Promise<ResourceContent> {
+    const content = await this.rulesService.getRule(ruleName);
+    if (!content) {
+      throw new ResourceNotFoundError(`Rule not found: ${ruleName}`);
+    }
+
+    return {
+      uri,
+      mimeType: 'text/markdown',
+      text: content,
+    };
+  }
+
+  private async readAgent(uri: string, agentName: string): Promise<ResourceContent> {
+    const agent = await this.agentsService.getAgent(agentName);
+    if (!agent) {
+      throw new ResourceNotFoundError(`Agent not found: ${agentName}`);
+    }
+
+    return {
+      uri,
+      mimeType: 'application/json',
+      text: JSON.stringify(agent, null, 2),
+    };
+  }
+
+  private async readSkill(uri: string, skillName: string): Promise<ResourceContent> {
+    const content = await this.rulesService.getSkill(skillName);
+    if (!content) {
+      throw new ResourceNotFoundError(`Skill not found: ${skillName}`);
+    }
+
+    return {
+      uri,
+      mimeType: 'text/markdown',
+      text: content,
+    };
+  }
+}
+
+// --- 5. Register in MCP Service ---
+
+/*
+// In mcp.service.ts:
+import { staticResources, resourceTemplates, ResourceHandler } from './resources/resource-handler';
+
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+  resources: await this.resourceHandler.listResources(),
+}));
+
+server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
+  resourceTemplates,
+}));
+
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => ({
+  contents: [await this.resourceHandler.readResource(request.params.uri)],
+}));
+*/
+
+// --- Error Types ---
+
+class ResourceNotFoundError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ResourceNotFoundError';
+  }
+}
+
+// Placeholder interfaces for dependency injection
+interface RulesService {
+  listRuleNames(): Promise<string[]>;
+  getRule(name: string): Promise<string | null>;
+  getSkill(name: string): Promise<string | null>;
+  readFile(path: string): Promise<string>;
+}
+
+interface AgentsService {
+  getAgent(name: string): Promise<Record<string, unknown> | null>;
+}
+
+interface ConfigService {
+  getProjectConfig(): Promise<Record<string, unknown>>;
+}

package/.ai-rules/skills/mcp-builder/examples/tool-example.ts

@@ -0,0 +1,198 @@
+/**
+ * MCP Tool Implementation Example
+ *
+ * Demonstrates a complete Tool handler following the MCP specification.
+ * Tools are functions the AI can call that may have side effects.
+ *
+ * Key patterns:
+ * - Schema-first design with JSON Schema validation
+ * - Structured error responses with isError flag
+ * - Input validation before processing
+ * - NestJS injectable service pattern
+ */
+
+import { Injectable } from '@nestjs/common';
+
+// --- 1. Define the Tool Schema (JSON Schema) ---
+
+export const fileAnalyzerToolSchema = {
+  name: 'analyze_file',
+  description:
+    'Analyze a source file for code quality metrics including complexity, ' +
+    'line count, and dependency analysis. Use when reviewing code quality ' +
+    'or planning refactoring.',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      filePath: {
+        type: 'string',
+        description: 'Relative path to the file from project root (e.g., "src/utils/parser.ts")',
+        minLength: 1,
+        maxLength: 500,
+      },
+      metrics: {
+        type: 'array',
+        description: 'Specific metrics to analyze (default: all)',
+        items: {
+          type: 'string',
+          enum: ['complexity', 'lines', 'dependencies', 'exports'],
+        },
+        default: ['complexity', 'lines', 'dependencies', 'exports'],
+      },
+      includeSource: {
+        type: 'boolean',
+        description: 'Whether to include the source code in the response (default: false)',
+        default: false,
+      },
+    },
+    required: ['filePath'],
+  },
+};
+
+// --- 2. Define Result Types ---
+
+interface ToolResult {
+  content: Array<{ type: 'text'; text: string }>;
+  isError?: boolean;
+}
+
+interface FileAnalysis {
+  filePath: string;
+  lineCount: number;
+  complexity: number;
+  dependencies: string[];
+  exports: string[];
+}
+
+// --- 3. Implement the Tool Handler ---
+
+@Injectable()
+export class FileAnalyzerHandler {
+  constructor(private readonly fileService: FileService) {}
+
+  async handle(params: {
+    filePath: string;
+    metrics?: string[];
+    includeSource?: boolean;
+  }): Promise<ToolResult> {
+    // Step 1: Validate input
+    if (!params.filePath?.trim()) {
+      return this.errorResult('filePath is required and cannot be empty');
+    }
+
+    if (params.filePath.includes('..')) {
+      return this.errorResult('filePath cannot contain path traversal (..)');
+    }
+
+    // Step 2: Check file exists
+    const exists = await this.fileService.exists(params.filePath);
+    if (!exists) {
+      return this.errorResult(`File not found: ${params.filePath}`);
+    }
+
+    // Step 3: Perform analysis
+    try {
+      const analysis = await this.analyze(params.filePath, params.metrics);
+      const output = this.formatAnalysis(analysis, params.includeSource);
+
+      return {
+        content: [{ type: 'text', text: output }],
+      };
+    } catch (error) {
+      return this.errorResult(
+        `Analysis failed for ${params.filePath}: ${(error as Error).message}`,
+      );
+    }
+  }
+
+  private async analyze(filePath: string, metrics?: string[]): Promise<FileAnalysis> {
+    const content = await this.fileService.read(filePath);
+    const lines = content.split('\n');
+    const selected = new Set(metrics ?? ['complexity', 'lines', 'dependencies', 'exports']);
+
+    return {
+      filePath,
+      lineCount: selected.has('lines') ? lines.length : -1,
+      complexity: selected.has('complexity') ? this.calculateComplexity(lines) : -1,
+      dependencies: selected.has('dependencies') ? this.extractDependencies(lines) : [],
+      exports: selected.has('exports') ? this.extractExports(lines) : [],
+    };
+  }
+
+  private calculateComplexity(lines: string[]): number {
+    const complexityKeywords = /\b(if|else|for|while|switch|case|catch|&&|\|\||\?)\b/g;
+    return lines.reduce((sum, line) => {
+      const matches = line.match(complexityKeywords);
+      return sum + (matches?.length ?? 0);
+    }, 1); // Base complexity of 1
+  }
+
+  private extractDependencies(lines: string[]): string[] {
+    const importPattern = /^import\s+.*from\s+['"]([^'"]+)['"]/;
+    return lines
+      .map(line => line.match(importPattern)?.[1])
+      .filter((dep): dep is string => dep !== undefined);
+  }
+
+  private extractExports(lines: string[]): string[] {
+    const exportPattern =
+      /^export\s+(?:default\s+)?(?:class|function|const|interface|type|enum)\s+(\w+)/;
+    return lines
+      .map(line => line.match(exportPattern)?.[1])
+      .filter((name): name is string => name !== undefined);
+  }
+
+  private formatAnalysis(analysis: FileAnalysis, includeSource?: boolean): string {
+    const sections: string[] = [`## File Analysis: ${analysis.filePath}`, ''];
+
+    if (analysis.lineCount >= 0) {
+      sections.push(`**Lines:** ${analysis.lineCount}`);
+    }
+    if (analysis.complexity >= 0) {
+      sections.push(`**Cyclomatic Complexity:** ${analysis.complexity}`);
+    }
+    if (analysis.dependencies.length > 0) {
+      sections.push('', '**Dependencies:**');
+      analysis.dependencies.forEach(dep => sections.push(`- \`${dep}\``));
+    }
+    if (analysis.exports.length > 0) {
+      sections.push('', '**Exports:**');
+      analysis.exports.forEach(exp => sections.push(`- \`${exp}\``));
+    }
+
+    return sections.join('\n');
+  }
+
+  private errorResult(message: string): ToolResult {
+    return {
+      content: [{ type: 'text', text: `Error: ${message}` }],
+      isError: true,
+    };
+  }
+}
+
+// --- 4. Register in MCP Service ---
+
+/*
+// In mcp.service.ts:
+import { fileAnalyzerToolSchema, FileAnalyzerHandler } from './tools/file-analyzer';
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [fileAnalyzerToolSchema],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  switch (request.params.name) {
+    case 'analyze_file':
+      return this.fileAnalyzerHandler.handle(request.params.arguments);
+    default:
+      throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
+  }
+});
+*/
+
+// Placeholder for dependency injection
+interface FileService {
+  exists(path: string): Promise<boolean>;
+  read(path: string): Promise<string>;
+}

package/.ai-rules/skills/mcp-builder/references/protocol-spec.md

@@ -0,0 +1,215 @@
+# MCP Protocol Quick Reference
+
+## Protocol Overview
+
+The Model Context Protocol (MCP) uses JSON-RPC 2.0 over stdio or HTTP+SSE transport. Servers expose three capability types: **Tools**, **Resources**, and **Prompts**.
+
+## JSON-RPC 2.0 Message Format
+
+### Request
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "search_rules",
+    "arguments": { "query": "TDD" }
+  }
+}
+```
+
+### Response (Success)
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "content": [{ "type": "text", "text": "..." }]
+  }
+}
+```
+
+### Response (Error)
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "error": {
+    "code": -32601,
+    "message": "Method not found"
+  }
+}
+```
+
+## Capability Methods
+
+### Tools
+
+| Method | Direction | Description |
+|--------|-----------|-------------|
+| `tools/list` | Client → Server | List available tools with schemas |
+| `tools/call` | Client → Server | Execute a tool by name with arguments |
+
+**Tool Result Shape:**
+
+```typescript
+interface ToolResult {
+  content: ContentBlock[];  // text, image, or resource content
+  isError?: boolean;        // true if the tool encountered an error
+}
+
+type ContentBlock =
+  | { type: 'text'; text: string }
+  | { type: 'image'; data: string; mimeType: string }
+  | { type: 'resource'; resource: ResourceContent };
+```
+
+### Resources
+
+| Method | Direction | Description |
+|--------|-----------|-------------|
+| `resources/list` | Client → Server | List available resources |
+| `resources/templates/list` | Client → Server | List URI templates for dynamic resources |
+| `resources/read` | Client → Server | Read a resource by URI |
+| `notifications/resources/list_changed` | Server → Client | Notify resource list changed |
+
+**Resource Shape:**
+
+```typescript
+interface Resource {
+  uri: string;          // e.g., "rules://core"
+  name: string;         // Human-readable name
+  description?: string; // What this resource contains
+  mimeType?: string;    // e.g., "text/markdown", "application/json"
+}
+
+interface ResourceContent {
+  uri: string;
+  mimeType?: string;
+  text?: string;   // For text content
+  blob?: string;   // For binary content (base64)
+}
+```
+
+### Prompts
+
+| Method | Direction | Description |
+|--------|-----------|-------------|
+| `prompts/list` | Client → Server | List available prompt templates |
+| `prompts/get` | Client → Server | Get a prompt with arguments filled in |
+
+**Prompt Shape:**
+
+```typescript
+interface Prompt {
+  name: string;
+  description?: string;
+  arguments?: PromptArgument[];
+}
+
+interface PromptArgument {
+  name: string;
+  description?: string;
+  required?: boolean;
+}
+
+interface GetPromptResult {
+  messages: Array<{
+    role: 'user' | 'assistant';
+    content: TextContent | ImageContent | EmbeddedResource;
+  }>;
+}
+```
+
+## Initialization Handshake
+
+```
+Client                          Server
+  |                                |
+  |-- initialize ----------------->|   (capabilities, clientInfo)
+  |<-- initialize result ----------|   (capabilities, serverInfo)
+  |-- notifications/initialized -->|   (confirm ready)
+  |                                |
+  |-- tools/list ----------------->|   (discover tools)
+  |-- resources/list ------------->|   (discover resources)
+  |-- prompts/list --------------->|   (discover prompts)
+```
+
+### Server Capabilities Declaration
+
+```typescript
+const serverCapabilities = {
+  tools: {},                    // Server provides tools
+  resources: {
+    subscribe: true,            // Supports resource subscriptions
+    listChanged: true,          // Sends list_changed notifications
+  },
+  prompts: {
+    listChanged: true,          // Sends list_changed notifications
+  },
+};
+```
+
+## Transport Modes
+
+### Stdio
+
+- Server reads JSON-RPC from stdin, writes to stdout
+- Logs MUST go to stderr (never stdout)
+- One message per line (newline-delimited JSON)
+- No HTTP overhead, fastest for local use
+
+### HTTP + SSE
+
+- Client opens SSE connection at `GET /sse`
+- Server sends `endpoint` event with message URL
+- Client sends JSON-RPC via `POST /messages`
+- Server streams responses via SSE
+
+```
+Client                              Server
+  |                                    |
+  |-- GET /sse ----------------------->|   (open SSE stream)
+  |<-- event: endpoint ---------------|   (data: /messages?sessionId=abc)
+  |                                    |
+  |-- POST /messages?sessionId=abc --->|   (JSON-RPC request)
+  |<-- event: message ----------------|   (JSON-RPC response via SSE)
+```
+
+## Error Codes
+
+| Code | Name | Description |
+|------|------|-------------|
+| `-32700` | Parse error | Invalid JSON |
+| `-32600` | Invalid request | Missing required fields |
+| `-32601` | Method not found | Unknown method |
+| `-32602` | Invalid params | Wrong parameter types |
+| `-32603` | Internal error | Server-side error |
+
+## Input Schema Best Practices
+
+- Always set `type: 'object'` at the top level
+- Mark required parameters in the `required` array
+- Add `description` to every property (LLMs use these to decide how to call)
+- Use `minLength`, `maximum`, `enum` constraints where applicable
+- Set sensible `default` values for optional parameters
+
+## URI Scheme Conventions
+
+```
+scheme://authority/path
+
+rules://core                   → Core rules
+rules://augmented-coding       → Augmented coding rules
+agents://solution-architect    → Agent definition
+config://project               → Project config
+skills://mcp-builder           → Skill content
+```
+
+- Use lowercase, hyphen-separated paths
+- Scheme should indicate the resource domain
+- Path should be human-readable and predictable