🚀 Greptile MCP服务器-TypeScript版

](https://badge.fury.io/js/greptile-mcp-server) ![TypeScript](http://www.typescriptlang.org/) ![MCP Compatible](https://modelcontextprotocol.io)

一种现代的、支持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密钥：

访问油脂设置
生成新的API密钥
将密钥复制到您的环境中

GitHub令牌：

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

🔧 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文件和环境变量有什么区别？

.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_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云部署

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

![Deploy to Smithery](https://smithery.ai/server/@sosacrazy126/greptile-mcp)

# 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
请求验证：输入验证和净化
速率限制：具有指数回退的内置重试逻辑
错误处理：无令牌暴露的全面错误处理

🤝 贡献

我们欢迎捐款！请查看我们的贡献指南了解详情。

开发流程

复刻仓库
创建要素分支(git checkout -b feature/amazing-feature)
通过测试进行更改
运行测试套件(npm test)
确保代码质量(npm run lint)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

📄 许可证

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

🙏 致谢

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

📞 支持

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

______________________________________________________________________

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

Greptile MCP

快速接入

详细介绍