Greptile MCP

🚀 Greptile MCP服务器-TypeScript版

一种现代的、支持TypeScript-powered的MCP（模型上下文协议）服务器，通过Greptile API提供支持AI的代码搜索和查询功能。使用官方MCP SDK构建，旨在与Claude Desktop、Continue和其他MCP兼容客户端等AI工具无缝集成。

✨ 特性

🔥 零安装体验

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

🧠 AI驱动的代码理解

• 自然语言查询：用简单的英语询问有关代码库的问题
• 深度代码分析：了解架构、模式和实现细节
• 跨存储库洞察：比较多个代码库中的模式和方法
• 会话连续性：通过对话逐步建立理解

⚡ 现代建筑

• 官方MCP SDK：内置TypeScript MCP SDK，完全符合协议要求
• 流媒体支持：服务器发送事件的实时响应
• 类型安全：具有全面类型定义的完全TypeScript集成
• 插件架构：定制工具和集成的可扩展设计

🛠️ 开发者体验

• NPX就绪：使用单个命令安装并运行
• 自动配置：智能配置检测和验证
• 交互式设置：首次用户的引导安装向导
• 全面帮助：内置文档和使用示例

🚀 快速开始

先决条件

• Node.js 18+ （为了获得最佳性能）
• Greptile API密钥 -获取你的 App.giant.Com
• GitHub代币 -生成时间 随着 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. 访问 油脂设置
2. 生成新的API密钥
3. 将密钥复制到您的环境中

GitHub令牌：

1. 访问
2. 创建“细粒度个人访问令牌”以提高安全性
3. 授予 repo 要索引的存储库的权限
4. 将令牌复制到您的环境中

🔧 MCP客户端集成

克劳德桌面版

添加到您的 claude_desktop_config.json:

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

继续IDE扩展

添加到“继续”配置中：

{
  "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 权限
• 在以下位置生成新令牌
• 为了提高安全性，请使用“细粒度个人访问令牌”
• 支票令牌尚未过期

❌ “Greptile API身份验证失败”

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

• 从获取新的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的问题
• 访问 MCP文件 获取客户端集成帮助

❓ 常见问题

Q： 我需要在本地安装任何东西才能使用它吗？

A. 不！服务器通过NPX运行，无需安装。跑 npx greptile-mcp-server 它将自动下载并运行。

Q： 我可以在任何兼容MCP的客户端上使用它吗？

A. 对！此服务器实现了标准的模型上下文协议，并与Claude Desktop、MCP CLI工具和任何其他MCP兼容客户端配合使用。

Q： 如何为私有存储库建立索引？

A. 确保您的GitHub令牌具有 repo 私有存储库的权限。令牌需要访问权限才能读取要索引的存储库。

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

A.

• .env文件 非常适合本地开发-它们只在文件所在的目录中工作
• 环境变量 它们是全系统的，可以在任何地方工作，使其更适合在npx的全球使用

Q： 使用Greptile需要多少钱？

A. 润滑脂的价格取决于您的使用情况。检查 Greptile的定价页面 以目前的价格。此MCP服务器本身是免费和开源的。

Q： 我可以将其用于多个存储库吗？

A. 对！您可以为多个存储库建立索引，并跨所有存储库进行查询。使用 index_repository 您要添加的每个存储库的工具。

Q： 为存储库建立索引需要多长时间？

A. 索引时间因存储库大小而异。小型存储库（\<1000个文件）通常需要1-2分钟，而大型存储库可能需要10-15分钟。您可以通过以下方式查看状态 get_repository_info 工具。

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

A. 您的代码由Greptile的API根据其安全和隐私政策进行处理。检查 Greptile的安全文件 有关数据处理和保留的详细信息。

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

A. 对！服务器可在Windows、macOS和Linux上运行。使用上面特定于平台的环境变量设置说明。

Q： 为什么我收到“找不到命令”错误？

A. 这通常意味着：

• 未安装NPX（安装包含NPX的Node.js）
• 您的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+使用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.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云部署

立即部署到 铁匠铺 零配置：

# 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 deploy
• 铁路：连接GitHub仓库，设置环境变量
• 渲染：使用 npm start 作为启动命令
• Heroku：标准Node.js部署
• 数字海洋应用平台：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. 复刻仓库
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. 打开拉取请求

📄 许可证

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

🙏 致谢

• Anthropic 用于模型上下文协议规范
• 希腊 用于强大的代码分析API
• TypeScript社区 卓越的工具和生态系统
• MCP社区 用于协议开发和反馈

📞 支持

• 文档: docs.greptile.com
• 问题:
• 讨论:
• Discord 的中文翻译是“不和谐”或“纷争”。: MCP社区不和

______________________________________________________________________

内置于❤️ 由Greptile团队提供•由TypeScript和模型上下文协议提供支持