CodeGrok MCP

CodeGrok MCP

人工智能助手的语义代码搜索

  

*让你的人工智能助手真正理解你的代码库*

特性 • 快速开始 • 能力 • 局限性 • 集成 • 用例

______________________________________________________________________

什么是CodeGrok MCP？

CodeGrok MCP是一个 模型上下文协议（MCP）服务器 它使人工智能助手能够使用 语义嵌入 和 树保姆解析.

与简单的文本搜索不同，CodeGrok了解代码结构——它知道什么是函数、类和方法，即使你用自然语言描述它，它也能找到相关的代码。

You: "Where is authentication handled?"
CodeGrok: Returns auth middleware, login handlers, JWT validation code...

为什么要使用CodeGrok？

问题： AI助手的上下文窗口有限。发送整个代码库是昂贵的，而且通常是不可能的。

解决方案： CodeGrok对代码进行一次索引，然后AI可以进行语义查询，只接收5-10个最相关的代码片段--代币减少10-100x vs天真的“读取所有文件”方法。

______________________________________________________________________

特性

• 语义代码搜索 -按含义查找代码，而不仅仅是关键字
• 支持9种语言 -Python、JavaScript、TypeScript、C、C++、Go、Java、Kotlin、Bash
• 28文件扩展名 -全面覆盖，包括 .jsx, .tsx, .mjs, .hpp等等。
• 快速并行索引 -多线程解析速度提高3-5倍
• 增量更新 -仅重新索引更改的文件（自动模式）
• 本地和私人 -所有数据都保留在您的机器上 .codegrok/ 文件夹
• 零LLM依赖 -轻量级、专注的工具（不需要API密钥）
• GPU加速 -自动检测CUDA以实现更快的嵌入
• 适用于任何MCP客户端 -克劳德、Cursor、克莱恩等

______________________________________________________________________

✅ CodeGrok能做什么

实时编码（人工智能辅助开发）

学习新的代码库

______________________________________________________________________

❌ CodeGrok不能做什么

重要提示： 了解限制有助于您有效地使用该工具。

不是为

技术限制

______________________________________________________________________

快速开始

安装

# Clone the repository
git clone https://github.com/rdondeti/CodeGrok_mcp.git
cd CodeGrok_mcp

# Option 1: Use setup script (recommended)
./setup.sh              # Linux/macOS
# or
.\setup.ps1             # Windows PowerShell

# Option 2: Manual install
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
pip install -e .

# Verify installation
codegrok-mcp --help

安装脚本选项：

第一指数

一旦与您的AI工具集成（见下文），请咨询您的助手：

"Learn my codebase at /path/to/my/project"

然后搜索：

"Find how API endpoints are defined"
"Where is error handling implemented?"
"Show me the database models"

______________________________________________________________________

🎯 用例

用例1：使用AI进行实时编码

CodeGrok如何节省代币：

Without CodeGrok:
  AI tries to read entire codebase → exceeds context window → fails or costs $$

With CodeGrok:
  AI: "I need to add a new route"
    ↓ calls get_sources("Express route definition")
  CodeGrok: Returns routes/api.js:15, routes/auth.js:8
    ↓ AI reads only those 2 files
  Result: 10-100x fewer tokens, faster responses

用例2：学习新的代码库

Step 1: "Learn my codebase at ~/projects/big-app"
Step 2: "Where is the main entry point?"
Step 3: "How is authentication implemented?"
Step 4: "Find the database connection logic"
Step 5: "Show me how API errors are handled"

用例3：代码审查协助

"Find all functions that handle user input"
"Where is validation performed?"
"Show me error handling patterns"

______________________________________________________________________

🔌 AI工具集成

克劳德代码（CLI）

将CodeGrok添加到Claude Code的最简单方法：

# Add the MCP server
claude mcp add codegrok-mcp -- codegrok-mcp

或者手动添加到您的设置中(~/.claude/settings.json):

{
  "mcpServers": {
    "codegrok": {
      "command": "codegrok-mcp"
    }
  }
}

克劳德代码中的用法：

> learn my codebase at ./my-project
> find authentication logic
> where is the main entry point?

______________________________________________________________________

克劳德桌面

添加到您的Claude Desktop配置中：

{
  "mcpServers": {
    "codegrok": {
      "command": "codegrok-mcp",
      "args": []
    }
  }
}

保存后重新启动Claude Desktop。

______________________________________________________________________

