Codesense MCP Server
a code analyzer mcp server for AI agent
Installation
npx codesense-mcp-serverAsk AI about Codesense MCP Server
Powered by Claude · Grounded in docs
I know everything about Codesense MCP Server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Code Sense - MCP代码分析服务
Code Sense是一个基于Go语言开发的MCP(Model Context Protocol)服务器,为AI提供项目代码分析能力。支持从GitHub、GitLab或本地路径获取代码仓库,并索引Go、JavaScript、TypeScript、Shell脚本、Python、Java、C++代码,让AI能够快速理解项目结构。
整体架构与功能
核心架构
Code Sense采用分层架构设计,主要包含以下核心模块:
-
MCP服务器层 (server.go)
- 实现MCP协议,提供标准化的工具接口
- 支持多仓库并发管理,每个仓库独立索引
- 实现TTL和LRU机制,自动管理资源
- 提供线程安全的仓库访问
-
代码索引层 (indexer.go)
- 解析Go、JavaScript、TypeScript、Shell脚本、Python、Java、C++代码
- 提取函数、类、类型、变量、常量等符号
- 建立代码符号索引,支持快速搜索
-
仓库获取层 (fetcher.go)
- 支持从GitHub、GitLab获取代码
- 支持本地文件系统读取
- 自动下载和解压GitHub仓库
-
配置管理层 (config.go)
- 统一的配置文件管理
- 支持命令行参数覆盖
- 灵活的配置项设置
工作流程
AI请求 → MCP服务器 → 仓库获取器 → 代码索引器 → 返回结果
↓
多仓库管理
↓
TTL/LRU清理
关键技术点
-
多仓库并发管理
- 每个仓库独立的CodeIndexer实例
- 使用sync.RWMutex保证并发安全
- 支持同时索引和查询多个仓库
-
资源自动管理
- TTL机制:仓库在指定时间未访问后自动清理(默认1小时)
- LRU策略:超过最大数量时淘汰最久未使用的仓库(默认最多30个)
- 定时清理:每10分钟自动清理过期仓库
-
代码解析技术
- Go代码:使用go/ast包解析AST,精确提取符号
- JS/TS代码:使用正则表达式和字符串匹配
- Shell脚本:使用正则表达式和字符串匹配
- Python/Java/C++代码:使用正则表达式和字符串匹配
- 支持多种符号类型:function、type、class、interface、variable、constant、alias
-
MCP协议实现
- 基于go-sdk实现标准MCP协议
- 提供丰富的工具接口
- 友好的输出格式,便于AI理解
-
多种传输方式支持
- 支持Stdio传输方式(默认)
- 支持SSE(Server-Sent Events)传输方式
- 支持Streamable传输方式
功能特性
- 多语言支持: 支持Go、JavaScript、TypeScript、Shell脚本、Python、Java、C++代码的索引和分析
- 多仓库来源: 支持从GitHub、GitLab或本地路径获取代码
- 多仓库并发: 支持同时索引多个仓库,每个仓库独立管理
- 智能代码索引: 自动识别函数、类、类型、变量、常量等代码符号
- 自动过期清理: 支持TTL(Time To Live)机制,自动清理过期仓库(默认1小时)
- LRU缓存管理: 支持LRU(Least Recently Used)策略,自动淘汰最久未使用的仓库(默认最多30个)
- MCP工具接口: 提供丰富的MCP工具,方便AI调用
- 友好的输出格式: 输出内容经过优化,易于AI理解和处理
- 多种传输方式: 支持Stdio、SSE、Streamable三种传输方式
- 大项目传输支持: 支持通过Base64编码的ZIP压缩包传输大型项目代码
项目结构
code-sense/
├── cmd/
│ └── server/
│ └── main.go # 主程序入口
├── internal/
│ ├── codeindex/
│ │ ├── indexer.go # 代码索引器实现
│ │ └── indexer_test.go # 索引器单元测试
│ ├── config/
│ │ └── config.go # 配置文件解析
│ ├── mcpserver/
│ │ ├── server.go # MCP服务器实现(支持多仓库)
│ │ └── server_test.go # MCP服务器单元测试
│ └── repository/
│ └── fetcher.go # 仓库获取器
├── config.yaml # 配置文件
├── go.mod # Go模块定义
└── README.md # 项目文档
核心逻辑
1. 代码索引器 (CodeIndexer)
代码索引器负责解析和分析代码文件,提取代码符号信息:
- Go代码解析: 使用Go标准库的
go/ast包解析AST,提取函数、类型、变量、常量等 - JavaScript/TypeScript解析: 使用正则表达式和字符串匹配提取函数、类、变量等符号
- 符号类型: 支持识别function、type、class、interface、variable、constant等类型
2. 仓库获取器 (RepositoryFetcher)
提供统一的接口获取代码仓库:
- GitHubFetcher: 使用GitHub API获取公开或私有仓库
- LocalFetcher: 从本地文件系统读取代码(用于测试和开发)
- GitLabFetcher: 预留接口,未来支持GitLab
3. MCP服务器 (MCPServer)
MCP服务器支持多仓库并发分析,每个仓库有独立的索引器和生命周期管理:
多仓库管理
- 独立索引器: 每个仓库拥有独立的CodeIndexer实例,互不干扰
- 仓库ID: 每个仓库分配唯一的repoId(格式:repo-xxxxxxxx)
- 并发安全: 使用sync.RWMutex保护仓库map,支持并发访问
TTL(Time To Live)机制
- 自动过期: 仓库在指定时间未访问后自动清理
- 默认TTL: 2小时
- 访问更新: 每次访问仓库时更新LastAccess时间
- 定时清理: 每10分钟自动清理过期仓库
LRU(Least Recently Used)策略
- 最大仓库数: 默认最多30个仓库
- 自动淘汰: 超过最大数量时,淘汰最久未使用的仓库
- 访问追踪: 记录每个仓库的最后访问时间
4. MCP工具接口
MCP服务器实现了以下工具,供AI调用:
fetch_repository
从GitHub/GitLab或本地路径获取代码仓库并建立索引,返回仓库ID。
参数:
repoUrl(string): 仓库URL(GitHub或GitLab地址或本地路径)token(string, 可选): 访问令牌
返回: 仓库ID和项目概览信息,包括文件数、符号数、语言分布等
create_repo_from_zip
从Base64编码的ZIP压缩包创建代码仓库并建立索引,返回仓库ID。支持大项目传输。
参数:
zipData(string): Base64编码的ZIP压缩包数据metadata(object, 可选): 项目元数据name(string): 项目名称description(string): 项目描述
返回: 仓库ID和项目概览信息,包括文件数、符号数、语言分布等
示例:
{
"tool": "create_repo_from_zip",
"arguments": {
"zipData": "UEsDBBQABgAIAAAAIQ...",
"metadata": {
"name": "my-project",
"description": "My awesome project"
}
}
}
返回示例:
仓库创建成功
仓库ID: repo-abc12345
来源: ZIP压缩包
本地路径: /tmp/code-sense-zip-xxx
项目名称: my-project
项目描述: My awesome project
索引统计:
文件数: 15
符号数: 45
语言分布: map[go:8 javascript:4 python:3]
search_symbols
搜索指定仓库中的代码符号(函数、类、变量等)。
参数:
repoId(string): 仓库IDquery(string): 搜索查询字符串
返回: 匹配的符号列表,包含名称、类型、文件位置、签名等信息
get_file_content
获取指定仓库中文件的完整内容。
参数:
repoId(string): 仓库IDfilePath(string): 文件路径
返回: 文件内容和语言类型
list_all_files
列出指定仓库中所有已索引的文件。
参数:
repoId(string): 仓库ID
返回: 文件列表,包含文件路径和语言类型
list_all_symbols
列出指定仓库中所有已索引的代码符号。
参数:
repoId(string): 仓库ID
返回: 按类型分组的符号列表
get_symbols_by_file
获取指定仓库中指定文件的所有符号。
参数:
repoId(string): 仓库IDfilePath(string): 文件路径
返回: 指定文件中的符号列表
get_project_summary
获取指定仓库的项目整体概览信息(文件数、符号数、语言分布等)。
参数:
repoId(string): 仓库ID
返回: 项目统计信息,包括仓库URL、创建时间、最后访问时间、TTL等
analyze_code_structure
分析指定仓库的代码结构,返回目录树和主要模块。
参数:
repoId(string): 仓库ID
返回: 项目的目录结构,使用图标标识不同语言
find_dependencies
查找指定符号的依赖关系,包括被哪些符号调用和调用了哪些符号。
参数:
repoId(string): 仓库IDsymbolName(string, 可选): 符号名称
返回: 符号依赖关系分析结果
示例:
{
"tool": "find_dependencies",
"arguments": {
"repoId": "repo-abc12345",
"symbolName": "hello"
}
}
返回示例:
依赖关系分析
仓库: repo-abc12345 (https://github.com/user/repo)
符号: hello
位置: /path/to/file.go:10
类型: function
签名: func hello(name string) string
相关符号 (同文件):
• goodbye (function) - /path/to/file.go:20
• helper (function) - /path/to/file.go:30
get_function_content
根据函数名获取函数的完整内容。
参数:
repoId(string): 仓库IDfunctionName(string): 函数名称
返回: 函数的完整内容,包括函数名、位置、类型、签名和函数内容
示例:
{
"tool": "get_function_content",
"arguments": {
"repoId": "repo-abc12345",
"functionName": "hello"
}
}
返回示例:
函数内容
仓库: repo-abc12345 (https://github.com/user/repo)
函数名: hello
位置: /path/to/file.go:10
类型: function
签名: func hello(name string) string
函数内容:
func hello(name string) string { return fmt.Sprintf("hello, %s", name) }
get_variable_definition
根据变量名获取变量的定义。
参数:
repoId(string): 仓库IDvariableName(string): 变量名称
返回: 变量的定义,包括变量名、位置、类型、签名和文件内容
示例:
{
"tool": "get_variable_definition",
"arguments": {
"repoId": "repo-abc12345",
"variableName": "config"
}
}
返回示例:
变量定义
仓库: repo-abc12345 (https://github.com/user/repo)
变量名: config
位置: /path/to/file.go:5
类型: variable
签名: var config Config
文件内容:
var config Config = Config{ Host: "localhost", Port: 8080, }
安装和配置
前置要求
- Go 1.23.8 或更高版本
- 访问GitHub仓库的权限(如需要访问私有仓库)
安装
git clone <repository-url>
cd code-sense
go mod download
go build -o code-sense ./cmd/server
配置文件
创建或编辑config.yaml文件:
server:
name: "code-sense"
version: "1.0.0"
port: 8080
mcp:
enabled: true
transport: "stdio"
codeIndex:
projectPath: "./test-project"
languages:
- go
- javascript
- typescript
github:
enabled: true
token: "your-github-token"
apiEndpoint: ""
gitlab:
enabled: true
token: ""
apiEndpoint: ""
logging:
level: "info"
format: "json"
使用方法
启动MCP服务器
使用本地项目测试
./code-sense -repo e:/cody/goproject/xllive/quick-connect
使用GitHub仓库
./code-sense -repo https://github.com/username/repo -token your-github-token
使用配置文件
./code-sense -config config.yaml
指定传输方式
# 使用Stdio传输(默认)
./code-sense -transport stdio
# 使用SSE传输
./code-sense -transport sse
# 使用Streamable传输
./code-sense -transport streamable
MCP工具调用示例
AI可以通过MCP协议调用以下工具:
1. 获取并索引仓库
{
"tool": "fetch_repository",
"arguments": {
"repoUrl": "https://github.com/username/repo",
"token": "your-token"
}
}
返回示例:
成功获取并索引仓库
仓库ID: repo-abc12345
项目概览:
{
"repoId": "repo-abc12345",
"projectPath": "/tmp/code-sense-xxx",
"repoUrl": "https://github.com/username/repo",
"createdAt": "2024-01-24T10:00:00Z",
"ttl": "1h0m0s",
"totalFiles": 15,
"totalSymbols": 45,
"languages": {
"go": 8,
"javascript": 4,
"typescript": 3
},
"symbolsByKind": {
"function": 20,
"type": 10,
"variable": 8,
"constant": 7
}
}
2. 搜索代码符号
{
"tool": "search_symbols",
"arguments": {
"repoId": "repo-abc12345",
"query": "hello"
}
}
返回示例:
仓库 repo-abc12345 中找到 2 个匹配 'hello' 的符号:
• hello (function)
文件: /path/to/file.go:10
签名: hello()
说明: 这是一个问候函数
• Hello (class)
文件: /path/to/file.ts:20
签名: class Hello
说明: Hello类定义
3. 获取文件内容
{
"tool": "get_file_content",
"arguments": {
"repoId": "repo-abc12345",
"filePath": "/path/to/file.go"
}
}
4. 获取项目概览
{
"tool": "get_project_summary",
"arguments": {
"repoId": "repo-abc12345"
}
}
返回示例:
仓库 repo-abc12345 概览:
仓库URL: https://github.com/username/repo
创建时间: 2024-01-24T10:00:00Z
最后访问: 2024-01-24T11:30:00Z
TTL: 1h0m0s
总文件数: 15
总符号数: 45
语言分布:
• go: 8 个文件
• javascript: 4 个文件
• typescript: 3 个文件
符号类型分布:
• function: 20 个
• type: 10 个
• variable: 8 个
• constant: 7 个
5. 查找依赖关系
{
"tool": "find_dependencies",
"arguments": {
"repoId": "repo-abc12345",
"symbolName": "hello"
}
}
返回示例:
依赖关系分析
仓库: repo-abc12345 (https://github.com/user/repo)
符号: hello
位置: /path/to/file.go:10
类型: function
签名: func hello(name string) string
相关符号 (同文件):
• goodbye (function) - /path/to/file.go:20
• helper (function) - /path/to/file.go:30
6. 获取函数内容
{
"tool": "get_function_content",
"arguments": {
"repoId": "repo-abc12345",
"functionName": "hello"
}
}
返回示例:
函数内容
仓库: repo-abc12345 (https://github.com/user/repo)
函数名: hello
位置: /path/to/file.go:10
类型: function
签名: func hello(name string) string
函数内容:
func hello(name string) string { return fmt.Sprintf("hello, %s", name) }
7. 获取变量定义
{
"tool": "get_variable_definition",
"arguments": {
"repoId": "repo-abc12345",
"variableName": "config"
}
}
返回示例:
变量定义
仓库: repo-abc12345 (https://github.com/user/repo)
变量名: config
位置: /path/to/file.go:5
类型: variable
签名: var config Config
文件内容:
var config Config = Config{ Host: "localhost", Port: 8080, }
多仓库使用流程
场景1: AI分析多个项目
1. AI调用 fetch_repository("https://github.com/user/repo1")
→ 返回 repoId: "repo-001"
2. AI调用 fetch_repository("https://github.com/user/repo2")
→ 返回 repoId: "repo-002"
3. AI调用 search_symbols("repo-001", "hello")
→ 在repo1中搜索
4. AI调用 search_symbols("repo-002", "hello")
→ 在repo2中搜索
场景2: 仓库自动清理
1. AI索引仓库repo-001
2. 1小时后未访问该仓库
3. 系统自动清理repo-001
场景3: LRU淘汰
1. AI连续索引31个仓库(超过最大数量30)
2. 系统自动淘汰最久未使用的仓库
3. 保留最新的30个仓库
测试
运行单元测试
go test ./...
运行特定包的测试
go test ./internal/codeindex -v
go test ./internal/mcpserver -v
整体代码功能与结构总结
项目概述
Code Sense是一个功能完整的MCP代码分析服务器,主要功能包括:
- 多语言代码索引: 支持Go、JavaScript、TypeScript、Shell脚本、Python、Java、C++七种编程语言的代码解析和索引
- 多仓库管理: 支持同时管理多个代码仓库,每个仓库独立索引,互不干扰
- 智能资源管理: 实现TTL过期和LRU淘汰机制,自动管理内存和资源
- MCP协议支持: 基于go-sdk实现标准MCP协议,提供12个工具接口
- 友好的AI集成: 输出格式经过优化,便于AI理解和处理
- 大项目传输支持: 支持通过Base64编码的ZIP压缩包传输大型项目代码
- 多种传输方式: 支持Stdio、SSE、Streamable三种传输方式
核心模块详解
1. MCP服务器模块 (server.go)
主要功能:
- 实现MCP协议,提供标准化的工具接口
- 管理多个代码仓库,每个仓库有独立的索引器
- 实现TTL和LRU机制,自动清理过期和最久未使用的仓库
- 提供线程安全的并发访问
核心结构:
Repository: 封装仓库信息,包含ID、URL、本地路径、索引器、创建时间、最后访问时间、TTL等MCPServer: MCP服务器主结构,包含server、indexers map、mutex、配置等
关键方法:
registerTools(): 注册所有MCP工具handleFetchRepository(): 处理获取仓库请求handleSearchSymbols(): 处理搜索符号请求handleGetFileContent(): 处理获取文件内容请求startCleanupRoutine(): 启动定时清理任务checkAndEvict(): 检查并执行LRU淘汰
2. 代码索引模块 (indexer.go)
主要功能:
- 解析Go、JavaScript、TypeScript、Shell脚本、Python、Java、C++代码文件
- 提取函数、类、类型、变量、常量等代码符号
- 建立代码符号索引,支持快速搜索
- 提供项目概览和文件列表
核心结构:
CodeIndexer: 代码索引器主结构,包含文件列表、符号列表、语言统计等Symbol: 代码符号结构,包含名称、类型、文件路径、行号、签名等
关键方法:
IndexDirectory(): 索引整个目录indexGoFile(): 解析Go文件indexJSFile(): 解析JavaScript文件indexTSFile(): 解析TypeScript文件indexShellFile(): 解析Shell脚本文件indexPythonFile(): 解析Python文件indexJavaFile(): 解析Java文件indexCppFile(): 解析C++文件SearchSymbols(): 搜索代码符号GetFileContent(): 获取文件内容GetProjectSummary(): 获取项目概览
3. 仓库获取模块 (fetcher.go)
主要功能:
- 从GitHub获取公开或私有仓库
- 从GitLab获取仓库(预留接口)
- 从本地文件系统读取代码
- 自动下载和解压GitHub仓库的tar.gz文件
核心结构:
RepositoryFetcher: 仓库获取器接口GitHubFetcher: GitHub仓库获取器实现LocalFetcher: 本地仓库获取器实现
关键方法:
FetchRepository(): 获取仓库到本地临时目录downloadRepository(): 下载GitHub仓库parseGitHubRepoURL(): 解析GitHub仓库URL
4. 配置管理模块 (config.go)
主要功能:
- 解析YAML配置文件
- 提供配置结构体定义
- 支持命令行参数覆盖
核心结构:
Config: 配置主结构,包含Server、MCP、CodeIndex、GitHub、GitLab等配置
MCP工具接口
Code Sense提供以下12个MCP工具接口:
- fetch_repository: 获取并索引仓库
- create_repo_from_zip: 从ZIP压缩包创建仓库
- search_symbols: 搜索代码符号
- get_file_content: 获取文件内容
- list_all_files: 列出所有文件
- list_all_symbols: 列出所有符号
- get_symbols_by_file: 获取文件中的符号
- get_project_summary: 获取项目概览
- analyze_code_structure: 分析代码结构
- find_dependencies: 查找符号依赖关系
- get_function_content: 获取函数内容
- get_variable_definition: 获取变量定义
测试验证
项目包含完整的单元测试,覆盖以下模块:
-
代码索引测试 (indexer_test.go)
- 测试Go代码解析
- 测试JavaScript代码解析
- 测试TypeScript代码解析
- 测试Shell脚本解析
- 测试Python代码解析
- 测试Java代码解析
- 测试C++代码解析
- 测试符号搜索功能
-
MCP服务器测试 (server_test.go)
- 测试仓库添加和获取
- 测试TTL过期机制
- 测试LRU淘汰策略
- 测试多仓库并发访问
测试成功案例
成功测试了GitHub上的go-xorm项目:
- 仓库URL: https://github.com/go-xorm/xorm.git
- 仓库ID: repo-0da2e4c1
- 总文件数: 102
- 总符号数: 2067
- 符号类型分布: constant(17), function(979), type(331), variable(740)
技术栈
- 语言: Go 1.23.8
- MCP SDK: github.com/modelcontextprotocol/go-sdk v1.2.0
- GitHub SDK: github.com/google/go-github/v68 v68.0.0
- 配置管理: gopkg.in/yaml.v3
- 并发控制: sync.RWMutex
- UUID生成: github.com/google/uuid
项目优势
- 多仓库并发: 支持同时索引和查询多个仓库,提高效率
- 自动资源管理: TTL和LRU机制自动清理过期和最久未使用的仓库
- 线程安全: 使用读写锁保证并发访问的安全性
- 友好的AI集成: 输出格式经过优化,便于AI理解和处理
- 完整的测试: 包含完整的单元测试,保证代码质量
- 灵活的配置: 支持配置文件和命令行参数,使用灵活
使用场景
Code Sense适用于以下场景:
- AI理解新项目: AI通过MCP工具快速获取项目代码信息
- AI查找特定功能: AI搜索代码符号,定位相关功能
- AI分析代码实现: AI获取文件内容,分析代码实现细节
- AI对比多个项目: AI同时索引多个项目,对比代码结构
- 代码审查: AI分析代码质量和结构
- 文档生成: AI基于代码索引自动生成文档
- 依赖分析: AI通过find_dependencies工具分析代码依赖关系
测试成功案例
测试go-xorm项目
使用GitHub上的go-xorm项目进行测试,成功获取并索引了代码:
仓库信息:
- URL: https://github.com/go-xorm/xorm.git
- 仓库ID: repo-0da2e4c1
索引结果:
- 总文件数: 102
- 总符号数: 2067
- 语言分布: Go语言2067个符号
- 符号类型分布:
- constant: 17个
- function: 979个
- type: 331个
- variable: 740个
测试命令:
./server.exe -repo https://github.com/go-xorm/xorm.git -token your-github-token
MCP调用示例:
{
"tool": "fetch_repository",
"arguments": {
"repoUrl": "https://github.com/go-xorm/xorm.git",
"token": "your-github-token"
}
}
返回结果:
{
"repoId": "repo-0da2e4c1",
"projectPath": "C:\\Users\\admin\\AppData\\Local\\Temp\\code-sense-2592620881",
"repoUrl": "https://github.com/go-xorm/xorm.git",
"createdAt": "2026-01-24T15:21:57+08:00",
"ttl": "1h0m0s",
"totalFiles": 102,
"totalSymbols": 2067,
"languages": {
"go": 2067
},
"symbolsByKind": {
"constant": 17,
"function": 979,
"type": 331,
"variable": 740
}
}
AI集成示例
Code Sense设计为与AI助手无缝集成。以下是使用场景:
场景1: AI理解新项目
用户: "帮我理解这个项目"
AI: 调用 fetch_repository 获取项目代码
AI: 调用 get_project_summary 获取项目概览
AI: 调用 analyze_code_structure 分析代码结构
AI: 基于返回的信息,向用户解释项目结构、主要模块和功能
场景2: AI查找特定功能
用户: "这个项目中有处理用户认证的函数吗?"
AI: 调用 search_symbols 搜索 "auth" 或 "login"
AI: 调用 get_file_content 查看相关文件内容
AI: 向用户说明找到的认证相关函数和实现
场景3: AI分析代码实现
用户: "这个函数是如何实现的?"
AI: 调用 search_symbols 找到目标函数
AI: 调用 get_file_content 获取函数所在文件
AI: 调用 get_symbols_by_file 获取文件中的所有符号
AI: 分析函数实现和依赖关系,向用户解释
场景4: AI对比多个项目
用户: "对比这两个项目的代码结构"
AI: 调用 fetch_repository 索引项目1
AI: 调用 fetch_repository 索引项目2
AI: 调用 analyze_code_structure 分析项目1
AI: 调用 analyze_code_structure 分析项目2
AI: 对比两个项目的结构,向用户说明差异
性能优化
多仓库并发
- 每个仓库独立索引,互不干扰
- 支持同时查询多个仓库
- 使用读写锁保证并发安全
内存管理
- TTL机制自动清理过期仓库
- LRU策略限制最大仓库数量
- 定时清理释放内存
索引优化
- 增量索引支持(未来)
- 符号缓存机制(未来)
- 智能预加载(未来)
注意事项
- GitHub Token: 访问私有仓库需要提供GitHub Personal Access Token
- 文件大小: 大型仓库可能需要较长时间索引
- 内存使用: 索引多个大型项目会占用较多内存
- 网络依赖: 从GitHub/GitLab获取代码需要网络连接
- TTL设置: 根据使用场景调整TTL,避免频繁重新索引
- 最大仓库数: 根据服务器内存调整maxRepos参数
许可证
MIT License
贡献
欢迎提交Issue和Pull Request!
联系方式
如有问题或建议,请提交Issue。
