Skip to main content
Glama
deenesjakoruzh
sosacrazy126

greptile-mcp

by sosacrazy126
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

šŸš€ Greptile MCP Server - TypeScript Edition

npm version TypeScript MCP Compatible

A modern, TypeScript-powered MCP (Model Context Protocol) server that provides AI-powered code search and querying capabilities through the Greptile API. Built with the official MCP SDK and designed for seamless integration with AI tools like Claude Desktop, Continue, and other MCP-compatible clients.

āœØ Features

šŸ”„ Zero-Installation Experience

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

šŸ§  AI-Powered Code Understanding

  • Natural Language Queries: Ask questions about codebases in plain English

  • Deep Code Analysis: Understand architecture, patterns, and implementation details

  • Cross-Repository Insights: Compare patterns and approaches across multiple codebases

  • Session Continuity: Build understanding progressively through conversation

āš” Modern Architecture

  • Official MCP SDK: Built with TypeScript MCP SDK for full protocol compliance

  • Streaming Support: Real-time responses with Server-Sent Events

  • Type Safety: Full TypeScript integration with comprehensive type definitions

  • Plugin Architecture: Extensible design for custom tools and integrations

šŸ› ļø Developer Experience

  • NPX Ready: Install and run with a single command

  • Auto-Configuration: Intelligent configuration detection and validation

  • Interactive Setup: Guided setup wizard for first-time users

  • Comprehensive Help: Built-in documentation and usage examples

Related MCP server: mcp-meilisearch

šŸš€ Quick Start

Prerequisites

Instant Start

# 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

Environment Setup

Option 1: .env File (Recommended for local development)

Create a .env file in your project root:

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

Option 2: System Environment Variables

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 Command Prompt:

# 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 Key and Token Setup

Greptile API Key:

  1. Visit Greptile Settings

  2. Generate a new API key

  3. Copy the key to your environment

GitHub Token:

  1. Visit GitHub Settings > Personal Access Tokens

  2. Create a "Fine-grained personal access token" for better security

  3. Grant repo permissions for repositories you want to index

  4. Copy the token to your environment

šŸ”§ MCP Client Integration

Claude Desktop

Add to your 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 Extension

Add to your Continue configuration:

{
  "contextProviders": [
    {
      "name": "greptile-mcp",
      "type": "mcp",
      "serverName": "greptile",
      "command": ["npx", "greptile-mcp-server"]
    }
  ]
}

Other MCP Clients

The server uses standard MCP protocol and works with any MCP-compatible client:

# Generic MCP client connection
your-mcp-client connect --command "npx greptile-mcp-server"

šŸ› ļø Available Tools

1. greptile_help

Get comprehensive documentation and usage examples.

{
  "name": "greptile_help"
}

2. index_repository

Index a repository to make it searchable.

{
  "name": "index_repository",
  "arguments": {
    "remote": "github",
    "repository": "microsoft/vscode",
    "branch": "main",
    "reload": true
  }
}

3. query_repository

Query repositories with natural language.

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

Get information about indexed repositories.

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

šŸ“– Usage Examples

Basic Workflow

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

Advanced Session-Based Exploration

// 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
  }
}

šŸ”€ Migration from Python Version

The TypeScript version maintains full compatibility with the Python implementation while adding significant improvements:

What's New

  • āœ… Official MCP SDK: Standards-compliant implementation

  • āœ… NPX Distribution: Zero-installation experience

  • āœ… Better Performance: V8 engine advantages for I/O operations

  • āœ… Type Safety: Full TypeScript integration

  • āœ… Modern Tooling: ESLint, Prettier, comprehensive testing

  • āœ… Enhanced CLI: Interactive setup and better UX

Migration Steps

# 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

šŸšØ Troubleshooting

Testing Your Setup

Always test your configuration after setup:

npx greptile-mcp-server test

Common Issues

āŒ "Environment variables missing"

Problem: Server can't find your API keys Solutions:

  • Restart your terminal after setting permanent environment variables

  • Verify environment variables are set:

    # Linux/macOS
echo $GREPTILE_API_KEY
echo $GITHUB_TOKEN

# Windows PowerShell
echo $env:GREPTILE_API_KEY
echo $env:GITHUB_TOKEN

  • Try using inline credentials:

    GREPTILE_API_KEY="your_key" GITHUB_TOKEN="your_token" npx greptile-mcp-server

āŒ "GitHub token validation failed"

Problem: GitHub token is invalid or has insufficient permissions Solutions:

  • Ensure your token has repo permissions

  • Generate a new token at GitHub Settings

  • For better security, use "Fine-grained personal access tokens"

  • Check token hasn't expired

āŒ "Greptile API authentication failed"

Problem: Greptile API key is invalid or expired Solutions:

  • Get a new API key from Greptile Settings

  • Verify the key is correctly copied (no extra spaces)

  • Check if your API key has expired

āŒ "Cannot find module" or import errors

Problem: NPX cache issues or incomplete installation Solutions:

  • Clear NPX cache: npx clear-npx-cache

  • Force fresh install: npx greptile-mcp-server@latest

  • Check Node.js version (requires Node 18+)

āŒ MCP client connection issues

Problem: Claude Desktop or other MCP client can't connect Solutions:

  • Verify MCP server configuration syntax

  • Check Claude Desktop logs for detailed error messages

  • Ensure environment variables are accessible to the MCP client

  • Try running the server manually first to verify it works