光标

Cursor通过其扩展系统支持MCP服务器：

1. 打开设置 → 扩展→ MCP
2. 添加服务器配置:

{
  "codegrok": {
    "command": "codegrok-mcp",
    "transport": "stdio"
  }
}

或添加到 .cursor/mcp.json 在您的项目中：

{
  "servers": {
    "codegrok": {
      "command": "codegrok-mcp"
    }
  }
}

______________________________________________________________________

风帆冲浪（Codeium）

Windsurf通过Cascade支持MCP：

1. 打开 级联设置
2. 引导到 MCP服务器
3. 添加配置：

{
  "codegrok": {
    "command": "codegrok-mcp",
    "transport": "stdio"
  }
}

______________________________________________________________________

Cline（VS代码）

在VS Code中添加到Cline的MCP设置中：

1. 打开命令选项板(Ctrl+Shift+P / Cmd+Shift+P)
2. 搜索“临床：打开MCP设置”
3. 添加：

{
  "mcpServers": {
    "codegrok": {
      "command": "codegrok-mcp"
    }
  }
}

______________________________________________________________________

Zed编辑

Zed通过其辅助面板支持MCP。添加到设置：

{
  "assistant": {
    "mcp_servers": {
      "codegrok": {
        "command": "codegrok-mcp"
      }
    }
  }
}

______________________________________________________________________

继续（VS代码/JetBrains）

添加到“继续”配置(~/.continue/config.json):

{
  "mcpServers": [
    {
      "name": "codegrok",
      "command": "codegrok-mcp"
    }
  ]
}

______________________________________________________________________

通用MCP客户端

对于任何兼容MCP的客户端，请使用stdio传输：

# Command to run
codegrok-mcp

# Transport
stdio (stdin/stdout)

# Protocol
Model Context Protocol (MCP)

______________________________________________________________________

MCP工具参考

CodeGrok提供 4工具 对于AI助手：

学习模式：

• auto （默认）：智能检测-如果存在，则增量重新索引，如果是新的，则完全索引
• full：强制完成重新索引（销毁现有索引）
• load_only：只需加载现有索引，无需任何索引

工具示例

学习代码库

{
  "tool": "learn",
  "arguments": {
    "path": "/home/user/my-project",
    "mode": "auto"
  }
}

答复：

{
  "success": true,
  "message": "Indexed 150 files with 1,247 symbols",
  "stats": {
    "total_files": 150,
    "total_symbols": 1247,
    "total_chunks": 2834,
    "indexing_time": 12.5
  }
}

搜索代码

{
  "tool": "get_sources",
  "arguments": {
    "question": "How is user authentication implemented?",
    "n_results": 5
  }
}

答复：

{
  "sources": [
    {
      "file": "src/auth/middleware.py",
      "symbol": "authenticate_request",
      "type": "function",
      "line": 45,
      "content": "def authenticate_request(request):\n    ...",
      "score": 0.89
    }
  ]
}

增量更新（使用自动学习模式）

{
  "tool": "learn",
  "arguments": {
    "path": "/home/user/my-project",
    "mode": "auto"
  }
}

响应（当索引存在时）：

{
  "success": true,
  "mode_used": "incremental",
  "files_added": 2,
  "files_modified": 5,
  "files_deleted": 1
}

______________________________________________________________________

支持的语言

总计：9种语言，28个文件扩展名

______________________________________________________________________

运作原理

建筑

┌─────────────────────────────────────────────────────────────┐
│                     MCP Client                               │
│        (Claude, Cursor, Cline, etc.)                        │
└─────────────────────────┬───────────────────────────────────┘
                          │ MCP Protocol (stdio)
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                   CodeGrok MCP Server                        │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   Parsers   │  │  Embeddings │  │   Vector Storage    │  │
│  │ (Tree-sitter)│  │ (Sentence   │  │    (ChromaDB)       │  │
│  │             │  │ Transformers)│  │                     │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

索引管道

Source Files → Tree-sitter Parser → Symbol Extraction →
Code Chunks → Embeddings → ChromaDB Storage

1. 解析：树保姆提取带有签名的函数、类和方法
2. 块：代码根据上下文（文档字符串、导入、调用）划分为语义块
3. 嵌入：句子变换器创建向量嵌入
4. 商店：ChromaDB在本地持久化向量 .codegrok/

搜索管道

Query → Embedding → Vector Similarity → Ranked Results

