Skip to main content
Glama
deenesjakoruzh
sosacrazy126

greptile-mcp

by sosacrazy126
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Greptile MCP 服务器 [已完成]

快速运行命令备忘单

✅ 项目状态：所有任务已完成（11/11）

请参阅PROJECT_COMPLETION.md了解已完成工作的摘要，并参阅USER_GUIDE.md了解使用说明。

环境

设置和安装

运行命令

本地（Python）

python -m venv .venv && source .venv/bin/activate && pip install -e .

python -m src.main

Docker

docker build -t greptile-mcp .

docker run --rm --env-file .env -p 8050:8050 greptile-mcp

锻造工艺

npm install -g smithery

smithery deploy （参见 smithery.yaml）

使用.env.example填写.env并在运行之前设置您的GREPTILE_API_KEY和GITHUB_TOKEN 。

有关完整的先决条件、高级代理使用、集成和故障排除：请参阅docs/README.md中的完整文档和AGENT_USAGE.md中的代理详细信息。

MCP（模型上下文协议）服务器实现与 Greptile API 集成，为 AI 代理提供代码搜索和查询功能。

铁匠徽章

特征

该服务器提供了四个基本的 Greptile 工具，使 AI 代理能够与代码库进行交互：

  1. index_repository ：索引存储库以进行代码搜索和查询。

    • 处理存储库以使其可搜索

    • 当存储库更改时更新现有索引

    • 配置通知首选项

  2. query_repository ：查询存储库以获取带有代码参考的答案。

    • 询问有关代码库的自然语言问题

    • 获取引用特定代码位置的详细答案

    • 支持使用会话 ID 的对话历史记录

  3. search_repository ：在存储库中搜索相关文件，但不生成完整答案。

    • 查找与特定概念或功能相关的文件

    • 获取按相关性排序的上下文匹配

    • 当仅需要文件位置时，比完整查询更快

  4. get_repository_info ：获取有关索引存储库的信息。

    • 检查索引状态和进度

    • 验证哪些存储库可供查询

    • 获取有关索引存储库的元数据

Related MCP server: mcp-meilisearch

Smithery部署

Greptile MCP 服务器支持通过 Smithery 进行部署。项目根目录中包含一个smithery.yaml配置文件。

Smithery 配置

Smithery 配置在smithery.yaml中定义，并支持以下选项：

build:
  dockerfile: Dockerfile

startCommand:
  type: stdio
  configSchema:
    type: object
    required:
      - greptileApiKey
      - githubToken
    properties:
      greptileApiKey:
        type: string
        description: "API key for accessing the Greptile API"
      githubToken:
        type: string
        description: "GitHub Personal Access Token for repository access"
      baseUrl:
        type: string
        description: "Base URL for Greptile API"
        default: "https://api.greptile.com/v2"
      host:
        type: string
        description: "Host to bind to when using SSE transport"
        default: "0.0.0.0"
      port:
        type: string
        description: "Port to listen on when using SSE transport"
        default: "8050"

与 Smithery 一起使用

要使用 Smithery 进行部署：

  1. 安装 Smithery： npm install -g smithery

  2. 部署服务器： smithery deploy

  3. 使用所需的 API 密钥配置您的 Smithery 客户端

其他文档

有关AI代理的详细使用说明，请参阅代理使用指南。

先决条件

  • Python 3.12+

  • Greptile API 密钥（来自https://app.greptile.com/settings/api ）

  • **GitHub 或 GitLab 个人访问令牌 (PAT)，**具有您要索引的存储库的repo (或等效读取) 权限

  • Docker （推荐部署）

所需的 Python 包

  • fastmcp ——MCP 服务器实现

  • httpx - 异步 HTTP 客户端

  • python-dotenv - 环境变量管理

  • uvicorn - 用于 SSE 传输的 ASGI 服务器

安装

使用 pip（用于开发或本地测试）

  1. 克隆此存储库：

    git clone https://github.com/sosacrazy126/greptile-mcp.git
cd greptile-mcp

  2. 创建虚拟环境（推荐）：

    python -m venv .venv
