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

MCP-TY

MCP-TY

为什么选择 ty？

返回格式

功能特性

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

精确定位工具

代码编辑工具

安装

前置条件

安装 mcp-ty

配置

Cursor 配置

Claude Desktop 配置

使用示例

1. 初始化项目

2. 跳转到定义

3. 查找所有引用

4. 获取类型信息

5. 检查类型错误

架构说明

与传统搜索的区别

局限性

开发

License

Latest Blog Posts

MCP directory API