MCP 从零到一【入门】

MCP 从零到一完整教程

适合人群：完全没接触过 MCP 的小白目标：理解 MCP 是什么，并实现一个简单的 MCP 工具集成到 Kiro

一、理论基础

什么是 MCP？

MCP（Model Context Protocol）是 Anthropic 提出的一个开放协议，本质上是一个标准化的通信协议，让 AI 助手（比如 Kiro/Claude）能够安全地调用外部工具和数据源。

可以把它理解成：

AI 是"大脑"
MCP Server 是"手和眼睛"
MCP 协议是它们之间的"神经系统"

架构图

scss 复制代码

┌─────────────┐     MCP协议      ┌─────────────────┐
│  AI 客户端   │ ◄──────────────► │   MCP Server    │
│  (Kiro)     │                  │  (你写的工具)    │
└─────────────┘                  └─────────────────┘
                                         │
                                    ┌────▼────┐
                                    │ 真实世界 │
                                    │文件/API  │
                                    │数据库等  │
                                    └─────────┘

MCP Server 能提供的三种能力

能力	说明	常用程度
Tools（工具）	AI 可以调用的函数，比如查天气、读文件	⭐⭐⭐ 最常用
Resources（资源）	AI 可以读取的数据，比如文件内容	⭐⭐
Prompts（提示词）	预定义的提示词模板	⭐

本教程重点实现 Tools。

二、环境准备

需要安装：

Node.js（推荐 v18+）
npm

检查是否已安装：

bash 复制代码

node --version
npm --version

三、动手实现一个简单的 MCP Server

我们来做一个**"计算器 + 时间查询 + 打招呼"**的 MCP 工具，包含：

add - 两数相加
get_current_time - 获取当前时间
greet - 打招呼（演示传参）

第一步：创建项目

bash 复制代码

mkdir my-first-mcp
cd my-first-mcp
npm init -y

第二步：安装依赖

bash 复制代码

npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node

依赖说明：

@modelcontextprotocol/sdk - MCP 官方 SDK
zod - 参数校验库，用来定义工具的入参类型
typescript / @types/node - TypeScript 支持

第三步：配置 TypeScript

创建 tsconfig.json：

json 复制代码

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

更新 package.json，添加 type 和 scripts：

json 复制代码

{
  "name": "my-first-mcp",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "dev": "tsc && node dist/index.js"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.0",
    "zod": "^3.0.0"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "typescript": "^5.0.0"
  }
}

第四步：编写 MCP Server 代码

创建目录和文件：

bash 复制代码

mkdir src
touch src/index.ts

写入以下内容到 src/index.ts：

typescript 复制代码

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

// 1. 创建 MCP Server 实例
const server = new McpServer({
  name: "my-first-mcp",   // 工具名称
  version: "1.0.0",        // 版本号
});

// 2. 注册工具：两数相加
server.tool(
  "add",                    // 工具名（AI 调用时用这个名字）
  "计算两个数字的和",         // 工具描述（AI 靠这个理解何时调用）
  {
    a: z.number().describe("第一个数字"),
    b: z.number().describe("第二个数字"),
  },
  async ({ a, b }) => {
    const result = a + b;
    return {
      content: [
        {
          type: "text",
          text: `${a} + ${b} = ${result}`,
        },
      ],
    };
  }
);

// 3. 注册工具：获取当前时间
server.tool(
  "get_current_time",
  "获取当前的日期和时间",
  {},  // 无需参数，传空对象
  async () => {
    const now = new Date();
    const timeStr = now.toLocaleString("zh-CN", {
      timeZone: "Asia/Shanghai",
      year: "numeric",
      month: "2-digit",
      day: "2-digit",
      hour: "2-digit",
      minute: "2-digit",
      second: "2-digit",
    });
    return {
      content: [
        {
          type: "text",
          text: `当前时间（北京时间）：${timeStr}`,
        },
      ],
    };
  }
);

