Crystal MCP Server

A high-performance Model Context Protocol (MCP) server for the Crystal programming language. This server provides Large Language Models (LLMs) and autonomous AI coding agents with deep, context-aware tools to analyze, build, test, format, and inspect Crystal codebases in real time.

---

Project Goal

The goal of this project is to bridge the gap between AI assistants and the Crystal development ecosystem. By exposing the Crystal compiler's capabilities, testing framework, and ecosystem tooling through the standard JSON-RPC 2.0 stdio transport, we enable AI agents to:

• Understand Context: Navigate method implementations, symbol definitions, and macro expansions.
• Enforce Quality: Verify build status without binary generation, format code in-flight, and execute static analysis via Ameba.
• Drive TDD Workflows: Run targeted specs and test suites with line-level filtering (path:line) and error trace captures.
• Inspect Type Topologies: Extract structured JSON type hierarchies and struct memory layouts.
• Explore Dependencies: Inspect workspace shard manifests (shard.yml/shard.lock) and query the Crystal standard library.
• High Concurrency: Asynchronous fiber-based request processing with thread-safe output guarantees.

---

Synergy with Crystalino LSP

For an optimal Crystal development experience in both human IDEs and autonomous AI agent environments, crystal-mcp pairs symbiotically with Crystalino:

Capability Domain	Crystalino (LSP Server)	Crystal MCP (MCP Server)
Protocol	Language Server Protocol (LSP 3.17)	Model Context Protocol (MCP 2024-11-05)
Primary Consumer	Editors & IDEs (Neovim, Crush, Helix, VSCode)	AI Agents & LLMs (Antigravity, Claude, OpenCode)
Code Completion	Real-time interactive completion & signature help	Context-directed symbol & stdio queries
Navigation & Renaming	Go-to-definition, find-references, lexical rename	AST implementation lookup & macro expansion
Test Execution	N/A (Editor runner)	Targeted spec execution (run_spec with path:line)
Build & Type Checking	Background compilation & diagnostic publishing	Zero-codegen build validation (check_build)
Linting & Formatting	Document formatting provider	Ameba static analysis (lint_code) & format_code
Type Topologies	Document symbols & hierarchical folding ranges	Structured JSON hierarchy & struct layouts (get_hierarchy)

---

Tool Catalog

The server exposes 10 MCP tools:

Core & Diagnostic Tools

• ping: Internal connectivity and latency health check returning "pong".

Compiler Proxy Tools

• check_build: Verify if a source file and its dependencies compile cleanly without generating binary output (--no-codegen).
• get_context: Retrieve context information (type, method scope) for a specific cursor location (file, line, col).
• get_implementations: Find all implementation locations of a method or type at a cursor position.
• expand_macro: Expand macros at a target location to inspect code generation.
• get_hierarchy: Inspect the type hierarchy, sub-types, and struct memory layout in structured JSON with optional regex filtering (-e).

Testing Engine Tools

• run_spec: Execute crystal spec with support for targeted files/lines (path:line), example description filters (-e), and fail-fast abort mode (--fail-fast).

Quality & Formatting Tools

• lint_code: Run static code analysis (Ameba) on a specific file to identify code smells and bugs.
• format_code: Format Crystal source files or verify formatting compliance (--check).

Ecosystem & Workspace Tools

• inspect_dependencies: List and inspect project dependencies across runtime and development scopes with optional project_path directory scoping.
• read_stdlib_signature: Search and retrieve method/type signatures and docstrings from the Crystal standard library.

---

Documentation

The project documentation is organized using a modular specification architecture:

• Master Functional Specification: Requirements and tool contracts.
  • Compiler Sub-Spec | Testing Sub-Spec | Quality Sub-Spec | Ecosystem Sub-Spec
• Master Technical Specification: Architectural blueprint and domain adapters.
  • Server Protocol | Compiler Adapter | Testing Adapter | Quality Adapter | Ecosystem Adapter | Command Runner
• Architecture Decision Records: Immutable engineering records (ADR-001, ADR-002).
• Project Roadmap: Phased delivery milestones (Phase 1, Phase 2).
• Operational Problematics: Persona friction scenarios and resolutions.
• Manual Testing Guide: Step-by-step interactive verification runbook.
• Release Instructions: Steps for versioning, tagging, and deployment.

---

Installation & Setup

Building & Installing from Source

1. Clone the repository:

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

2. Build the release binary:

   make build

3. Install to ~/.local/bin:

   make install

Verify the installation:

crystal-mcp --version

Client Configuration

Add crystal-mcp to your client configuration:

Google Antigravity (AGY) (~/.gemini/config/mcp_config.json)

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

OpenCode (config.json)

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

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "crystal-mcp": {
      "command": "/home/YOUR_USER/.local/bin/crystal-mcp"
    }
  }
}

VS Code/Cursor (Cline/Roo Code)

{
  "mcpServers": {
    "crystal-mcp": {
      "command": "/home/YOUR_USER/.local/bin/crystal-mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}

---

Development & Verification

This project uses a GNUmakefile for common development tasks:

• Build Release: make build
• Build Development (Dynamic): make dev
• Run Unit Specs & Linter: make test
• Run Linter Only: make lint
• End-to-End Integration Suite: ./scripts/integration_test.bash
• Generate API Documentation: make docs

---

Supporting the Project

If you find crystal-mcp valuable for your Crystal development, CI/CD pipelines, or autonomous agent workflows, consider supporting its maintenance:

You can also sponsor Rénich Bon Ćirić directly on Liberapay (renich).

---

License & Authors

• License: GNU General Public License v3.0 (GPLv3)
• Author: Rénich Bon Ćirić <renich@woralelandia.com> | woralelandia.com