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 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 에서 에이전트 세부 정보를 참조하세요.

Greptile API와 통합되어 AI 에이전트에 코드 검색 및 쿼리 기능을 제공하는 MCP(Model Context Protocol) 서버 구현입니다.

대장간 배지

특징

이 서버는 AI 에이전트가 코드베이스와 상호 작용할 수 있도록 하는 4가지 필수 Greptile 도구를 제공합니다.

  1. index_repository : 코드 검색 및 쿼리를 위해 저장소를 인덱싱합니다.

    • 저장소를 검색 가능하게 처리

    • 저장소가 변경되면 기존 인덱스를 업데이트합니다.

    • 알림 환경 설정 구성

  2. query_repository : 코드 참조로 답변을 얻기 위해 저장소를 쿼리합니다.

    • 코드베이스에 대한 자연어 질문을 하세요

    • 특정 코드 위치를 참조하는 자세한 답변을 받으세요

    • 세션 ID를 사용한 대화 기록 지원

  3. search_repository : 전체 답변을 생성하지 않고 관련 파일에 대한 저장소를 검색합니다.

    • 특정 개념이나 기능과 관련된 파일 찾기

    • 관련성 순으로 정렬된 문맥별 일치 항목 가져오기

    • 파일 위치만 필요한 경우 전체 쿼리보다 빠릅니다.

  4. get_repository_info : 인덱스된 저장소에 대한 정보를 가져옵니다.

    • 인덱싱 상태 및 진행 상황 확인

    • 쿼리에 사용할 수 있는 저장소를 확인하세요.

    • 인덱싱된 저장소에 대한 메타데이터 가져오기

Related MCP server: mcp-meilisearch

대장간 배치

Greptile MCP 서버는 Smithery를 통한 배포를 지원합니다. smithery.yaml 구성 파일은 프로젝트 루트에 포함되어 있습니다.

대장간 구성

Smithery 구성은 smithery.yaml 에 정의되어 있으며 다음 옵션을 지원합니다.

지엑스피1

Smithery와 함께 사용

Smithery를 사용하여 배포하려면:

  1. Smithery 설치: npm install -g smithery

  2. 서버 배포: smithery deploy

  3. 필요한 API 키로 Smithery 클라이언트를 구성하세요.

추가 문서

AI 에이전트에 대한 자세한 사용 지침은 에이전트 사용 가이드를 참조하세요.

필수 조건

  • 파이썬 3.12+

  • Greptile API 키 ( https://app.greptile.com/settings/api 에서)

  • 인덱싱하려는 저장소에 대한 repo (또는 동등한 읽기) 권한이 있는 GitHub 또는 GitLab 개인 액세스 토큰(PAT)

  • 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 에서 수신합니다.

Stdio Transport

.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)에서 수신합니다.

Stdio Transport

TRANSPORT=stdio 로 Docker 컨테이너를 실행하도록 MCP 클라이언트를 구성합니다.

# 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"
    }
  }
}

Stdio 구성을 사용한 Python 예제

명령이 실행되는 환경에서 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"
      }
    }
  }
}

Stdio 구성을 사용한 Docker 예제

{
  "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

기여하다

기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.

  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 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

( 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