GoContext MCP服务器

](https://golang.org) ![License](LICENSE)

GoContext是一个模型上下文协议（MCP）服务器，为Go代码库提供符号感知语义搜索。它利用Go的原生AST解析功能来理解代码结构、类型和域关系，特别是对于使用域驱动设计（DDD）模式的大型项目。

特性

AST本地解析：使用Go的标准库(go/parser, go/ast, go/types)用于精确的符号提取
语义搜索：矢量嵌入支持自然语言代码搜索（“身份验证逻辑”）
混合搜索：将向量相似性与BM25关键字搜索相结合，以获得最佳结果
增量索引：SHA-256文件哈希跟踪更改，仅重新索引修改过的文件
DDD模式检测：自动识别聚合、实体、存储库、服务、CQRS模式
离线操作：使用本地嵌入在没有网络访问的情况下工作
单一二进制：无外部依赖，易于部署

快速开始

安装

选项1：下载预构建二进制文件（推荐）

从以下网址下载适用于您平台的最新版本发布页面:

# macOS Apple Silicon
curl -LO https://github.com/dshills/gocontext-mcp/releases/download/v1.0.0/gocontext-darwin-arm64
chmod +x gocontext-darwin-arm64
sudo mv gocontext-darwin-arm64 /usr/local/bin/gocontext

# macOS Intel
curl -LO https://github.com/dshills/gocontext-mcp/releases/download/v1.0.0/gocontext-darwin-amd64
chmod +x gocontext-darwin-amd64
sudo mv gocontext-darwin-amd64 /usr/local/bin/gocontext

# Linux x86_64
curl -LO https://github.com/dshills/gocontext-mcp/releases/download/v1.0.0/gocontext-linux-amd64
chmod +x gocontext-linux-amd64
sudo mv gocontext-linux-amd64 /usr/local/bin/gocontext

# Verify installation
gocontext --version

选项2：使用Go安装

go install github.com/dshills/gocontext-mcp/cmd/gocontext@latest

备注：需要Go 1.25.4+。构建模式（CGO vs Pure Go）取决于您的 CGO_ENABLED 环境变量。

选项3：从源代码构建

# Clone the repository
git clone https://github.com/dshills/gocontext-mcp.git
cd gocontext-mcp

# Build with CGO (includes sqlite-vec extension for fast vector search)
make build

# Or build pure Go version (no C compiler needed)
make build-purego

# Binary available at bin/gocontext

有关特定于平台的详细说明，请参阅 docs/installation.md.

构建要求

CGO构建（推荐）:

转到1.25.4或更高版本
C编译器（gcc、clang）
通过sqlite-vec扩展提供更快的矢量搜索

纯Go构建:

转到1.25.4或更高版本
不需要C编译器
使用modernc.org/sqlite（纯Go sqlite实现）
矢量运算速度稍慢

配置

MCP服务器设置

将GoContext添加到MCP客户端配置中：

克劳德代码 (~/.config/claude-code/mcp_settings.json):

{
  "mcpServers": {
    "gocontext": {
      "command": "/path/to/gocontext-mcp/bin/gocontext",
      "args": ["serve"],
      "env": {
        "JINA_API_KEY": "your-jina-api-key"
      }
    }
  }
}

用于Codex CLI:

{
  "mcpServers": {
    "gocontext": {
      "command": "/path/to/gocontext-mcp/bin/gocontext",
      "args": ["serve"]
    }
  }
}

嵌入提供程序配置

GoContext支持多个嵌入提供程序：

名称 AI （默认值，建议用于代码）：

   export JINA_API_KEY="your-api-key"

获取API密钥：https://jina.ai/embeddings/

OpenAI:

   export OPENAI_API_KEY="your-api-key"
   export GOCONTEXT_EMBEDDING_PROVIDER="openai"

本地（离线）:

   export GOCONTEXT_EMBEDDING_PROVIDER="local"

使用捆绑的本地模型，不需要API密钥。

工作流程：索引和查询您的代码库

使用MCP客户端配置GoContext后，请按照以下步骤添加和查询Go代码库：

步骤1：检查代码库是否已索引

在索引之前，请检查代码库是否已被索引：

通过克劳德代码或MCP客户端： 询问：“检查/path/to/my/go/project的索引状态”

这使用了 get_status 工具内部检查：

项目是否被索引
索引的文件和块的数量
上次索引时间戳
数据库运行状况

步骤2：为新代码库建立索引

要首次索引Go代码库，请执行以下操作：

通过克劳德代码或MCP客户端： 问：“将代码库索引到/path/to/my/go/project”

发生了什么：

GoContext使用AST解析所有Go文件
提取函数、类型、接口及其文档
在函数/类型边界处创建语义块
为每个块生成向量嵌入
将所有内容存储在本地SQLite数据库中

您可以指定的选项：

包含测试文件：“索引/路径/到/项目，包括测试文件”
强制重新索引：“强制重新索引/path/to/project”（忽略缓存，重新处理所有文件）
排除供应商：“索引/路径/到/项目排除供应商目录”（默认行为）

典型索引时间： 50k LOC代码库需要2-3分钟

步骤3：查询索引代码库

索引后，您可以使用自然语言或关键字进行搜索：

自然语言查询：

“在/path/to/project中查找身份验证中间件函数”
“在/path/to/project中显示数据库存储库实现”
“/path/to/project中的错误处理逻辑在哪里？”
“在/path/to/project的API包中查找所有HTTP处理程序”

关键字查询：

“在/path/to/project中搜索‘事务’”
“在/path/to/project中查找名为'Validate'的方法”

筛选查询：

“在/path/to/project的auth包中查找函数”
“在/path/to/project中显示服务实现（DDD模式）”
“在/path/to/project中查找所有导出的函数”

步骤4：代码更改后重新索引

GoContext会自动检测已更改的文件，并且只会重新索引已修改的文件：

通过克劳德代码或MCP客户端： 询问：“重新索引/路径/到/我的/去/项目”

发生了什么：

GoContext检查文件哈希值（SHA-256）
仅处理自上次索引以来已更改的文件
比完全索引快得多（10次文件更改通常\<30秒）

强制完全重新索引（如果需要）： 问：“强制重新索引/路径/到/我的/去/项目”

工作流会话示例

You: Check status of /home/user/myproject
Claude: The project is not indexed yet. Would you like me to index it?

You: Yes, index it including test files
Claude: Indexing /home/user/myproject...
[After ~2 minutes]
Claude: Successfully indexed 245 files, created 1834 chunks.

You: Find authentication middleware
Claude: Found 3 results:
1. AuthMiddleware (internal/auth/middleware.go:15)
   - func AuthMiddleware(next http.Handler) http.Handler
2. JWTAuthMiddleware (internal/auth/jwt.go:42)
   - func JWTAuthMiddleware() gin.HandlerFunc
...

You: Show me the implementation of AuthMiddleware
Claude: [Shows full code with context]

搜索模式

GoContext支持三种搜索模式：

混合（默认）：将向量相似性与关键字匹配相结合，以获得最佳结果
矢量：纯语义搜索，即使关键字不匹配，也能找到概念上相似的代码
关键词：使用BM25算法的传统文本搜索

通过克劳德代码： 搜索模式将根据您的查询自动选择。要获得更多控制：

“使用语义搜索在/path/to/project中查找身份验证”（矢量模式）
“在/path/to/project中使用关键字搜索'http.Handler'”（关键字模式）

性能提示

首次索引：50-100k LOC代码库需要2-5分钟
重新索引：典型代码更改时间\<30秒（10个文件）
搜索：对于大多数查询，\<500ms
缓存：缓存频繁查询以获得即时结果

故障排除

“未找到结果”

确保代码库已编入索引：先检查状态
尝试不同的查询术语：使用同义词或更具体的术语
检查过滤器：删除包装或符号类型的过滤器
如果使用纯矢量/关键字，请尝试混合搜索模式

“索引速度慢”

确保您使用的是CGO构建（更快的向量操作）
检查网络连接（用于远程嵌入API）
考虑使用本地嵌入进行离线操作
如果不需要，排除供应商目录和测试文件

“搜索结果不相关”

尝试使用上下文进行更具体的查询
使用过滤器按包或符号类型缩小范围
如果使用域驱动设计，请指定DDD模式
如果代码库发生重大变化，请重新索引

用法

MCP工具

GoContext提供了三种MCP工具：

1. `index_codebase`

索引Go代码库以进行语义搜索：

{
  "path": "/path/to/your/go/project",
  "force_reindex": false,
  "include_tests": true,
  "include_vendor": false
}

响应:

{
  "status": "success",
  "files_indexed": 245,
  "files_skipped": 12,
  "files_failed": 0,
  "chunks_created": 1834,
  "embeddings_generated": 1834,
  "duration_ms": 45230
}

2. `search_code`

按语义或关键字搜索索引代码：

{
  "path": "/path/to/your/go/project",
  "query": "authentication middleware handlers",
  "limit": 10,
  "search_mode": "hybrid",
  "filters": {
    "symbol_types": ["function", "method"],
    "packages": ["internal/auth"],
    "ddd_patterns": ["service"]
  }
}

响应:

{
  "results": [
    {
      "rank": 1,
      "relevance_score": 0.89,
      "symbol": {
        "name": "AuthMiddleware",
        "kind": "function",
        "package": "internal/auth",
        "signature": "func AuthMiddleware(next http.Handler) http.Handler"
      },
      "file": "internal/auth/middleware.go",
      "content": "func AuthMiddleware(next http.Handler) http.Handler { ... }",
      "context": {
        "before": "package auth\n\nimport \"net/http\"",
        "after": "func ValidateToken(token string) bool { ... }"
      }
    }
  ],
  "total_results": 8,
  "search_duration_ms": 234,
  "cache_hit": false
}

3. `get_status`

检查索引状态：

{
  "path": "/path/to/your/go/project"
}

响应:

{
  "indexed": true,
  "project": {
    "root_path": "/path/to/your/go/project",
    "module_name": "github.com/yourorg/yourproject",
    "total_files": 245,
    "total_chunks": 1834,
    "last_indexed_at": "2025-11-06T10:30:00Z"
  },
  "health": {
    "database_accessible": true,
    "fts_indexes_built": true
  }
}

发展

项目结构

gocontext-mcp/
├── cmd/gocontext/          # Main entry point
├── internal/               # Internal packages
│   ├── parser/            # AST parsing and symbol extraction
│   ├── chunker/           # Code chunking for embeddings
│   ├── embedder/          # Embedding generation (Jina/OpenAI/local)
│   ├── indexer/           # Indexing coordinator
│   ├── searcher/          # Hybrid search (vector + BM25)
│   ├── storage/           # SQLite + vector extension
│   └── mcp/               # MCP protocol handlers
├── pkg/types/             # Shared types and interfaces
└── tests/                 # Unit and integration tests
    ├── unit/
    ├── integration/
    └── testdata/

构建命令

# Development build (format, lint, test, build)
make dev

# Run all tests
make test

# Run tests with race detector
make test-race

# Generate coverage report
make test-coverage

# Run linters
make lint

# Run benchmarks
make bench

# Profile CPU usage
make bench-cpu

# Profile memory usage
make bench-mem

# Full CI pipeline
make ci

# Clean build artifacts
make clean

构建标签详解

CGO构建

用途 sqlite_vec 构建标签以包含sqlite-vec扩展：

CGO_ENABLED=1 go build -tags "sqlite_vec" -o bin/gocontext ./cmd/gocontext

优点:

快速向量相似性搜索（本机C实现）
大型代码库的性能更好
建议用于生产

缺点:

在构建时需要C编译器
二进制是特定于平台的

纯Go构建

用途 purego 纯Go SQLite驱动程序的build标签：

CGO_ENABLED=0 go build -tags "purego" -o bin/gocontext-purego ./cmd/gocontext

优点:

不需要C编译器
交叉编译到任何平台
单静态二进制

缺点:

较慢的向量操作（纯Go实现）
向量搜索的内存使用率更高

测试

# Run unit tests
go test ./pkg/...
go test ./internal/...

# Run integration tests
go test ./tests/integration/...

# Run specific test
go test -v ./internal/parser -run TestParseFile

# Run with race detector
go test -race ./...

# Generate coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

代码检查

# Run linters
golangci-lint run

# Auto-fix issues
golangci-lint run --fix

演出

目标

索引：100k LOC小于5分钟
搜索延迟：p95\<500ms
重新索引：10次文件更改小于30秒
记忆：100000 LOC代码库小于500MB
解析：100个文件在\<1秒内

基准测试

# Run all benchmarks
make bench

# Profile specific component
go test -bench=BenchmarkParsing -benchmem ./internal/parser

# CPU profiling
make bench-cpu
go tool pprof cpu.prof

# Memory profiling
make bench-mem
go tool pprof mem.prof

建筑

核心组件

解析器：使用AST从Go源代码中提取符号、类型和签名
Chunker：在函数/类型边界处将代码划分为语义块
嵌入器：生成向量嵌入（Jina AI、OpenAI或局部模型）
索引器：协调解析、分块、嵌入和并发工作池
搜索者：混合搜索结合向量相似度+BM25文本搜索
存储：用于嵌入的带矢量扩展的SQLite数据库

数据流

索引管道：

Go Files → Parser (AST extraction) → Chunker (semantic boundaries) →
Embedder (vectors) → Storage (SQLite)

搜索管道：

Query → Embedder (vectorize) → Hybrid Search (vector + BM25) →
Optional Reranker → Top-K Results

贡献

欢迎投稿！请看贡献.md 作为指导方针。

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

致谢

内置 mcp走用于MCP协议支持
用途 sqlite-vc 用于矢量搜索
嵌入提供者：名称 AI, OpenAI

支持

问题：
文档： docs/
讨论：

Gocontext MCP

快速接入

详细介绍