vibes-plug 2.5.0 → 2.11.0

package/skills/mcp-server-architect/SKILL.md

@@ -1,194 +1,294 @@
----
-name: mcp-server-architect
-description: "Expert guide for designing, building, and security-hardening Model Context Protocol (MCP) servers and tool integrations in TypeScript, Python, and Go / Panduan ahli merancang, membangun, dan mengamankan server Model Context Protocol (MCP) dan integrasi tool dalam TypeScript, Python, dan Go."
-author: "Roedy Rustam"
----
-
-# MCP Server Architect (v1.9+ Edition)
-
-[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
-
----
-
-<a name="english"></a>
-## English
-
-### Description
-Expert guide for designing, building, and security-hardening **Model Context Protocol (MCP)** servers and client integrations. Covers MCP v1.9+ specification (including the new Streamable HTTP transport), tool/resource/prompt design, Zod validation, OAuth 2.1 authorization, and multi-server orchestration patterns for production AI applications.
-
-### Trigger Conditions
-- Building an MCP server to expose tools, resources, or prompt templates to AI agents.
-- Integrating third-party APIs or databases as MCP tools for LLM consumption.
-- Implementing MCP client logic in an AI agent or chatbot.
-- Securing MCP servers with OAuth 2.1 and permission scoping.
-- Deploying MCP servers to edge/serverless environments.
-
-### MCP v1.9+ Specification Overview
-
-MCP standardizes how AI models interact with external tools and data. The 2026 specification (v1.9) introduces:
-
-| Feature | Description |
-|---|---|
-| **Streamable HTTP** | New bidirectional transport via HTTP streaming — replaces SSE for cloud deployments |
-| **stdio** | Original transport for local/CLI tools — still recommended for local MCP |
-| **OAuth 2.1** | Standard authorization flow for MCP servers requiring user consent |
-| **Tool Annotations** | `readOnlyHint`, `destructiveHint`, `idempotentHint` for safer agent decisions |
-| **Audio Content** | Support for audio data in tool responses |
-| **Resource Links** | Resources can now link to external URIs |
-
-### Core MCP Concepts
-
-| Primitive | What It Is | Example |
-|---|---|---|
-| **Tool** | Executable function the LLM can call | `search_database`, `send_email` |
-| **Resource** | Read-only data the LLM can read | File contents, DB records |
-| **Prompt** | Reusable prompt templates | `code_review_prompt` |
-| **Sampling** | Server requests LLM completion | Agent asks LLM to classify |
-
-### Building an MCP Server (TypeScript)
-
-#### 1. Setup with `@modelcontextprotocol/sdk`
-```typescript
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { z } from 'zod';
-
-const server = new McpServer({
-  name: 'my-api-server',
-  version: '1.0.0',
-});
-```
-
-#### 2. Define Tools with Zod Validation
-```typescript
-server.tool(
-  'search_products',
-  'Search the product catalog by query and category',
-  {
-    query: z.string().min(1).describe('Search query string'),
-    category: z.enum(['electronics', 'clothing', 'books']).optional(),
-    limit: z.number().int().min(1).max(50).default(10),
-  },
-  {
-    readOnlyHint: true,     // v1.9 annotation: this tool does not modify state
-    idempotentHint: true,   // safe to call multiple times
-  },
-  async ({ query, category, limit }) => {
-    const results = await productDB.search({ query, category, limit });
-    return {
-      content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
-    };
-  }
-);
-```
-
-#### 3. Expose Resources
-```typescript
-server.resource(
-  'company-docs',
-  'docs://{path}',
-  { mimeType: 'text/markdown' },
-  async (uri) => {
-    const path = uri.pathname;
-    const content = await fs.readFile(`./docs${path}`, 'utf-8');
-    return { contents: [{ uri: uri.href, mimeType: 'text/markdown', text: content }] };
-  }
-);
-```
-
-#### 4. Streamable HTTP Transport (v1.9 — Production Deployment)
-```typescript
-import express from 'express';
-
-const app = express();
-app.use(express.json());
-
-app.all('/mcp', async (req, res) => {
-  const transport = new StreamableHTTPServerTransport({
-    sessionIdGenerator: () => crypto.randomUUID(),
-  });
-  await server.connect(transport);
-  await transport.handleRequest(req, res, req.body);
-});
-
-app.listen(3000, () => console.log('MCP Server running on :3000'));
-```
-
-#### 5. OAuth 2.1 Authorization (Secure MCP)
-For MCP servers requiring user consent (e.g., accessing user's GitHub repos):
-```typescript
-import { ProxyOAuthServerProvider } from '@modelcontextprotocol/sdk/server/auth/providers/proxyOAuth.js';
-
-const authProvider = new ProxyOAuthServerProvider({
-  endpoints: {
-    authorizationUrl: 'https://github.com/login/oauth/authorize',
-    tokenUrl: 'https://github.com/login/oauth/access_token',
-  },
-  clientId: process.env.GITHUB_CLIENT_ID!,
-  clientSecret: process.env.GITHUB_CLIENT_SECRET!,
-  scopes: ['repo', 'read:user'],
-});
-
-server.setAuthProvider(authProvider);
-```
-
-### Security Hardening
-
-- **Validate ALL inputs**: Every tool parameter must be validated with Zod before execution. Never trust LLM-generated inputs directly.
-- **Principle of Least Privilege**: Each tool should only request the minimum permissions needed.
-- **Rate Limiting**: Implement per-session rate limits to prevent prompt injection loops.
-- **Sanitize Outputs**: Never return raw database records with sensitive fields (passwords, API keys). Always filter/select only what's needed.
-- **Audit Logging**: Log every tool call with session ID, tool name, parameters, and result status.
-- **Tool Annotations**: Use `destructiveHint: true` for tools that modify or delete data — agents should ask for human confirmation before calling these.
-
-### Multi-Server Orchestration
-When building AI apps with multiple MCP servers:
-```typescript
-// Client connecting to multiple MCP servers
-const client = new McpClient({ name: 'my-agent', version: '1.0.0' });
-
-// Connect to multiple specialized servers
-await client.connect(new StdioTransport({ command: 'node', args: ['file-server.js'] }));
-await client.connect(new StreamableHTTPTransport({ url: 'https://api.mydb.com/mcp' }));
-
-// List all available tools across servers
-const { tools } = await client.listTools();
-```
-
----
-
-<a name="bahasa-indonesia"></a>
-## Bahasa Indonesia
-
-### Deskripsi
-Panduan ahli untuk merancang, membangun, dan mengamankan server **Model Context Protocol (MCP)** dan integrasi klien. Mencakup spesifikasi MCP v1.9+ (termasuk transport Streamable HTTP baru), desain tool/resource/prompt, validasi Zod, otorisasi OAuth 2.1, dan pola orkestrasi multi-server untuk aplikasi AI produksi.
-
-### Kondisi Pemicu
-- Membangun MCP server untuk mengekspos tool, resource, atau prompt template ke agen AI.
-- Mengintegrasikan API pihak ketiga atau database sebagai MCP tool untuk konsumsi LLM.
-- Mengimplementasikan logika klien MCP dalam agen AI atau chatbot.
-- Mengamankan MCP server dengan OAuth 2.1 dan pembatasan izin.
-- Men-deploy MCP server ke lingkungan edge/serverless.
-
-### Ringkasan Spesifikasi MCP v1.9+
-
-MCP menstandarisasi cara model AI berinteraksi dengan tool dan data eksternal. Spesifikasi 2026 (v1.9) memperkenalkan:
-- **Streamable HTTP**: Transport dua arah baru via HTTP streaming — menggantikan SSE untuk deployment cloud.
-- **Tool Annotations**: `readOnlyHint`, `destructiveHint`, `idempotentHint` untuk keputusan agen yang lebih aman.
-- **OAuth 2.1**: Alur otorisasi standar untuk MCP server yang memerlukan izin pengguna.
-
-### Membangun MCP Server (TypeScript)
-
-Gunakan `@modelcontextprotocol/sdk` untuk TypeScript. Definisikan tool dengan validasi Zod yang ketat, tambahkan anotasi v1.9 (`readOnlyHint`, `destructiveHint`), dan gunakan Streamable HTTP transport untuk deployment cloud produksi.
-
-### Keamanan MCP
-
-- **Validasi SEMUA input**: Setiap parameter tool harus divalidasi dengan Zod sebelum eksekusi.
-- **Prinsip Least Privilege**: Setiap tool hanya boleh meminta izin minimum yang diperlukan.
-- **Rate Limiting**: Batasi panggilan per sesi untuk mencegah loop prompt injection.
-- **Sanitasi Output**: Jangan pernah mengembalikan field sensitif (password, API key).
-- **Audit Logging**: Catat setiap panggilan tool dengan session ID, nama tool, parameter, dan status hasil.
-- **Anotasi Tool**: Gunakan `destructiveHint: true` untuk tool yang memodifikasi/menghapus data — agen harus meminta konfirmasi manusia sebelum memanggilnya.
-
-### Orkestrasi Multi-Server
-Klien MCP dapat terhubung ke beberapa server sekaligus, menyatukan semua tool dari server yang berbeda menjadi satu daftar yang tersedia untuk agen.
+---
+name: mcp-server-architect
+description: "Ultimate guide for designing, building, and security-hardening modern AI Tools/Bots via Model Context Protocol (MCP v1.x) in TypeScript and Python / Panduan utama merancang, membangun, dan mengamankan AI Tools/Bots modern melalui Model Context Protocol (MCP) dalam TypeScript dan Python."
+author: "Roedy Rustam"
+---
+
+# MCP Server Architect (Modern AI Tools & Agentic Protocol)
+
+[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
+
+---
+
+<a name="english"></a>
+## English
+
+### Orchestration & Integration
+Connects and orchestrates with relevant domain skills: `ai-llm-integration-expert` for core LLM routing and RAG pipelines, `mcp-client-orchestrator` for agent client consumption, and `doku-mcp-server` for payments integration examples. Ensure cohesive execution when spawning subagents.
+
+### Description
+Ultimate architectural guide for engineering high-performance, production-ready AI Tools/Bots via the **Model Context Protocol (MCP v1.x)**. Enforces the use of `FastMCP` (Python) and `@modelcontextprotocol/sdk` (TypeScript). Mandates strict security guardrails, schema validation, stateful resource streaming, and support for both Standard Stdio and Streamable HTTP / Server-Sent Events (SSE) transports.
+
+### Trigger Conditions
+- Building an MCP server to expose tools, resources, or prompt templates to AI agents.
+- Integrating backend APIs, file systems, or databases as MCP agent tools.
+- Implementing stateful, real-time MCP servers (resource subscriptions, log tailing, live metrics).
+- Securing and auditing MCP servers exposing sensitive financial or production data.
+
+---
+
+### SDK Selection (Mandatory Standard)
+1. **Python**: `FastMCP` (FastAPI-like high-level DX for MCP tools, resources, and prompt templates).
+2. **TypeScript**: `@modelcontextprotocol/sdk` (official SDK using the `McpServer` high-level abstraction with `zod`).
+
+---
+
+### Production Implementation Recipes
+
+#### Recipe 1: Production TypeScript MCP Server (Streamable HTTP / SSE)
+```typescript
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import express from 'express';
+import { z } from 'zod';
+
+// Initialize the high-level MCP Server
+const server = new McpServer({
+  name: 'enterprise-analytics-mcp',
+  version: '1.0.0',
+});
+
+// Register a type-safe Tool with Zod validation
+server.tool(
+  'calculate_metrics',
+  'Calculates business analytics metrics across timeframes',
+  {
+    metricName: z.enum(['arr', 'churn', 'cac', 'ltv']).describe('The metric to compute'),
+    quarter: z.string().regex(/^Q[1-4]-202[0-9]$/).describe('Target quarter, e.g., Q1-2026'),
+  },
+  async ({ metricName, quarter }) => {
+    // Implement business logic with database access
+    const mockData = { arr: '$2.4M', churn: '1.2%', cac: '$450', ltv: '$9,200' };
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify({ metric: metricName, quarter, value: mockData[metricName] }),
+        },
+      ],
+    };
+  }
+);
+
+// Register a Resource Template with dynamic URI
+server.resource(
+  'system_health',
+  new ResourceTemplate('system://health/{service}', { list: undefined }),
+  async (uri, { service }) => {
+    return {
+      contents: [
+        {
+          uri: uri.href,
+          text: JSON.stringify({ service, status: 'HEALTHY', latencyMs: 14, timestamp: new Date().toISOString() }),
+        },
+      ],
+    };
+  }
+);
+
+// Expose via Express with SSE Transport
+const app = express();
+let transport: SSEServerTransport | null = null;
+
+app.get('/sse', async (req, res) => {
+  transport = new SSEServerTransport('/messages', res);
+  await server.connect(transport);
+});
+
+app.post('/messages', async (req, res) => {
+  if (transport) {
+    await transport.handlePostMessage(req, res);
+  } else {
+    res.status(400).send('Transport not established');
+  }
+});
+
+app.listen(3001, () => {
+  console.log('MCP Server listening on http://localhost:3001/sse');
+});
+```
+
+#### Recipe 2: Production FastMCP Server (Python)
+```python
+from fastmcp import FastMCP, Context
+from pydantic import BaseModel, Field
+from typing import Literal
+
+mcp = FastMCP("enterprise-vault-mcp", dependencies=["pydantic"])
+
+class QueryParams(BaseModel):
+    account_id: str = Field(..., description="UUID of customer account")
+    status_filter: Literal["active", "suspended", "all"] = Field("active", description="Status filter")
+
+@mcp.tool(name="fetch_account_summary", description="Retrieves account telemetry and balance")
+async def fetch_account_summary(params: QueryParams, ctx: Context) -> str:
+    ctx.info(f"Auditing request for account: {params.account_id}")
+    
+    # Secure business logic with RLS validation
+    result = {
+        "account_id": params.account_id,
+        "balance_usd": 125430.50,
+        "tier": "enterprise",
+        "status": params.status_filter
+    }
+    return str(result)
+
+@mcp.resource("config://app-settings")
+def get_app_settings() -> str:
+    """Provides application configuration context to the agent."""
+    return '{"environment": "production", "rate_limit_rpm": 600, "region": "ap-southeast-1"}'
+
+if __name__ == "__main__":
+    # Runs standard Stdio transport or streamable HTTP
+    mcp.run(transport="stdio")
+```
+
+---
+
+### Security & Operational Guardrails
+1. **OAuth 2.1 & Bearer Authentication**: Bind session tokens to transport connections. Validate claims before executing any tool logic.
+2. **Schema Strictness**: Never use untyped payloads. Every argument must have explicit types, range constraints, and descriptions to guide LLM tool-calling accuracy.
+3. **Row-Level Security (RLS)**: Enforce tenant and user context propagation to the database layer.
+4. **Circuit Breakers & Rate Limits**: Cap consecutive tool executions per agent turn to prevent endless agentic recursive loops.
+5. **Idempotency**: All destructive or state-mutating tools must require an `idempotency_key` argument.
+
+---
+
+<a name="bahasa-indonesia"></a>
+## Bahasa Indonesia
+
+### Integrasi Orkestrasi
+Terhubung dan mengorkestrasi dengan skill domain relevan: `ai-llm-integration-expert` untuk perutean LLM inti dan pipeline RAG, `mcp-client-orchestrator` untuk konsumsi klien agen, serta `doku-mcp-server` untuk contoh integrasi pembayaran.
+
+### Deskripsi
+Panduan arsitektur utama untuk membangun AI Tools/Bots modern dan siap produksi via **Model Context Protocol (MCP v1.x)**. Mewajibkan penggunaan `FastMCP` (Python) dan `@modelcontextprotocol/sdk` (TypeScript). Menerapkan pengamanan ketat, validasi skema, streaming resource stateful, serta dukungan transport Standar Stdio maupun Streamable HTTP / SSE.
+
+### Kondisi Pemicu
+- Membangun server MCP untuk mengekspos alat (*tools*), resource, atau template prompt ke agen AI.
+- Mengintegrasikan API backend, sistem file, atau database sebagai alat agen AI.
+- Mengimplementasikan server MCP stateful dan real-time (langganan resource, tailing log, metrik langsung).
+- Mengamankan server MCP yang mengekspos data finansial atau produksi yang sensitif.
+
+---
+
+### Standar Pemilihan SDK (Wajib)
+1. **Python**: `FastMCP` (pengalaman developer tingkat tinggi ala FastAPI untuk tools, resource, dan template prompt).
+2. **TypeScript**: `@modelcontextprotocol/sdk` (SDK resmi menggunakan abstraksi `McpServer` dengan `zod`).
+
+---
+
+### Resep Implementasi Produksi
+
+#### Resep 1: Server MCP TypeScript Produksi (Streamable HTTP / SSE)
+```typescript
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import express from 'express';
+import { z } from 'zod';
+
+const server = new McpServer({
+  name: 'enterprise-analytics-mcp',
+  version: '1.0.0',
+});
+
+// Pendaftaran Tool dengan validasi ketat Zod
+server.tool(
+  'calculate_metrics',
+  'Menghitung metrik analitik bisnis untuk kuartal tertentu',
+  {
+    metricName: z.enum(['arr', 'churn', 'cac', 'ltv']).describe('Metrik yang ingin dihitung'),
+    quarter: z.string().regex(/^Q[1-4]-202[0-9]$/).describe('Target kuartal, misal: Q1-2026'),
+  },
+  async ({ metricName, quarter }) => {
+    const data = { arr: '$2.4M', churn: '1.2%', cac: '$450', ltv: '$9,200' };
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify({ metrik: metricName, kuartal: quarter, nilai: data[metricName] }),
+        },
+      ],
+    };
+  }
+);
+
+// Pendaftaran Template Resource dengan URI Dinamis
+server.resource(
+  'system_health',
+  new ResourceTemplate('system://health/{service}', { list: undefined }),
+  async (uri, { service }) => {
+    return {
+      contents: [
+        {
+          uri: uri.href,
+          text: JSON.stringify({ layanan: service, status: 'HEALTHY', latensiMs: 14, waktu: new Date().toISOString() }),
+        },
+      ],
+    };
+  }
+);
+
+const app = express();
+let transport: SSEServerTransport | null = null;
+
+app.get('/sse', async (req, res) => {
+  transport = new SSEServerTransport('/messages', res);
+  await server.connect(transport);
+});
+
+app.post('/messages', async (req, res) => {
+  if (transport) {
+    await transport.handlePostMessage(req, res);
+  } else {
+    res.status(400).send('Transport belum terhubung');
+  }
+});
+
+app.listen(3001, () => {
+  console.log('Server MCP berjalan pada http://localhost:3001/sse');
+});
+```
+
+#### Resep 2: Server FastMCP Produksi (Python)
+```python
+from fastmcp import FastMCP, Context
+from pydantic import BaseModel, Field
+from typing import Literal
+
+mcp = FastMCP("enterprise-vault-mcp", dependencies=["pydantic"])
+
+class ParameterAkun(BaseModel):
+    account_id: str = Field(..., description="UUID akun pengguna")
+    status_filter: Literal["active", "suspended", "all"] = Field("active", description="Filter status")
+
+@mcp.tool(name="ambil_ringkasan_akun", description="Mengambil telemetri dan saldo akun")
+async def ambil_ringkasan_akun(params: ParameterAkun, ctx: Context) -> str:
+    ctx.info(f"Memproses permintaan untuk akun: {params.account_id}")
+    hasil = {
+        "account_id": params.account_id,
+        "saldo_usd": 125430.50,
+        "tier": "enterprise",
+        "status": params.status_filter
+    }
+    return str(hasil)
+
+@mcp.resource("config://app-settings")
+def ambil_pengaturan_aplikasi() -> str:
+    """Menyediakan konteks konfigurasi aplikasi ke agen AI."""
+    return '{"environment": "production", "rate_limit_rpm": 600, "region": "ap-southeast-1"}'
+
+if __name__ == "__main__":
+    mcp.run(transport="stdio")
+```
+
+---
+
+### Keamanan & Batasan Operasional
+1. **Otentikasi OAuth 2.1 & Bearer**: Ikat token sesi ke koneksi transport. Validasi hak akses sebelum mengeksekusi logika alat.
+2. **Validasi Skema Ketat**: Hindari penggunaan parameter tanpa tipe data yang jelas. Setiap argumen wajib memiliki tipe data, batas nilai, dan deskripsi.
+3. **Row-Level Security (RLS)**: Teruskan identitas pengguna dan penyewa (tenant) ke lapisan database driver.
+4. **Circuit Breakers & Rate Limits**: Batasi pemanggilan tool berulang dalam satu giliran respon untuk mencegah perulangan tak terkontrol (*infinite loops*).
+5. **Idempotency**: Semua tool yang memodifikasi data wajib mendukung argumen `idempotency_key`.
+
+## Integrasi Orkestrasi
+- Terintegrasi dengan: `ai-llm-integration-expert`, `mcp-client-orchestrator`, `doku-mcp-server`, `zero-trust-secret-vault`.