Greptile

🚀 Greptile MCP 服务 - TypeScript 版

这是一款采用 TypeScript 构建的现代 MCP（Model Context Protocol）服务，通过 Greptile API 提供 AI 驱动的代码搜索与查询能力。它使用官方 MCP SDK 构建，旨在与 Claude Desktop、Continue 等 AI 工具及其他兼容 MCP 的客户端无缝集成。

✨ 功能

🔥 零安装体验

# Start immediately with npx - no setup required!
npx greptile-mcp-server --api-key=xxx --github-token=yyy

🧠 AI 驱动的代码理解

• 自然语言查询：使用通俗易懂的英语提问，查询代码库相关问题
• 深度代码分析：理解架构、模式和实现细节
• 跨代码库洞察：比较多个代码库中的模式和方法
• 会话连续性：通过对话逐步加深理解

⚡ 现代架构

• 官方 MCP SDK：采用 TypeScript MCP SDK 构建，完全符合协议规范
• 流式传输支持：通过 Server-Sent Events 提供实时响应
• 类型安全：全面集成 TypeScript，并提供完善的类型定义
• 插件架构：可扩展的设计，支持自定义工具和集成

🛠️ 开发者体验

• 支持 NPX：使用一条命令即可安装并运行
• 自动配置：智能检测并验证配置
• 交互式设置：为首次使用的用户提供引导式设置向导
• 完善的帮助信息：内置文档和使用示例

🚀 快速开始

前置要求

• Node.js 18+（以获得最佳性能）
• Greptile API 密钥 - 前往 app.greptile.com 获取
• GitHub 令牌 - 前往 github.com/settings/tokens 生成，并授予 repo 权限

即刻启动

# Start immediately (will prompt for credentials if not set)
npx greptile-mcp-server

# With inline credentials
npx greptile-mcp-server --api-key=your_key --github-token=your_token

# Interactive setup wizard
npx greptile-mcp-server init

# Test connectivity
npx greptile-mcp-server test

环境设置

选项 1：.env 文件（推荐用于本地开发）

在项目根目录中创建 .env 文件：

GREPTILE_API_KEY=your_greptile_api_key_here
GITHUB_TOKEN=your_github_personal_access_token_here
GREPTILE_BASE_URL=https://api.greptile.com/v2  # Optional

选项 2：系统环境变量

Linux/macOS（Bash/Zsh）：

# Current session
export GREPTILE_API_KEY="your_api_key_here"
export GITHUB_TOKEN="your_github_token_here"

# Permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export GREPTILE_API_KEY="your_api_key_here"' >> ~/.bashrc
echo 'export GITHUB_TOKEN="your_github_token_here"' >> ~/.bashrc
source ~/.bashrc

Windows PowerShell：

# Current session
$env:GREPTILE_API_KEY="your_api_key_here"
$env:GITHUB_TOKEN="your_github_token_here"

# Permanent
setx GREPTILE_API_KEY "your_api_key_here"
setx GITHUB_TOKEN "your_github_token_here"
# Note: Restart terminal after using setx

Windows 命令提示符：

# Current session
set GREPTILE_API_KEY=your_api_key_here
set GITHUB_TOKEN=your_github_token_here

# Permanent
setx GREPTILE_API_KEY "your_api_key_here"
setx GITHUB_TOKEN "your_github_token_here"

API 密钥和令牌设置

Greptile API 密钥：

1. 访问 Greptile 设置
2. 生成新的 API 密钥
3. 将密钥复制到环境中

GitHub 令牌：

1. 访问 GitHub 设置 > 个人访问令牌
2. 创建“精细化个人访问令牌”以提高安全性
3. 为要编入索引的代码库授予 repo 权限
4. 将令牌复制到环境中

🔧 MCP 客户端集成

Claude Desktop

添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "greptile": {
      "command": "npx",
      "args": ["greptile-mcp-server"],
      "env": {
        "GREPTILE_API_KEY": "your_api_key",
        "GITHUB_TOKEN": "your_github_token"
      }
    }
  }
}

Continue IDE 扩展

添加到 Continue 配置中：

{
  "contextProviders": [
    {
      "name": "greptile-mcp",
      "type": "mcp",
      "serverName": "greptile",
      "command": ["npx", "greptile-mcp-server"]
    }
  ]
}

