Crystal MCP Server

A Model Context Protocol (MCP) server for the Crystal programming language. This server provides LLMs with context-aware tools to analyze, inspect, and work with Crystal codebases.

Project Goal

The goal of this project is to bridge the gap between AI assistants and the Crystal development environment. By exposing the Crystal compiler's capabilities and ecosystem tools through the MCP standard, we enable AI agents to:

Understand code context and symbol resolution.
Navigate implementations and macros.
Check build status and lint code.
Explore dependencies and the standard library.
Concurrency: Asynchronous request processing ensures the editor remains responsive even during long-running operations.

Features (Tools)

The server exposes the following tools:

Compiler Tools

get_context: Retrieve context information for a specific file, line, and column.
get_implementations: Find implementations of a method or type at a cursor position.
expand_macro: Expand macros at a specific location to debug code generation.
check_build: Verify if a file (and its dependencies) compiles correctly.

Ecosystem Tools

inspect_dependencies: List and inspect current project dependencies (shards).
read_stdlib_signature: Search and retrieve signatures from the Crystal standard library.

Quality Tools

lint_code: Run static analysis (Ameba) on a specific file to find code smells and issues.

Installation

Manual Install

Clone the repository:

git clone https://gitlab.com/renich/crystal-mcp.git
cd crystal-mcp

Build the project:
```
make build
```
Install to ~/.local/bin:
```
make install
```

Configuration

Add the server to your MCP client configuration (e.g., ~/.opencode/config.json):

{
  "mcpServers": {
    "crystal-mcp": {
      "command": "/home/YOUR_USER/.local/bin/crystal-mcp",
      "args": [],
      "env": {}
    }
  }
}

Development

This project uses a GNUmakefile for common development tasks.

Build: make build (Release binary)
Test: make test (Run specs)
Lint: make lint (Run Ameba)
Docs: make docs (Generate API documentation in docs/technical/api)

Viewing Documentation

After generating the documentation with make docs, you can view it by opening docs/technical/api/index.html in your web browser.

Dependencies

Crystal >= 1.19.1
Ameba (installed via shards install)

License

GPLv3