MCP (Model Context Protocol): Panduan Lengkap untuk Pembangun

Model Context Protocol (MCP) ialah standard terbuka yang dicipta oleh Anthropic yang mentakrifkan cara model AI berkomunikasi dengan alat luaran, sumber data dan perkhidmatan. Fikirkan ia sebagai "USB-C untuk AI" - penyambung sejagat yang membolehkan mana-mana ejen AI berkomunikasi dengan mana-mana alat melalui antara muka yang diseragamkan.

Sejak pelancaran, MCP telah melepasi 97 juta muat turun SDK bulanan dan telah diterima pakai oleh semua pembekal AI utama: Anthropic, OpenAI, Google, Microsoft dan Amazon. Dalam panduan ini, kita akan meneroka semua yang anda perlu tahu untuk membina dengan MCP.

Mengapa MCP Wujud

Sebelum MCP, setiap aplikasi AI perlu membina integrasi tersuai untuk setiap alat yang ingin digunakan. Mahu AI anda membaca fail? Tulis kod tersuai. Buat pertanyaan pangkalan data? Lagi kod tersuai. Pos ke Slack? Satu lagi integrasi.

Ini mewujudkan masalah N×M: N aplikasi AI setiap satu memerlukan M integrasi tersuai, menyebabkan usaha berganda dan ekosistem yang berpecah.

MCP menyelesaikan ini dengan satu protokol yang mana-mana klien AI boleh gunakan untuk berkomunikasi dengan mana-mana pelayan MCP:

Konsep Teras

MCP mempunyai tiga primitif asas:

1. Alat (Tools)

Alat ialah fungsi yang AI boleh panggil. Ia mewakili tindakan seperti "cipta fail", "buat pertanyaan pangkalan data" atau "hantar mesej". Setiap alat mempunyai nama, penerangan dan JSON Schema untuk parameternya.

{
  name: "create_issue",
  description: "Create a new GitHub issue",
  inputSchema: {
    type: "object",
    properties: {
      title: { type: "string", description: "Issue title" },
      body: { type: "string", description: "Issue body" },
      repo: { type: "string", description: "Repository name" }
    },
    required: ["title", "repo"]
  }
}

2. Sumber (Resources)

Sumber ialah data yang AI boleh baca. Ia mewakili fail, rekod pangkalan data, respons API atau mana-mana sumber data lain. Sumber dikenal pasti melalui URI.

{
  uri: "file:///Users/dev/project/README.md",
  name: "Project README",
  mimeType: "text/markdown"
}

3. Prompt

Prompt ialah templat yang boleh diguna semula yang membantu menstruktur interaksi. Ia boleh mengandungi parameter dinamik dan berguna untuk menyeragamkan aliran kerja biasa.

{
  name: "code_review",
  description: "Review code changes for quality and security",
  arguments: [
    { name: "diff", description: "The code diff to review", required: true }
  ]
}

Seni Bina

MCP mengikuti seni bina klien-pelayan:

• Hos: Aplikasi AI (Claude Desktop, Cursor, aplikasi tersuai anda)
• Klien: Mengekalkan sambungan 1:1 dengan pelayan MCP
• Pelayan: Mendedahkan alat, sumber dan prompt kepada klien
• Pengangkutan: Komunikasi berlaku melalui JSON-RPC 2.0 menerusi stdio (tempatan) atau Server-Sent Events (jauh)

Membina Pelayan MCP

Mari kita bina pelayan MCP praktikal yang berinteraksi dengan senarai tugas yang disimpan dalam fail JSON.

Persediaan

mkdir mcp-todo-server && cd mcp-todo-server
npm init -y
npm install @modelcontextprotocol/sdk zod

Pelaksanaan Pelayan

// src/index.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import fs from "fs";

const TODO_FILE = "./todos.json";

function readTodos(): { id: number; text: string; done: boolean }[] {
  if (!fs.existsSync(TODO_FILE)) return [];
  return JSON.parse(fs.readFileSync(TODO_FILE, "utf-8"));
}

function writeTodos(todos: { id: number; text: string; done: boolean }[]) {
  fs.writeFileSync(TODO_FILE, JSON.stringify(todos, null, 2));
}

const server = new McpServer({
  name: "todo-server",
  version: "1.0.0",
});

// Tool: Add a todo
server.tool(
  "add_todo",
  "Add a new todo item",
  { text: z.string().describe("The todo text") },
  async ({ text }) => {
    const todos = readTodos();
    const newTodo = { id: Date.now(), text, done: false };
    todos.push(newTodo);
    writeTodos(todos);
    return { content: [{ type: "text", text: `Added: "${text}"` }] };
  }
);