Getting Help

  • Run npx greptile-mcp-server init for interactive setup

  • Run npx greptile-mcp-server test for detailed diagnostics

  • Check the Greptile Documentation for API-specific issues

  • Visit MCP Documentation for client integration help

ā“ Frequently Asked Questions

Q: Do I need to install anything locally to use this?

A: No! The server runs via NPX with zero installation required. Just run npx greptile-mcp-server and it will download and run automatically.

Q: Can I use this with any MCP-compatible client?

A: Yes! This server implements the standard Model Context Protocol and works with Claude Desktop, MCP CLI tools, and any other MCP-compatible client.

Q: How do I index private repositories?

A: Ensure your GitHub token has repo permissions for private repositories. The token needs access to read the repositories you want to index.

Q: What's the difference between .env files and environment variables?

A:

  • .env files are great for local development - they only work in the directory where the file exists

  • Environment variables are system-wide and work everywhere, making them better for global usage with npx

Q: How much does it cost to use Greptile?

A: Greptile pricing depends on your usage. Check Greptile's pricing page for current rates. This MCP server itself is free and open-source.

Q: Can I use this with multiple repositories?

A: Yes! You can index multiple repositories and query across all of them. Use the index_repository tool for each repository you want to add.

Q: How long does it take to index a repository?

A: Indexing time varies by repository size. Small repos (< 1000 files) typically take 1-2 minutes, while larger repos may take 10-15 minutes. You can check status with the get_repository_info tool.

Q: Is my code data secure?

A: Your code is processed by Greptile's API according to their security and privacy policies. Check Greptile's security documentation for details about data handling and retention.

Q: Can I run this on Windows?

A: Yes! The server works on Windows, macOS, and Linux. Use the platform-specific environment variable setup instructions above.

Q: Why do I get "command not found" errors?

A: This usually means:

  • NPX is not installed (install Node.js which includes NPX)

  • Your PATH doesn't include Node.js binaries

  • There's a typo in the command (it's npx greptile-mcp-server not npx @greptile/mcp-server)

šŸ—ļø Development

Local Development

# 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

Project Structure

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

Build Configuration

  • TypeScript: ES2022 target with strict mode

  • Build Tool: tsup for dual ESM/CJS output

  • Testing: Mocha + Chai with TypeScript support

  • Code Quality: ESLint + Prettier with TypeScript rules

šŸ”§ Configuration Options

CLI Arguments

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

Environment Variables

Variable

Description

Default

GREPTILE_API_KEY

Greptile API key

Required

GITHUB_TOKEN

GitHub personal access token

Required

GREPTILE_BASE_URL

API base URL

https://api.greptile.com/v2

Configuration File (Optional)

Create 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
  }
};

šŸš€ Deployment

Smithery Cloud Deployment

Deploy instantly to Smithery with zero configuration:

Deploy to Smithery

# Install Smithery CLI
npm install -g smithery

# Deploy from repository
smithery deploy

# Or deploy with custom configuration
smithery deploy --config smithery.yaml

# Monitor deployment
smithery status
smithery logs

Docker Deployment

# 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

Environment Variables for Deployment

# 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

Cloud Platforms

  • Smithery: One-click deployment with smithery deploy

  • Railway: Connect GitHub repo, set environment variables

  • Render: Use npm start as start command

  • Heroku: Standard Node.js deployment

  • DigitalOcean App Platform: Docker or buildpack deployment

šŸš¦ Performance & Benchmarks

Startup Performance

  • Cold Start: < 2 seconds

  • Memory Usage: ~50MB base footprint

  • Concurrent Requests: Handles 100+ concurrent MCP tool calls

API Performance

  • Query Response: Typically 1-3 seconds

  • Streaming: Real-time chunk delivery

  • Repository Indexing: Varies by repository size (usually 30s-5min)

Compared to Python Version

  • 40% Faster Startup - V8 vs Python runtime

  • 60% Smaller Container - Node.js vs Python base images

  • 30% Better Memory Efficiency - V8 garbage collection

  • Native Streaming - Better SSE performance

šŸ›”ļø Security & Best Practices

Token Security

  • Environment Variables: Store tokens in environment, not code

  • Minimal Permissions: Use GitHub tokens with only required repo permissions

  • Token Rotation: Regularly rotate API keys and tokens

  • Local Storage: Never commit tokens to version control

Network Security

  • HTTPS Only: All API communications use HTTPS

  • Request Validation: Input validation and sanitization

  • Rate Limiting: Built-in retry logic with exponential backoff

  • Error Handling: Comprehensive error handling without token exposure

šŸ¤ Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/amazing-feature)

  3. Make your changes with tests

  4. Run the test suite (npm test)

  5. Ensure code quality (npm run lint)

  6. Commit your changes (git commit -m 'Add amazing feature')

  7. Push to the branch (git push origin feature/amazing-feature)

  8. Open a Pull Request

šŸ“„ License

This project is licensed under the MIT License - see the LICENSE file for details.

šŸ™ Acknowledgments

  • Anthropic for the Model Context Protocol specification

  • Greptile for the powerful code analysis API

  • TypeScript Community for excellent tooling and ecosystem

  • MCP Community for protocol development and feedback

šŸ“ž Support

Built with ā¤ļø by the Greptile team ā€¢ Powered by TypeScript and the Model Context Protocol

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