其他 MCP 客户端

该服务使用标准 MCP 协议，可与任何兼容 MCP 的客户端配合使用：

# Generic MCP client connection
your-mcp-client connect --command "npx greptile-mcp-server"

🛠️ 可用工具

1. greptile_help

获取完整的文档和使用示例。

{
  "name": "greptile_help"
}

2. index_repository

为代码库编制索引，以便进行搜索。

{
  "name": "index_repository",
  "arguments": {
    "remote": "github",
    "repository": "microsoft/vscode",
    "branch": "main",
    "reload": true
  }
}

3. query_repository

使用自然语言查询代码库。

{
  "name": "query_repository",
  "arguments": {
    "query": "How is authentication implemented in this codebase?",
    "repositories": [
      {
        "remote": "github",
        "repository": "microsoft/vscode", 
        "branch": "main"
      }
    ],
    "stream": false,
    "session_id": "optional-session-id"
  }
}

4. get_repository_info

获取已编入索引的代码库信息。

{
  "name": "get_repository_info",
  "arguments": {
    "remote": "github",
    "repository": "microsoft/vscode",
    "branch": "main"
  }
}

📖 使用示例

基本工作流

# 1. Start the server
npx greptile-mcp-server

# 2. In your MCP client, index a repository
{
  "tool": "index_repository",
  "arguments": {
    "remote": "github",
    "repository": "microsoft/vscode",
    "branch": "main"
  }
}

# 3. Query the codebase
{
  "tool": "query_repository", 
  "arguments": {
    "query": "How does VS Code handle file watching?",
    "repositories": [{"remote": "github", "repository": "microsoft/vscode", "branch": "main"}]
  }
}

基于会话的高级探索

// Start with architecture overview
const session = "exploration-session-1";

// Query 1: High-level understanding
{
  "tool": "query_repository",
  "arguments": {
    "query": "What is the overall architecture of this codebase?",
    "session_id": session,
    "repositories": [...]
  }
}

// Query 2: Deep dive (builds on previous context)
{
  "tool": "query_repository", 
  "arguments": {
    "query": "How do the main components we just discussed interact with each other?",
    "session_id": session  // Same session for continuity
  }
}

// Query 3: Implementation details
{
  "tool": "query_repository",
  "arguments": {
    "query": "Show me the specific implementation of the component interaction patterns",
    "session_id": session
  }
}

🔀 从 Python 版本迁移

TypeScript 版本与 Python 实现完全兼容，同时还带来了多项重要改进：

新增内容

• ✅ 官方 MCP SDK：符合标准的实现
• ✅ NPX 分发：无需安装即可使用
• ✅ 性能更佳：V8 引擎在 I/O 操作方面的优势
• ✅ 类型安全：全面集成 TypeScript
• ✅ 现代化工具：ESLint、Prettier 和全面的测试
• ✅ 增强的 CLI：交互式设置和更好的用户体验

迁移步骤

# Old Python usage
python -m src.main

# New TypeScript usage  
npx greptile-mcp-server

# Same MCP tools and API compatibility
# No changes needed in MCP client configurations

🚨 故障排除

测试你的设置

设置完成后，请务必测试配置：

npx greptile-mcp-server test

常见问题

❌ “缺少环境变量”

问题： 服务无法找到你的 API 密钥 解决方案：

• 设置永久环境变量后，重启终端
• 验证环境变量已设置：

  # Linux/macOS
  echo $GREPTILE_API_KEY
  echo $GITHUB_TOKEN
  
  # Windows PowerShell
  echo $env:GREPTILE_API_KEY
  echo $env:GITHUB_TOKEN
  

• 尝试使用内联凭据：

  GREPTILE_API_KEY="your_key" GITHUB_TOKEN="your_token" npx greptile-mcp-server
  

❌ “GitHub 令牌验证失败”

问题： GitHub 令牌无效或权限不足 解决方案：

• 确保令牌具有 repo 权限
• 在 GitHub 设置中生成新令牌
• 为了更好的安全性，请使用“细粒度个人访问令牌”
• 检查令牌是否已过期

❌ “Greptile API 身份验证失败”

问题： Greptile API 密钥无效或已过期 解决方案：

