┌─────────────────────────────────────────────────────────────────┐
│                    ภาพรวมโครงสร้าง MCP                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   ┌──────────────┐         JSON-RPC 2.0          ┌──────────────┐│
│   │   MCP Client │  ◄──────────────────────────► │   MCP Server  ││
│   │  (ChatGPT,   │     (stdio, HTTP/SSE)        │  (APIs ของคุณ,││
│   │   Cursor,    │                               │  ฐานข้อมูล,  ││
│   │   n8n,       │                               │  ไฟล์ ฯลฯ)   ││
│   │   OpenClaw)  │                               │              ││
│   └──────────────┘                               └──────────────┘│
│          │                                               │       │
│          │           การแลกเปลี่ยนความสามารถ            │       │
│          │  ───────────────────────────────────────────► │       │
│          │  ◄─────────────────────────────────────────── │       │
│          │                                               │       │
│          │           การเรียกใช้ Tools / คำขอ Resources│       │
│          │  ───────────────────────────────────────────► │       │
│          │  ◄─────────────────────────────────────────── │       │
│          │                                               │       │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│              Flow การตรวจสอบสิทธิ Enterprise MCP                │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ขั้นตอนที่ 1: การค้นพบ Client                                   │
│  ───────────────────────────                                     │
│  Client ขอความสามารถของ server                                  │
│                                                                  │
│  GET /.well-known/mcp                                            │
│  การตอบสนองรวมถึง:                                               │
│    - ความสามารถที่มีอยู่                                          │
│    - ข้อกำหนดการตรวจสอบสิทธิ                                    │
│    - Endpoints การอนุญาต                                        │
│                                                                  │
│  ขั้นตอนที่ 2: การตรวจสอบสิทธิ                                  │
│  ─────────────────────────────                                   │
│  Client ตรวจสอบสิทธิโดยใช้วิธีที่กำหนดค่า:                      │
│                                                                  │
│  วิธีที่รองรับ:                                                   │
│    - OAuth 2.0 (Authorization Code + PKCE)                      │
│    - OAuth 2.0 (Client Credentials)                              │
│    - mTLS (Mutual TLS)                                           │
│    - JWT Bearer Tokens                                           │
│    - API Key (พร้อมการสนับสนุนการหมุนเวียน)                      │
│                                                                  │
│  ขั้นตอนที่ 3: การแลกเปลี่ยน Token                              │
│  ─────────────────────────────                                   │
│  Client ที่ตรวจสอบสิทธิแล้วได้รับ MCP access token:            │
│                                                                  │
│  {                                                               │
│    "access_token": "mcp_at_...",                                 │
│    "token_type": "Bearer",                                       │
│    "expires_in": 3600,                                           │
│    "scope": "tools:read tools:execute resources:read",         │
│    "server_metadata": {                                          │
│      "instance_id": "srv_abc123",                              │
│      "region": "us-west-2",                                      │
│      "capabilities": [...]                                         │
│    }                                                             │
│  }                                                               │
│                                                                  │
│  ขั้นตอนที่ 4: คำขอที่ได้รับอนุญาต                               │
│  ─────────────────────────────────                               │
│  Client รวม token ไว้ในทุกคำขอ:                                 │
│                                                                  │
│  Authorization: Bearer mcp_at_...                                │
│  X-MCP-Client-Version: 2026-07-28                                │
│                                                                  │
│  Server ตรวจสอบ token ตรวจสอบ scopes ประมวลผลคำขอ               │
│                                                                  │
│  ขั้นตอนที่ 5: การรีเฟรช Token                                    │
│  ─────────────────────────────                                   │
│  Tokens รีเฟรชโดยอัตโนมัติก่อนหมดอายุ                          │
│  Refresh tokens ช่วยให้เกิดเซสชันระยะยาว                       │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

