🌐 Greptile Context Bridge - TypeScript Edition

This server functions as a cutting-edge MCP (Model Context Protocol) gateway, utilizing the powerful Greptile platform for advanced code indexing, search, and comprehension. It is engineered using the official MCP SDK, ensuring robust compatibility with leading AI assistants such as Claude Desktop and Continue.

🌟 Core Capabilities

💡 Intelligent Code Access

• Semantic Querying: Leverage natural language to probe codebase complexities.
• Architectural Mapping: Extract deep understanding of software designs and implementation specifics.
• Multi-Repo Analysis: Synthesize knowledge across disparate codebases concurrently.
• Contextual Memory: Maintain conversational state across successive interactions.

🛠️ Technical Foundation

• SDK Driven: Built atop the TypeScript MCP Software Development Kit for strict protocol adherence.
• Event Streaming: Utilizes Server-Sent Events (SSE) for low-latency response delivery.
• Type Integrity: Full TypeScript integration guarantees compile-time safety.
• Modular Design: Extensible framework supporting future tooling integration.

▶️ Immediate Deployment

Prerequisite Checklist

1. Runtime: Node.js version 18 or newer.
2. Greptile Credential: An active API key from Greptile Console.
3. GitHub Access: A Personal Access Token (PAT) with repo scope access to target codebases.

Instant Launch Command

Execute directly via npx without prior local installation: bash

Launch interactively, prompting for required secrets

npx greptile-mcp-server

Launch with secrets injected via command line

npx greptile-mcp-server --api-key=G_KEY --github-token=GH_TOKEN

Initiate the guided setup sequence

npx greptile-mcp-server setup-wizard

Credential Management Strategies

Method A: Dedicated Configuration File (.env)

Recommended for local execution environments: env GREPTILE_API_KEY="your_greptile_key" GITHUB_TOKEN="your_github_pat"

Optional endpoint override

GREPTILE_ENDPOINT="https://api.greptile.com/v2"

Method B: Operating System Environment Variables

**Linux/macOS (Bash/Zsh): bash export GREPTILE_API_KEY="your_key" export GITHUB_TOKEN="your_token"

**Windows (PowerShell): powershell $env:GREPTILE_API_KEY="your_key" $env:GITHUB_TOKEN="your_token"

🧩 Client Integration Blueprints

This bridge adheres strictly to the MCP specification, allowing easy hooking into various consuming applications.

For Claude Desktop Users

Configure your client settings file (claude_desktop_config.json) as follows:

{ "mcpServers": { "greptile-bridge": { "command": "npx", "args": ["greptile-mcp-server"], "env": { "GREPTILE_API_KEY": "runtime_key", "GITHUB_TOKEN": "runtime_token" } } } }

For Continue IDE Extension Users

Update your configuration (continue.json) within the contextProviders section:

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

🔧 Exposed Toolset

1. greptile_diagnostic_report

Retrieves detailed usage instructions and help documentation.

{ "name": "greptile_diagnostic_report" }

2. repository_ingest

Initiates the indexing process for a specified code repository.

{ "name": "repository_ingest", "arguments": { "source_system": "github", "repo_slug": "microsoft/vscode", "ref": "main", "force_refresh": true } }

3. code_semantic_query

Executes a natural language query against indexed source code.

{ "name": "code_semantic_query", "arguments": { "probe_text": "Detail the mechanism for handling application state serialization within this project structure.", "targets": [ { "source": "github", "slug": "microsoft/vscode", "ref": "main" } ], "output_format": "streamed", "session_handle": "optional-contextual-id" } }

4. get_ingestion_status

Fetches the current indexing status and metadata for a repository.

{ "name": "get_ingestion_status", "arguments": { "source_system": "github", "repo_slug": "microsoft/vscode", "ref": "main" } }

🔬 Advanced Workflow: Contextual Deep Dive

This sequence demonstrates maintaining state (session_handle) for progressive understanding.

javascript const ongoing_analysis_id = "dev-drill-001";

// Step 1: Initial high-level architectural probing { "tool": "code_semantic_query", "arguments": { "probe_text": "Outline the primary service boundaries in this application.", "session_handle": ongoing_analysis_id, "targets": [...] } }

// Step 2: Follow-up question leveraging prior findings { "tool": "code_semantic_query", "arguments": { "probe_text": "Elaborate on the data flow across the boundaries identified in the previous step.", "session_handle": ongoing_analysis_id } }

// Step 3: Requesting concrete code samples for the derived flow { "tool": "code_semantic_query", "arguments": { "probe_text": "Provide the specific functions implementing the cross-boundary communication protocols.", "session_handle": ongoing_analysis_id } }

🔄 Migration Note (From Python Implementation)

This Node.js/TypeScript iteration supersedes older Python versions, offering significant technical advancement while preserving functional parity:

Improvement Area	TypeScript/Node.js Advantage
Distribution	Immediate execution via npx (no Python environment setup)
Performance	Superior I/O handling via V8 engine optimizations
Reliability	Full static typing guarantees fewer runtime errors
Ecosystem	Access to modern NPM tooling (TS, ESLint, etc.)

🚨 Diagnostic Procedures

To verify system health: bash npx greptile-mcp-server system-check

Common Fault Rectification

Issue: Authentication Secrets Undetected

Symptom: Server logs indicate missing GREPTILE_API_KEY or GITHUB_TOKEN. Remedy: Ensure variables are exported in the current shell session, or restart the terminal after making permanent OS environment changes. Alternatively, pass credentials inline during invocation.

Issue: GitHub Token Authorization Failure

Symptom: Inability to fetch data from private or protected repositories. Remedy: Verify the PAT possesses the necessary repo scope. Consider generating a fresh, fine-grained token for enhanced security posture.

Issue: Connection Timeout / Unresponsive Client

Symptom: MCP client (e.g., Claude) reports inability to establish communication. Remedy: Confirm the server is running and accessible. Review the client's specific MCP server configuration block for syntax errors or incorrect command definitions.

❓ FAQ Summary

Q: Is local software installation mandatory? A: Negative. npx handles all necessary runtime downloads dynamically.

Q: Can this process data from enterprise GitHub instances? A: Yes, by setting the GREPTILE_BASE_URL to point to your self-hosted GitHub Enterprise endpoint, provided your PAT is valid for that instance.

Q: How is data privacy managed? A: Code context is transmitted via secure transport (HTTPS) to the Greptile backend, governed strictly by their published data governance policies. This server component itself does not persistently store sensitive keys beyond the active session (unless configured via .env for convenience).

🏗️ Internal Structure

src/ ├── cli_entrypoint.ts # Handles command-line arguments (npx execution) ├── mcp_core.ts # Core server logic implementing the MCP interface ├── greptile_adapter.ts # Abstraction layer for Greptile API interaction ├── schema/ # Defines tool argument validation schemas └── config/ # Configuration loading (Env, file, CLI)

⚖️ Licensing

MIT License. See the accompanying LICENSE.md file for complete legal details.

🙏 Gratitude

This project extends thanks to the contributors of the Model Context Protocol specification and the underlying Greptile platform.