Cicada MCP Server for Elixir AST Code Intelligence

Overview

Cicada is an MCP (Model Context Protocol) server focused on Elixir AST (Abstract Syntax Tree) code intelligence. It parses Elixir projects into AST-aware indexes and exposes structured context that language models and developer tools can consume. Instead of sending raw source text, tools can request precise AST fragments, symbol metadata, or repository-scoped search results so downstream models get smaller, more relevant, and semantically rich context.

This approach is useful when building code assistants, automated code reviewers, or advanced search tools that need to operate with an understanding of Elixir semantics (modules, functions, specs, macros). By serving AST fragments over a lightweight protocol, Cicada helps reduce prompt noise, improve relevance of LLM completions, and enable deterministic analysis workflows over codebases.

Features

• Parses Elixir source into AST and stores navigable metadata
• Exposes context via a Model Context Protocol (MCP)-style HTTP/JSON API
• Per-file and symbol-scoped queries (module, function, spec, macro)
• Text- and AST-aware search across repositories
• Incremental indexing support for fast updates on file change
• Streaming/context windowing to feed models only the needed AST nodes
• Extensible: designed to integrate with LLMs, language servers, or CI tooling

Installation / Configuration

Clone and run the server locally. The examples assume you have Elixir and Erlang installed.

Clone and fetch dependencies:

git clone https://github.com/wende/cicada.git
cd cicada
mix deps.get
mix compile

Run the server (development):

mix run --no-halt

A minimal configuration example (config/config.exs):

import Config

config :cicada,
  port: 8080,
  repo_root: "/path/to/your/elixir/project",
  persistence_path: "priv/cicada/index.db",
  index_interval_ms: 2000,
  log_level: :info

Configuration keys (typical):

Adjust repo_root and persistence_path for your environment before starting the server in production.

Available Resources

Cicada provides the following common resources (HTTP/JSON endpoints are illustrative; consult the repo for exact routes):

• GET /health — basic readiness check
• POST /mcp/context — request contextual AST fragments for a symbol or file range
• POST /search — perform AST-aware search with filters (module, arity, macro, spec)
• WebSocket /stream — subscribe to incremental index updates or streaming context windows

Example minimal curl request (requesting context for a module):

curl -X POST http://localhost:8080/mcp/context \
  -H "Content-Type: application/json" \
  -d '{
    "mcp_version": "1.0",
    "query": { "type": "module", "name": "MyApp.Foo" },
    "options": { "include_ast": true, "max_nodes": 500 }
  }'

Typical response shape:

{
  "contexts": [
    {
      "file": "lib/my_app/foo.ex",
      "range": { "start_line": 1, "end_line": 120 },
      "ast": { /* compact AST fragment */ },
      "symbols": [ { "name": "bar", "arity": 2, "kind": "