YOKATLAS API MCP 服务器

该项目使用提供 YÖKATLAS 数据访问的 yokatlas-py Python 库创建了一个 FastMCP 服务器。这样，YÖKATLAS API 函数就可以作为工具被支持 Model Context Protocol (MCP) 的 LLM（大型语言模型）应用程序和其他客户端使用。

🎯 主要特性

• 为程序化访问 YÖKATLAS 数据提供标准的 MCP 接口。
• 获取本科和专科学位课程详情。
• 对本科和专科课程进行全面搜索（偏好向导）。
• 与 Claude Desktop 应用轻松集成。
• 能够生成包含课程详情或搜索结果的 PDF 报告，并下载到本地系统。

📋 先决条件

• Python 版本: 您的系统上必须安装 Python 3.8 或更高版本。您可以从 python.org 下载 Python。
• pip: 需要随 Python 安装的 pip 包管理器处于工作状态。

⚙️ 安装步骤（针对 Claude Desktop）

为了能够将项目加载到 Claude Desktop 应用中，您首先需要安装 uv 和 fastmcp 命令行工具，然后获取项目文件。

1. uv 安装

uv 是一个用 Rust 编写的非常快速的 Python 包构建器、解析器和虚拟环境管理器。推荐在 fastmcp 安装及 Claude Desktop 集成时使用 uv。

• 对于 macOS 和 Linux:
  打开终端并运行以下命令：
  bash
  curl -LsSf https://astral.sh/uv/install.sh | sh

• 对于 Windows (使用 PowerShell):
  打开 PowerShell 并运行以下命令：
  bash
  powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

• 或者通过 pip 安装（所有平台）:
  如果上述方法不起作用或您更喜欢使用 pip，则可以执行：
  bash
  pip install uv

安装完成后，可能需要重启您的终端或更新 PATH 环境变量（例如，在 Linux/macOS 上运行 source $HOME/.cargo/env 或 source $HOME/.bashrc, source $HOME/.zshrc 等），以确保系统能够识别 uv 命令。可以通过运行 uv --version 来验证安装是否成功。

2. fastmcp 命令行工具 (CLI) 安装

fastmcp CLI 用于管理和特别是通过 fastmcp install 命令来安装到 Claude Desktop 中。建议使用 uv 进行安装：

bash
uv pip install fastmcp

如果您在安装 uv 时遇到问题或希望使用 pip，也可以直接通过 pip 安装 fastmcp：
bash
pip install fastmcp

可以通过运行 fastmcp --version 来验证安装是否成功。

3. 获取项目文件

将此 YOKATLAS MCP 服务器的源代码克隆到您的计算机上。
bash
git clone https://github.com/saidsurucu/yokatlas-mcp.git
cd yokatlas-mcp

这将使您进入包含 README.md 文件和 yokatlas_mcp_server.py 脚本的目录。

4. 了解服务器特定依赖项

为了让这个服务器 (yokatlas_mcp_server.py) 正常运行，它需要一些 Python 库。这些库将在 Claude Desktop 集成期间（通过 fastmcp install 或手动安装）指定：

• yokatlas-py
• beautifulsoup4
• setuptools
• reportlab （用于生成 PDF 报告）
• fastmcp （服务器本身也需要）(Eğer sunucuyu bağımsız olarak geliştirmek veya test etmek isterseniz, bir sanal ortam (python -m venv .venv & .venv/bin/activate veya .venvScriptsactivate) oluşturup bu bağımlılıkları uv pip install fastmcp yokatlas-py beautifulsoup4 setuptools reportlab komutuyla kurabilirsiniz.)

🚀 Claude Desktop 整合 (fastmcp install 命令 - 推荐)

完成上述安装步骤后，将此服务器作为永久工具添加到 Claude Desktop 应用程序中的最简单方法是使用 fastmcp install 命令：

1. 确保您在包含 yokatlas_mcp_server.py 文件的 yokatlas-mcp 目录中。

2. 运行以下命令：
   bash
   fastmcp install yokatlas_mcp_server.py --name "YOKATLAS API 服务" --with yokatlas-py --with beautifulsoup4 --with setuptools --with reportlab

   • --name "YOKATLAS API 服务": 工具将在 Claude Desktop 中显示为此名称。
   • --with yokatlas-py --with beautifulsoup4 --with setuptools --with reportlab: 指定服务器运行所需的 Python 依赖项。fastmcp 本身也将被包含在这个环境中（fastmcp install 会自动处理这一点）。

该命令将使用 uv 为您的服务器创建一个隔离的 Python 环境，安装指定的依赖项，并将工具注册到 Claude Desktop 应用程序中。安装完成后，“YOKATLAS API 服务”将在您的 Claude Desktop 应用程序中可用。

⚙️ Claude Desktop 手动安装（通过配置文件 - 替代方案）

除了使用 fastmcp install 命令外，您还可以手动将服务器添加到 Claude Desktop 应用程序中。这种方法涉及直接编辑配置文件，提供了更多的控制。

警告： 在编辑配置文件时请小心。错误的配置可能导致 Claude Desktop 应用程序无法正常工作。

1. 打开 Claude Desktop 设置：
   在 Claude Desktop 应用程序中，从菜单栏（macOS 上是顶部菜单，Windows 上通常是应用程序内菜单）选择“Settings...”（设置...）选项。

2. 进入开发者设置并编辑配置文件：
   在打开的设置窗口中，点击左侧菜单中的“Developer”（开发者）标签，然后点击“Edit Config”（编辑配置）按钮。

   此操作将在以下位置创建（如果不存在的话）并显示 claude_desktop_config.json 文件：

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%Claudeclaude_desktop_config.json