source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`

  3. 安装依赖项：

    pip install -e .

  4. 根据.env.example创建.env文件：

    cp .env.example .env

  5. 在.env文件中配置环境变量：

    GREPTILE_API_KEY=your_api_key_here
GITHUB_TOKEN=your_github_token_here

使用 Docker（推荐部署）

  1. 克隆存储库：

    git clone https://github.com/sosacrazy126/greptile-mcp.git
cd greptile-mcp

  2. 根据.env.example创建一个.env文件并配置您的环境变量。

  3. 构建 Docker 镜像：

    docker build -t greptile-mcp .

运行服务器

使用 pip

SSE 传输（默认）

确保在.env文件中设置了TRANSPORT=sse和PORT=8050 （或您选择的端口）。

python -m src.main

服务器将监听http://<HOST>:<PORT>/sse 。

标准传输

在.env文件中设置TRANSPORT=stdio 。使用 stdio 时，MCP 客户端通常会启动 MCP 服务器进程。

# Usually invoked by an MCP client, not directly
TRANSPORT=stdio python -m src.main

使用 Docker

SSE 传输（默认）

# Mounts the .env file for configuration and maps the port
docker run --rm --env-file .env -p 8050:8050 greptile-mcp

服务器将监听http://localhost:8050/sse （如果不是 localhost，则为主机 IP）。

标准传输

配置您的 MCP 客户端以使用TRANSPORT=stdio运行 Docker 容器。

# Example of running with stdio transport
docker run --rm -i --env-file .env -e TRANSPORT=stdio greptile-mcp

与 MCP 客户端集成

SSE配置示例

将其添加到您的 MCP 客户端的配置中（例如mcp_config.json ）：

{
  "mcpServers": {
    "greptile": {
      "transport": "sse",
      "url": "http://localhost:8050/sse"
    }
  }
}

Python 与 Stdio 配置示例

确保在运行命令的环境中设置了TRANSPORT=stdio ：

{
  "mcpServers": {
    "greptile": {
      "transport": "stdio",
      "command": "/path/to/your/greptile-mcp/.venv/bin/python",
      "args": ["-m", "src.main"],
      "env": {
        "TRANSPORT": "stdio",
        "GREPTILE_API_KEY": "YOUR-GREPTILE-API-KEY",
        "GITHUB_TOKEN": "YOUR-GITHUB-TOKEN",
        "GREPTILE_BASE_URL": "https://api.greptile.com/v2"
      }
    }
  }
}

Docker 与 Stdio 配置示例

{
  "mcpServers": {
    "greptile": {
      "transport": "stdio",
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "TRANSPORT=stdio",
        "-e", "GREPTILE_API_KEY",
        "-e", "GITHUB_TOKEN",
        "-e", "GREPTILE_BASE_URL",
        "greptile-mcp"
      ],
      "env": {
        "GREPTILE_API_KEY": "YOUR-GREPTILE-API-KEY",
        "GITHUB_TOKEN": "YOUR-GITHUB-TOKEN",
        "GREPTILE_BASE_URL": "https://api.greptile.com/v2"
      }
    }
  }
}

详细使用指南

代码库分析工作流程

  1. 您想要使用index_repository分析的索引存储库

  2. 使用get_repository_info验证索引状态以确保处理完成

  3. 使用query_repository使用自然语言查询存储库

  4. 使用search_repository查找与功能或概念相关的特定文件

对话上下文的会话管理

当通过任何客户端（包括 Smithery）与 Greptile MCP 服务器交互时，适当的会话管理对于维护对话上下文至关重要：

  1. 在对话开始时生成唯一的会话 ID

  2. 对所有相关的后续查询重复使用相同的会话 ID

  3. 开始新对话时创建新的会话 ID

会话 ID 管理示例：

# Generate a unique session ID
import uuid
session_id = str(uuid.uuid4())

# Initial query
initial_response = query_repository(
    query="How is authentication implemented?",
    repositories=[{"remote": "github", "repository": "owner/repo", "branch": "main"}],
    session_id=session_id  # Include the session ID
)

# Follow-up query using the SAME session ID
followup_response = query_repository(
    query="Can you provide more details about the JWT verification?",
    repositories=[{"remote": "github", "repository": "owner/repo", "branch": "main"}],
    session_id=session_id  # Reuse the same session ID
)

Smithery 集成重要提示：通过 Smithery 连接的代理必须生成并维护自己的会话 ID。Greptile MCP 服务器不会自动生成会话 ID。会话 ID 应包含在代理的对话状态中。

最佳实践

  • 索引性能：较小的存储库索引速度更快。对于大型的单一存储库，请考虑索引特定的分支或标签。

  • 查询优化：查询时务必具体。包含相关的技术术语，以获得更好的结果。

  • 存储库选择：查询多个存储库时，按相关性顺序列出它们以获得最佳结果。

  • 会话管理：使用会话 ID 来跟踪后续问题，以维护查询的上下文。

API 参考

1. 索引库

对存储库进行索引，以便在将来的查询中可以搜索它。

参数：

  • remote （字符串）：存储库主机，可以是“github”或“gitlab”

  • repository （字符串）：所有者/repo 格式的存储库（例如“greptileai/greptile”）

  • branch （字符串）：要索引的分支（例如“main”）

  • reload （布尔值，可选）：是否强制重新处理先前索引的存储库

  • notify （布尔值，可选）：索引完成时是否发送电子邮件通知

例子：

// Tool Call: index_repository
{
  "remote": "github",
  "repository": "greptileai/greptile",
  "branch": "main",
  "reload": false,
  "notify": false
}

回复：

{
  "message": "Indexing Job Submitted for: greptileai/greptile",
  "statusEndpoint": "https://api.greptile.com/v2/repositories/github:main:greptileai%2Fgreptile"
}

2. 查询存储库

使用自然语言查询存储库以获取带有代码参考的答案。

参数：

  • query （字符串）：关于代码库的自然语言查询

  • repositories （数组）：要查询的存储库列表，每个存储库的格式如下：

    {
  "remote": "github",
  "repository": "owner/repo",
  "branch": "main"
}

  • session_id （字符串，可选）：用于继续对话的会话 ID

  • stream （布尔值，可选）：是否流式传输响应

  • genius （布尔值，可选）：是否使用增强查询功能

例子：

// Tool Call: query_repository
{
  "query": "How is authentication handled in this codebase?",
  "repositories": [
    {
      "remote": "github",
      "repository": "greptileai/greptile",
      "branch": "main"
    }
  ],
  "session_id": null,
  "stream": false,
  "genius": true
}

回复：

{
  "message": "Authentication in this codebase is handled using JWT tokens...",
  "sources": [
    {
      "repository": "greptileai/greptile",
      "remote": "github",
      "branch": "main",
      "filepath": "/src/auth/jwt.js",
      "linestart": 14,
      "lineend": 35,
      "summary": "JWT token validation middleware"
    }
  ]
}

3. 搜索存储库

搜索存储库以查找相关文件但不生成完整答案。

参数：

  • query （字符串）：关于代码库的搜索查询

  • repositories （数组）：要搜索的存储库列表

  • session_id （字符串，可选）：用于继续对话的会话 ID

  • genius （布尔值，可选）：是否使用增强搜索功能

例子：

// Tool Call: search_repository
{
  "query": "Find files related to authentication middleware",
  "repositories": [
    {
      "remote": "github",
      "repository": "greptileai/greptile", 
      "branch": "main"
    }
  ],
  "session_id": null,
  "genius": true
}

回复：

{
  "sources": [
    {
      "repository": "greptileai/greptile",
      "remote": "github",
      "branch": "main",
      "filepath": "/src/auth/middleware.js",
      "linestart": 1,
      "lineend": 45,
      "summary": "Authentication middleware implementation"
    },
    {
      "repository": "greptileai/greptile",
      "remote": "github",
      "branch": "main",
      "filepath": "/src/auth/jwt.js",
      "linestart": 1,
      "lineend": 78,
      "summary": "JWT token handling functions"
    }
  ]
}

4. 获取存储库信息

获取有关已索引的特定存储库的信息。

参数：

  • remote （字符串）：存储库主机，可以是“github”或“gitlab”

  • repository （字符串）：所有者/repo 格式的存储库

  • branch （字符串）：被索引的分支

例子：

// Tool Call: get_repository_info
{
  "remote": "github",
  "repository": "greptileai/greptile",
  "branch": "main"
}

回复：

{
  "repository": "greptileai/greptile",
  "remote": "github",
  "branch": "main",
  "private": false,
  "status": "COMPLETED",
  "filesProcessed": 234,
  "numFiles": 234,
  "sha": "a1b2c3d4e5f6..."
}

集成示例

1. 通过 Anthropic API 与 Claude.ai 集成

from anthropic import Anthropic
import json
import requests

# Set up Anthropic client
anthropic = Anthropic(api_key="your_anthropic_key")

# Function to call Greptile MCP
def query_code(question, repositories):
    response = requests.post(
        "http://localhost:8050/tools/greptile/query_repository",
        json={
            "query": question,
            "repositories": repositories,
            "genius": True
        }
    )
    return json.loads(response.text)

# Ask Claude with enhanced code context
def ask_claude_with_code_context(question, repositories):
    # Get code context from Greptile
    code_context = query_code(question, repositories)
    
    # Format the context for Claude
    formatted_context = f"Code Analysis Result:\n{code_context['message']}\n\nRelevant Files:\n"
    for source in code_context.get('sources', []):
        formatted_context += f"- {source['filepath']} (lines {source['linestart']}-{source['lineend']})\n"
    
    # Send to Claude with context
    message = anthropic.messages.create(
        model="claude-3-opus-20240229",
        max_tokens=1000,
        messages=[
            {"role": "user", "content": f"Based on this code context:\n\n{formatted_context}\n\nQuestion: {question}"}
        ]
    )
    
    return message.content

# Example usage
answer = ask_claude_with_code_context(
    "How does the authentication system work?",
    [{"remote": "github", "repository": "greptileai/greptile", "branch": "main"}]
)
print(answer)

2. 与基于 LLM 的聊天机器人集成

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
import httpx
import json

app = FastAPI()

# Greptile MCP endpoint
GREPTILE_MCP_URL = "http://localhost:8050/tools/greptile"

@app.post("/chat")
async def chat_endpoint(request: Request):
    data = await request.json()
    user_message = data.get("message", "")
    
    # Check if this is a code-related question
    if "code" in user_message or "repository" in user_message or "function" in user_message:
        # Query the repository through Greptile MCP
        async with httpx.AsyncClient() as client:
            response = await client.post(
                f"{GREPTILE_MCP_URL}/query_repository",
                json={
                    "query": user_message,
                    "repositories": [
                        {"remote": "github", "repository": "your-org/your-repo", "branch": "main"}
                    ],
                    "genius": True
                }
            )
            
            greptile_result = response.json()
            
            # Process the result and return to the user
            answer = greptile_result.get("message", "")
            sources = greptile_result.get("sources", [])
            
            return JSONResponse({
                "message": answer,
                "code_references": sources
            })
    
    # For non-code questions, use your regular LLM
    return JSONResponse({
        "message": "This appears to be a general question. I'll handle it normally."
    })

# Run with: uvicorn app:app --reload

3. 命令行代码查询工具

#!/usr/bin/env python3
import argparse
import json
import requests
import sys

def main():
    parser = argparse.ArgumentParser(description="Query code repositories using natural language")
    parser.add_argument("query", help="The natural language query about the code")
    parser.add_argument("--repo", "-r", required=True, help="Repository in format github:owner/repo:branch")
    parser.add_argument("--genius", "-g", action="store_true", help="Use enhanced query capabilities")
    args = parser.parse_args()
    
    # Parse the repository string
    try:
        remote, repo_path = args.repo.split(":", 1)
        if ":" in repo_path:
            repo, branch = repo_path.split(":", 1)
        else:
            repo = repo_path
            branch = "main"
    except ValueError:
        print("Error: Repository must be in format 'github:owner/repo:branch' or 'github:owner/repo'")
        sys.exit(1)
        
    # Prepare the request
    payload = {
        "query": args.query,
        "repositories": [
            {
                "remote": remote,
                "repository": repo,
                "branch": branch
            }
        ],
        "genius": args.genius
    }
    
    # Make the request
    try:
        response = requests.post(
            "http://localhost:8050/tools/greptile/query_repository",
            json=payload
        )
        response.raise_for_status()
    except requests.exceptions.RequestException as e:
        print(f"Error: {e}")
        sys.exit(1)
    
    # Process the response
    result = response.json()
    
    # Display the answer
    print("\n=== ANSWER ===\n")
    print(result.get("message", "No answer found"))
    
    # Display the sources
    sources = result.get("sources", [])
    if sources:
        print("\n=== CODE REFERENCES ===\n")
        for i, source in enumerate(sources, 1):
            print(f"{i}. {source['filepath']} (lines {source.get('linestart', '?')}-{source.get('lineend', '?')})")
            print(f"   Repository: {source['repository']} ({source['branch']})")
            if 'summary' in source:
                print(f"   Summary: {source['summary']}")
            print()

if __name__ == "__main__":
    main()

故障排除

常见问题

1. 身份验证失败

症状：您收到401 Unauthorized或未Repository not found with configured credentials错误。

解决方案：

  • 验证您的 Greptile API 密钥是否有效并在.env文件中正确设置

  • 检查你的 GitHub/GitLab 令牌是否已过期（它们通常会在一段设定的时间后过期）

  • 确保您的 GitHub/GitLab 令牌具有访问存储库的repo范围

  • 直接使用 GitHub API 测试您的 GitHub 令牌以验证其是否正常工作

测试 GitHub 令牌：

curl -H "Authorization: token YOUR_GITHUB_TOKEN" https://api.github.com/user

2. 未找到存储库

症状：API 返回 404 错误或“未找到存储库”消息。

解决方案：

  • 验证存储库是否存在并且可以使用 GitHub/GitLab 令牌进行访问

  • 仔细检查存储库格式（应该是owner/repo ）

  • 对于私有存储库，请确保您的令牌具有适当的访问权限

  • 验证分支名称是否正确

3.连接问题

症状：无法连接到 MCP 服务器。

解决方案：

  • 检查服务器是否正在运行（ ps aux | grep src.main ）

  • 验证端口未被其他应用程序使用

  • 检查网络设置和防火墙配置

  • 通过更改.env文件中的PORT值尝试不同的端口

4. Docker问题

症状：Docker 容器无法启动或运行正常。

解决方案：

  • 检查 Docker 日志： docker logs <container_id>

  • 验证.env文件是否已正确挂载

  • 确保docker run命令中的端口映射正确

  • 检查 Docker 网络配置是否允许所需的连接

日志和调试

要启用更详细的日志记录，请设置以下环境变量：

# Add to your .env file
DEBUG=true
LOG_LEVEL=debug

要对特定的 MCP 交互进行故障排除，请检查 MCP 服务器日志：

# Run with enhanced logging
LOG_LEVEL=debug python -m src.main

高级配置

环境变量

多变的

描述

默认

TRANSPORT

传输方法（ sse或stdio ）

sse

HOST

绑定到 SSE 传输的主机

0.0.0.0

PORT

SSE运输港口

8050

GREPTILE_API_KEY

您的 Greptile API 密钥

（必需的）

GITHUB_TOKEN

GitHub/GitLab 个人访问令牌

（必需的）

GREPTILE_BASE_URL

Greptile API 基本 URL

https://api.greptile.com/v2

DEBUG

启用调试模式

false

LOG_LEVEL

日志级别

info

自定义 API 端点

如果您需要使用自定义 Greptile API 端点（例如，用于企业安装），请修改GREPTILE_BASE_URL环境变量：

GREPTILE_BASE_URL=https://greptile.your-company.com/api/v2

性能调优

对于生产部署，请考虑以下性能优化：

  1. 工作者配置：当使用 Uvicorn 的 SSE 传输时，配置适当的工作者数量：

    # For CPU-bound applications: workers = 1-2 × CPU cores
uvicorn src.main:app --workers 4

  2. 超时设置：调整大型存储库的超时：

    # Add to .env
GREPTILE_TIMEOUT=120.0  # Default is 60.0 seconds

  3. 内存优化：对于大型部署，请考虑容器资源限制：

    docker run --rm --env-file .env -p 8050:8050 --memory="1g" --cpus="1.0" greptile-mcp

贡献

欢迎贡献代码！欢迎提交 Pull 请求。

  1. 分叉存储库

  2. 创建你的功能分支（ git checkout -b feature/amazing-feature ）

  3. 提交您的更改（ git commit -m 'Add some amazing feature' ）

  4. 推送到分支（ git push origin feature/amazing-feature ）

  5. 打开拉取请求

开发设置

为了开发，请安装其他依赖项：

pip install -e ".[dev]"

运行测试：

pytest

执照

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

由（ https://github.com/sosacrazy126 ）构建

Available Tools

5 tools
get_repository_infoC

Get information about an indexed repository including status and metadata

ParametersJSON Schema
NameRequiredDescriptionDefault
remoteYesRepository host
repositoryYesRepository in owner/repo format
branchYesBranch that was indexed

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It states the tool retrieves information, implying it's read-only, but doesn't disclose behavioral traits like authentication requirements, rate limits, error conditions, or what 'indexed' means operationally. The description is minimal and lacks context about the tool's behavior beyond its basic function.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core purpose. Every word earns its place, with no redundant or vague language. It's appropriately sized for a simple retrieval tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and no output schema, the description is incomplete for a tool with 3 required parameters. It doesn't explain what 'indexed' entails, what 'status and metadata' includes, or the response format. For a retrieval tool with structured inputs, more context is needed to guide effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with clear descriptions for all parameters (e.g., 'Repository host', 'Repository in owner/repo format', 'Branch that was indexed'). The description adds no additional semantic meaning beyond the schema, such as explaining format constraints or relationships between parameters. Baseline 3 is appropriate as the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'information about an indexed repository', specifying it includes 'status and metadata'. This distinguishes it from sibling tools like 'index_repository' (which creates) and 'query_repository' (which searches content), but doesn't explicitly differentiate from 'greptile_env_check' or 'greptile_help' in terms of scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., that the repository must already be indexed), exclusions, or compare to siblings like 'query_repository' for different types of information needs. Usage is implied but not explicitly stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

greptile_env_checkB

Check environment variable configuration and setup status

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states what the tool does but doesn't describe how it behaves—for example, whether it's a read-only check, what output format to expect, if it has side effects, or any error conditions. This leaves significant gaps in understanding the tool's operational characteristics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's function without any wasted words. It's appropriately sized for a simple tool and front-loaded with the core purpose, making it easy for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is adequate but has clear gaps. It explains what the tool does but lacks details on behavioral traits, usage context, or output expectations, which are important even for simple tools to ensure correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters, and the input schema has 100% description coverage (though empty). The description doesn't need to add parameter information, so it appropriately focuses on the tool's purpose. A baseline score of 4 is applied since no parameters exist, and the description doesn't attempt to explain nonexistent parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose as checking environment variable configuration and setup status, which is a specific verb+resource combination. However, it doesn't differentiate itself from sibling tools like 'get_repository_info' or 'greptile_help', which might also provide status information, so it doesn't reach the highest score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention any prerequisites, exclusions, or specific contexts for usage, leaving the agent to infer when this check is appropriate compared to other tools on the server.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

greptile_helpA

Get comprehensive help and usage examples for all Greptile MCP tools

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It states the tool provides 'comprehensive help and usage examples,' which suggests it's a read-only, informational resource without side effects. However, it lacks details on behavioral traits like response format, potential rate limits, or error handling, which would be useful given the absence of annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that clearly conveys the tool's function without any wasted words. It's front-loaded with the core purpose ('Get comprehensive help and usage examples') and specifies the scope ('for all Greptile MCP tools'), making it easy to understand at a glance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is adequate but could be more complete. It covers the basic purpose but doesn't address potential context like what 'comprehensive help' includes, whether it's interactive, or how it integrates with sibling tools. For a help tool in this environment, more detail on output or usage scenarios would enhance completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters, and schema description coverage is 100%, so there's no need for parameter details in the description. The baseline for 0 parameters is 4, as the description appropriately focuses on the tool's purpose without unnecessary parameter explanations.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get comprehensive help and usage examples for all Greptile MCP tools.' It specifies the verb ('Get') and resource ('help and usage examples'), and the scope ('for all Greptile MCP tools') is well-defined. However, it doesn't explicitly differentiate from sibling tools like 'greptile_env_check' which might also provide system information.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context—when users need help or examples for Greptile tools—but doesn't provide explicit guidance on when to use this tool versus alternatives. There's no mention of prerequisites, timing, or comparisons to sibling tools like 'get_repository_info' or 'query_repository', leaving usage somewhat open to interpretation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

index_repositoryC

Index a repository to make it searchable for future queries

ParametersJSON Schema
NameRequiredDescriptionDefault
remoteYesRepository host (github or gitlab)
repositoryYesRepository in owner/repo format
branchYesBranch to index
reloadNoForce reprocessing of previously indexed repository
notifyNoSend email notification when indexing completes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden but offers limited behavioral insight. It mentions the outcome ('make it searchable') but omits critical details: whether indexing is idempotent, time-consuming, or requires specific permissions; what 'searchable' entails (e.g., content types indexed); or side effects like notifications. The 'reload' and 'notify' parameters hint at reprocessing and notifications, but the description doesn't explain these behaviors.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core action ('index a repository') and purpose ('make it searchable'). It avoids redundancy and waste, though it could be slightly more informative without losing conciseness. Structure is clear but minimal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, no output schema, and a mutation tool (indexing implies write operation), the description is incomplete. It lacks details on behavioral traits (e.g., idempotency, performance), output format, error handling, or dependencies. For a 5-parameter tool that modifies state, more context is needed to guide safe and effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents all 5 parameters (remote, repository, branch, reload, notify). The description adds no parameter-specific information beyond implying indexing scope, but doesn't detail how parameters interact (e.g., 'reload' vs. initial indexing). Baseline is 3 since the schema handles parameter documentation adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('index') and resource ('repository') with a specific purpose ('to make it searchable for future queries'). It distinguishes from siblings like 'get_repository_info' (read-only info) and 'query_repository' (search after indexing), though it doesn't explicitly name alternatives. The purpose is specific but could be more precise about what 'indexing' entails.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides minimal guidance, stating the tool makes repositories searchable for future queries, which implies it should be used before querying. However, it lacks explicit when-to-use rules (e.g., prerequisites, timing), when-not-to-use scenarios (e.g., if already indexed), or named alternatives like 'reload' parameter for reprocessing. No sibling tools are referenced for comparison.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query_repositoryC

Query repositories using natural language to get detailed answers with code references

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesNatural language query about the codebase
repositoriesNoList of repositories to query
session_idNoSession ID for conversation continuity (auto-generated if not provided)
streamNoEnable streaming response
geniusNoUse enhanced query capabilities
timeoutNoRequest timeout in milliseconds
previous_messagesNoPrevious conversation messages for context

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'natural language querying' and 'detailed answers with code references,' but fails to describe critical behaviors such as authentication requirements, rate limits, error handling, or what constitutes a 'detailed answer.' For a complex tool with 7 parameters, this is a significant gap in transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that clearly states the tool's core functionality without unnecessary details. It's front-loaded with the main purpose and avoids redundancy, making it easy for an agent to parse quickly. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (7 parameters, no annotations, no output schema), the description is insufficient. It lacks information on behavioral traits, output format, error conditions, and how it differs from siblings. For a query tool that likely returns structured data, the absence of output details and usage context makes it incomplete for effective agent operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, so each parameter is documented in the schema itself. The description adds no additional semantic context beyond implying natural language input for the 'query' parameter. This meets the baseline of 3, as the schema handles the heavy lifting, but the description doesn't enhance understanding of parameter usage or interactions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Query repositories using natural language to get detailed answers with code references.' It specifies the action (query), resource (repositories), and outcome (detailed answers with code references). However, it doesn't explicitly differentiate from sibling tools like 'get_repository_info' or 'index_repository', which prevents a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'get_repository_info' for metadata or 'index_repository' for preparation, nor does it specify scenarios where this tool is preferred. This lack of comparative context leaves the agent without clear usage direction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updates
    • First observedget_repository_info
    • First observedgreptile_env_check
    • First observedgreptile_help
    • First observedindex_repository
    • First observedquery_repository
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 5 tools

Disambiguation5/5

Each tool has a clearly distinct purpose with no overlap. get_repository_info retrieves metadata, greptile_env_check verifies setup, greptile_help provides documentation, index_repository prepares data, and query_repository performs searches. An agent can easily differentiate them.

Naming Consistency3/5

The naming is mixed: three tools use a verb_noun pattern (get_repository_info, index_repository, query_repository), while two use a noun_verb pattern (greptile_env_check, greptile_help). This inconsistency is noticeable but still readable, as all names are descriptive and in snake_case.

Tool Count5/5

With 5 tools, this server is well-scoped for its purpose of repository indexing and querying. Each tool earns its place by covering essential functions like setup, indexing, querying, and help, without being overly sparse or bloated.

Completeness4/5

The tool set covers the core workflow for a repository search service: environment setup, indexing, querying, and metadata retrieval, with a help tool for guidance. A minor gap is the lack of tools for managing indexed repositories (e.g., delete or update), but agents can work around this.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers