glyph

glyph

一个 Model Context Protocol (MCP) 服务，使用 Tree-sitter 的声明式查询语言从你的代码库中提取符号大纲。为 LLM 编码 Agent 提供所需的上下文，实现干净、高效的符号提取。也可以作为独立的命令行工具使用。

安装

macOS

安装 Go：

$ brew install go

安装 glyph 的最新版本：

$ GOBIN=/usr/local/bin go install "github.com/benmyles/glyph@latest"

功能说明

glyph 接受一个文件路径 glob，递归发现匹配的代码文件，并使用 Tree-sitter 强大的查询语言解析它们，以生成准确的符号大纲。你可以控制详细程度——从高层结构到包含可见性修饰符的完整函数签名。

为什么选择 glyph？

LLM 编码 Agent 在理解代码结构时表现最佳。glyph 通过提供干净的多文件符号映射来弥合这一差距，作为高效上下文而不会超出 token 限制。

核心特性

• 基于声明式查询的提取 - 使用 Tree-sitter 的查询语言进行精确、可维护的符号提取
• 基于 glob 的文件发现 - 使用熟悉的模式指向你的代码
• 语言无关的架构 - 只需查询模式即可轻松添加新语言
• 可配置的详细级别 - 选择你需要的上下文量
• 多文件支持 - 获得整个项目的统一视图
• MCP 原生 - 专为与 AI 编码工作流无缝集成而构建
• 高性能 - 优化的 Tree-sitter 查询实现快速提取

支持的语言

• Go - 函数、方法、类型、结构体、接口、常量、变量
• Java - 类、接口、方法、构造函数、字段、枚举、record、注解
• JavaScript/TypeScript - 函数、类、方法、箭头函数、变量、接口、类型别名
• Python - 函数、类、带装饰器的定义、赋值
• 易于扩展 - 添加新语言只需约 20 行查询模式

架构

glyph 使用现代化的声明式方法：

• Tree-sitter 查询 取代复杂的 AST 遍历逻辑
• 语言特定的查询模式 定义要提取的符号
• 统一的提取引擎 适用于所有语言
• 模块化设计 将查询、提取、格式化和文件处理等关注点分离

符号类型

glyph 使用简洁的符号类型名称以最小化 token 使用：

• func - 函数和类函数声明
• method - 类/结构体方法
• class - 类
• interface - 接口
• struct - 结构体 (Go)
• type - 类型声明 (Go)
• const - 常量
• var - 变量
• field - 类/结构体字段
• constructor - 构造函数
• enum - 枚举
• record - Record (Java)
• annotation - 注解 (Java)
• property - 属性 (TypeScript)

用法

与 AI 编码助手集成

Claude Code

使用 MCP 命令将 glyph 添加到 Claude Code：

# Add glyph as a local MCP server (for your current project)
claude mcp add glyph /usr/local/bin/glyph mcp

验证安装：

# List all configured servers
claude mcp list

# Check glyph server details
claude mcp get glyph

你也可以随时在 Claude Code 中使用 /mcp 命令查看服务状态。

Cursor

将 glyph 添加到你的 Cursor MCP 配置：

1. 打开 Cursor 设置 (Cmd/Ctrl + ,)
2. 搜索 "MCP" 或导航到 Extensions → MCP
3. 将 glyph 添加到你的 MCP 服务：

{
  "mcpServers": {
    "glyph": {
      "command": "/usr/local/bin/glyph",
      "args": ["mcp"]
    }
  }
}

配置完成后，你可以通过 MCP 接口使用 glyph 从代码库中提取符号大纲，帮助 AI 更好地理解你的代码结构。

MCP 服务模式（默认）

将 glyph 作为 MCP 服务运行，以便与 LLM 编码 Agent 集成：

$ glyph mcp

命令行模式

直接从命令行使用 glyph 提取符号：

$ glyph cli '/path/to/project/*.go'

$ glyph cli -detail=minimal '/path/to/project/**/*.js'

选项：

• -detail：详细级别（minimal、standard 或 full）。默认为 standard。

注意：所有文件模式必须使用绝对路径。

详细级别

Minimal

仅显示符号名称、类型和行号：

- func: main (line 15)
- struct: Server (line 5)
- method: Start (line 10)

Standard（默认）

显示签名和声明：

- func: func main()
- struct: type Server struct
- method: func (s *Server) Start() error

完整

显示带有代码块的完整符号定义：

- func (lines 15-20):

func main() { server := &Server{} server.Start() }

开发

$ git clone https://github.com/benmyles/glyph
$ cd glyph

$ make clean

$ make test

$ make build

$ make install DESTDIR=/usr/local/bin

添加新语言

得益于基于查询的架构，添加对新语言的支持非常简单：

1. 在 file_utils.go 中添加语言检测（约 2 行）
2. 在 queries.go 中添加查询模式（约 10-20 行）
3. 在 queries.go 中添加到查询分发器（约 5 行）

添加 Rust 支持的示例：

// In file_utils.go
case ".rs":
    return rust.GetLanguage(), nil

// In queries.go
var rustQueries = map[string]string{
    "functions": `
        (function_item
            name: (identifier) @name
        ) @function
    `,
    "structs": `
        (struct_item
            name: (type_identifier) @name
        ) @struct
    `,
    // ... more patterns
}

性能

• 借助 Tree-sitter 的增量解析实现快速解析
• 优化查询以实现高效的符号提取
• 通过流式文件处理实现最低内存占用
• 解析器复用以在多个文件中获得更好的性能