tools:read          - แสดงรายการ tools ที่มีอยู่
tools:execute       - เรียกใช้ tools
resources:read      - เข้าถึง resources
resources:write     - แก้ไข resources
prompts:read        - เข้าถึง prompts ของ server
sampling:request    - ขอ sampling ฝั่ง client
admin:configure     - การกำหนดค่า server (สำหรับ admin เท่านั้น)

// สถานะเซสชันฝั่ง client
const mcpSession = {
  // ข้อมูลการเชื่อมต่อ server (สามารถเป็นอินสแตนซ์ใดก็ได้)
  serverEndpoint: "https://mcp-api.company.com/v1",
  
  // การตรวจสอบสิทธิ
  accessToken: "mcp_at_...",
  tokenExpiry: 1719234567000,
  
  // บริบทการสนทนา (จัดการโดย client)
  context: {
    conversationId: "conv_xyz789",
    toolResults: [...],      // ผลลัพธ์การเรียกใช้ tool ก่อนหน้า
    resourceCache: {...},    // ข้อมูลทรัพยากรที่แคชไว้
    preferences: {...}       // การตั้งค่าผู้ใช้
  },
  
  // แคชความสามารถ
  serverCapabilities: {...}
};

// ทุกคำขอรวม context
const request = {
  jsonrpc: "2.0",
  id: 123,
  method: "tools/call",
  params: {
    name: "search_database",
    arguments: {...},
    // ส่ง context เซสชันกับทุกคำขอ
    context: mcpSession.context
  }
};

// นิยาม tool ที่ดี
{
  name: "search_customer_database",
  description: "ค้นหาในฐานข้อมูล CRM ใช้สิ่งนี้เมื่อผู้ใช้ถามเกี่ยวกับลูกค้าเฉพาะบัญชีหรือข้อมูลการติดต่อ คืนค่าข้อมูลลูกค้าพร้อมชื่อ อีเมล โทรศัพท์ และสถานะบัญชี",
  inputSchema: {
    type: "object",
    properties: {
      query: {
        type: "string",
        description: "สตริงคำค้นหา สามารถเป็นชื่อบางส่วน อีเมล หรือหมายเลขโทรศัพท์"
      },
      limit: {
        type: "integer",
        description: "จำนวนผลลัพธ์สูงสุดที่จะคืนค่า (1-100)",
        default: 10,
        minimum: 1,
        maximum: 100
      }
    },
    required: ["query"]
  }
}

// การใช้งานพื้นฐาน - เฉพาะสิ่งจำเป็น
{
  name: "send_email",
  description: "ส่งอีเมลถึงผู้รับ",
  inputSchema: {
    type: "object",
    properties: {
      to: { type: "string", format: "email" },
      subject: { type: "string" },
      body: { type: "string" }
    },
    required: ["to", "subject", "body"]
  }
}

// การใช้งานขั้นสูง - ตัวเลือกเพิ่มเติมสำหรับ clients ที่ซับซ้อน
{
  name: "send_email_advanced",
  description: "ส่งอีเมลด้วยตัวเลือกขั้นสูงรวมถึงไฟล์แนบ CC/BCC การกำหนดเวลา และการติดตาม",
  inputSchema: {
    // Schema ขยายด้วยตัวเลือกทั้งหมด
  }
}

interface ToolResponse<T> {
  // ตัวบ่งชี้ความสำเร็จ
  success: boolean;
  
  // ข้อมูลผลลัพธ์ (เมื่อสำเร็จ)
  data?: T;
  
  // รายละเอียดข้อผิดพลาด (เมื่อล้มเหลว)
  error?: {
    code: string;
    message: string;
    details?: unknown;
  };
  
  // เมตาดาต้า
  meta: {
    executionTime: number;
    requestId: string;
    cached: boolean;
  };
}

# รูปแบบ URI มาตรฐาน
database://table/records/{id}
file://documents/contracts/{filename}
api://service/endpoint/resource
config://settings/environment

