Skip to main content
Glama

MCP-TY

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

为什么选择 ty?

  • 极速:基于 Rust 的增量分析(Salsa 架构),毫秒级响应

  • 低内存:可同时分析多个项目而不会撑爆内存

  • 精准:语义级别的代码理解,而不是简单的文本搜索

  • 与 uv 集成:自动识别虚拟环境和依赖

Related MCP server: mcp-pyright

返回格式

所有工具返回 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

Available Tools

16 tools
analyze_fileC

Analyze a Python file: get structure and diagnostics summary.

Inputs: file_path (required). Returns: result

apply_code_actionC

Apply a code action by index (from get_code_actions).

Inputs: file_path (required), line (required), column (required), action_index (required). Returns: result

find_usagesB

Find all references to symbol at position (1-based).

Inputs: file_path (required), line (required), column (required). Returns: result

get_code_actionsB

Get available quick fixes and refactorings at position (1-based).

Inputs: file_path (required), line (required), column (required). Returns: result

get_completionsB

Get code completion suggestions at position (1-based).

Inputs: file_path (required), line (required), column (required). Returns: result

get_definitionC

Go to definition of symbol at position (1-based).

Inputs: file_path (required), line (required), column (required). Returns: result

get_diagnosticsB

Get type errors and warnings for a file.

Inputs: file_path (required). Returns: result

get_edit_previewC

Preview changes a code action would make.

Inputs: file_path (required), line (required), column (required), action_index (required). Returns: result

get_type_infoB

Get type information for symbol at position (1-based).

Inputs: file_path (required), line (required), column (required). Returns: result

list_file_symbolsC

List all symbols defined in a file.

Inputs: file_path (required). Returns: result

read_codeB

Read file content, optionally by line range (1-based).

Inputs: file_path (required), start_line, end_line. Returns: result

read_contextC

Read code around a specific line with context.

Inputs: file_path (required), line (required), context. Returns: result

safe_renameB

Rename symbol across project. Set apply=True to execute.

Inputs: file_path (required), line (required), column (required), new_name (required), +1 more. Returns: result

search_symbolC

Search symbols (classes, functions, variables) across the project.

Inputs: query (required). Returns: result

start_projectB

Initialize ty for a Python project. Must be called first.

Inputs: project_path (required). Returns: result

stop_projectC

Stop ty and release resources.

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 16 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap: analyze_file examines structure, get_completions provides suggestions, safe_rename handles renaming, etc. The descriptions make it easy to differentiate between analysis, navigation, editing, and project management functions.

    Naming Consistency5/5

    All tools follow a consistent verb_noun or verb_noun_noun pattern (e.g., analyze_file, get_completions, safe_rename). The naming is uniform throughout, using snake_case exclusively with clear action-oriented verbs like get, find, apply, and list.

    Tool Count4/5

    With 16 tools, the count is slightly high but reasonable for a comprehensive Python code analysis server. It covers diagnostics, navigation, refactoring, and project setup, though it might benefit from slight consolidation in areas like read_code and read_context.

    Completeness5/5

    The toolset provides complete coverage for Python code analysis and editing: it includes project initialization (start_project), file reading (read_code), diagnostics (get_diagnostics), navigation (get_definition, find_usages), refactoring (safe_rename, apply_code_action), and cleanup (stop_project). No obvious gaps exist for its intended domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that exposes Pyright language server functionality for Python, providing tools for type checking, code completions, and finding definitions. It enables AI models to perform static analysis and code formatting through the Model Context Protocol.
      7
      34 PyPI
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      A production-ready MCP server that enables AI assistants to intelligently understand, analyze, edit, navigate, and review software projects with multi-workspace support, Git integration, and semantic search.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server that gives AI coding agents codebase navigation intelligence, enabling symbol lookup, reference finding, type inspection, and diagnostics through tools like locate, refs, hover, diagnostics, status, and rename.
      548 npm
      MIT