Sherpa

1 forks

9 stars

Free

What is Sherpa

Sherpa is a versatile tool developed by CartographAI designed to be your friendly guide through any codebase. By leveraging the Model Context Protocol (MCP), Sherpa enables secure connections to various data sources, allowing users to interact with codebases in a highly intuitive manner. Whether you have a local project or a remote Git repository, Sherpa helps you understand and navigate the code by chatting with it directly. This open-source tool uses advanced language models to provide intelligent code analysis, supporting a variety of models like Anthropic's Claude Sonnet, Google's Gemini, and OpenAI's GPT models.

How to Use Sherpa

Using Sherpa is straightforward and user-friendly. Here's a step-by-step guide:

Start Sherpa: Open your terminal and run the command:
```
npx @cartographai/sherpa <path/to/your/project>
```
or
```
npx @cartographai/sherpa <git_url>
```
Replace <path/to/your/project> with the path to your local project or <git_url> with the URL of a Git repository. This command launches a local server and opens the Sherpa web app in your browser.
Configure API Keys: Once the web app is open, go to the settings panel to input your API keys for the language models you wish to use. This ensures Sherpa can access the right tools to assist you.
Interact with the Codebase: Begin chatting with Sherpa by asking questions about the codebase. You can inquire about specific files or the overall structure, and Sherpa will use its built-in tools to provide comprehensive answers.

Key Features of Sherpa

Intelligent Code Analysis: Sherpa smartly determines which files to read to ensure your queries are answered accurately. It examines the project structure and content to provide precise insights.
Multiple LLM Support: With support for multiple language models, Sherpa offers flexibility in how you interact with your codebase.
Privacy and Security: Sherpa operates fully locally, ensuring no data is sent to external servers. You bring your own API keys, maintaining complete privacy.
Interactive Chat Interface: The user-friendly web interface, built with SvelteKit, makes it easy to chat with Sherpa, view tools in use, and see the context provided to the language model.
Persistent Chat History: Your conversations are stored locally, allowing you to resume previous sessions effortlessly.
Secure Filesystem Access: Sherpa uses a secure MCP filesystem server to restrict file access to authorized directories only, preventing unauthorized data exposure.
Git Integration: Whether you're working with local files or remote repositories, Sherpa's Git support makes it adaptable to various development environments.
Open Source Accessibility: Being open source, Sherpa allows customization and extension for specific use cases, making it a flexible tool for developers.

Sherpa combines advanced technology with ease of use, making it a powerful companion for anyone looking to explore and understand complex codebases efficiently.

Sherpa, your friendly codebase guide

npx @cartographai/sherpa Chat with any codebase with a single command. sherpa Asking Sherpa about itself

Features

Intelligent Code Analysis: Sherpa intelligently determines which files to read to answer your questions about a codebase. It uses a combination of tools to understand the project structure and content.
Multiple LLM Support: Sherpa supports various language models, including Anthropic's Claude Sonnet 3.5, Google's Gemini 2.0, and OpenAI's GPT-4o and o3-mini models.
Fully Local and Private: Bring your own API key, no data is sent to our servers
Interactive Chat Interface: A user-friendly web UI (built with SvelteKit) allows you to interact with Sherpa, view the tools being used, and see the context provided to the language model.
Chat History: Your conversation history is stored locally in your browser's local storage, so you can easily pick up where you left off.
Secure Filesystem Access: Sherpa uses a secure Model Context Protocol filesystem server that restricts access to a specified directory, preventing unauthorized file access.
Git Support: You can use Sherpa with local directories or directly with remote Git repositories.
Open Source: Sherpa is open source, allowing you to modify and extend it for your specific use cases.

Usage

Run Sherpa: Execute the following command in your terminal, replacing with the actual path to your project or with a Git repository URL:

npx @cartographai/sherpa <path/to/your/project>

npx @cartographai/sherpa <git_url>

This command will:

Clone the repository to a cache directory if a git url is provided.
Start a local server (Hono) that handles API requests.
Open the Sherpa web app in your default browser (localhost:3031).

Configure API Keys: In the web app's settings panel (click the "Config" button), enter your API keys for the language models you want to use (Anthropic, Gemini, or OpenAI).
Start Chatting: Ask Sherpa questions about the codebase. You can refer to specific files or directories, and Sherpa will use its tools to find the relevant information.

How it Works

Sherpa reads (or clones) a codebase:

Launches a web app and a sandbox server to access your code
Use the chat interface to ask questions about the codebase
Sherpa intelligently uses tools to read and explore the codebase to find the context to answer your question (or you can ask it to read all the files immediately) To know more, ask Sherpa to explain itself

npx @cartographai/sherpa

Development

To run Sherpa in development mode:

Setup Instructions

Clone the repository:

git clone 
cd sherpa

Install dependencies:

bun install

Build the project:

bun run build

Running the Application

Backend Server

Start the backend server with either a local project path or git URL

bun run dev:server <path/to/your/project>

bun run dev:server <git_url>

The backend server will be available at ` Note that the backend bundles the web app so if you are only developing the backend, you don't need to run the web application.

Web Application (Optional)

In a separate terminal

bun run dev:web

This will start the web app with hot reloading. Open ` in your browser. This requires the backend server to be running.

Acknowledgements

The video I look at open source differently now by Hrishi was the inspiration to create this as an open source tool.
Anthropic's Model Context Protocol filesystem implementation
Simon Willson's files-to-prompt repo for XML template implementation

How to Use

To use the sherpa, follow these steps:

Visit https://github.com/CartographAI/sherpa
Follow the setup instructions to create an account (if required)
Connect the MCP server to your Claude Desktop application
Start using sherpa capabilities within your Claude conversations

Additional Information

Created

January 21, 2025

Company

CartographAI

Related MCP Servers

Start building your own MCP Server

Interested in creating your own MCP Server? Check out the official documentation and resources.

Learn More