// นิยาม resource
{
  uri: "database://customers/active",
  name: "ลูกค้าที่ใช้งานอยู่",
  description: "รายการลูกค้าที่กำลังใช้งานอยู่ในปัจจุบัน",
  mimeType: "application/json",
  size: 15420,
  
  // ความสามารถ
  capabilities: {
    // การสนับสนุนสำหรับการสมัครสมาชิก (การอัปเดตแบบสด)
    subscribe: true,
    
    // การสนับสนุนการแบ่งหน้า
    pagination: {
      supported: true,
      defaultLimit: 100,
      maxLimit: 1000
    },
    
    // การสนับสนุนการค้นหา/กรอง
    filtering: {
      supported: true,
      operators: ["eq", "neq", "gt", "lt", "contains", "startsWith"]
    },
    
    // การสนับสนุนการจัดเรียง
    sorting: {
      supported: true,
      defaultField: "createdAt",
      defaultDirection: "desc"
    }
  }
}

// Client สมัครสมาชิกการอัปเดต resource
const subscription = await client.subscribeResource({
  uri: "database://orders/pending",
  
  // ตัวเลือก: กรองการสมัครสมาชิก
  filter: {
    region: "europe",
    priority: "high"
  },
  
  // Handler สำหรับการอัปเดต
  onUpdate: (update) => {
    console.log(`คำสั่งซื้อใหม่: ${update.data.orderId}`);
  },
  
  onError: (error) => {
    console.error(`ข้อผิดพลาดการสมัครสมาชิก: ${error.message}`);
  }
});

// ยกเลิกการสมัครสมาชิกเมื่อเสร็จสิ้น
await subscription.unsubscribe();

interface SamplingRequest {
  // ข้อความสำหรับ AI (คล้ายกับ API chat completions)
  messages: Array<{
    role: "user" | "assistant" | "system";
    content: string;
  }>;
  
  // การตั้งค่าโมเดล
  modelPreferences?: {
    hints?: string[];           // คำใบ้โมเดล (เช่น ["claude-3-opus", "gpt-4"])
    priority?: "speed" | "quality";  // การตั้งค่าการปรับให้เหมาะสม
  };
  
  // พารามิเตอร์การเติมเต็ม
  maxTokens?: number;
  temperature?: number;
  
  // เมตาดาต้าสำหรับบริบท client
  metadata: {
    requestId: string;
    purpose: string;
    clientInfo: {
      name: string;
      version: string;
    };
  };
}

// Server ขอ sampling จาก client
async function processDocument(document: Document) {
  // Server ดำเนินการประมวลผลเบื้องต้น
  const extractedData = await extractData(document);
  
  // ขอความช่วยเหลือ AI สำหรับสรุป
  const samplingResult = await client.requestSampling({
    messages: [
      {
        role: "system",
        content: "คุณเป็นผู้ช่วยวิเคราะห์เอกสาร สรุปประเด็นสำคัญ"
      },
      {
        role: "user",
        content: `ข้อมูลเอกสาร: ${JSON.stringify(extractedData)}`
      }
    ],
    maxTokens: 500,
    metadata: {
      requestId: generateId(),
      purpose: "document_summary",
      clientInfo: { name: "mcp-server", version: "1.0.0" }
    }
  });
  
  // รวมการประมวลผล server กับการสรุป AI
  return {
    data: extractedData,
    summary: samplingResult.content
  };
}

my-mcp-server/
├── src/
│   ├── index.ts              // จุดเริ่มต้น
│   ├── server.ts             // การตั้งค่า MCP server
│   ├── auth/
│   │   ├── oauth.ts          // การใช้งาน OAuth
│   │   ├── jwt.ts            // การตรวจสอบ JWT
│   │   └── scopes.ts         // การตรวจสอบ scope
│   ├── tools/
│   │   ├── index.ts          // การลงทะเบียน tool
│   │   ├── customer-search.ts
│   │   ├── order-management.ts
│   │   └── email-sender.ts
│   ├── resources/
│   │   ├── index.ts          // การลงทะเบียน resource
│   │   ├── customer-data.ts
│   │   └── order-stream.ts
│   ├── handlers/
│   │   ├── tools.ts          // Handlers คำขอ tool
│   │   ├── resources.ts      // Handlers คำขอ resource
│   │   └── sampling.ts       // Handlers คำขอ sampling
│   └── utils/
│       ├── validation.ts
│       ├── errors.ts
│       └── logging.ts
├── tests/
│   ├── unit/
│   └── integration/
├── config/
│   ├── development.yaml
│   └── production.yaml
├── Dockerfile
├── package.json
└── tsconfig.json