• 从 Greptile 设置获取新的 API 密钥
• 确认密钥复制正确（没有多余空格）
• 检查 API 密钥是否已过期

❌ “找不到模块”或导入错误

问题： NPX 缓存问题或安装不完整 解决方案：

• 清除 NPX 缓存：npx clear-npx-cache
• 强制全新安装：npx greptile-mcp-server@latest
• 检查 Node.js 版本（需要 Node 18+）

❌ MCP 客户端连接问题

问题： Claude Desktop 或其他 MCP 客户端无法连接 解决方案：

• 验证 MCP 服务配置语法
• 查看 Claude Desktop 日志，获取详细错误信息
• 确保 MCP 客户端可以访问环境变量
• 先尝试手动运行服务，确认其正常工作

获取帮助

• 运行 npx greptile-mcp-server init 进行交互式设置
• 运行 npx greptile-mcp-server test 进行详细诊断
• API 特定问题请查看 Greptile 文档
• 客户端集成方面的帮助请访问 MCP 文档

❓ 常见问题

问：使用该工具需要在本地安装任何内容吗？

答： 不需要！该服务通过 NPX 运行，无需安装。只需运行 npx greptile-mcp-server，它就会自动下载并运行。

问：我可以将它与任何兼容 MCP 的客户端搭配使用吗？

答： 可以！该服务实现了标准的 Model Context Protocol，可与 Claude Desktop、MCP CLI 工具以及任何其他兼容 MCP 的客户端配合使用。

问：如何为私有仓库建立索引？

答： 确保你的 GitHub 令牌对私有仓库具有 repo 权限。该令牌需要有权读取你想要建立索引的仓库。

问：.env 文件和环境变量有什么区别？

答：

• .env 文件适合本地开发——仅在文件所在目录中生效
• 环境变量是系统级的，可在任何地方使用，因此更适合通过 npx 全局使用

问：使用 Greptile 的费用是多少？

答： Greptile 的定价取决于你的使用情况。请查看 Greptile 定价页面了解当前费率。此 MCP 服务本身是免费开源的。

问：我可以将它用于多个仓库吗？

答： 可以！你可以为多个仓库建立索引，并跨所有仓库进行查询。对想要添加的每个仓库使用 index_repository 工具即可。

问：为一个仓库建立索引需要多长时间？

答： 索引时间取决于仓库大小。小型仓库（< 1000 个文件）通常需要 1-2 分钟，较大的仓库可能需要 10-15 分钟。你可以使用 get_repository_info 工具查看状态。

Q：我的代码数据安全吗？

A： Greptile 的 API 会根据其安全与隐私政策处理你的代码。有关数据处理和保留的详情，请查看 Greptile 的安全文档。

Q：我可以在 Windows 上运行吗？

A： 可以！此服务可在 Windows、macOS 和 Linux 上运行。请使用上文中针对各平台的环境变量设置说明。

Q：为什么会出现“command not found”错误？

A： 这通常意味着：

• 未安装 NPX（安装 Node.js 即可获得 NPX）
• PATH 中未包含 Node.js 二进制文件
• 命令中有拼写错误（应为 npx greptile-mcp-server，而不是 npx @greptile/mcp-server）

🏗️ 开发

本地开发

# Clone and setup
git clone https://github.com/greptile/mcp-server.git
cd mcp-server
npm install

# Development with hot reload
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Type checking
npm run typecheck

# Linting and formatting
npm run lint
npm run format

项目结构

src/
├── cli.ts              # NPX CLI interface
├── server.ts           # Core MCP server implementation  
├── index.ts            # Module exports
├── clients/
│   └── greptile.ts     # Greptile API client
├── types/
│   └── index.ts        # TypeScript type definitions
└── utils/
    └── index.ts        # Utility functions

tests/
├── unit/               # Unit tests
└── integration/        # Integration tests

构建配置

• TypeScript：ES2022 目标版本，启用严格模式
• 构建工具：使用 tsup 输出 ESM/CJS 双格式
• 测试：Mocha + Chai，支持 TypeScript
• 代码质量：ESLint + Prettier，使用 TypeScript 规则

🔧 配置选项

CLI 参数

