🚀 Greptile MCP Server - TypeScript 版本

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

✨ 功能

🔥 零安装体验

# 立即启动，无需设置！
npx greptile-mcp-server --api-key=xxx --github-token=yyy

🧠 基于人工智能的代码理解

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

⚡ 现代架构

• 官方 MCP SDK：使用 TypeScript MCP SDK 实现完全协议合规
• 流支持：实时响应，使用 Server-Sent Events
• 类型安全：全面的 TypeScript 集成和类型定义
• 插件架构：可扩展设计，用于自定义工具和集成

🛠️ 开发者体验

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

🚀 快速开始

前提条件

• Node.js 18+（为了最佳性能）
• Greptile API 密钥 - 在 app.greptile.com 获取
• GitHub 令牌 - 在 github.com/settings/tokens 生成，需有 repo 权限

即时启动

# 立即启动（如果未设置凭据，将提示输入）
npx greptile-mcp-server

# 使用内联凭据
npx greptile-mcp-server --api-key=your_key --github-token=your_token

# 交互式设置向导
npx greptile-mcp-server init

# 测试连接
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  # 可选

方案 2：系统环境变量

Linux/macOS (Bash/Zsh):

# 当前会话
export GREPTILE_API_KEY="your_api_key_here"
export GITHUB_TOKEN="your_github_token_here"

# 永久设置（添加到 ~/.bashrc 或 ~/.zshrc）
echo 'export GREPTILE_API_KEY="your_api_key_here"' >> ~/.bashrc
echo 'export GITHUB_TOKEN="your_github_token_here"' >> ~/.bashrc
source ~/.bashrc

Windows PowerShell:

# 当前会话
$env:GREPTILE_API_KEY="your_api_key_here"
$env:GITHUB_TOKEN="your_github_token_here"

# 永久设置
setx GREPTILE_API_KEY "your_api_key_here"
setx GITHUB_TOKEN "your_github_token_here"
# 注意：使用 setx 后需要重启终端

Windows 命令提示符:

# 当前会话
set GREPTILE_API_KEY=your_api_key_here
set GITHUB_TOKEN=your_github_token_here

# 永久设置
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 兼容客户端：

# 通用 MCP 客户端连接
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": "如何在这个代码库中实现身份验证？",
    "repositories": [
      {
        "remote": "github",
        "repository": "microsoft/vscode", 
        "branch": "main"
      }
    ],
    "stream": false,
    "session_id": "可选会话ID"
  }
}

4. get_repository_info

获取已索引仓库的信息。

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

📖 使用示例

基本工作流程

# 1. 启动服务器
npx greptile-mcp-server

# 2. 在您的 MCP 客户端中索引一个仓库
{
  "tool": "index_repository",
  "arguments": {
    "remote": "github",
    "repository": "microsoft/vscode",
    "branch": "main"
  }
}

# 3. 查询代码库
{
  "tool": "query_repository", 
  "arguments": {
    "query": "VS Code 如何处理文件监视？",
    "repositories": [{"remote": "github", "repository": "microsoft/vscode", "branch": "main"}]
  }
}

高级基于会话的探索

// 从架构概述开始
const session = "exploration-session-1";

// 查询 1：高层次理解
{
  "tool": "query_repository",
  "arguments": {
    "query": "这个代码库的整体架构是什么？",
    "session_id": session,
    "repositories": [...]
  }
}

// 查询 2：深入挖掘（基于先前的上下文）
{
  "tool": "query_repository", 
  "arguments": {
    "query": "我们刚刚讨论的主要组件是如何相互作用的？",
    "session_id": session  // 同一会话以保持连续性
  }
}

// 查询 3：实现细节
{
  "tool": "query_repository",
  "arguments": {
    "query": "展示组件交互模式的具体实现",
    "session_id": session
  }
}

🔀 从 Python 版本迁移

TypeScript 版本保持与 Python 实现的完全兼容性，并增加了显著改进：

新特性

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

迁移步骤

# 旧的 Python 使用方式
python -m src.main

# 新的 TypeScript 使用方式  
npx greptile-mcp-server

# 相同的 MCP 工具和 API 兼容性
# 不需要更改 MCP 客户端配置

🚨 故障排除

测试您的设置

设置后始终测试您的配置：

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 进行详细诊断
• 查看 Greptile 文档 以解决 API 特定问题
• 访问 MCP 文档 以获得客户端集成帮助

❓ 常见问题

Q: 我需要在本地安装什么才能使用？

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

Q: 我可以使用任何 MCP 兼容客户端吗？

A: 可以！此服务器实现了标准的 Model Context Protocol，适用于 Claude Desktop、MCP CLI 工具和其他任何 MCP 兼容客户端。

Q: 如何索引私有仓库？

A: 确保您的 GitHub 令牌具有私有仓库的 repo 权限。令牌需要访问您要索引的仓库。

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

A:

• .env 文件非常适合本地开发——它们仅在文件存在的目录中起作用
• 环境变量是系统范围的，可以在任何地方使用，因此更适合全局使用与 npx

Q: 使用 Greptile 的费用是多少？

A: Greptile 的定价取决于您的使用情况。查看 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 未安装（安装 Node.js，其中包含 NPX）
• 您的 PATH 不包括 Node.js 二进制文件
• 命令中有拼写错误（应为 npx greptile-mcp-server 而不是 npx @greptile/mcp-server）

🏗️ 开发

本地开发

# 克隆并设置
git clone https://github.com/greptile/mcp-server.git
cd mcp-server
npm install

# 开发模式带热重载
npm run dev

# 生产构建
npm run build

# 运行测试
npm test

# 类型检查
npm run typecheck

# 代码检查和格式化
npm run lint
npm run format

项目结构

src/
├── cli.ts              # NPX CLI 接口
├── server.ts           # 核心 MCP 服务器实现  
├── index.ts            # 模块导出
├── clients/
│   └── greptile.ts     # Greptile API 客户端
├── types/
│   └── index.ts        # TypeScript 类型定义
└── utils/
    └── index.ts        # 工具函数

tests/
├── unit/               # 单元测试
└── integration/        # 集成测试

构建配置

• 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	Grept_ile 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 云部署

立即部署到 Smithery，无需配置