// src/server.ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListResourcesRequestSchema,
  ListToolsRequestSchema,
  ReadResourceRequestSchema,
  ErrorCode,
  McpError
} from "@modelcontextprotocol/sdk/types.js";

import { authenticateRequest } from "./auth/jwt.js";
import { checkScope } from "./auth/scopes.js";
import { toolHandlers } from "./handlers/tools.js";
import { resourceHandlers } from "./handlers/resources.js";

class MCPServer {
  private server: Server;

  constructor() {
    this.server = new Server(
      {
        name: "enterprise-mcp-server",
        version: "1.0.0"
      },
      {
        capabilities: {
          tools: {},
          resources: {
            subscribe: true
          },
          sampling: {}
        }
      }
    );

    this.setupHandlers();
    this.setupErrorHandling();
  }

  private setupHandlers() {
    // แสดงรายการ tools ที่มีอยู่
    this.server.setRequestHandler(ListToolsRequestSchema, async (request) => {
      // ตรวจสอบสิทธิและอนุญาต
      const auth = await authenticateRequest(request);
      checkScope(auth, "tools:read");
      
      return {
        tools: [
          {
            name: "search_customers",
            description: "ค้นหาในฐานข้อมูลลูกค้า",
            inputSchema: {
              type: "object",
              properties: {
                query: { type: "string" },
                limit: { type: "number", default: 10 }
              },
              required: ["query"]
            }
          },
          {
            name: "create_order",
            description: "สร้างคำสั่งซื้อใหม่",
            inputSchema: {
              type: "object",
              properties: {
                customerId: { type: "string" },
                items: { type: "array" },
                shippingAddress: { type: "object" }
              },
              required: ["customerId", "items"]
            }
          }
        ]
      };
    });

    // เรียกใช้ tool calls
    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
      const auth = await authenticateRequest(request);
      checkScope(auth, "tools:execute");
      
      const handler = toolHandlers[request.params.name];
      if (!handler) {
        throw new McpError(
          ErrorCode.MethodNotFound,
          `ไม่พบ tool: ${request.params.name}`
        );
      }
      
      return await handler(request.params.arguments, auth);
    });

    // แสดงรายการ resources ที่มีอยู่
    this.server.setRequestHandler(ListResourcesRequestSchema, async (request) => {
      const auth = await authenticateRequest(request);
      checkScope(auth, "resources:read");
      
      return {
        resources: [
          {
            uri: "database://customers/active",
            name: "ลูกค้าที่ใช้งานอยู่",
            mimeType: "application/json"
          },
          {
            uri: "database://orders/pending",
            name: "คำสั่งซื้อที่รอดำเนินการ",
            mimeType: "application/json"
          }
        ]
      };
    });

    // อ่านเนื้อหา resource
    this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
      const auth = await authenticateRequest(request);
      checkScope(auth, "resources:read");
      
      const handler = resourceHandlers[request.params.uri];
      if (!handler) {
        throw new McpError(
          ErrorCode.InvalidRequest,
          `ไม่พบ resource: ${request.params.uri}`
        );
      }
      
      return await handler(request.params.uri, auth);
    });
  }

  private setupErrorHandling() {
    this.server.onerror = (error) => {
      console.error("[MCP Error]", error);
    };

    process.on("SIGINT", async () => {
      await this.server.close();
      process.exit(0);
    });
  }

  async run() {
    const transport = new StdioServerTransport();
    await this.server.connect(transport);
    console.error("MCP server กำลังทำงานผ่าน stdio");
  }
}