// 4. 注册工具：打招呼
server.tool(
  "greet",
  "向指定的人打招呼",
  {
    name: z.string().describe("要打招呼的人的名字"),
    language: z
      .enum(["zh", "en", "ja"])
      .optional()
      .describe("语言：zh=中文, en=英文, ja=日文，默认中文"),
  },
  async ({ name, language = "zh" }) => {
    const greetings: Record<string, string> = {
      zh: `你好，${name}！欢迎使用 MCP！`,
      en: `Hello, ${name}! Welcome to MCP!`,
      ja: `こんにちは、${name}さん！MCPへようこそ！`,
    };
    return {
      content: [
        {
          type: "text",
          text: greetings[language],
        },
      ],
    };
  }
);

// 5. 启动 Server（使用标准输入输出通信）
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  // 注意：日志必须用 stderr，不能用 stdout（stdout 是 MCP 通信通道）
  console.error("MCP Server 已启动！");
}

main().catch(console.error);

第五步：构建

bash 复制代码

npm run build

构建成功后会生成 dist/index.js。

验证能否正常运行（运行后没有报错就对了，Ctrl+C 退出）：

bash 复制代码

node dist/index.js

四、集成到 Kiro

找到 MCP 配置文件

Kiro 的全局 MCP 配置文件路径：

javascript 复制代码

~/.kiro/settings/mcp.json

编辑配置文件

打开该文件（不存在则新建），添加你的 MCP Server：

json 复制代码

{
  "mcpServers": {
    "my-first-mcp": {
      "command": "node",
      "args": ["/Users/你的用户名/my-first-mcp/dist/index.js"],
      "disabled": false,
      "autoApprove": ["add", "get_current_time", "greet"]
    }
  }
}

⚠️ 把路径替换成你实际的项目绝对路径，例如： /Users/hb29531/my-first-mcp/dist/index.js

重新连接 MCP Server

打开命令面板：Cmd + Shift + P
搜索 MCP
点击 Reconnect MCP Servers

或者在 Kiro 功能面板的 MCP Server 视图中手动重连。

五、验证效果

配置好后，在 Kiro 聊天框里直接问：

复制代码

帮我计算 123 + 456

现在几点了？

用英文跟 Tom 打个招呼

Kiro 会自动识别意图并调用你的 MCP 工具。

六、完整项目结构

css 复制代码

my-first-mcp/
├── src/
│   └── index.ts        ← 核心代码（你编写的）
├── dist/               ← 编译产物（build 后自动生成）
│   └── index.js
├── package.json
├── tsconfig.json
└── node_modules/

七、关键概念回顾

概念	说明
`McpServer`	MCP Server 的核心类，用来注册工具
`server.tool(name, desc, schema, handler)`	注册一个工具
`z.number() / z.string()`	用 zod 定义参数类型
`StdioServerTransport`	通过标准输入输出与 AI 通信
`autoApprove`	配置哪些工具无需用户确认直接执行

八、进阶方向

掌握基础后，可以继续探索：

方向	说明
调用外部 API	在工具里用 `fetch` 请求天气、股票等接口
读写文件	用 `fs` 模块操作本地文件
查询数据库	连接 MySQL/SQLite 做数据查询工具
封装内部系统	包装公司内部 SOA/HTTP 接口
发布到 npm	让别人也能用 `uvx` 一键安装你的 MCP

九、快速上手命令汇总

bash 复制代码

# 1. 创建项目
mkdir my-first-mcp && cd my-first-mcp
npm init -y

# 2. 安装依赖
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node

# 3. 创建配置文件（tsconfig.json、更新 package.json）

# 4. 创建源码
mkdir src && touch src/index.ts
# 写入上面的代码...

# 5. 构建
npx tsc

# 6. 测试运行
node dist/index.js

# 7. 配置到 ~/.kiro/settings/mcp.json，重连即可