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 的增量解析。
• 優化的查詢：實現高效的符號提取。
• 最小內存使用：採用流式文件處理。
• 解析器重用：在多個文件中提高性能。