// Tool: List todos
server.tool(
  "list_todos",
  "List all todo items",
  {},
  async () => {
    const todos = readTodos();
    const list = todos
      .map((t) => `${t.done ? "✅" : "⬜"} [${t.id}] ${t.text}`)
      .join("\n");
    return { content: [{ type: "text", text: list || "No todos yet." }] };
  }
);

// Tool: Complete a todo
server.tool(
  "complete_todo",
  "Mark a todo as completed",
  { id: z.number().describe("The todo ID to complete") },
  async ({ id }) => {
    const todos = readTodos();
    const todo = todos.find((t) => t.id === id);
    if (!todo) return { content: [{ type: "text", text: "Todo not found." }] };
    todo.done = true;
    writeTodos(todos);
    return { content: [{ type: "text", text: `Completed: "${todo.text}"` }] };
  }
);

// Resource: Current todos as a readable resource
server.resource(
  "todos://list",
  "Current todo list",
  async () => ({
    contents: [{
      uri: "todos://list",
      mimeType: "application/json",
      text: JSON.stringify(readTodos(), null, 2),
    }],
  })
);

// Start the server
const transport = new StdioServerTransport();
await server.connect(transport);

Konfigurasi

Untuk menggunakan pelayan ini dengan Claude Desktop, tambahkan ke konfigurasi anda:

{
  "mcpServers": {
    "todo": {
      "command": "npx",
      "args": ["tsx", "/path/to/mcp-todo-server/src/index.ts"]
    }
  }
}

Membina Klien MCP

Anda juga boleh membina klien tersuai yang menyambung ke mana-mana pelayan MCP:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["tsx", "./src/index.ts"],
});

const client = new Client({ name: "my-client", version: "1.0.0" });
await client.connect(transport);

// List available tools
const { tools } = await client.listTools();
console.log("Available tools:", tools.map((t) => t.name));

// Call a tool
const result = await client.callTool({
  name: "add_todo",
  arguments: { text: "Write MCP blog post" },
});
console.log(result);

Pelayan MCP Popular

Ekosistem MCP telah berkembang pesat. Berikut adalah beberapa pelayan paling popular:

MCP vs A2A (Agent-to-Agent)

Sementara MCP mengendalikan komunikasi ejen-ke-alat, protokol A2A (Agent-to-Agent) Google mengendalikan komunikasi ejen-ke-ejen. Mereka saling melengkapi:

• MCP: Bagaimana ejen AI menggunakan alat (integrasi menegak)
• A2A: Bagaimana ejen AI bekerjasama antara satu sama lain (integrasi mendatar)

Amalan Terbaik

1. Pastikan pelayan berfokus: Satu pelayan untuk setiap domain (pelayan GitHub, pelayan Slack, dll.). Jangan bina pelayan monolitik.
2. Sahkan input dengan Zod: Sentiasa sahkan input alat dengan skema yang sesuai.
3. Kendalikan ralat dengan baik: Kembalikan mesej ralat yang bermakna, bukan stack trace.
4. Gunakan sumber untuk data baca sahaja: Jika AI hanya perlu membaca data, dedahkan sebagai sumber berbanding alat.
5. Tambah penerangan yang sesuai: Penerangan alat dan parameter yang baik membantu AI memahami bila dan bagaimana menggunakan setiap alat.
6. Uji dengan MCP Inspector: Gunakan npx @modelcontextprotocol/inspector untuk menguji pelayan anda secara interaktif.

Mula

# Create a new MCP server from template
npx @modelcontextprotocol/create-server my-server

# Test with the MCP Inspector
npx @modelcontextprotocol/inspector npx tsx ./src/index.ts

Kesimpulan

MCP telah menjadi standard de facto untuk penggunaan alat AI pada tahun 2026. Sama ada anda membina ejen AI tersuai, memperluaskan Claude Code, atau mencipta integrasi untuk platform sedia ada, memahami MCP adalah penting. Protokol ini cukup mudah untuk dipelajari dalam satu petang tetapi cukup berkuasa untuk membina aliran kerja AI peringkat pengeluaran.

Langkah seterusnya:

• Terokai Spesifikasi MCP
• Layari pelayan MCP sedia ada untuk inspirasi
• Bina pelayan pertama anda dengan TypeScript atau Python SDK
• Uji dengan Claude Desktop atau MCP Inspector