从零搭建 MCP Server:AI 助手也能直接操作文件系统

嘿，小伙伴们好呀！

最近玩了个挺有意思的东西 —— MCP（Model Context Protocol）。

起因是之前配置了下 Agent，让它去帮我更新下这个 GitHub 仓库，用到了这个 Github MCP 工具。

挺好奇它的原理，便自己做了个 能操作文件系统的MCP demo 来学习下。

一起来看看吧。

<(￣︶￣)↗[GO!]

01

PART

🤔 什么是 MCP？

CHAPTER

一句话解释

MCP 就是 AI 和外部工具之间的桥梁。

以前，AI 只能跟你聊天，想让它帮你创建文件、查数据？门儿都没有。

现在，通过 MCP 协议，AI 可以像调用函数一样，直接执行本地代码。

举个例子

你对 Trae 说：

"帮我在桌面创建一个 todo.txt 文件"

Trae 会：

1. 1理解你的意图
2. 2找到对应的 MCP 工具（write_file）
3. 3调用工具执行操作
4. 4返回结果给你

整个过程，你只需要说人话就行。

工作原理

text
你 (用户)
　　　　↓ 自然语言提问
Trae (AI 助手)
　　　　↓ 解析意图，选择工具
MCP Server (你的本地服务)
　　　　↓ 执行具体操作
文件系统 / 数据库 / API

这就像你雇了个助理，助理不用懂怎么编程，只要会"打电话"给专业人士就行。

02

PART

🚀 动手搭建：文件管理器 MCP Server

SETUP

下面是实践内容 —— 来搭建一个能操作文件系统的 MCP Server。

就不用 Java 了 哈哈，用 node.js 来写快些~

(～￣▽￣)～

环境准备

• Node.js（推荐 v18+）
• npm 或 yarn
• 一个支持 MCP 的 AI 助手（比如 Trae、Cursor、Claude Desktop）

第一步：初始化项目

bash
mkdir my-mcp-server
cd my-mcp-server
npm init -y

第二步：安装依赖

bash
npm install @modelcontextprotocol/sdk zod

• @modelcontextprotocol/sdk — MCP 的核心 SDK
• zod — 参数验证库

第三步：编写核心代码

创建 src/index.js 文件：

javascript
import * as z from 'zod';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js';
import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
import { randomUUID } from 'node:crypto';
import fs from 'fs';
import path from 'path';

引入我们需要的模块

第四步：注册工具

javascript
const getServer = () => {
　　const server = new McpServer({
　　　　name: 'File Manager',
　　　　version: '1.0.0',
　　　　description: '文件管理 MCP Server'
　　}, {
　　　　capabilities: { logging: {} }
　　});
　　server.registerTool('list_files', {
　　　　title: '列出文件',
　　　　description: '列出指定目录下的所有文件和文件夹',
　　　　inputSchema: {
　　　　　　directory: z.string().describe('要列出的目录路径')
　　　　}
　　}, async ({ directory }) => {
　　　　const files = fs.readdirSync(directory);
　　　　const fileInfo = files.map(file => {
　　　　　　const filePath = path.join(directory, file);
　　　　　　const stats = fs.statSync(filePath);
　　　　　　return {
　　　　　　　　name: file,
　　　　　　　　type: stats.isDirectory() ? 'directory' : 'file',
　　　　　　　　size: stats.size,
　　　　　　　　modified: stats.mtime.toISOString()
　　　　　　};
　　　　});
　　　　return {
　　　　　　content: [{ type: 'text', text: JSON.stringify(fileInfo, null, 2) }]
　　　　};
　　});
　　// ... 注册其他工具
};

这段代码做了三件事：

1. 1创建一个 MCP Server 实例
2. 2注册一个 list_files 工具
3. 3定义工具的参数和处理函数

你可以像这样注册任意多个工具。

第五步：配置 HTTP 传输

javascript
const PORT = 8080;
const app = createMcpExpressApp();
const transports = {};
const mcpPostHandler = async (req, res) => {
　　const sessionId = req.headers['mcp-session-id'];
　　if (sessionId && transports[sessionId]) {
　　　　await transports[sessionId].handleRequest(req, res, req.body);
　　} else if (!sessionId && isInitializeRequest(req.body)) {
　　　　const transport = new StreamableHTTPServerTransport({
　　　　　　sessionIdGenerator: () => randomUUID(),
　　　　　　onsessioninitialized: (sid) => {
　　　　　　　　transports[sid] = transport;
　　　　　　}
　　　　});
　　　　transport.onclose = () => {
　　　　　　delete transports[transport.sessionId];
　　　　};
　　　　const server = getServer();
　　　　await server.connect(transport);
　　　　await transport.handleRequest(req, res, req.body);
　　} else {
　　　　res.status(400).json({
　　　　　　jsonrpc: '2.0',
　　　　　　error: { code: -32000, message: 'Bad Request' },
　　　　　　id: null
　　　　});
　　}
};
app.post('/mcp', mcpPostHandler);
app.listen(PORT, () => {
　　console.log(`MCP Server running on http://localhost:${PORT}/mcp`);
});

这里的关键是：

1. 1使用 HTTP 传输方式（还有 stdio 方式，但 HTTP 更稳定）
2. 2维护一个会话池，每个会话对应一个 transport
3. 3初始化请求创建新会话，后续请求复用会话

03

PART

📝 测试运行

TESTING

启动服务器

bash
npm start

看到下面的输出就说明启动成功了：

text
🚀 文件管理 MCP Server 启动中...
🔗 HTTP 地址: http://localhost:8080/mcp
✅ MCP Server 已启动，等待客户端连接...

配置 Trae

打开 Trae 的 mcp.json 配置文件，添加：

json
{
　　"mcpServers": {
　　　　"file-manager": {
　　　　　　"url": "http://localhost:8080/mcp"
　　　　}
　　}
}

配置成功后可以看到这个 MCP 👇

开始使用

现在你可以直接用自然语言操作文件系统了：

text
帮我列出当前目录下的文件
帮我读取 package.json 文件内容
帮我创建一个 demo.txt 文件
帮我删除 demo.txt 文件

比如我让它创建个文件，可以看到它调用了这个工具 👇

04

PART

💡 遇到的坑

PITFALLS

坑 1：协议版本不匹配

刚开始我用了错误的协议版本，导致 initialize 请求一直失败。

解决方案：确保你的请求包含正确的 protocolVersion 和 clientInfo。

javascript
{
　　"jsonrpc": "2.0",
　　"method": "initialize",
　　"params": {
　　　　"protocolVersion": "2024-11-05",
　　　　"capabilities": {},
　　　　"clientInfo": {
　　　　　　"name": "test-client",
　　　　　　"version": "1.0.0"
　　　　}
　　}
}

坑 2：会话管理

MCP 使用会话机制，每个会话有一个 ID。

注意：

• 初始化请求不需要会话 ID（会自动生成）
• 后续请求必须带上会话 ID
• 会话过期后需要重新初始化

坑 3：传输方式选择

MCP 支持两种传输方式：

demo 选择了 HTTP 的方式。一开始没配置好，用了 stdio 没连上。

///

LAST

🎉 总结

SUMMARY

搭建一个 MCP Server 其实很简单，核心就三步：

快去试试吧~ ヾ(≧▽≦*)o