Glyph

🚀 glyph

glyph 是一个模型上下文协议（MCP）服务器，它使用 Tree-sitter 的声明式查询语言从你的代码库中提取符号大纲。通过简洁高效的符号提取，为大语言模型（LLM）编码代理提供所需的上下文信息。此外，它也可以作为一个独立的命令行工具使用。

🚀 快速开始

✨ 主要特性

• 基于声明式查询的提取：使用 Tree-sitter 的查询语言进行精确且易于维护的符号提取。
• 基于通配符的文件发现：使用熟悉的模式指定代码文件。
• 语言无关架构：只需添加查询模式，即可轻松支持新的语言。
• 可配置的详细程度：可根据需求选择所需的上下文详细程度。
• 多文件支持：提供整个项目的统一视图。
• 原生支持 MCP：可无缝集成到 AI 编码工作流程中。
• 高性能：优化 Tree-sitter 查询以实现快速提取。

📦 安装指南

macOS

安装 Go：

$ brew install go

安装最新版本的 glyph：

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

📚 详细文档

它的作用

glyph 接受一个文件路径通配符，递归查找匹配的代码文件，并使用 Tree-sitter 强大的查询语言对其进行解析，以生成准确的符号大纲。你可以控制详细程度，从高级结构到带有可见性修饰符的完整函数签名。

为什么选择 glyph？

当大语言模型（LLM）编码代理理解你的代码结构时，它们的工作效果最佳。glyph 通过提供简洁的多文件符号映射，在不超出令牌限制的情况下提供有效的上下文信息，从而弥补了这一差距。

支持的语言

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

架构

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

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

符号类型

glyph 使用简洁的符号类型名称以减少令牌使用：

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

💻 使用示例

与 AI 编码助手集成

Claude Code

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

# 将 glyph 添加为本地 MCP 服务器（用于当前项目）
claude mcp add glyph /usr/local/bin/glyph mcp

验证安装：

# 列出所有配置的服务器
claude mcp list

# 检查 glyph 服务器详细信息
claude mcp get glyph

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

Cursor

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

1. 打开 Cursor 设置（Cmd/Ctrl + ,）。
2. 搜索 "MCP" 或导航到扩展 → MCP。
3. 将 glyph 添加到你的 MCP 服务器：

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

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

MCP 服务器模式（默认）

将 glyph 作为 MCP 服务器运行，以集成到 LLM 编码代理中：

$ glyph mcp

命令行模式

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

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

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

选项：

• -detail：详细程度（minimal、standard 或 full），默认为 standard。

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

详细程度

基础用法

最低详细程度 仅显示符号名称、类型和行号：

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

标准详细程度（默认） 显示签名和声明：

- 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 的增量解析。
• 优化查询：实现高效的符号提取。
• 最小内存使用：采用流式文件处理。
• 解析器重用：在多个文件中实现更好的性能。