1. 嵌入查询：将自然语言转换为向量
2. 搜索：在ChromaDB中查找相似的向量
3. 返回：带有文件路径、行号和代码段的Top-k结果

存储

所有数据都存储在项目的本地：

your-project/
└── .codegrok/
    ├── chroma/           # Vector database
    └── metadata.json     # Index metadata (stats, file mtimes)

______________________________________________________________________

配置

环境变量

嵌入模型

默认模型(nomic-ai/CodeRankEmbed)针对代码检索进行了优化，包括：

• 768维嵌入
• 8192最大序列长度
• CodeSearchNet基准测试的最新性能

安全说明： trust_remote_code

默认嵌入模型(nomic-ai/CodeRankEmbed)要求 trust_remote_code=True 当通过句子转换器加载时。此标志允许执行与模型捆绑在一起的自定义Python代码。

为什么需要：

• 该模型使用自定义Nomic BERT架构，该架构不是标准HuggingFace模型库的一部分
• 自定义文件： modeling_hf_nomic_bert.py （模型架构）， configuration_hf_nomic_bert.py （配置）

安全审计： 自定义代码已经过审查，其中包含：

• 标准PyTorch神经网络定义
• 不 exec(), eval()，或动态代码执行
• 没有子进程或shell命令
• 除了HuggingFace的标准模型下载API之外，没有网络请求
• 仅从受信任的库（torch、transformer、einops、safetensor）导入

为了获得最大的安全性：

• 自己查看模型代码： 在HuggingFace上嵌入动态人工智能/代码库
• 在生产部署中固定到特定的模型版本
• 考虑使用Microsoft CodeBERT(microsoft/codebert-base)作为一种不需要 trust_remote_code （存在潜在的质量权衡）

______________________________________________________________________

发展

设置

# Clone
git clone https://github.com/rdondeti/CodeGrok_mcp.git
cd CodeGrok_mcp

# Run setup script
./setup.sh              # Linux/macOS (includes dev dependencies)
.\setup.ps1             # Windows PowerShell

# For clean reinstall:
./setup.sh --clean

测试

# Run all tests
pytest

# Run with coverage
pytest --cov=src/codegrok_mcp --cov-report=term-missing

# Run specific test categories
pytest tests/unit/ -v          # Fast unit tests
pytest tests/integration/ -v   # Integration tests (uses real embeddings)
pytest tests/mcp/ -v           # MCP protocol simulation tests

代码质量

# Format code
black src/

# Type checking
mypy src/

# Linting
flake8 src/

______________________________________________________________________

常见问题解答和故障排除

Server won't start

# Check installation
pip show codegrok-mcp

# Check Python version (need 3.10+)
python --version

# Reinstall
pip install -e .

Indexing is slow

• 大型代码库（>10k个文件）在第一个索引上需要更长的时间
• 使用 learn 在首次索引增量更新后再次进行（自动模式）
• 关闭其他繁重的应用程序
• 考虑先为子目录建立索引

Search returns irrelevant results

• 在查询中更加具体（例如，“JWT令牌验证”而不是“auth”）
• 如果代码库发生重大变化，请重新索引
• 检查您正在搜索的代码类型是否存在

Out of memory

• 索引代码库的较小部分
• 默认 coderankembed 型号使用~500MB-2GB RAM
• 关闭其他应用程序

"No index loaded" error

使用 learn 工具优先：

"Learn my codebase at /path/to/project"

______________________________________________________________________

与其他工具的比较

______________________________________________________________________

贡献

欢迎投稿！拜托：

1. 克隆该仓库
2. 创建要素分支(git checkout -b feature/amazing)
3. 进行更改
4. 运行测试(pytest)
5. 格式代码(black src/)
6. 提交拉取请求

开发指南

• 遵循黑色格式（行长100）
• 为所有函数添加类型提示
• 为新功能编写测试
• 更新文档

______________________________________________________________________

许可证

MIT许可证-请参阅 许可证 了解详情。

______________________________________________________________________

相关项目

• 模型上下文协议 -支持这种集成的协议
• 树保姆 -快速、准确的代码解析
• 色度数据库 -用于嵌入的矢量数据库
• 句子转换 -最先进的嵌入技术

______________________________________________________________________

支持

• 问题:
• 讨论:

______________________________________________________________________

由...制作❤️ 对于那些希望人工智能真正理解其代码的开发人员

⬆ 返回顶部