codefinder (Asd Noor)

CodeMap

语义代码图引擎——MCP服务器和CLI

CodeMap使用Tree sitter AST解析和语言服务器协议丰富来构建和维护代码库的实时语义图。它将图形作为 MCP服务器 （针对AI代理） 人性化CLI.

______________________________________________________________________

特性

• 多语言AST解析 --Go、Python、JavaScript、TypeScript、Lua、Zig、Templ
• LSP富集 --通过gopls、pylsp、typescript语言服务器、lua语言服务器、zls、templ-lsp实现跨文件引用和接口
• 实时更新 --具有500ms去抖动功能的文件监视器；具有5分钟空闲超时的后台守护进程
• LSP诊断 --在索引和可查询过程中捕获的错误、警告、提示
• 持久图 --SQLite采用WAL模式，递归CTE用于依赖遍历
• 自动安装LSP --缺少的语言服务器在首次使用时下载到 ~/.cache/codemap/；后续运行时进行静音后台升级
• MCP服务器 --stdio上的6个工具、4个提示、2个资源端点
• 命令行界面 --8个子命令 --json 输出和制表格式的表

______________________________________________________________________

安装

git clone https://github.com/yourusername/codemap.git
cd codemap
go build -o codemap .

转到1.25.6+ 必修的。CGo必须可用（Tree sitter语法和templ解析器需要）。

放置结果 codemap 二进制文件在你的某处 $PATH.

______________________________________________________________________

快速开始

作为MCP服务器

# Run in your project directory (indexes on startup, watches for changes)
cd /path/to/project
codemap serve

# Or specify the project root explicitly
codemap --project-dir /path/to/project serve

添加到您的MCP客户端配置中（例如Claude Desktop）：

{
  "mcpServers": {
    "codemap": {
      "command": "/absolute/path/to/codemap",
      "args": ["--project-dir", "/absolute/path/to/project"]
    }
  }
}

serve 也是 默认命令 --跑步 codemap 不使用子命令启动MCP服务器。

作为CLI

# Build or rebuild the index
codemap index

# Show index statistics
codemap status

# List all symbols in a file
codemap symbols internal/graph/store.go

# Find all locations of a symbol
codemap symbol Open --source

# Show transitive dependents of a symbol
codemap impact NodeID --json

# Show LSP diagnostics
codemap diagnostics --severity 1

______________________________________________________________________

CLI 参考

所有子命令都接受两个持久全局标志：

数据库路径解析：

子命令

codemap serve

通过stdio启动MCP服务器。当没有给出子命令时，这是默认值。

______________________________________________________________________

codemap watch [--foreground|-f]

生成一个后台文件监视器守护进程。守护进程以增量方式重新索引更改的文件，并在以下时间停止运行 5分钟不活动.通行证 --foreground （或 -f)在当前进程中运行观察程序——它保持活动状态，直到中断（SIGINT/SIGTERM），其生命周期与父进程绑定。 --daemon 是内部的（由生成的进程使用）。

______________________________________________________________________

codemap index

执行符号索引的完整（重新）构建。块直到完成并打印 nodes=N edges=M.

______________________________________________________________________

codemap status

从现有索引中打印节点和边计数。如果尚未构建索引，则返回错误。

______________________________________________________________________

codemap symbols  [--json]

列出中定义的每个符号 ``。接受相对或绝对路径。

KIND      NAME          LINES   (internal/graph/store.go)
function  Open          88-115
function  OpenReadOnly  118-133
function  BulkUpsert…   136-160

______________________________________________________________________

codemap symbol  [--source] [--json]

查找以下所有位置 ` 在整个项目中。 --source` 包括源代码片段。

KIND      FILE                        LINES   NAME
function  internal/graph/store.go     88-115  Open

______________________________________________________________________

codemap impact  [--json]

显示每个符号 传递取决于 `` （通过递归CTE进行反向边缘遍历）。

______________________________________________________________________

codemap diagnostics [--file PATH] [--severity N] [--json]

列出上次索引运行期间捕获的LSP诊断。

SEVERITY  FILE                  LINE  COL  SOURCE  MESSAGE
error     internal/graph/st…    42    5    gopls   undefined: foo

______________________________________________________________________

MCP工具

MCP资源

MCP提示

______________________________________________________________________

语言支持

生成的文件(_templ.go, .sql.go, _string.go)自动跳过。

______________________________________________________________________

LSP自动安装

CodeMap按以下顺序解析语言服务器二进制文件：

1. 系统 $PATH --如果 gopls （或任何其他LSP二进制文件）已安装，可以直接使用
2. ~/.cache/codemap/ --以前自动下载的二进制文件缓存在此处
3. 自动下载 --如果在任何地方都找不到，则下载二进制文件并保存到 ~/.cache/codemap/

A. 静音背景升级检查 每个进程运行一次。如果缓存二进制文件的更新版本可用，则会在不阻塞主索引流的情况下重新安装。

要使用自己的LSP安装，只需确保它们已打开 $PATH --CodeMap将找到并使用它们。

______________________________________________________________________

建筑

codemap
├── MCP server (serve command / default)
│   └── JSON-RPC over stdio
│       ├── 6 tools
│       ├── 4 prompts
│       └── 2 resource endpoints
│
├── CLI (index / status / symbols / symbol / impact / diagnostics)
│   └── reads the same SQLite database (read-only)
│
└── Engine (shared by all modes)
    ├── Scanner — Tree-sitter AST parsing → graph.Node values
    ├── LSP Service — references + implementations → graph.Edge values
    │   └── per-language Client with adaptive warmup + notification handling
    ├── Graph Store — SQLite (WAL, foreign keys, recursive CTEs)
    │   ├── nodes (symbols)
    │   ├── edges (references, implements)
    │   └── diagnostics + diagnostic_edges
    └── Watcher — fsnotify + 500 ms debounce + 5 min idle timeout

节点ID

节点ID是确定的： SHA256(filePath + ":" + name + ":" + kind)[:16] （32个十六进制字符）。这使得增量更新具有冲突安全性和幂等性。

数据模型

// Node
{
  "id": "a3f1…c9d2",
  "name": "Open",
  "kind": "function",
  "file_path": "/abs/path/to/store.go",
  "line_start": 88,
  "line_end": 115,
  "col_start": 1,
  "col_end": 1,
  "name_line": 88,
  "name_col": 6,
  "symbol_uri": "file:///abs/path/to/store.go"
}

// Edge
{
  "source_id": "a3f1…c9d2",
  "target_id": "b7e4…1a88",
  "relation": "references"  // or "implements"
}

// Diagnostic
{
  "id": "d9c3…7f41",
  "file_path": "/abs/path/to/store.go",
  "line": 42,
  "col": 5,
  "severity": 1,
  "code": "undeclared",
  "source": "gopls",
  "message": "undefined: foo"
}

______________________________________________________________________

项目结构

codemap/
├── main.go              # Cobra root command + serve / watch / index
├── commands.go          # CLI subcommands: status, symbols, symbol, impact, diagnostics
├── SYSTEM_PROMPT.md     # Embedded MCP usage guidelines
├── go.mod / go.sum
├── mise.toml            # Task runner (build, test, vet)
├── internal/
│   ├── daemon/          # PID file management, detached process spawning
│   ├── db/              # EnsureDir helper
│   ├── graph/
│   │   ├── types.go     # Node, Edge, Diagnostic, DiagnosticEdge types + constants
│   │   └── store.go     # Open/OpenReadOnly, all CRUD, recursive CTE queries, diagnostics
│   ├── lsp/
│   │   ├── lsp.go       # Client (send loop, notification handling, DrainDiagnostics), Service
│   │   ├── transport.go # LSP stdio framing (Content-Length headers)
│   │   └── types.go     # JSON-RPC 2.0 + LSP protocol types
│   ├── pkgmgr/
│   │   ├── manager.go   # Manager.ResolveBinary, Install
│   │   ├── metadata.go  # Per-binary install/version/latest recipes, archive extraction
│   │   └── upgrade.go   # Background silent upgrade checks
│   ├── scanner/
│   │   ├── scanner.go   # New(root), Scan, ScanFile — Tree-sitter walk
│   │   └── queries.go   # Tree-sitter S-expression queries per language
│   ├── server/
│   │   ├── server.go    # New/NewWatch, ForceIndex, WaitForIndex, runIndex, saveDiagnostics
│   │   ├── tools.go     # MCP tool registration (6 tools)
│   │   ├── resources.go # MCP resource registration
│   │   ├── prompts.go   # MCP prompt registration
│   │   └── query.go     # NodeWithSource, NodeToWithSource, AbsFilePath (shared by MCP + CLI)
│   ├── treesittertempl/ # CGo wrapper for the Templ tree-sitter grammar (parser.c + scanner.c)
│   └── watcher/
│       └── watcher.go   # New, Run(ctx, cancel), idle timeout, debounce, reindexFile
├── util/
│   ├── git.go           # FindGitRoot(dir)
│   ├── hash.go          # NodeID, DiagnosticID
│   └── uri.go           # PathToURI, URIToPath
└── tests/
    ├── integration_test.go
    └── lsp_integration_test.go

______________________________________________________________________

建造和测试

# Build
go build -o codemap .
# or
mise run build

# Test
go test ./...
# or
mise run test

# Vet
go vet ./...
# or
mise run vet

______________________________________________________________________

故障排除

project has not been indexed yet — run: codemap index 跑 codemap index 使用前一次 status, symbols, symbol, impact，或 diagnostics.

LSP富集不产生边缘 语言服务器需要几秒钟来为工作区建立索引。第一次运行包括每种语言5秒的预热等待。后续运行将立即使用缓存的二进制文件。

inotify: too many open files （Linux）

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

大型代码库内存高/索引慢 树保姆扫描速度快；瓶颈是LSP富集。跑 codemap index 一次，然后使用watcher守护进程(codemap watch)用于增量更新。

______________________________________________________________________

许可证

GNU通用公共许可证v3.0--请参阅 许可证.