从0到1：解锁Mcp Server编写秘籍

更多大模型学习资料，搜索【码上有模力】GZH

什么是 Mcp Server

在 AI 迅猛发展的当下，Mcp Server 宛如一颗耀眼新星，在 AI 领域占据着关键地位。它的出现，犹如为 AI 大模型搭建了一座与外部世界沟通的桥梁，让 AI 能够突破自身局限，与各类外部工具实现高效协作，完成更为复杂和多样化的任务。简单来说，Mcp Server 本质上是一个服务程序，作为 AI 与外部工具的中间层，代替人类访问并且操作外部工具。其工作原理基于一种标准化的协议，大模型通过操作系统的标准输入输出（STDIO），也就是我们常说的输入与输出通道，或者 SSE 协议来调用 Mcp Server 。当大模型有需求时，会向 Mcp Server 发送特定格式的请求，这些请求以 JSON 等常见的数据交换格式进行封装，包含了明确的指令和相关参数 。Mcp Server 在接收到请求后，会依据自身预设的逻辑和功能，通过执行代码功能或者使用 API 请求，去访问相应的外部工具，完成任务后再将结果返回给大模型 。

举个例子，当你使用搭载了 Mcp Server 的 AI 助手查询今天广州的天气时，AI 助手（大模型）会将这个查询需求按照特定的协议格式，通过 STDIO 或 SSE 发送给负责天气查询的 Mcp Server。Mcp Server 接收到请求后，利用自身集成的天气查询接口（比如调用天气 API），获取广州当天的天气数据，然后再将这些数据按照规定格式返回给 AI 助手，AI 助手就能将天气信息呈现给你了 。正是通过这样的机制，Mcp Server 赋予了 AI 更强大的能力，使其能够与各种外部资源交互，为用户提供更智能、更实用的服务 。它的核心价值在于，打破了 AI 大模型与外部工具之间的壁垒，让 AI 不再局限于自身的知识储备，能够实时获取最新信息，执行更多实际操作，极大地拓展了 AI 的应用场景和实用性 。

前期准备工作

在正式开启 Mcp Server 的编写之旅前，我们得先把前期准备工作做实做细，这就好比建造高楼得先打好坚实的地基一样 。准备工作主要包括开发环境搭建和了解 Mcp Server 开发相关知识，每一个环节都至关重要，缺一不可 。

开发环境搭建

开发环境的搭建是编写 Mcp Server 的首要任务，它为后续的开发工作提供了必要的软件支持和运行基础 。目前，Mcp Server 的开发可以基于多种编程语言，其中 Python 和 Java 是较为常用的两种 。

如果选择 Python 作为开发语言，首先要确保系统中安装了 Python 环境，建议安装 Python 3.10 及以上版本，以充分利用 Python 的新特性和更好的兼容性 。安装过程相对简单，可从 Python 官方网站（https://www.python.org/downloads/）下载对应操作系统的安装包，按照安装向导的提示进行操作即可 。安装完成后，可以在命令行中输入 “python --version” 来验证是否安装成功 。

除了 Python 本身，还需要安装一些相关的依赖包 。在 Mcp Server 开发中，常用的依赖包有 MCP SDK 和 httpx 。MCP SDK 是开发 Mcp Server 的核心工具包，它提供了一系列用于构建和管理 Mcp Server 的接口和功能；httpx 则是一个强大的 HTTP 客户端库，用于处理 HTTP 请求和响应，方便 Mcp Server 与外部 API 进行交互 。安装这些依赖包可以使用 Python 的包管理工具 pip，在命令行中执行 “pip install mcp [cli] httpx” 命令即可完成安装 。为了避免不同项目之间的依赖冲突，还可以使用虚拟环境 。通过 “python -m venv mcp-env” 命令创建一个名为 mcp-env 的虚拟环境，然后使用 “source mcp-env/bin/activate”（Linux/Mac 系统）或 “mcp-env\Scripts\activate”（Windows 系统）命令激活虚拟环境，这样在该环境中安装的依赖包就不会影响到系统全局环境 。

要是你对 Java 更熟悉，那么基于 Java 开发 Mcp Server 也是个不错的选择 。Java 开发需要安装 Java Development Kit（JDK），建议安装 JDK 17 及以上版本 。同样，从 Oracle 官方网站（https://www.oracle.com/java/technologies/downloads/）下载 JDK 安装包并进行安装 。安装完成后，配置好 JAVA_HOME 环境变量，在命令行中输入 “java -version” 验证安装是否成功 。在 Java 开发 Mcp Server 时，若使用 Spring Boot 框架，可以通过在项目的 pom.xml 文件中添加相应的依赖来引入 Spring AI MCP 扩展，比如添加如下依赖：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-mcp-server-webmvc-spring-boot-starter</artifactId>
</dependency>

这只是一个简单的示例，实际开发中可能还需要根据具体需求添加其他依赖 。同时，还需要安装 Maven 或 Gradle 等项目构建工具，用于管理项目的依赖和构建过程 。Maven 可以从 Apache Maven 官方网站（https://maven.apache.org/download.cgi）下载并解压，然后配置好 MAVEN_HOME 环境变量；Gradle 则可以从 Gradle 官方网站（https://gradle.org/install/）获取安装包并安装 。

了解 Mcp Server 开发相关知识

在搭建好开发环境后，深入了解 Mcp Server 开发所需的基础知识就显得尤为重要，这些知识将贯穿整个开发过程 。Mcp Server 开发的核心是对 MCP 协议的理解和运用 。MCP 协议作为连接 AI 能力与真实世界的标准化协议，通过定义 Resources（静态资源）、Prompts（提示词模板）和 Tools（可执行工具）三大核心能力，为开发者提供了一种模块化的方式来为 LLM 扩展各种交互能力 。

Resources 主要是指可供 LLM 访问的只读数据，比如文件、文档等，它为模型提供了额外的上下文信息 。在实际开发中，我们可能会将一些本地文件系统中的数据作为 Resources 暴露给 Mcp Server，以便模型能够访问和利用这些数据 。例如，在一个文档问答系统中，可以将相关的文档资源注册到 Mcp Server 中，当用户提出问题时，模型可以借助这些文档资源来生成更准确的回答 。

Prompts 则是预定义的模板或指令，用于指导语言模型的交互，它能够帮助我们定制 LLM 的响应，使其更符合我们的需求 。举个例子，在开发一个智能客服系统时，可以定义一些常见问题的 Prompt 模板，当用户的问题匹配到相应的模板时，模型就能根据模板的指导生成针对性的回答 。

Tools 是 LLM 可调用的动作或函数，这是 Mcp Server 赋予模型强大能力的关键所在 。通过 Tools，模型可以执行各种实际操作，如调用 API、访问数据库、执行本地脚本等 。以调用 API 为例，我们可以在 Mcp Server 中定义一个工具，该工具能够调用天气 API，当模型接收到用户询问天气的请求时，就可以调用这个工具来获取实时的天气信息，并返回给用户 。

理解 MCP 协议中的这些关键概念，掌握它们的使用方法和技巧，是开发出高效、稳定的 Mcp Server 的基础 。此外，还需要了解一些相关的开发工具和技术，如调试工具、日志记录等，这些工具和技术能够帮助我们在开发过程中快速定位和解决问题，提高开发效率 。

编写 Mcp Server 代码

在完成前期准备工作后，就正式进入 Mcp Server 的代码编写环节 。这是实现 Mcp Server 功能的核心步骤，需要我们精心设计和编写每一行代码，确保其功能的正确性和稳定性 。

初始化项目

首先，我们要创建一个新的 Mcp Server 项目 。以 Python 开发为例，在命令行中使用如下命令创建一个新的项目目录：

mkdir mcp_server_project
cd mcp_server_project

这两行命令首先创建了一个名为 mcp_server_project 的项目目录，然后进入到该目录中 。接下来，我们初始化项目的结构 。在项目目录下，创建一个名为 mcp_server 的文件夹，用于存放 Mcp Server 的核心代码 。同时，在项目根目录下创建一个名为 requirements.txt 的文件，用于记录项目所需的依赖包 。在这个文件中，添加我们之前安装的依赖包：

mcp[cli]

httpx

这样，项目的基本结构就搭建好了 。如果是基于 Java 开发，使用 Maven 构建项目的话，可以通过 Maven 命令来创建项目骨架 。在命令行中执行：

mvn archetype:generate -DgroupId=com.example -DartifactId=mcp-server -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

这条命令会在当前目录下创建一个名为 mcp-server 的项目，项目结构遵循 Maven 的标准结构 。进入项目目录后，在 src/main/java/com/example 目录下创建 Mcp Server 的 Java 代码文件，在 src/main/resources 目录下存放项目的配置文件等 。同时，在项目的 pom.xml 文件中添加所需的依赖，如前面提到的 Spring AI MCP 扩展依赖 。

定义工具函数

工具函数是 Mcp Server 实现功能的关键组件，它负责与外部工具进行交互并返回结果 。在 Python 中，我们可以使用装饰器来定义工具函数 。以一个简单的获取系统信息的工具函数为例：

from mcp.server import tool
import psutil


@tool
def get_system_info() -> dict:
    """
    返回当前设备的CPU、内存和磁盘使用情况
    """
    return {
        "cpu": psutil.cpu_percent(),
        "memory": psutil.virtual_memory()._asdict(),
        "disk": psutil.disk_usage('/')._asdict()
    }

在这段代码中，我们使用了 @tool 装饰器将 get_system_info 函数注册为一个工具函数 。该函数内部使用 psutil 库获取系统的 CPU 使用率、内存使用情况和磁盘使用情况，并将这些信息以字典的形式返回 。工具函数的编写要点在于，要明确函数的功能和输入输出，使用清晰的 docstring 来描述函数的作用和参数含义，以便大模型能够正确理解和调用 。同时，要确保函数能够正确地与外部工具或资源进行交互，获取准确的结果 。

实现业务逻辑

在定义好工具函数后，就需要在工具函数中实现具体的业务逻辑 。比如，我们要实现一个调用天气 API 获取天气信息的工具函数 。假设我们使用 OpenWeatherMap 的 API，首先需要在项目中安装 httpx 库用于发送 HTTP 请求，然后编写如下代码：

import asyncio
import os
import httpx
from mcp.server import tool
from mcp.types import TextContent


@tool
async def get_weather(city: str) -> TextContent:
    api_key = os.getenv('OPENWEATHER_API_KEY')
    if not api_key:
        raise ValueError('OPENWEATHER_API_KEY environment variable not set')
    url = "https://api.openweathermap.org/data/2.5/weather"
    params = {
        "q": city,
        "appid": api_key,
        "units": "metric"
    }
    async with httpx.AsyncClient() as client:
        resp = await client.get(url, params=params)
        data = resp.json()
        weather_desc = data["weather"][0]["description"]
        temp = data["main"]["temp"]
        return TextContent(type="text", text=f"{city}天气：{weather_desc}，温度：{temp}°C")

在这个工具函数中，首先从环境变量中获取 OpenWeatherMap 的 API 密钥，如果未设置则抛出异常 。然后构建 API 请求的 URL 和参数，使用 httpx 库发送异步 HTTP 请求 。接收到响应后，解析 JSON 数据，提取天气描述和温度信息，最后将结果以 TextContent 的形式返回 。这里结合实际场景，通过调用外部 API 实现了获取天气信息的业务逻辑 。在实现业务逻辑时，要考虑到各种异常情况的处理，如网络请求失败、API 密钥错误等，确保工具函数的稳定性和可靠性 。

配置和启动服务器

完成工具函数的编写后，还需要配置服务器的参数，并启动 Mcp Server 。在 Python 中，可以通过如下方式配置和启动服务器：

import asyncio
from mcp.server.fastmcp import FastMCP
from mcp.server.stdio import stdio_server


mcp = FastMCP("My MCP Server")


@mcp.tool()
async def my_tool(input_text: str):
    return f"Processed: {input_text}"


async def main():
    async with stdio_server() as (read_stream, write_stream):
        await mcp.run(read_stream, write_stream, mcp.create_initialization_options())


if __name__ == "__main__":
    asyncio.run(main())

这段代码使用 sse_server 创建基于 Server-Sent Events 的服务器传输实例，并指定端口号为 54321 。在启动服务器时，还可以根据需求配置其他参数，如超时时间、环境变量等 。通过合理配置服务器参数，可以使 Mcp Server 更好地适应不同的运行环境和业务需求 。

测试与调试

测试工具和方法

在完成 Mcp Server 的代码编写后，测试与调试是确保其稳定运行和功能正常的关键环节 。这里我们主要介绍使用 MCP Inspector 和客户端进行测试的方法 。MCP Inspector 是一个非常实用的图形界面工具，它能够让我们在不与 LLM / AI 智能体集成的情况下，对自定义的 Mcp Server 进行测试 。使用 MCP Inspector 进行测试的步骤如下：首先，打开终端，确保处于项目的工作环境中（如果使用了虚拟环境，需先激活虚拟环境），然后输入 “mcp dev your_server_file.py” 命令（your_server_file.py 为你编写的 Mcp Server 的主代码文件） 。如果之前没有安装 CLI，系统会提示安装，按照提示操作即可 。安装完成后，重新运行命令，会显示一个 URL（通常是本地主机地址） 。在浏览器中打开这个 URL，点击 “Connect” 按钮，即可将 MCP Inspector 连接到服务器 。连接成功后，就可以进行各种功能测试了 。例如，点击 “List Templates”，选择显示的模板，输入相关参数，点击 “Read Resources”，查看资源读取功能是否正常；进入导航栏的 “Tools”，点击 “List Tools”，选择想要测试的工具，输入工具所需的参数，然后点击 “Run Tool”，查看工具的执行结果是否符合预期 。

除了使用 MCP Inspector，还可以通过客户端进行功能测试 。以 Python 开发的 Mcp Server 为例，可以创建一个 MCP 客户端来调用服务器中的工具 。在项目中创建一个 client.py 文件，代码示例如下：

import asyncio
from mcp.client.stdio import stdio_client
from mcp import ClientSession, StdioServerParameters


# 为stdio连接创建服务器参数 - 连接到本地的Mcp Server
server_params = StdioServerParameters(
    # 服务器执行的命令，这里假设使用uv来运行Mcp Server的主代码文件
    command='uv',
    # 运行的参数
    args=['run', 'your_server_file.py'],
    # 环境变量，默认为None，表示使用当前环境变量
    # env=None
)


# 定义协程函数(coroutine function)
# 用于定义与Mcp Server交互的异步流程
async def main():
    """
    主函数 - 异步执行MCP客户端与服务器的交互
    这个函数执行以下任务:
    1. 建立与本地Mcp Server的连接
    2. 创建会话并初始化
    3. 列出可用的工具
    4. 执行工具调用示例
    5. 调用资源获取相关信息
    """
    # 创建stdio客户端
    async with stdio_client(server_params) as (stdio, write):
        # 创建ClientSession对象
        async with ClientSession(stdio, write) as session:
            # 初始化ClientSession
            await session.initialize()
            # 列出可用的工具
            print("==== 可用的工具 ====")
            response = await session.list_tools()
            tools = response.tools
            for tool in tools:
                print(f" - {tool.name}: {tool.description}")
            # 工具调用示例
            print("\n==== 工具调用示例 ====")
            # 假设服务器中有一个名为add的工具，用于两个数相加
            a, b = 1, 2
            print(f"➡️ 加法: {a} + {b}")
            add_result = await session.call_tool('add', {'a': a, 'b': b})
            print(f"✅ 结果: {add_result}\n")


if __name__ == '__main__':
    # 程序入口点
    # asyncio.run()函数用于运行异步函数main()，它会创建一个事件循环
    # 并在事件循环中执行main()函数，直到其完成后关闭事件循环
    asyncio.run(main())

在上述代码中，首先创建了连接到本地 Mcp Server 的参数，然后通过 stdio_client 建立与服务器的连接 。在会话中，先初始化会话，接着列出服务器提供的可用工具，最后进行了一个工具调用的示例 。通过这种方式，可以从客户端角度全面测试 Mcp Server 的各项功能是否正常 。

常见问题及解决

在测试过程中，可能会遇到各种各样的问题，下面列举一些常见问题及相应的解决方案 。如果在使用 MCP Inspector 时，遇到工具未被识别的情况，首先要检查工具函数的定义是否正确，是否使用了正确的装饰器来注册工具 。例如，在 Python 中，使用 @tool 装饰器时，确保装饰器的导入路径正确，并且函数的参数和返回值类型定义清晰 。同时，检查工具函数的 docstring 是否准确描述了工具的功能和参数，因为 MCP Inspector 会根据 docstring 来识别和展示工具信息 。如果是客户端连接问题，如无法连接到服务器，要检查服务器的启动参数是否正确，特别是端口号是否被占用 。可以使用命令 “netstat -ano | findstr : 端口号”（Windows 系统）或 “lsof -i : 端口号”（Linux/Mac 系统）来查看端口的占用情况 。如果端口被占用，修改服务器的启动端口号 。

另外，网络传输协议的兼容性问题也可能导致测试失败 。Mcp Server 支持多种传输协议，如 stdio 和 sse 。如果使用 sse 协议时出现问题，检查服务器和客户端的配置是否一致，包括 URL 地址、端口号等 。同时，确保服务器端的 sse_server 配置正确，例如：

async with sse_server(port=54321) as (read_stream, write_stream):
    await mcp.run(read_stream, write_stream, mcp.create_initialization_options())

在这个示例中，要确保端口号 54321 没有被其他程序占用，并且客户端在连接时使用的是相同的端口号和 URL 。如果遇到数据解析错误，可能是因为服务器返回的数据格式不符合客户端的预期 。在定义工具函数的返回值时，要严格按照 MCP 协议规定的数据格式进行返回 。例如，对于文本内容的返回，使用 TextContent 类型进行包装：

from mcp.types import TextContent


@tool
async def get_weather(city: str) -> TextContent:
    # 工具函数实现
    return TextContent(type="text", text=f"{city}天气信息")

通过这种方式，确保数据在服务器和客户端之间能够正确传输和解析 。在测试与调试过程中，遇到问题要冷静分析，从代码逻辑、配置参数、数据格式等多个方面进行排查，逐步解决问题，以确保 Mcp Server 的稳定性和可靠性 。

优化与扩展

性能优化技巧

在 Mcp Server 的开发过程中，性能优化是提升其整体表现和用户体验的关键环节。通过采用有效的优化策略，可以显著提高 Mcp Server 的响应速度、降低资源消耗，使其在高负载情况下也能稳定运行 。

优化代码是提升性能的基础。在代码编写过程中，要遵循高效的编程规范和算法。例如，避免在循环中进行不必要的计算和 I/O 操作，因为循环的高频执行会使这些操作的开销被放大，严重影响性能 。以 Python 开发的 Mcp Server 为例，如果在循环中频繁打开和关闭文件，会导致大量的系统资源消耗和时间浪费。可以将文件操作移到循环外部，或者使用缓存机制减少文件读取次数 。同时，合理使用数据结构也至关重要 。不同的数据结构在查找、插入和删除操作上的时间复杂度不同，根据具体的业务场景选择合适的数据结构能够大幅提升操作效率 。比如，在需要频繁查找元素的场景中，使用字典（Python 中的 dict）比列表（list）更合适，因为字典的查找时间复杂度为 O (1)，而列表的查找时间复杂度为 O (n) 。

合理设置缓存也是优化 Mcp Server 性能的重要手段 。缓存可以减少对外部资源的重复访问，将常用的数据或计算结果存储在内存中，当再次需要时可以直接从缓存中获取，从而大大提高响应速度 。在 Mcp Server 中，可以对工具函数的执行结果进行缓存 。例如，对于一些调用频率较高且结果相对稳定的工具函数，如获取天气信息的工具函数，在第一次调用获取结果后，将结果缓存起来，当后续再次调用时，先检查缓存中是否有对应的结果，如果有则直接返回，避免重复调用天气 API，减少网络请求和数据处理的时间 。可以使用 Python 的 functools.lru_cache 装饰器来实现简单的函数结果缓存 。同时，还可以根据实际情况设置缓存的过期时间，以保证缓存数据的时效性 。例如，对于天气信息的缓存，可以设置较短的过期时间，如 1 小时，确保获取的天气数据是相对最新的 。

功能扩展思路

随着业务需求的不断变化和发展，Mcp Server 的功能扩展显得尤为重要 。通过合理地扩展功能，可以使 Mcp Server 更好地满足不同用户和场景的需求，提升其通用性和实用性 。

根据实际需求添加新的工具是功能扩展的常见方式 。在不同的业务领域，用户可能需要 Mcp Server 调用各种不同的外部工具来完成任务 。比如，在金融领域，可以添加股票查询工具，让 Mcp Server 能够调用金融数据 API，获取股票的实时价格、走势等信息 。在电商领域，可以添加商品搜索工具，通过调用电商平台的 API，实现根据关键词搜索商品、获取商品详情等功能 。在添加新工具时，要确保工具函数的定义清晰、准确，遵循 Mcp Server 的开发规范，同时要处理好工具函数与其他部分代码的兼容性和协同工作问题 。

扩展资源也是丰富 Mcp Server 功能的有效途径 。除了常见的文件资源，还可以考虑引入更多类型的资源 。例如，在一些数据分析场景中，可以将数据库中的数据作为资源暴露给 Mcp Server 。通过配置相应的数据库连接信息，让 Mcp Server 能够读取数据库中的数据，并提供给大模型使用 。这样，大模型在处理相关任务时，就可以利用数据库中的数据进行分析和决策 。可以使用 SQLAlchemy 等数据库连接库来实现 Mcp Server 与数据库的交互 。同时，还可以对资源进行分类管理，提高资源的查找和使用效率 。

根据用户反馈和业务发展趋势，优化和扩展提示也是必不可少的 。用户在使用 Mcp Server 的过程中，可能会提出对提示的改进意见或新的需求 。例如，用户希望提示能够更加详细地指导大模型生成特定格式的回答，或者希望增加一些针对特定任务的提示 。我们可以根据这些反馈，对现有的提示进行优化，使其更符合用户的期望 。同时，随着业务的发展，可能会出现新的业务场景和任务，这就需要我们添加新的提示来满足这些需求 。在优化和扩展提示时，要充分考虑大模型的特点和用户的使用习惯，确保提示能够有效地引导大模型生成高质量的回答 。