Glyph

🚀 glyph

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

🚀 快速开始

安装

macOS

安装 Go：

$ brew install go

安装最新版本的 glyph：

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

功能概述

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

选择 glyph 的原因

大语言模型编码代理在理解代码结构时能发挥最佳效果。glyph 通过提供简洁的多文件符号映射来填补这一差距，这些映射可作为高效的上下文，同时不会超出令牌限制。

✨ 主要特性

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

📦 安装指南

macOS

安装 Go：

$ brew install go

安装最新版本的 glyph：

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

💻 使用示例

与 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 服务器运行，以便与大语言模型编码代理集成：

$ 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() }

📚 详细文档

支持的语言

• 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）

🔧 技术细节

开发

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