context-sherpa

Context Sherpa is an MCP server that helps AI coding agents enforce project-specific linting rules and dynamic code guidance. It uses ast-grep-based rules to validate code, and it can adjust those rules based on natural language feedback. The server exposes tools your agent can invoke to initialize its linting project, scan code snippets, or scan file paths against the central ruleset. To use it, run the context-sherpa binary with your project root (as shown in the MCP configuration), and then integrate the agent with the provided tools to perform scans and manage rules.

The primary tools are:

• initialize_ast_grep: Sets up an ast-grep project by creating sgconfig.yml and a rules folder if they are not already present.
• scan_code: Validates a given code snippet against the project’s sgconfig.yml rules, returning any violations found as a structured list.
• scan_path: Scans files, directories, or glob patterns to detect rule violations across multiple files in the project.

You can guide your agent to request scans, add or remove rules via natural language feedback, and rely on the results to iterate on coding standards within your repository. The workflow supports cross-platform usage and is designed to be self-contained within a single executable that you run locally.

Prerequisites:

• A Go toolchain installed (go1.x)
• Optional: ast-grep installed via your preferred method (see installation steps below)

1. Install Context Sherpa (Go binary)

• Run the recommended Go install command:

go install github.com/hackafterdark/context-sherpa/cmd/context-sherpa@latest

2. Install ast-grep (choose one method):

• Homebrew (macOS/Linux):

brew install ast-grep

• Cargo (Rust):

cargo install ast-grep --locked

• npm (Node.js):

npm i @ast-grep/cli -g

• Other methods: see the ast-grep quick-start guide, or pip/other package managers as suitable for your OS.

3. Verify installations

• Context Sherpa version:

context-sherpa --version

• ast-grep version:

ast-grep --version

4. (Optional) If you need a custom ast-grep path, you can run Context Sherpa with an explicit path to ast-grep:

context-sherpa --astGrepPath="/custom/path/to/ast-grep" --projectRoot="/path/to/your/project"

5. Prepare your project and run

• Start the MCP-enabled server by launching the context-sherpa binary with your project root as configured above. You can then configure your MCP client to point at this server using the provided mcpServers configuration.

Tips and notes:

• Ensure ast-grep is accessible in your PATH or specify a custom path via the --astGrepPath option.
• Place context-sherpa.exe (Windows) and ast-grep.exe in your project directory for best path resolution on Windows.
• If you change project structure, you may need to re-run initialize_ast_grep to recreate sgconfig.yml and the rules directory.
• The MCP configuration example always uses the --projectRoot flag to ensure files like sgconfig.yml and rules exist in your actual project directory, not the binary's directory.
• For verbose debugging, enable additional logging in the tool or run with any supported verbose flags (if available in your build).
• If you want to customize rule management by natural language, you can extend rules in the rules directory and restart or refresh the server to pick up changes.