MCP-TY MCP Server

MCP-TY

基于 ty 类型检查器的 MCP 服务器，为 AI 提供精确的 Python 代码语义分析能力。

为什么选择 ty？

• 极速：基于 Rust 的增量分析（Salsa 架构），毫秒级响应
• 低内存：可同时分析多个项目而不会撑爆内存
• 精准：语义级别的代码理解，而不是简单的文本搜索
• 与 uv 集成：自动识别虚拟环境和依赖

返回格式

所有工具返回 JSON 格式的结构化数据：

// 成功
{"status": "ok", "data": {...}}

// 错误
{"status": "error", "message": "..."}

// 未找到
{"status": "not_found", "message": "..."}

功能特性

符号搜索工具（替代原生搜索）

精确定位工具

代码编辑工具

为什么代码编辑功能很重要？

传统 AI 修改代码的方式是"生成新代码"，这容易产生幻觉或遗漏。 而基于 ty 的编辑是语义级精确计算：

AI 发指令 → ty 分析类型系统 → 计算精确的 diff → 应用修改

这种方式的优势：

• 重命名时找到所有真实引用，不会漏改或错改
• 自动修复知道如何添加正确的 import
• 修改是可预览的，AI 可以先看再决定是否应用

安装

前置条件

确保已安装 ty：

# 使用 uv 安装
uv tool install ty

# 或使用 pipx
pipx install ty

安装 mcp-ty

# 克隆项目
git clone https://github.com/yourusername/mcp-ty.git
cd mcp-ty

# 使用 uv 安装
uv sync

配置

Cursor 配置

在 Cursor 的 MCP 配置文件中添加：

{
  "mcpServers": {
    "ty-context-engine": {
      "command": "uv",
      "args": [
        "--directory",
        "D:/PythonProjectAll/mcp-ty",
        "run",
        "mcp-ty"
      ]
    }
  }
}

Claude Desktop 配置

编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "ty-context-engine": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-ty",
        "run",
        "mcp-ty"
      ]
    }
  }
}

使用示例

1. 初始化项目

首先，让 AI 初始化要分析的项目：

请初始化项目 D:/MyPythonProject 进行类型分析

AI 会调用 start_project 工具。

2. 跳转到定义

在 src/models/user.py 的第 45 行第 10 列，帮我找到这个函数的定义

3. 查找所有引用

找出 User 类在整个项目中的所有使用位置

4. 获取类型信息

告诉我 src/services/auth.py 第 23 行的 session 变量是什么类型

5. 检查类型错误

检查 src/api/routes.py 有没有类型错误

架构说明

┌─────────────┐     stdio      ┌─────────────┐     JSON-RPC     ┌─────────┐
│  AI Client  │ ◄────────────► │  MCP Server │ ◄───────────────► │   ty    │
│  (Cursor)   │                │  (FastMCP)  │                   │ server  │
└─────────────┘                └─────────────┘                   └─────────┘

• AI Client：Cursor、Claude Desktop 等支持 MCP 的 AI 客户端
• MCP Server：本项目，作为桥梁连接 AI 和 ty
• ty server：Astral 开发的高性能 Python 类型检查器 LSP 服务

与传统搜索的区别

局限性

ty 提供的是代码结构语义，不是自然语言语义：

• 能做：找到 process_order 函数的所有调用链
• 不能做：理解"帮我找处理退款的代码"（除非函数名就叫退款）

建议：将 ty 的结构化检索与 RAG 向量搜索结合，是目前最强的 AI 代码理解方案。

开发

# 安装开发依赖
uv sync --dev

# 运行测试
uv run pytest

# 类型检查
uv run ty check

License

MIT