npx greptile-mcp-server \
  --api-key="your_key" \
  --github-token="your_token" \
  --base-url="https://api.greptile.com/v2" \
  --repositories='[{"remote":"github","repository":"owner/repo","branch":"main"}]' \
  --stream=true \
  --timeout=60000 \
  --verbose

环境变量

变量	说明	默认值
GREPTILE_API_KEY	Greptile API 密钥	必填
GITHUB_TOKEN	GitHub 个人访问令牌	必填
GREPTILE_BASE_URL	API 基础 URL	https://api.greptile.com/v2

配置文件（可选）

创建 greptile.config.js：

export default {
  apiKey: process.env.GREPTILE_API_KEY,
  githubToken: process.env.GITHUB_TOKEN,
  repositories: [
    { remote: 'github', repository: 'owner/repo', branch: 'main' }
  ],
  features: {
    streaming: true,
    orchestration: true,
    flowEnhancement: true
  }
};

🚀 部署

Smithery Cloud 部署

无需配置，即可立即部署到 Smithery：

# Install Smithery CLI
npm install -g smithery

# Deploy from repository
smithery deploy

# Or deploy with custom configuration
smithery deploy --config smithery.yaml

# Monitor deployment
smithery status
smithery logs

Docker 部署

# Build Docker image
docker build -t greptile-mcp .

# Run with environment variables
docker run -e GREPTILE_API_KEY=your_key \
           -e GITHUB_TOKEN=your_token \
           -p 8080:8080 \
           greptile-mcp

# Or build Smithery-optimized image
npm run smithery:build

部署环境变量

# Required
GREPTILE_API_KEY=your_greptile_api_key
GITHUB_TOKEN=your_github_token

# Optional
GREPTILE_BASE_URL=https://api.greptile.com/v2
TRANSPORT=stdio
HOST=0.0.0.0
PORT=8080

云平台

• Smithery：使用 smithery deploy 一键部署
• Railway：连接 GitHub 仓库并设置环境变量
• Render：使用 npm start 作为启动命令
• Heroku：标准 Node.js 部署
• DigitalOcean App Platform：通过 Docker 或 buildpack 部署

🚦 性能与基准测试

启动性能

• 冷启动：< 2 秒
• 内存用量：基础占用约 50MB
• 并发请求：可处理 100+ 个并发 MCP 工具调用

API 性能

• 查询响应：通常为 1-3 秒
• 流式传输：实时传递数据块
• 仓库索引：耗时因仓库大小而异（通常为 30 秒至 5 分钟）

与 Python 版本相比

• 启动速度快 40% - V8 与 Python 运行时相比
• 容器体积小 60% - Node.js 与 Python 基础镜像相比
• 内存效率高 30% - 得益于 V8 垃圾回收
• 原生流式传输 - SSE 性能更佳

🛡️ 安全与最佳实践

令牌安全

• 环境变量：将令牌存储在环境变量中，而非代码中
• 最小权限：GitHub 令牌仅授予必需的 repo 权限
• 令牌轮换：定期轮换 API 密钥和令牌
• 本地存储：切勿将令牌提交到版本控制系统

网络安全

• 仅使用 HTTPS：所有 API 通信均使用 HTTPS
• 请求验证：验证并清理输入
• 速率限制：内置指数退避重试逻辑
• 错误处理：全面处理错误，避免泄露令牌

🤝 参与贡献

欢迎贡献！详情请参阅我们的贡献指南。

开发工作流

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 编写代码并添加测试
4. 运行测试套件（npm test）
5. 确保代码质量（npm run lint）
6. 提交更改（git commit -m 'Add amazing feature'）
7. 推送到分支（git push origin feature/amazing-feature）
8. 创建 Pull Request

📄 许可证

此项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

🙏 致谢

• Anthropic：感谢其制定 Model Context Protocol 规范
• Greptile：感谢其提供强大的代码分析 API
• TypeScript 社区：感谢其提供优秀的工具和生态系统
• MCP 社区：感谢其为协议开发提供支持和反馈

📞 支持

• 文档：docs.greptile.com
• 问题反馈：GitHub Issues
• 讨论：GitHub Discussions
• Discord：MCP 社区 Discord

---

由 Greptile 团队倾心打造 • 由 TypeScript 和 Model Context Protocol 提供支持