const server = new MCPServer();
server.run().catch(console.error);

// src/handlers/tools.ts
import { z } from "zod";

// Schemas การตรวจสอบอินพุต
const SearchCustomersSchema = z.object({
  query: z.string().min(1),
  limit: z.number().min(1).max(100).default(10)
});

const CreateOrderSchema = z.object({
  customerId: z.string(),
  items: z.array(z.object({
    sku: z.string(),
    quantity: z.number().min(1),
    price: z.number().positive()
  })).min(1),
  shippingAddress: z.object({
    street: z.string(),
    city: z.string(),
    country: z.string()
  }).optional()
});

// การใช้งาน tools
export const toolHandlers: Record<string, Function> = {
  async search_customers(args: unknown, auth: AuthContext) {
    // ตรวจสอบอินพุต
    const validated = SearchCustomersSchema.parse(args);
    
    // ตรวจสอบสิทธิเพิ่มเติม
    if (!auth.permissions.includes("customer:read")) {
      throw new McpError(
        ErrorCode.InvalidRequest,
        "สิทธิไม่เพียงพอสำหรับการค้นหาลูกค้า"
      );
    }
    
    // ดำเนินการค้นหา
    const customers = await db.customers.search({
      query: validated.query,
      limit: validated.limit,
      tenantId: auth.tenantId  // การแยกส่วนแบบ multi-tenant
    });
    
    // ส่งคืนการตอบสนองที่มีโครงสร้าง
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            success: true,
            data: customers,
            meta: {
              count: customers.length,
              query: validated.query
            }
          }, null, 2)
        }
      ]
    };
  },

  async create_order(args: unknown, auth: AuthContext) {
    const validated = CreateOrderSchema.parse(args);
    
    // ตรวจสอบว่าลูกค้าอยู่ใน tenant
    const customer = await db.customers.findById(validated.customerId);
    if (customer.tenantId !== auth.tenantId) {
      throw new McpError(
        ErrorCode.InvalidRequest,
        "ไม่พบลูกค้า"
      );
    }
    
    // สร้างคำสั่งซื้อพร้อม audit trail
    const order = await db.orders.create({
      ...validated,
      tenantId: auth.tenantId,
      createdBy: auth.userId,
      createdAt: new Date()
    });
    
    // ส่งคืนการตอบสนองความสำเร็จ
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            success: true,
            data: {
              orderId: order.id,
              status: "created",
              total: order.items.reduce((sum, item) => sum + item.price * item.quantity, 0)
            },
            meta: {
              executionTime: Date.now() - startTime
            }
          }, null, 2)
        }
      ]
    };
  }
};

# Dockerfile
FROM node:20-alpine

WORKDIR /app

# ติดตั้ง dependencies
COPY package*.json ./
RUN npm ci --only=production

# คัดลอก source
COPY dist/ ./dist/

# ผู้ใช้ non-root เพื่อความปลอดภัย
USER node

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD node -e "console.log('healthcheck')" || exit 1

# เปิดพอร์ตสำหรับ transport HTTP
EXPOSE 3000

# เริ่มต้น server
CMD ["node", "dist/index.js"]

# docker-compose.yml
version: "3.8"

services:
  mcp-server:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - JWT_SECRET=${JWT_SECRET}
      - DATABASE_URL=${DATABASE_URL}
      - REDIS_URL=${REDIS_URL}
    depends_on:
      - redis
      - db
    restart: unless-stopped
    deploy:
      replicas: 3
      resources:
        limits:
          cpus: '1'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    volumes:
      - redis-data:/data

  db:
    image: postgres:16-alpine
    environment:
      - POSTGRES_USER=mcp
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=mcp_data
    volumes:
      - postgres-data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  redis-data:
  postgres-data: