File_analysis_mcp

开始构建您自己的服务器，以便在 Claude for Desktop 和其他客户端中使用。

本 README 文件提供了一个关于创建自定义 MCP 服务器并将其作为软件包发布到 PyPI 的全面指南。按照概述的步骤有效地构建、配置和部署您的服务器。

---

什么是模型上下文协议 (MCP)？

MCP 代表 模型上下文协议 —— 它是一种允许开发者使用自定义工具和服务器扩展 AI 助手（如 Claude）的协议。

• 示例：您可以构建天气服务器、计算器、金融助手或您能想象的任何东西。

MCP 是一种开放协议，它标准化了应用程序如何向 LLM 提供上下文。可以将 MCP 视为 AI 应用程序的 USB-C 端口。正如 USB-C 提供了一种将您的设备连接到各种外围设备和配件的标准化方式一样，MCP 提供了一种将 AI 模型连接到不同数据源和工具的标准化方式。

---

通用架构

flowchart LR
    subgraph "您的计算机"
        Host["带有 MCP 客户端的主机\n(Claude, IDE, 工具)"]
        S1["MCP 服务器 A"]
        S2["MCP 服务器 B"]
        S3["MCP 服务器 C"]
        Host <-->|"MCP 协议"| S1
        Host <-->|"MCP 协议"| S2
        Host <-->|"MCP 协议"| S3
        S1 <--> D1[("本地\n数据源 A")]
        S2 <--> D2[("本地\n数据源 B")]
    end
    subgraph "互联网"
        S3 <-->|"Web APIs"| D3[("远程\n服务 C")]
    end

详细架构说明

1. 带有 MCP 客户端的主机（例如，Claude Desktop）：

   • 这是 LLM（如 Claude）运行的应用程序
   • 包含与服务器通信的 MCP 客户端实现
   • 管理用户交互并呈现结果
   • 负责在用户、LLM 和适当的服务器之间路由请求

2. MCP 服务器 A、B、C：

   • 在您的本地机器上运行的独立进程
   • 每个服务器提供特定的功能（例如，文件分析、数据库访问、天气数据）
   • 服务器在具有自己依赖项的隔离环境中运行
   • 可以用不同的语言编写（Python、TypeScript、Java 等）
   • 使用标准化的 MCP 协议与主机通信

3. 本地数据源：

   • 您本地机器上的文件、数据库或其他资源
   • 由 MCP 服务器安全地访问
   • 数据永远不会离开您的机器，除非明确设计为这样做
   • 示例：您的文档、本地 SQLite 数据库、配置文件

4. 远程服务：

   • 互联网上的外部 API 和 Web 服务
   • MCP 服务器可以充当这些服务的安全桥梁
   • 示例：天气 API、股票数据、新闻服务

5. MCP 协议：

   • 客户端和服务器之间的标准化通信格式
   • 在各种传输层上使用 JSON-RPC 2.0
   • 用于请求、响应和通知的结构化消息类型
   • 启用功能发现的能力协商

关键组件

• MCP 主机：诸如 Claude Desktop、IDE 或 AI 工具之类的程序，它们希望通过 MCP 访问数据。
• MCP 客户端：与服务器保持 1:1 连接的协议客户端。
• MCP 服务器：轻量级程序，每个程序都通过标准化的模型上下文协议公开特定的功能。
• 本地数据源：您的计算机的文件、数据库和服务，MCP 服务器可以安全地访问它们。
• 远程服务：可以通过互联网访问的外部系统（例如，通过 API），MCP 服务器可以连接到它们。

---

为什么选择 MCP？

MCP 帮助您在 LLM 之上构建代理和复杂的工作流程。LLM 经常需要与数据和工具集成，而 MCP 提供了：

• 一个不断增长的预构建集成列表，您的 LLM 可以直接插入。
• 在 LLM 提供商和供应商之间切换的灵活性。
• 在您的基础设施中保护数据的最佳实践。

---

什么是 MCP 服务器？

模型上下文协议 (MCP) 服务器是一种将 AI 模型连接到外部数据源和工具的服务。

核心 MCP 概念

MCP 服务器可以提供三种主要类型的功能：

1. 资源：可以被客户端读取的类似文件的数据（如 API 响应或文件内容）。
2. 工具：可以被 LLM 调用的函数（需要用户批准）。
3. 提示：帮助用户完成特定任务的预写模板。

---

什么是 UV？

UV 是一个现代、快速的 Python 包安装程序和解析器，用 Rust 构建。它被设计为 pip、pipx 和 poetry 等工具的替代品，在保持兼容性的同时提供显著的性能改进。

关键 UV 功能

• 速度：由于 Rust 实现，通常比 pip 快 10-100 倍
• 兼容性：保持与 pip、requirements.txt 和 pyproject.toml 的兼容性
• 隔离：创建干净、可重现的环境
• 缓存：智能缓存系统，避免冗余下载
• 现代解析器：高效的依赖关系解析算法

UV 的工作原理

UV 通过以下方式加速 Python 包管理：

1. 并行操作：并行下载和安装软件包
2. 高效解析：优化软件包元数据的解析
3. 智能缓存：缓存 wheels 和元数据以避免冗余操作
4. 原生实现：用 Rust 编写以提高性能
5. Wheel 优先级：优先使用 wheels 而不是源代码分发

UV 与其他包管理器

功能	UV	pip	pipx	Poetry
速度	极快	较慢	中等	中等
原生语言	Rust	Python	Python	Python
环境管理	是	有限	是	是
锁定文件	是	否	否	是
依赖关系解析	高级	基本	基本	高级
项目创建	是	否	否	是
MCP 集成	原生支持	需要额外设置	有限	有限

UV 特别适合 MCP 服务器开发，因为：

• Claude Desktop 使用 UV 来管理服务器环境
• 它创建隔离的环境，防止依赖冲突
• 更快的安装意味着更快的开发周期
• uv init 命令可以高效地设置项目结构

---

什么是 FastMCP？

FastMCP 是一个高级的、Pythonic 的框架，用于构建 MCP 服务器。它通过提供直观的装饰器和对底层 MCP 协议的抽象，显著简化了创建 MCP 兼容的工具、资源和提示的过程。

为什么选择 FastMCP？

虽然有很多方法可以构建 MCP 服务器，但 FastMCP 因以下几个原因而脱颖而出：

1. 简单性：使用单个装饰器将 Python 函数转换为 MCP 工具
2. 类型安全：利用 Python 类型提示自动生成模式
3. 减少样板代码：消除大部分协议级别的代码
4. Pythonic 设计：遵循 Python 约定和最佳实践
5. 快速开发：显著缩短开发时间

FastMCP 与替代方案

功能	FastMCP	原始 MCP SDK	自定义实现
易用性	★★★★★	★★★☆☆	★☆☆☆☆
灵活性	★★★★☆	★★★★★	★★★★★
开发速度	★★★★★	★★★☆☆	★★☆☆☆
可维护性	★★★★★	★★★☆☆	★★☆☆☆
协议合规性	★★★★★	★★★★★	各不相同

FastMCP 的工作原理

FastMCP 通过以下关键机制运行：

1. 基于装饰器的注册：使用装饰器将常规 Python 函数转换为 MCP 工具和资源
2. 自动类型转换：将 Python 类型映射到 JSON 模式以实现 MCP 合规性
3. 协议处理：自动管理所有底层协议细节
4. 上下文管理：提供一个直观的 Context 对象来访问 MCP 功能
5. 传输抽象：处理不同的传输机制，无需开发人员参与

---

我们将要构建什么

基本数学计算器 MCP

一个模型上下文协议 (MCP) 服务器，提供用于基本数学运算的工具。

功能

• 基本数学运算（加法、减法、乘法、除法）
• 边缘情况的错误处理（如除以零）
• 通过 MCP 资源提供基本帮助信息

---

注意：我们在此处选择 Claude Desktop 仅用于演示目的。

<details> <summary>为什么选择 Claude for Desktop 而不是 Claude.ai？</summary> 因为服务器在本地运行，所以 MCP 目前仅支持桌面主机。 </details>

本教程将主要关注工具。

让我们开始构建我们的基本数学计算器服务器！ 您可以在此处找到我们将要构建的完整代码。

---

先决知识

本快速入门假定您熟悉：

• Python
• 像 Claude 这样的 LLM

---

系统要求

• 已安装 Python 3.10 或更高版本。
• 您必须使用 Python MCP SDK 1.2.0 或更高版本。

---

设置您的环境

首先，让我们安装 uv 并设置我们的 Python 项目和环境：

UV：一个快速的 Python 包和项目管理器，用 Rust 编写。

MacOS/Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

注意：之后重新启动您的终端，以确保 uv 命令被识别。

---

创建和设置您的项目

MacOS/Linux

# 为我们的项目创建一个新目录
uv init basic_math_calculator_mcp
cd basic_math_calculator_mcp

# 创建虚拟环境并激活它
uv venv
source .venv/bin/activate

# 安装依赖项
uv add "mcp[cli]"

# 创建我们的服务器目录和文件
mkdir -p src/basic_math_calculator_mcp
touch src/basic_math_calculator_mcp/server.py
touch src/basic_math_calculator_mcp/__init__.py

以下是每个命令的解释：

uv init basic_math_calculator_mcp - 使用 UV 包管理器创建一个名为 "basic_math_calculator_mcp" 的新项目目录。

cd basic_math_calculator_mcp - 将您的当前目录更改为新创建的项目文件夹。

uv venv - 创建一个 Python 虚拟环境以隔离项目依赖项。

source .venv/bin/activate - 激活虚拟环境，以便安装的软件包进入此环境。

uv add "mcp[cli]" - 安装带有其命令行界面工具的模型上下文协议 SDK。

mkdir -p src/basic_math_calculator_mcp - 创建一个遵循 Python 包标准的源代码目录结构。

touch src/basic_math_calculator_mcp/server.py - 创建一个空的 server.py 文件，您将在其中编写 MCP 服务器代码。

touch src/basic_math_calculator_mcp/__init__.py - 创建一个空的 init.py 文件，该文件将目录标记为 Python 包。

Windows

# 为我们的项目创建一个新目录
uv init basic_math_calculator_mcp
cd basic_math_calculator_mcp

# 创建虚拟环境并激活它
uv venv
.venv\Scripts\activate

# 安装依赖项
uv add "mcp[cli]"

# 创建我们的服务器目录和文件
mkdir -p src\basic_math_calculator_mcp
new-item src\basic_math_calculator_mcp\server.py
new-item src\basic_math_calculator_mcp\__init__.py

---

构建您的服务器

导入包和设置实例

让我们在 src/basic_math_calculator_mcp/server.py 中实现我们的服务器：

from mcp.server.fastmcp import FastMCP, Context

# 创建一个专门用于基本数学运算的 MCP 服务器
mcp = FastMCP(
    "Basic Math Calculator",
    dependencies=[]  # 基本数学运算不需要外部依赖项
)

# 基本数学运算
@mcp.tool()
def add(a: float, b: float) -> float:
    """
    将两个数字相加。
    
    Args:
        a: 第一个数字
        b: 第二个数字
        
    Returns:
        a 和 b 的总和
    """
    return a + b

@mcp.tool()
def subtract(a: float, b: float) -> float:
    """
    从第一个数字中减去第二个数字。
    
    Args:
        a: 要从中减去的数字
        b: 要减去的数字
        
    Returns:
        a - b 的结果
    """
    return a - b

@mcp.tool()
def multiply(a: float, b: float) -> float:
    """
    将两个数字相乘。
    
    Args:
        a: 第一个数字
        b: 第二个数字
        
    Returns:
        a 和 b 的乘积
    """
    return a * b

@mcp.tool()
def divide(a: float, b: float) -> str:
    """
    将第一个数字除以第二个数字。
    
    Args:
        a: 分子
        b: 分母
        
    Returns:
        a / b 的结果
    """
    if b == 0:
        return "Error: Division by zero is not allowed"
    return str(a / b)

# 具有基本计算器说明的资源
@mcp.resource("calculator://help")
def calculator_help() -> str:
    """基本计算器帮助信息。"""
    return """
    # 基本数学计算器
    
    此计算器提供以下操作：
    
    - 加法：使用带有两个数字的 `add` 工具
    - 减法：使用带有两个数字的 `subtract` 工具
    - 乘法：使用带有两个数字的 `multiply` 工具
    - 除法：使用带有两个数字的 `divide` 工具
    
    示例：
    - 要将 5 和 3 相加，请使用：`add(5, 3)`
    """

def run():
    """运行 MCP 服务器"""
    mcp.run()

if __name__ == "__main__":
    run()

代码解释：

• from mcp.server.fastmcp import FastMCP, Context - 导入 FastMCP 框架和 Context 以创建 MCP 服务器
• mcp = FastMCP("Basic Math Calculator", dependencies=[]) - 创建具有名称且没有依赖项的服务器
• @mcp.tool() - 装饰器，用于将函数注册为 MCP 工具
• add(a: float, b: float) -> float - 加法函数，接受两个参数并返回它们的总和
• subtract(a: float, b: float) -> float - 减法函数
• multiply(a: float, b: float) -> float - 乘法函数
• divide(a: float, b: float) -> str - 具有零除处理的除法函数
• @mcp.resource("calculator://help") - 在给定 URI 注册资源
• calculator_help() -> str - 返回帮助信息的函数
• run() - 启动服务器的函数
• if __name__ == "__main__": run() - 直接执行文件时运行服务器

---

创建包初始化

在 src/basic_math_calculator_mcp/__init__.py 中：

"""Basic Math Calculator MCP Server - 用于执行基本数学运算的工具"""

from .server import mcp, run

__version__ = "0.1.0"

您的服务器已完成！运行 uv run server.py 以确认一切正常。

---

测试和调试

使用 MCP Inspector 运行：

uv run mcp dev path/to/your/server/file

MCP Inspector 是一个交互式开发工具，用于测试和调试 MCP 服务器。

什么是 MCP Inspector？

MCP Inspector 是一个基于浏览器的交互式开发环境，用于测试和调试 MCP 服务器。它提供了一个可视化界面，允许您：

1. 连接到 MCP 服务器：通过各种传输方法
2. 探索可用功能：查看资源、工具和提示
3. 执行工具：使用自定义输入测试工具
4. 查看资源内容：浏览和检查资源
5. 监控消息：查看所有交换的协议消息
6. 调试问题：识别和修复服务器中的问题

MCP Inspector 的工作原理

MCP Inspector 通过以下关键组件运行：

服务器启动器，传输桥，Web 界面，测试设施，调试工具

1. 使用您指定的命令启动您的服务器进程
2. 使用指定的传输建立连接
3. 执行 MCP 初始化和功能协商
4. 发现可用的工具、资源和提示
5. 为每个功能呈现适当的 UI 元素
6. 接受用户输入以测试工具和资源
7. 根据用户操作向您的服务器发送请求
8. 显示结果和发生的任何错误

---

使用 Claude for Desktop 测试您的服务器

注意：Claude for Desktop 尚未在 Linux 上提供。

配置 Claude for Desktop

在以下位置打开您的 Claude for Desktop 应用程序配置文件：

• MacOS/Linux：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：$env:AppData\Claude\claude_desktop_config.json

