基于MCP协议构建专属AI开发助手：从原理到实践

1. 项目概述一个为开发者定制的MCP服务器最近在折腾AI应用开发特别是想给Claude、Cursor这类智能助手增加一些“超能力”让它们能直接操作我本地的开发环境。比如让AI帮我直接运行单元测试、查看最近的Git提交、或者分析某个目录下的代码结构。这听起来很酷对吧但市面上现成的工具要么功能太泛要么配置复杂得让人头疼。直到我发现了“CCCpan/mcp-custom-dev”这个项目它精准地切中了我的需求一个专门为开发者定制的、高度可配置的模型上下文协议Model Context Protocol MCP服务器实现。简单来说MCP就像是一个翻译官和接线员它定义了一套标准让AI助手客户端能够安全、可控地调用我们本地环境或远程服务服务器端提供的各种工具Tools和资源Resources。而“mcp-custom-dev”这个项目就是提供了一个MCP服务器的“骨架”或“样板间”。它不是一个开箱即用、功能固定的成品而是一个让你能快速搭建属于自己专属开发助手的脚手架。你可以基于它轻松地将你日常的开发命令如git status、npm run test、find . -name “*.py”、内部API甚至是复杂的构建流水线封装成AI可以理解和调用的工具。这个项目特别适合两类开发者一是希望深度集成AI到自身工作流的效率追求者二是想要为团队构建统一AI赋能平台的技术负责人。它解决了“通用AI工具不懂我具体业务”和“自己从头实现MCP服务器门槛高”这两个核心痛点。接下来我就结合自己把它跑起来并扩展功能的实际经历拆解一下它的核心设计、如何上手以及如何让它真正为你所用。2. 核心设计思路与架构拆解2.1 为什么是MCP协议层的价值在深入代码之前有必要先理解MCP协议本身的价值。在AI原生应用爆发之前我们想让程序A调用程序B的功能有REST API、GraphQL、gRPC等多种方式。但当调用方变成了大型语言模型LLM情况就变了。LLM不擅长处理复杂的、非结构化的协议细节和状态管理。MCP协议的核心贡献在于它为“AI助手调用外部功能”这个场景定义了一套极简的、基于JSON-RPC的标准化对话流程。服务器只需要向客户端宣告“我这里有这些工具每个工具都有明确的名称、描述和参数JSON Schema和资源如只读的文本文件。” 客户端AI在需要时就会按照Schema来构造参数并发起调用。这个过程对AI来说是高度结构化和可预测的极大地提高了工具调用的准确性和可靠性。“mcp-custom-dev”项目正是基于这个协议构建了一个服务器端的样板。它没有试图做一个大而全的工具箱而是把重心放在了“如何让开发者最方便地添加自己的工具”上。这种设计哲学非常务实因为开发者的需求千差万别一个固定的工具列表永远无法满足所有人。2.2 项目骨架与模块化设计克隆项目后浏览其目录结构就能清晰看出它的设计思路mcp-custom-dev/ ├── src/ │ ├── tools/ # 工具模块目录 │ │ ├── __init__.py │ │ ├── system_info.py # 示例工具获取系统信息 │ │ └── custom_tool.py # 自定义工具模板 │ ├── resources/ # 资源模块目录可选 │ ├── server.py # MCP服务器主入口 │ └── config.py # 配置文件 ├── requirements.txt # Python依赖 ├── README.md └── .env.example # 环境变量示例这种模块化设计是项目的精髓。src/tools/目录下的每一个Python文件理论上都可以定义一个或多个工具。服务器启动时会自动发现并加载这些工具。这意味着扩展功能变得极其简单你不需要去修改核心的server.py只需要在tools/目录下新建一个文件按照模板实现你的工具逻辑即可。这种“约定大于配置”的方式既保证了核心的稳定性又赋予了极大的灵活性。config.py和.env文件则负责管理配置比如服务器监听的端口、是否启用调试模式、某些工具所需的API密钥等。将配置外部化使得部署和不同环境间的切换变得容易。2.3 安全与执行沙箱考量任何允许AI执行本地命令的项目安全都是头等大事。“mcp-custom-dev”在安全设计上采取了“责任共担”的模式。项目本身提供了执行自定义代码的能力但将具体命令的安全边界交给了开发者自己来定义。这听起来有点吓人但实际上它通过设计引导你走向安全工具隔离每个工具在独立的模块中实现一个工具的崩溃不会直接影响服务器或其他工具。参数化输入工具通过定义严格的JSON Schema来声明输入参数AI只能传递符合格式的数据这在一定程度上防止了注入攻击。无默认高危工具项目自带的示例工具如get_system_info是只读的、无害的。危险的命令如rm -rf、任意命令执行不会作为默认工具提供。依赖最小化项目依赖非常干净主要是mcp标准库和一些基础工具减少了供应链攻击面。然而最重要的安全闸门在于开发者自身。当你编写一个执行shell命令的工具时你必须非常谨慎地处理输入避免将未经验证的用户输入直接拼接成命令。项目给了你一把锋利的刀但刀口朝向哪里需要你自己来决定。在后续的实操部分我会重点分享如何安全地实现命令执行类工具。3. 从零开始环境搭建与快速启动3.1 基础环境准备这个项目是Python实现的所以首先确保你的系统有Python 3.8或更高版本。我推荐使用pyenv或conda来管理Python版本避免污染系统环境。# 1. 克隆项目 git clone https://github.com/CCCpan/mcp-custom-dev.git cd mcp-custom-dev # 2. 创建并激活虚拟环境强烈推荐 python -m venv venv # 在Windows上: venv\Scripts\activate # 在macOS/Linux上: source venv/bin/activate # 3. 安装依赖 pip install -r requirements.txt依赖项通常包括mcp这个核心库以及其他一些用于示例工具的辅助库如psutil用于获取系统信息。安装过程一般很顺利。3.2 配置与首次运行首次运行前最好先复制环境变量示例文件并查看配置文件。cp .env.example .env # 此时可以编辑 .env 文件但首次运行通常不需要修改接下来直接运行服务器python src/server.py如果一切正常你会看到类似下面的输出表明MCP服务器已经在标准输入输出stdio上启动了。MCP服务器通常以stdio方式与客户端如Claude Desktop通信而不是HTTP服务。INFO: Started MCP server on stdio. Available tools: get_system_info注意你可能看到服务器启动后似乎“挂起”了没有返回命令行提示符。这是正常的因为MCP服务器设计为通过标准输入输出stdio与父进程通常是AI客户端进行持续通信。你直接在前台运行它它就在等待客户端连接。要测试它我们需要一个MCP客户端。3.3 使用MCP Inspector进行本地测试为了在不启动完整AI客户端的情况下调试和测试你的工具Anthropic官方提供了一个非常实用的工具叫MCP Inspector。它是一个基于Web的图形化界面可以连接到你的MCP服务器列出所有可用的工具和资源并允许你手动调用它们观察请求和响应。首先全局安装MCP Inspector需要Node.js环境npm install -g modelcontextprotocol/inspector然后在一个新的终端窗口导航到你的项目目录确保虚拟环境已激活运行mcp-inspector python src/server.py这个命令会启动Inspector并让它执行python src/server.py作为子进程即你的MCP服务器。浏览器会自动打开一个页面通常是http://localhost:5173。在Inspector的界面上你就能看到get_system_info这个工具点击它再点击“Call”就能看到返回的系统信息JSON数据。这是开发过程中不可或缺的一步它能让你快速验证工具是否被正确加载、参数Schema是否定义准确、以及工具逻辑是否按预期工作。4. 核心实战打造你的专属开发工具集项目自带的get_system_info工具只是个引子。真正的威力在于添加你自己的工具。下面我将以三个典型的开发者场景为例手把手带你创建工具。4.1 工具一智能Git状态查询作为开发者最常问的问题之一就是“我改了哪些文件”。让我们创建一个工具让AI能告诉我们当前Git仓库的状态。在src/tools/目录下新建一个文件git_tools.pyimport subprocess import json from typing import Any from mcp.types import Tool def run_git_command(args: list[str]) - tuple[str, str, int]: 安全地运行git命令返回(stdout, stderr, returncode)。 try: result subprocess.run( [git] args, capture_outputTrue, textTrue, cwd., # 在当前目录运行 timeout10 # 设置超时防止挂起 ) return result.stdout, result.stderr, result.returncode except subprocess.TimeoutExpired: return , Command timed out, -1 except FileNotFoundError: return , Git is not installed or not in PATH, -1 async def get_git_status() - dict[str, Any]: 获取当前Git仓库的状态概览。 返回一个包含分支、提交、变更文件等信息的字典。 status_info {} # 1. 获取当前分支 stdout, stderr, rc run_git_command([branch, --show-current]) if rc 0: status_info[current_branch] stdout.strip() else: status_info[current_branch] fError: {stderr.strip()} # 2. 获取与远程的差异例如领先或落后多少个提交 stdout, stderr, rc run_git_command([status, -sb]) if rc 0: # 状态简览通常在输出的第一行 status_info[short_status] stdout.split(\n)[0] if stdout else # 3. 获取暂存区和非暂存区的变更文件列表更结构化 changed_files {staged: [], unstaged: [], untracked: []} # 使用 git status --porcelain 获取机器可读的输出 stdout, stderr, rc run_git_command([status, --porcelain]) if rc 0: for line in stdout.strip().split(\n): if not line: continue # porcelain格式: XY filename # X: 暂存区状态 Y: 工作区状态 code line[:2] filename line[3:] if code ??: changed_files[untracked].append(filename) elif code[0] ! and code[0] ! ?: # 暂存区有变化 changed_files[staged].append(f{code} {filename}) elif code[1] ! : # 工作区有变化但未暂存 changed_files[unstaged].append(f{code} {filename}) status_info[changed_files] changed_files # 4. 获取最近一次提交信息 stdout, stderr, rc run_git_command([log, -1, --oneline]) if rc 0 and stdout: status_info[last_commit] stdout.strip() return { content: [{ type: text, text: json.dumps(status_info, indent2, ensure_asciiFalse) }] } # 定义工具元数据供MCP服务器发现 get_git_status_tool Tool( nameget_git_status, description获取当前Git仓库的详细状态包括分支、变更文件列表和最近提交。, inputSchema{ type: object, properties: {}, # 此工具不需要输入参数 required: [] } )接下来我们需要在服务器启动时注册这个工具。修改src/server.py或相应的工具加载模块确保导入了新的工具模块。在mcp-custom-dev的架构中通常有一个自动发现机制。你需要检查项目是如何加载tools/目录下模块的。如果它是动态扫描的你可能只需要确保你的git_tools.py文件存在即可。如果它是静态注册的你需要在适当的位置比如一个__init__.py或主服务器文件中的列表添加你的工具。假设项目使用动态加载那么重启服务器后使用MCP Inspector你应该能看到新增的get_git_status工具。调用它你会得到一个结构化的JSON清晰展示了Git状态。实操心得错误处理是关键run_git_command函数封装了subprocess.run并添加了超时和异常捕获。永远不要相信外部命令一定能成功执行。结构化数据优于纯文本虽然我们可以直接返回git status的原始文本但将其解析为结构化的JSON如按staged、unstaged分类文件对AI客户端更友好AI能更精准地理解和回答后续问题例如“我有多少个未暂存的文件”。工作目录工具默认在当前工作目录运行git命令。如果你希望更灵活可以考虑将cwd工作目录作为一个可选的工具参数。4.2 工具二项目文件树导航另一个常见场景是想让AI了解我们项目的目录结构。我们可以创建一个工具让它列出指定目录下的文件和文件夹。在src/tools/目录下创建file_tools.pyimport os import json from pathlib import Path from typing import Any, Optional from mcp.types import Tool async def list_directory_contents( path: Optional[str] ., max_depth: Optional[int] 2, exclude_dirs: Optional[list[str]] None ) - dict[str, Any]: 列出指定目录下的内容以树状结构返回。 Args: path: 要列出的目录路径默认为当前目录。 max_depth: 遍历的最大深度默认为2即当前目录及其直接子目录。 exclude_dirs: 要排除的目录名列表例如 [.git, node_modules, __pycache__]。 if exclude_dirs is None: exclude_dirs [.git, node_modules, __pycache__, venv, .idea, .vscode] start_path Path(path).resolve() if not start_path.exists() or not start_path.is_dir(): return { content: [{ type: text, text: f错误路径 {path} 不存在或不是一个目录。 }] } def build_tree(dir_path: Path, current_depth: int) - dict: if current_depth max_depth: return {name: dir_path.name / (depth exceeded), type: dir, children: []} tree {name: dir_path.name /, type: dir, children: []} try: entries sorted(os.scandir(dir_path), keylambda e: (not e.is_dir(), e.name.lower())) for entry in entries: if entry.name in exclude_dirs: continue if entry.is_dir(): tree[children].append(build_tree(Path(entry.path), current_depth 1)) else: tree[children].append({name: entry.name, type: file}) except PermissionError: tree[children].append({name: [Permission Denied], type: error}) return tree tree_data build_tree(start_path, 0) # 为了在AI客户端中清晰显示我们可以生成一个文本形式的树状图和一个结构化的JSON def tree_to_text(node: dict, prefix: str ) - str: lines [] children node.get(children, []) for i, child in enumerate(children): is_last i len(children) - 1 connector └── if is_last else ├── lines.append(prefix connector child[name]) if child[type] dir: extension if is_last else │ lines.append(tree_to_text(child, prefix extension)) return \n.join(lines) text_tree f{start_path}/\n tree_to_text(tree_data) full_response { text_summary: text_tree, structured_data: tree_data } return { content: [{ type: text, text: json.dumps(full_response, indent2, ensure_asciiFalse) }] } list_directory_tool Tool( namelist_directory, description以树状结构列出指定目录的内容。可以控制遍历深度和排除特定目录如.git, node_modules。, inputSchema{ type: object, properties: { path: { type: string, description: 目录路径默认为当前目录(.)。, default: . }, max_depth: { type: integer, description: 最大遍历深度默认为2。, default: 2, minimum: 1, maximum: 5 # 防止深度过大导致性能问题 }, exclude_dirs: { type: array, items: {type: string}, description: 要排除的目录名列表。, default: [.git, node_modules, __pycache__, venv] } }, required: [] } )这个工具比第一个更复杂它展示了MCP工具的另一个强大特性参数化。我们定义了path、max_depth和exclude_dirs三个输入参数每个都有描述、类型和默认值。AI客户端在调用时可以根据用户的指令如“列出src目录下除了tests以外的所有文件深度为3”来填充这些参数。注意事项路径安全我们使用Path().resolve()来解析路径防止目录遍历攻击。在生产环境中可能需要更严格的路径白名单限制。性能与深度限制通过max_depth参数并设置最大值和exclude_dirs默认排除大型依赖目录防止因遍历整个巨大目录树而导致服务器阻塞。双格式输出我们同时返回了易于人类阅读的文本树和结构化的JSON数据。这兼顾了AI分析和开发者直接查看的需求。4.3 工具三安全的Shell命令执行高阶这是最强大也最危险的一类工具。我们必须极其小心地实现它只允许执行预定义的安全命令集或者对输入进行严格的过滤和沙箱化。方案A预定义命令集推荐给初学者创建一个工具只允许执行一个预先批准的命令列表比如ls,pwd,cat仅限特定文件python --version等。在src/tools/下创建safe_shell_tools.pyimport subprocess import shlex from typing import Any from mcp.types import Tool # 预定义的安全命令白名单 SAFE_COMMANDS { list_files: {cmd: [ls, -la], desc: 列出当前目录详细文件信息}, current_dir: {cmd: [pwd], desc: 显示当前工作目录}, python_version: {cmd: [python, --version], desc: 显示Python版本}, disk_usage: {cmd: [df, -h], desc: 显示磁盘使用情况}, } async def execute_safe_command(command_key: str) - dict[str, Any]: 执行一个预定义的安全命令。 if command_key not in SAFE_COMMANDS: return { content: [{ type: text, text: f错误命令 {command_key} 不在安全白名单中。可用命令{list(SAFE_COMMANDS.keys())} }] } cmd_info SAFE_COMMANDS[command_key] try: result subprocess.run( cmd_info[cmd], capture_outputTrue, textTrue, timeout15 ) output f$ { .join(cmd_info[cmd])}\n output f退出码: {result.returncode}\n if result.stdout: output f标准输出:\n{result.stdout}\n if result.stderr: output f标准错误:\n{result.stderr}\n return {content: [{type: text, text: output}]} except subprocess.TimeoutExpired: return {content: [{type: text, text: f命令执行超时。}]} except Exception as e: return {content: [{type: text, text: f执行命令时发生异常{e}}]} execute_safe_command_tool Tool( nameexecute_safe_command, description执行一个预定义的安全Shell命令。避免直接执行任意用户输入。, inputSchema{ type: object, properties: { command_key: { type: string, description: f要执行的安全命令键。可选值{list(SAFE_COMMANDS.keys())}, enum: list(SAFE_COMMANDS.keys()) # 使用enum严格限制输入 } }, required: [command_key] } )方案B受限的通用执行需高级安全措施如果你确实需要更灵活的执行能力可以考虑以下加固措施命令前缀限制只允许以特定前缀开头如git,npm run,python -m pytest等。参数过滤使用shlex.split安全地分割参数避免;、、|等命令注入。沙箱环境考虑使用docker run在容器内执行命令或使用subprocess的cwd限制在特定沙箱目录。用户身份以低权限用户运行MCP服务器进程。核心安全警告永远不要实现一个接收纯字符串并直接调用os.system(command)或subprocess.run(command, shellTrue)的工具。这等于将你服务器的Shell完全暴露给了AI以及任何能向AI发送指令的人。方案A是更安全的选择。即使采用方案B也必须结合严格的输入验证、白名单和沙箱机制。5. 集成与使用连接AI客户端工具开发并测试完毕后下一步就是让它们能被真正的AI助手调用。这里以集成到Claude Desktop为例。5.1 配置Claude DesktopClaude Desktop支持通过配置文件来添加自定义的MCP服务器。找到配置文件位置macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json编辑配置文件如果文件不存在就创建它。添加以下内容假设你的项目路径是/Users/yourname/Projects/mcp-custom-dev{ mcpServers: { my-custom-dev-tools: { command: /Users/yourname/Projects/mcp-custom-dev/venv/bin/python, args: [ /Users/yourname/Projects/mcp-custom-dev/src/server.py ], env: { PYTHONPATH: /Users/yourname/Projects/mcp-custom-dev/src } } } }关键点解释command: 必须指向你虚拟环境中的Python解释器绝对路径。这是最常见的错误来源。使用which python在激活的虚拟环境中来获取完整路径。args: 包含要执行的Python脚本的绝对路径。env: 设置PYTHONPATH确保你的工具模块能被正确导入。重启Claude Desktop保存配置文件后完全退出并重启Claude Desktop应用。5.2 验证与使用重启后当你新建一个对话Claude的输入框上方可能会显示一个微小的服务器连接图标或者你可以直接询问Claude“你现在可以使用哪些工具” 或者 “你能用我的开发工具吗”。Claude应该会回复它已连接到一个MCP服务器并列出可用的工具如get_git_status,list_directory,execute_safe_command。现在你可以尝试以下对话“请帮我检查一下当前项目的Git状态。”“列出src目录下的所有Python文件。”“显示一下当前目录。”Claude会理解你的意图选择合适的工具并调用它然后将工具返回的结构化结果整合成自然的语言回复给你。6. 进阶技巧与最佳实践6.1 工具设计的“用户体验”为AI设计工具和为人类设计API略有不同清晰的名称和描述工具名name要直观描述description要准确说明功能、输入和输出。这是AI选择工具的主要依据。结构化的输出尽可能返回结构化的JSON数据而不是纯文本段落。AI能更好地解析JSON中的字段。同时可以在JSON中包含一个text_summary字段提供人类可读的摘要。合理的错误信息工具执行失败时返回的错误信息应有助于AI理解问题所在从而可能调整问题或提示用户。例如“路径不存在”比“命令执行错误”更有用。6.2 性能与资源管理异步执行MCP工具函数定义为async def。如果你的工具涉及I/O操作网络请求、文件读写、数据库查询确保使用异步库如aiohttp,aiofiles避免阻塞服务器主线程。超时机制所有涉及外部调用的操作都必须设置超时并在工具函数中妥善处理TimeoutError。资源缓存对于耗时的、不常变的数据如项目依赖树可以考虑在工具内部实现简单的缓存机制但要注意缓存失效。6.3 调试与日志在开发过程中启用详细的日志记录至关重要。你可以在server.py中配置Python的logging模块将日志输出到文件以便查看工具被调用的情况、参数和内部错误。import logging logging.basicConfig(levellogging.DEBUG, format%(asctime)s - %(name)s - %(levelname)s - %(message)s)同时MCP Inspector是你的最佳调试伙伴一定要善用它来手动测试工具调用。6.4 扩展方向“mcp-custom-dev”只是一个起点。你可以基于它扩展出无限可能集成内部系统连接公司的项目管理Jira、监控Grafana、部署K8s系统让AI成为你的运维助手。代码分析工具集成pylint、black、mypy让AI不仅能写代码还能帮你检查和格式化代码。数据库查询安全地封装数据库查询工具切记使用参数化查询防止SQL注入让AI帮你分析数据。组合工具设计一些“宏工具”例如一个prepare_for_pr工具它内部依次调用run_tests、check_format、get_git_diff等多个工具实现一键化操作。7. 常见问题与故障排除在实际搭建和使用过程中你可能会遇到以下问题问题现象可能原因解决方案Claude Desktop 提示“无法连接MCP服务器”或工具列表为空。1. 配置文件路径或格式错误。2.command中的Python路径错误最常见。3. 服务器脚本启动失败。1. 检查配置文件JSON语法和存放路径。2.绝对确保command指向虚拟环境内的Python。在终端中cd到项目目录激活虚拟环境运行which python复制完整路径。3. 在终端手动运行配置中的命令看是否有Python错误输出。工具在MCP Inspector中可见但调用时返回错误或超时。1. 工具函数内部有未处理的异常。2. 工具执行时间过长。3. 依赖包未安装。1. 查看服务器终端的日志输出如果你在终端前台运行。2. 在工具函数中添加更详细的try...except和日志。3. 检查工具所需的Python包是否已在虚拟环境中安装。AI助手选择了错误的工具或无法理解何时使用工具。1. 工具名称或描述不够清晰。2. 用户指令模糊。1. 优化工具的name和description使其更精准。例如run_specific_test比run_test更好。2. 在对话中更明确地指示AI例如“请使用list_directory工具查看src目录”。添加了新工具文件但服务器没有加载。工具自动发现机制可能不是全动态的。检查项目加载工具的机制。可能需要重启服务器或者修改某个注册工具列表的__init__.py文件。执行Shell命令的工具返回“Permission Denied”。运行MCP服务器的进程用户权限不足。确保该用户有权限执行目标命令。对于高危操作考虑是否需要调整权限或者重新设计工具避免需要高权限。最后一点体会CCCpan/mcp-custom-dev这个项目的价值不在于它本身提供了多少功能而在于它提供了一个极其清晰、模块化的起点极大地降低了为AI构建私有化、专业化工具链的门槛。它把复杂的协议交互封装好了让你可以专注于最有价值的部分——定义那些真正能提升你个人或团队开发效率的专属工具。从简单的Git查询开始逐步构建起一个理解你代码库、熟悉你工作流程的智能副驾这个过程本身就充满了乐趣和成就感。