3. 编辑配置文件：
   使用文本编辑器打开 claude_desktop_config.json 文件。文件内容将具有如下结构。在 mcpServers 对象中（如果 mcpServers 对象不存在，请先创建它及其包含的 {} 大括号），为“YOKATLAS API 服务”添加以下 JSON 块。

   json
   {
   "mcpServers": {
   // ... (如果有其他服务器定义，可以保留在这里，用逗号分隔) ...

    "YOKATLAS API 服务": {
      "command": "uv",
      "args": [
        "run",
        "--with", "beautifulsoup4",
        "--with", "fastmcp",
        "--with", "setuptools",
        "--with", "yokatlas-py",
        "--with", "reportlab",
        "fastmcp", "run",
        "/完整/项目/路径/yokatlas-mcp/yokatlas_mcp_server.py"
      ]
    }
   

   }
   }

   重要提示：* 如果 mcpServers 对象中已经存在其他服务器，请将 "YOKATLAS API Servisi" 条目与它们一起用逗号分隔添加。请确保 JSON 格式有效（例如，条目之间应该有逗号，最后一个条目之后不应有逗号）。

• 请不要忘记将 "/tam/proje/yolunuz/yokatlas-mcp/yokatlas_mcp_server.py" 部分替换为系统中 yokatlas_mcp_server.py 文件的完整且正确的路径。例如："/Users/kullaniciadiniz/Documents/GitHub/yokatlas-mcp/yokatlas_mcp_server.py" (macOS/Linux) 或 "C:\\Users\\kullaniciadiniz\\Documents\\GitHub\\yokatlas-mcp\\yokatlas_mcp_server.py" (Windows - 注意在 JSON 中使用双反斜杠 \)。如果您从 https://github.com/saidsurucu/yokatlas-mcp.git 克隆了仓库，并将其克隆到文档/GitHub下，则路径将是 "/Users/saidsurucu/Documents/GitHub/yokatlas-mcp/yokatlas_mcp_server.py"（根据您的用户名和克隆位置进行调整）。
• 由于此配置使用了 uv 命令，因此需要在您的系统上安装 uv 并将其添加到 PATH 中（参见“安装步骤 > 1. uv 安装”）。
• 必需的 Python 包 (beautifulsoup4, fastmcp, setuptools, yokatlas-py, reportlab) 将通过 uv run --with ... 命令自动管理。

1. 重启 Claude Desktop:
   保存并关闭配置文件后，为了使更改生效，请完全关闭并重新启动 Claude Desktop 应用程序。

成功安装后，在 Claude Desktop 应用程序中，您应该能在输入框右下角看到扳手 (🛠️) 图标，点击后可以看到 "YOKATLAS API Servisi" 工具。

🛠️ 可用工具 (MCP Tools)

此 FastMCP 服务器提供以下工具：

1. get_associate_degree_atlas_details

   • 描述: 获取特定副学士学位课程（副学士学位地图）在给定年份的所有详细信息。
   • 参数: program_id: str, year: int

2. get_bachelor_degree_atlas_details

   • 描述: 获取特定学士学位课程（学士学位地图）在给定年份的所有详细信息。
   • 参数: program_id: str, year: int

3. search_bachelor_degree_programs

   • 描述: 根据各种标准搜索学士学位课程（学士学位选择向导）。
   • 参数: uni_adi: str, program_adi: str, puan_turu: str (例如: SAY, EA), alt_bs: int, ust_bs: int 等等。（详情请参阅 yokatlas_mcp_server.py 脚本中的工具定义。）

4. search_associate_degree_programs

   • 描述: 根据各种标准搜索副学士学位课程（副学士学位选择向导）。
   • 参数: uni_adi: str, program_adi: str, alt_puan: float, ust_puan: float 等等。（详情请参阅 yokatlas_mcp_server.py 脚本中的工具定义。）

5. generate_pdf_report

   • 描述: 从 YOKATLAS 数据生成格式良好的 PDF 报告并保存到本地系统。
   • 参数:
     • data: dict - 数据源（来自其他 YOKATLAS 工具的结果）
     • report_type: str - 报告类型 ( bachelor_search , associate_search , bachelor_details , associate_details )
     • title: str - 报告标题（默认: "YOKATLAS 报告")
     • language: str - 报告语言（目前仅支持 tr）
     • save_to_downloads: bool - 选项以将 PDF 保存至下载文件夹（默认: True）
   • 返回: 包含 Base64 编码数据、文件名及本地文件路径的字典

📊 PDF 报告生成功能新增的PDF报告生成功能允许您将YOKATLAS数据转换为外观专业的PDF文档。此功能包括：

• 以整齐的表格形式可视化搜索结果
• 按部分组织程序详细信息
• 支持土耳其语字符
• 自动页面布局和格式化
• 针对不同结果类型定制格式
• 信息分类
• 将PDF文件保存到本地系统（下载文件夹）

为了使该功能更加模块化和可持续，PDF生成操作已被移至一个单独的模块yokatlas_pdf_generator.py中。

PDF报告示例用法

在Claude Desktop应用程序中，您可以使用如下示例工作流：

1. 首先执行一次程序搜索：

   搜索计算机工程专业

2. 将搜索结果转换为PDF并下载到您的电脑上：

   将这些结果创建为PDF报告并下载

3. 或者获取特定程序的详细信息，并将其转换为PDF：

   提供关于ODTÜ计算机工程专业的详细信息并创建PDF报告

您的PDF报告将自动保存到您计算机的“下载”(Downloads)文件夹中。

📜 许可证

本项目根据MIT许可证授权。