MCP-TY

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

为什么选择 ty？

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

返回格式

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

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

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

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

功能特性

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

工具	功能	LSP 接口
search_symbol	关键词搜索符号，返回文件名+行号	workspace/symbol
list_file_symbols	列出文件中的所有符号结构	textDocument/documentSymbol

精确定位工具

工具	功能	LSP 接口
start_project	初始化项目分析	initialize
get_definition	跳转到符号定义	textDocument/definition
find_usages	查找所有引用	textDocument/references
get_type_info	获取类型信息	textDocument/hover
get_diagnostics	获取类型错误	textDocument/publishDiagnostics
get_completions	代码补全建议	textDocument/completion
analyze_file	文件综合分析	多个接口组合

代码编辑工具

工具	功能	LSP 接口
safe_rename	跨文件安全重命名符号	textDocument/rename
get_code_actions	获取可用的快速修复	textDocument/codeAction
apply_code_action	应用指定的代码操作	textDocument/codeAction
get_edit_preview	预览代码修改内容	textDocument/codeAction

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

传统 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 服务

与传统搜索的区别

场景	grep/文本搜索	ty 语义分析
搜索 User	返回几千个匹配	只返回 class User 的定义
查找方法调用	可能匹配注释和字符串	只匹配真正的方法调用
理解类型	无法推断	精确显示推断类型
重构安全性	容易改错	找到所有真实引用

局限性

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

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

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

开发

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

# 运行测试
uv run pytest

# 类型检查
uv run ty check

License

MIT