如果该文件不存在，请创建它。

示例配置

Windows

{
    "mcpServers": {
        "calculator": {
            "command": "uv",
            "args": [
                "--directory",
                "C:\\ABSOLUTE\\PATH\\TO\\PARENT\\FOLDER\\server",
                "run",
                "server.py"
            ]
        }
    }
}

MacOS/Linux

{
    "mcpServers": {
        "calculator": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/server",
                "run",
                "server.py"
            ]
        }
    }
}

警告：您可能需要在 command 字段中提供 uv 可执行文件的完整路径。使用 which uv (MacOS/Linux) 或 where uv (Windows) 找到它。

保存文件并重新启动 Claude for Desktop。

---

在 PyPI 上部署和发布您的 MCP 服务器

什么是 PyPI？

PyPI（Python 包索引）是 Python 包的官方存储库。它充当一个中心枢纽，Python 开发人员可以在其中上传、共享和分发他们的代码，以便其他人可以通过 pip 轻松安装它。

为什么选择 PyPI？

• 集中式分发：轻松接触到广泛的 Python 用户。
• 易于安装：只需 pip install package-name。
• 版本控制：维护和分发多个版本。
• 集成：与 pip、build、twine 和 uv 等工具无缝协作。

PyPI 的替代方案

替代方案	描述	与 PyPI 的比较
TestPyPI	PyPI 的暂存版本	用于在生产发布之前进行测试
GitHub Releases	通过 GitHub 分发 wheels 或源代码	手动安装；缺乏自动化和可发现性
Private Indexes	自托管（例如，Nexus、Artifactory）	适用于内部/组织使用；不公开
Conda	适用于数据科学和科学计算环境	更适合二进制包，但生态系统不同

底线：PyPI 仍然是最受欢迎和广泛采用的 Python 包分发平台。

---

将您的 MCP 服务器发布到 PyPI

我们将使用 UV – 一种快速、现代的 Python 打包工具 – 而不是传统的工具，如 build 和 twine。

先决条件

• 带有 pyproject.toml 和可选的 README.md、LICENSE 和 __init__.py 的 Python 项目
• 在 PyPI 上注册并验证您的电子邮件
• 安装 UV：

curl -Ls https://astral.sh/uv/install.sh | sh

确保它在您的 PATH 中：~/.local/bin/uv

---

使用 UV 构建包

uv build

这会创建一个带有 .tar.gz 和 .whl 文件的 dist/ 文件夹

使用 UV 发布到 PyPI

uv publish

系统将提示您输入您的 PyPI 用户名/密码 或 API 令牌（推荐）。

如果成功，您将看到：

Uploading your-package-nam-veriosn-py3-none-any.whl to PyPI
View at: https://pypi.org/project/your-package-name

---

为什么选择 UV 而不是 Twine/Build？

工具	角色	优点	缺点
UV	构建 + 发布	快速、现代、单命令	仍然是新的，不断发展
Twine	仅上传	完善	需要单独的构建步骤
Build	仅构建	简单可靠	需要与 Twine 配对

---

---

与其他用户共享包

标准共享

• 分享 PyPI 链接：https://pypi.org/project/your-package-name
• 其他人可以通过以下方式安装：

pip install your-package-name

Claude Desktop 集成

uv pip install your-package-name

手动配置（推荐）

{
  "mcpServers": {
    "mcp-server": {
      "command": "uv",
      "args": [
        "run",
        "mcp-server"
      ]
    }
  }
}

---

总结

• PyPI 是公共 Python 包的首选平台。
• UV 简化了构建和发布的过程。
• 在完全发布之前使用 TestPyPI 进行验证。
• 您的 MCP 服务器可以通过 CLI 或代码安装和运行。
• 通过 PyPI 链接和 Claude Desktop 集成与用户分享。

您现在可以充满信心地构建、发布和分发您的 MCP 服务器。