Clojure MCP

Um servidor MCP que fornece um conjunto completo de ferramentas para desenvolvimento em Clojure, exigindo um servidor nREPL em execução.

GitHub

782

Experimente este MCPPatrocinado

Documentação

Clojure MCP: Desenvolvimento Orientado por REPL com Assistência de IA

ClojureMCP é um servidor MCP para Clojure!

Sumário

O que é ClojureMCP?
Como eu uso?
Principais Recursos
Ajuda e Recursos da Comunidade
📋 Instalação
Assistentes CLI
Claude Desktop
- Gerenciamento do Resumo do Projeto
- Resumir e Retomar Sessão de Chat
Chaves de API LLM
🧰 Ferramentas Disponíveis
🔧 Personalização
Opções de CLI
⚙️ Configuração
📝 Licença

O que é ClojureMCP?

ClojureMCP é um servidor MCP que conecta um cliente LLM (como Claude Code ou Claude Desktop) ao seu projeto Clojure. Ele fornece ferramentas de REPL e ferramentas de edição cientes de Clojure, projetadas para lidar com os parênteses e a formatação do Clojure de forma confiável.

Dependendo do seu cliente LLM, o ClojureMCP pode:

Fornecer um conjunto completo de ferramentas de assistência de código cientes de Clojure para aplicativos de chat de desktop, como o Claude Desktop, ou
Preencher lacunas específicas do Clojure para assistentes CLI que já possuem ótimas ferramentas de edição de arquivos e shell (como integração REPL + edições cientes de Clojure).

Como eu uso?

Instale o ClojureMCP (clojure -Ttools install-latest ...).
Registre-o como um servidor MCP no seu cliente LLM.

Se você estiver usando um assistente CLI, geralmente preferirá manter as ferramentas nativas de edição de arquivos do CLI e usar o ClojureMCP principalmente para integração REPL (e como fallback de edição).

Se você estiver usando um aplicativo de chat de desktop, normalmente usará o conjunto completo de ferramentas do ClojureMCP.

Principais Recursos

Conexão REPL Clojure - que repara delimitadores antes da avaliação
Edição ciente de Clojure - usando parinfer, cljfmt e clj-rewrite
Conjunto otimizado de ferramentas para Desenvolvimento Clojure

Ajuda e Recursos da Comunidade

O Canal #ai-assisted-coding no Slack Clojurians é muito ativo e é onde passo muito tempo.
A Wiki do ClojureMCP tem informações sobre várias integrações e sandboxing.

📋 Instalação

Pré-requisitos

Clojure
Java (JDK 17 ou posterior)
Opcional, mas ALTAMENTE recomendado: ripgrep para melhor desempenho de grep e glob_files

Instalar ClojureMCP

Instale o ClojureMCP usando o instalador de ferramentas Clojure:

clojure -Ttools install-latest :lib io.github.bhauman/clojure-mcp :as mcp

Isso instala o ClojureMCP globalmente, tornando clojure -Tmcp start disponível em qualquer diretório.

Assistentes CLI

Assistentes de codificação CLI (Claude Code, Codex, Gemini CLI) já possuem ótimas ferramentas de edição inline-diff e shell.

Comece com clojure-mcp-light - ele fornece integração REPL e reparo de delimitadores, preservando a exibição inline-diff nativa do seu CLI. Isso funciona bem para a maioria dos desenvolvimentos Clojure.

Considere adicionar ClojureMCP com o perfil :cli-assist se você quiser:

Fallback de edição estrutural - clojure-mcp-light pode reparar parênteses após uma edição ser bem-sucedida, mas não pode ajudar quando a string de correspondência de localizar/substituir não corresponde ao código (acontece <5% das vezes, mas pode atrapalhar o LLM). A edição estrutural visa formas por tipo e nome, evitando esse problema.
Ferramenta REPL de primeira classe - LLMs tendem a usar ferramentas MCP mais prontamente do que comandos CLI, o que pode levar a um uso mais frequente do REPL.

Adicionar ClojureMCP ao clojure-mcp-light pode proporcionar uma experiência aprimorada de desenvolvimento Clojure para assistentes CLI.

Adicionando ClojureMCP com `:cli-assist`

# Claude Code
claude mcp add clojure-mcp -- clojure -Tmcp start :config-profile :cli-assist

# OpenAI Codex
codex mcp add clojure-mcp -- clojure -Tmcp start :config-profile :cli-assist

# Google Gemini CLI
gemini mcp add clojure-mcp clojure -Tmcp start :config-profile :cli-assist

Prefere as ferramentas de edição/leitura do clojure-mcp? Se você deixar o agente conduzir e se importar menos com o diff inline nativo, troque :cli-assist por :cli-assist-full. Isso torna read_file, clojure_edit, clojure_edit_replace_sexp e paren_repair de primeira classe (em vez de fallbacks) e instrui o assistente a fazer todas as edições de arquivos Clojure por meio delas — o que contorna o conflito de "arquivo modificado desde a leitura" do editor host sem qualquer configuração de permissão. (Usuários avançados que desejam uma garantia rígida podem adicionalmente adicionar regras permissions.deny do Claude Code, como "Edit(/**/*.clj)", para que o editor nativo não possa tocar em arquivos Clojure.)

Verificar a instalação iniciando o servidor

A partir do diretório do seu projeto:

clojure -Tmcp start :config-profile :cli-assist

Você deve ver uma saída JSON-RPC como esta:

{"jsonrpc":"2.0","method":"notifications/tools/list_changed"}
{"jsonrpc":"2.0","method":"notifications/tools/list_changed"}
{"jsonrpc":"2.0","method":"notifications/resources/list_changed"}
{"jsonrpc":"2.0","method":"notifications/prompts/list_changed"}

Claude Desktop

Aplicativos de chat de desktop (como o Claude Desktop) iniciam servidores MCP fora do diretório do seu projeto e não fornecem ferramentas de codificação integradas. Nesse ambiente, você normalmente usará o conjunto completo de ferramentas do ClojureMCP e o conectará a um nREPL em execução no seu projeto.

O ClojureMCP foi inicialmente desenvolvido para transformar o Claude Desktop em um assistente de codificação semelhante ao Claude Code, com ferramentas projetadas para funcionar efetivamente com a linguagem de programação Clojure.

Iniciar um nREPL no seu projeto

Inicie um servidor nREPL a partir do diretório do seu projeto. Se você ainda não tem um alias ou configuração nREPL, consulte doc/nrepl.md.

Configurar o Claude Desktop

Escolha o executável de shell que provavelmente captará sua configuração de ambiente:

Se você estiver usando Bash, encontre o caminho explícito do executável bash:

$ which bash
/opt/homebrew/bin/bash

Se você estiver usando Z Shell, encontre o caminho explícito do executável zsh:

$ which zsh
/bin/zsh

Agora vamos usar este caminho de shell explícito no parâmetro command na configuração do Claude Desktop, como visto abaixo.

Crie ou edite ~/Library/Application\ Support/Claude/claude_desktop_config.json:

{
    "mcpServers": {
        "clojure-mcp": {
            "command": "/opt/homebrew/bin/bash",
            "args": [
                "-c",
                "clojure -Tmcp start :not-cwd true :port 7888"
            ]
        }
    }
}

A flag :not-cwd true diz ao ClojureMCP para não usar o diretório de trabalho atual (que para o Claude Desktop não é o seu projeto). Em vez disso, ele inspeciona a conexão nREPL para descobrir o diretório de trabalho do projeto.

Isso permite um padrão de trabalho simples: iniciar um REPL na porta 7888 e, em seguida, iniciar o Claude Desktop e permitir que ele detecte onde você está trabalhando.

Quando quiser mudar para um projeto diferente, você pararia o REPL atual em execução na porta 7888 e iniciaria um servidor nREPL no projeto em que deseja trabalhar, na porta 7888.

Testar a configuração

Inicie o nREPL no seu projeto alvo:
```
cd /path/to/your/project
clojure -M:nrepl
```
Procure por: nREPL server started on port 7888...
Reinicie o Claude Desktop (necessário após alterações de configuração)
Verifique a Conexão: No Claude Desktop, clique no botão + na área de chat. Você deve ver "Add from clojure-mcp" no menu. É importante notar que pode levar alguns momentos para que isso apareça.
Se houve um erro, consulte o Guia de Solução de Problemas. Se conectou, vá para a seção Iniciando uma nova conversa no Claude Desktop.

IMPORTANTE: Desative os recursos do Claude Desktop

Execução de Código e criação de arquivos: off

A execução de código e a criação de arquivos fornecem ferramentas que competem com o ClojureMCP; é melhor desativá-las.

Vá para configurações > Capacidades > Execução de Código e criação de arquivos e desative.

Você também pode querer desativar Artifacts.

Outros Clientes além do Claude Desktop

Consulte a Wiki para informações sobre como configurar outros clientes MCP.

Iniciando uma nova conversa no Claude Desktop

Depois que tudo estiver configurado, sugiro iniciar um novo chat no Claude.

A primeira coisa que você vai querer fazer é inicializar o contexto sobre o projeto Clojure na conversa anexada ao nREPL.

No Claude Desktop, clique nas ferramentas + e opcionalmente adicione

recurso PROJECT_SUMMARY.md - (peça ao LLM para criar isso) veja abaixo
recurso Clojure Project Info - que inspeciona o projeto conectado ao nREPL
recurso LLM_CODE_STYLE.md - que são suas instruções pessoais de estilo de codificação (copie o deste repositório para a raiz do seu projeto)
prompt clojure_repl_system_prompt - instruções sobre como codificar - bastante inspirado no Claude Code

Então inicie o chat.

Eu começaria declarando um problema e depois conversando com o LLM para projetar interativamente uma solução. Você pode pedir ao Claude para "apresentar uma solução para minha revisão".

Itere um pouco e então peça para ele:

A. codificar e validar a ideia no REPL.

Não subestime as habilidades dos LLMs de usar o REPL! Os LLMs atuais são absolutamente fantásticos em usar o REPL do Clojure.

B. pedir ao LLM para fazer as alterações no código-fonte e depois validar o código no REPL após a edição do arquivo.

C. pedir para executar os testes. D. pedir para commitar as alterações.

Crie um branch e peça ao LLM para commitar com frequência para que ele não estrague um bom trabalho indo em uma direção ruim.

Gerenciamento do Resumo do Projeto

Este projeto inclui um fluxo de trabalho para manter um PROJECT_SUMMARY.md amigável para LLM que ajuda assistentes a entender rapidamente a estrutura do código.

Como Funciona

Criando o Resumo: Para gerar ou atualizar o arquivo PROJECT_SUMMARY.md, use o prompt MCP no menu + > clojure-mcp create-update-project-summary. Este prompt irá:
- Analisar a estrutura do código
- Documentar arquivos-chave, dependências e ferramentas disponíveis
- Gerar documentação abrangente em um formato otimizado para assistentes LLM
Usando o Resumo: Ao iniciar uma nova conversa com um assistente:
- O recurso "Project Summary" carrega automaticamente o PROJECT_SUMMARY.md
- Isso dá ao assistente contexto imediato sobre a estrutura do projeto
- O assistente pode fornecer ajuda mais precisa sem exploração demorada
Mantendo-o Atualizado: No final de uma sessão produtiva em que novos recursos ou componentes foram adicionados:
- Invoque o prompt create-update-project-summary novamente
- O sistema atualizará o PROJECT_SUMMARY.md com a funcionalidade recém-adicionada
- Isso garante que o resumo permaneça atualizado com o desenvolvimento em andamento

Este fluxo de trabalho cria um ciclo virtuoso onde cada sessão se baseia no conhecimento acumulado das sessões anteriores, tornando o assistente cada vez mais eficaz à medida que seu projeto evolui.

Resumir e Retomar Sessão de Chat

O servidor Clojure MCP fornece um par de prompts que permitem continuidade de conversa entre sessões de chat usando a ferramenta scratch_pad. Por padrão, os dados são armazenados apenas em memória para a sessão atual. Para persistir resumos entre reinicializações do servidor, você deve habilitar a persistência do scratch pad usando as opções de configuração descritas na seção de scratch pad.

Como Funciona

O sistema usa dois prompts complementares:

chat-session-summarize: Cria um resumo da conversa atual
- Salva um resumo detalhado no scratch pad
- Captura o que foi feito, no que está sendo trabalhado e o que vem a seguir
- Aceita um parâmetro opcional chat_session_key (padrão é "chat_session_summary")
chat-session-resume: Restaura o contexto de uma conversa anterior
- Lê o arquivo PROJECT_SUMMARY.md
- Chama clojure_inspect_project para o estado atual do projeto
- Recupera o resumo da sessão anterior do scratch pad
- Fornece um breve resumo de 8 linhas de onde as coisas pararam
- Aceita um parâmetro opcional chat_session_key (padrão é "chat_session_summary")

Fluxo de Trabalho de Uso

Encerrando uma Sessão:

No final de uma conversa produtiva, invoque o prompt chat-session-summarize
O assistente armazenará um resumo abrangente no scratch pad
Este resumo persiste entre sessões graças ao estado global do scratch pad

Iniciando uma Nova Sessão:

Ao continuar o trabalho, invoque o prompt chat-session-resume
O assistente carregará todo o contexto relevante e fornecerá um breve resumo
Você pode então continuar de onde parou com contexto completo

Uso Avançado com Múltiplas Sessões

Você pode manter múltiplos contextos de conversa paralelos usando chaves personalizadas:

# For feature development
chat-session-summarize with key "feature-auth-system"

# For bug fixing
chat-session-summarize with key "debug-memory-leak"

# Resume specific context
chat-session-resume with key "feature-auth-system"

Isso permite alternar entre diferentes contextos de desenvolvimento, mantendo o estado completo de cada thread de conversa.

Trabalhando com Múltiplos REPLs

Com list_nrepl_ports, o agente pode descobrir tanto seus REPLs Clojure quanto shadow-cljs simultaneamente. A ferramenta identifica quais REPLs são instâncias shadow-cljs, permitindo que o agente avalie em qualquer um dos REPLs usando clojure_eval com o parâmetro port apropriado.

Chaves de API LLM

Isso NÃO é necessário para usar o servidor Clojure MCP.

IMPORTANTE: se você tiver as seguintes chaves de API definidas no seu ambiente, o ClojureMCP fará chamadas a elas quando você usar as ferramentas dispatch_agent, architect e code_critique. Essas chamadas gerarão cobranças de API.

Existem algumas ferramentas MCP fornecidas que são agentes por si só e precisam de chaves de API para funcionar.

Para usar as ferramentas de agente, você precisará de chaves de API de um ou mais destes provedores:

GEMINI_API_KEY - Para modelos Google Gemini
- Obtenha sua chave de API em: https://makersuite.google.com/app/apikey
- Usado por: dispatch_agent, architect, code_critique
OPENAI_API_KEY - Para modelos GPT
- Obtenha sua chave de API em: https://platform.openai.com/api-keys
- Usado por: dispatch_agent, architect, code_critique
ANTHROPIC_API_KEY - Para modelos Claude
- Obtenha sua chave de API em: https://console.anthropic.com/
- Usado por: dispatch_agent

Definindo Variáveis de Ambiente

Opção 1: Exporte no seu shell

export ANTHROPIC_API_KEY="your-anthropic-api-key-here"
export OPENAI_API_KEY="your-openai-api-key-here"
export GEMINI_API_KEY="your-gemini-api-key-here"

Opção 2: Adicione ao seu perfil de shell (.bashrc, .zshrc, etc.)

# Add these lines to your shell profile
export ANTHROPIC_API_KEY="your-anthropic-api-key-here"
export OPENAI_API_KEY="your-openai-api-key-here"
export GEMINI_API_KEY="your-gemini-api-key-here"

Configurando Chaves LLM para o Claude Desktop

Ao configurar o Claude Desktop, certifique-se de que ele possa acessar suas variáveis de ambiente atualizando sua configuração.

Pessoalmente, eu source diretamente no comando bash:

{
    "mcpServers": {
        "clojure-mcp": {
            "command": "/bin/sh",
            "args": [
                "-c",
                "source ~/.api_credentials.sh && PATH=/your/bin/path:$PATH && clojure -Tmcp start :not-cwd true :port 7888"
            ]
        }
    }
}

Nota: As ferramentas de agente funcionarão com qualquer chave de API disponível. Você não precisa de todas as três - basta configurar aquelas às quais você tem acesso. As ferramentas selecionarão automaticamente entre os modelos disponíveis. Por enquanto, a API ANTHROPIC está limitada ao dispatch_agent.

🧰 Ferramentas Disponíveis

As ferramentas padrão incluídas no main.clj são organizadas por categoria para suportar diferentes fluxos de trabalho:

Ferramentas Somente Leitura

Nome da Ferramenta	Descrição	Exemplo de Uso
`LS`	Retorna uma visão em árvore recursiva de arquivos e diretórios	Explorando a estrutura do projeto
`read_file`	Leitor de arquivos inteligente com exploração baseada em padrões para arquivos Clojure	Lendo arquivos com visualização recolhida, correspondência de padrões
`grep`	Busca rápida de conteúdo usando expressões regulares	Encontrando arquivos que contêm padrões específicos
`glob_files`	Localização de arquivos baseada em padrões	Encontrando arquivos por padrões de nome como `*.clj`

Avaliação de Código

Nome da Ferramenta	Descrição	Exemplo de Uso
`clojure_eval`	Avalia código Clojure no namespace atual; suporta o parâmetro opcional `port` para fluxos de trabalho multi-REPL	Testando expressões, conectando-se a diferentes REPLs
`list_nrepl_ports`	Descobre servidores nREPL em execução na máquina	Encontrando REPLs disponíveis para conectar
`bash`	Executa comandos shell no sistema host	Executando testes, comandos git, operações de arquivo

Ferramentas de Edição de Arquivos

Nome da Ferramenta	Descrição	Exemplo de Uso
`clojure_edit`	Edição de formas Clojure ciente da estrutura	Substituindo/inserindo funções, lidando com defmethod
`clojure_edit_replace_sexp`	Modifica expressões dentro de funções	Alterando s-expressions específicas
`file_edit`	Edita arquivos substituindo strings de texto	Reparo parinfer após edição, se necessário
`file_write`	Escreve arquivos completos com verificações de segurança	Criando novos arquivos, sobrescrevendo com validação

Ferramentas de Agente (Requerem Chaves de API)

Nome da Ferramenta	Descrição	Exemplo de Uso
`dispatch_agent`	Inicia agentes com ferramentas somente leitura para buscas complexas	Exploração e análise de arquivos em várias etapas
`architect`	Planejamento técnico e orientação de implementação	Design de sistemas, decisões de arquitetura

Ferramentas Experimentais

Nome da Ferramenta	Descrição	Exemplo de Uso
`scratch_pad`	Espaço de trabalho persistente para armazenamento estruturado de dados	Rastreamento de tarefas, planejamento, comunicação entre ferramentas com persistência opcional de arquivos (desativada por padrão)
`code_critique`	Revisão interativa de código e sugestões de melhoria	Melhoria iterativa da qualidade do código

Principais Recursos das Ferramentas

Leitura Inteligente de Arquivos (`read_file`)

Visualização Recolhida: Mostra apenas assinaturas de funções para arquivos Clojure grandes
Correspondência de Padrões: Use name_pattern para encontrar funções por nome, content_pattern para pesquisar conteúdo
Suporte a defmethod: Lida com valores de dispatch como "area :rectangle" ou dispatches de vetor
Multilíngue: Arquivos Clojure recebem recursos inteligentes, outros arquivos mostram conteúdo bruto

Edição Ciente da Estrutura (`clojure_edit`)

Operações Baseadas em Formas: Direcione funções por tipo e identificador, não por correspondência de texto
Múltiplas Operações: Replace, insert_before, insert_after
Validação de Sintaxe: Linting integrado previne parênteses desbalanceados
Tratamento de defmethod: Funciona com nomes qualificados e valores de dispatch

Avaliação de Código (`clojure_eval`)

Integração com REPL: Executa na sessão nREPL conectada
Funções Auxiliares: Ferramentas integradas de exploração de namespaces e símbolos
Múltiplas Expressões: Avalia e particiona múltiplas expressões

Comandos Shell (`bash`)

Execução Configurável: Pode executar via nREPL ou localmente com base na configuração
Isolamento de Sessão: Ao usar o modo nREPL, executa em sessão separada para evitar interferência no REPL
Truncamento de Saída: Limite consistente de 8500 caracteres com alocação inteligente de stderr/stdout
Segurança de Caminhos: Valida caminhos do sistema de arquivos contra diretórios permitidos

Sistema de Agentes (`dispatch_agent`)

Busca Autônoma: Lida com tarefas complexas de exploração em várias etapas
Acesso Somente Leitura: Agentes têm acesso somente leitura às ferramentas
Resultados Detalhados: Retorna análise e descobertas

Bloco de Anotações (`scratch_pad`)

Espaço de Trabalho Persistente: Armazene dados estruturados para planejamento e comunicação entre ferramentas
Somente em Memória: Os dados são armazenados apenas em memória e perdidos quando a sessão termina (comportamento padrão)
Operações Baseadas em Caminhos: Use set_path, get_path, delete_path para manipulação precisa de dados
Compatibilidade JSON: Armazene qualquer dado compatível com JSON (objetos, arrays, strings, números, booleanos)

🔧 Personalização

O ClojureMCP foi projetado para ser altamente personalizável. Durante a fase alfa, criar seu próprio servidor MCP personalizado é a principal forma de configurar o sistema para suas necessidades específicas.

Você pode personalizar:

Ferramentas - Escolha quais ferramentas incluir, crie novas com multimétodos ou mapas simples
Prompts - Adicione prompts específicos do projeto para seus fluxos de trabalho
Recursos - Exponha sua documentação, configuração e informações do projeto
Seleção de Ferramentas - Crie servidores somente leitura, servidores de desenvolvimento ou configurações especializadas

A abordagem de personalização é fácil e empoderadora - você está essencialmente construindo seu próprio companheiro de desenvolvimento de IA personalizado.

📖 Documentação Completa de Personalização

Para um início rápido: Criando Seu Próprio Servidor MCP Personalizado - É por aqui que a maioria dos usuários deve começar.

Opções de CLI

Os valores passados para clojure -Tmcp start são valores EDN.

`:port`

Opcional - A porta do servidor nREPL para conectar. Ao usar :start-nrepl-cmd sem :port, a porta será descoberta automaticamente a partir da saída do comando.

:port 7888

`:host`

Opcional - O host do servidor nREPL. O padrão é localhost se não for especificado.

:host "localhost" ou :host "0.0.0.0"

`:not-cwd`

Opcional - Se verdadeiro, não use o diretório de trabalho atual como diretório do projeto. Requer que :port seja especificado. O servidor MCP fará a introspecção da conexão nREPL para descobrir o diretório de trabalho do projeto.

Isso é essencial para o Claude Desktop e outros clientes que iniciam o servidor MCP fora do diretório do seu projeto. Ao conectar-se a um nREPL em execução no seu projeto, o ClojureMCP pode determinar o diretório de trabalho correto automaticamente.

:not-cwd true

`:start-nrepl-cmd`

Opcional - Um comando para iniciar automaticamente um servidor nREPL se um já não estiver em execução. Deve ser especificado como um vetor de strings. O servidor MCP iniciará esse processo e gerenciará seu ciclo de vida.

Quando usado sem :port, o servidor MCP analisará automaticamente a porta da saída do comando. Quando usado com :port, ele usará essa porta fixa em vez disso.

Importante: Esta opção requer iniciar o clojure-mcp a partir do diretório do seu projeto (onde seu deps.edn ou project.clj está localizado). O servidor nREPL será iniciado no diretório de trabalho atual. Isso é particularmente útil para o Claude Code e outros clientes LLM de linha de comando onde você deseja inicialização automática do nREPL sem gerenciamento manual de processos.

Nota para usuários do Claude Desktop: O Claude Desktop não inicia servidores MCP a partir do diretório do seu projeto, então :start-nrepl-cmd não funcionará a menos que você também forneça :project-dir como um argumento de linha de comando apontando para seu projeto específico. Por exemplo: :project-dir '"/path/to/your/clojure/project"'. Essa limitação não afeta o Claude Code ou outras ferramentas baseadas em CLI que você executa a partir do diretório do seu projeto.

:start-nrepl-cmd ["lein" "repl" ":headless"] ou :start-nrepl-cmd ["clojure" "-M:nrepl"]

`:fallback-nrepl`

Opcional - Quando true, o ClojureMCP primeiro tentará anexar-se a :port. Se nada estiver escutando lá (ou :port for omitido completamente), ele inicia um nREPL local em uma porta efêmera e conecta-se a ela. O fallback nunca ocupa seu :port configurado, então uma sessão de editor posterior ainda pode reivindicá-lo.

Isso é destinado a usuários que nem sempre têm um nREPL gerenciado pelo editor em execução — por exemplo, ao iniciar o Claude Desktop sem primeiro iniciar um REPL do projeto, ou ao trabalhar em projetos pequenos via Vim. Sem esta flag, o ClojureMCP falha ao iniciar se não conseguir alcançar :port, o que o Claude Desktop exibe como um erro de "Servidor desconectado".

O comando padrão é construído a partir da dependência nREPL do próprio clojure-mcp (portanto, nenhuma versão é codificada) e é executado através de clojure -Sdeps ... -M -m nrepl.cmdline. O ~/.clojure/deps.edn do usuário ainda é mesclado pela CLI clojure, então as bibliotecas que você mantém globalmente disponíveis (ex.: Criterium) permanecem no classpath do REPL iniciado.

O processo iniciado é limpo automaticamente quando o servidor MCP é encerrado.

:fallback-nrepl true

`:fallback-nrepl-cmd`

Opcional - Substitui o comando de fallback padrão. Deve ser um vetor de strings. Usado apenas quando :fallback-nrepl é true. Não inclua uma porta explícita no comando; o lançador precisa analisar a porta descoberta a partir da saída do processo.

:fallback-nrepl-cmd ["lein" "repl" ":headless"]

`:fallback-nrepl-dir`

Opcional - Diretório de trabalho para o REPL de fallback iniciado. O padrão é :project-dir se definido, caso contrário $HOME. Útil quando você deseja que o REPL de fallback capture o deps.edn de um projeto automaticamente.

:fallback-nrepl-dir "/path/to/scratch"

`:config-file`

Opcional - Especifique a localização de um arquivo de configuração. Deve ser um caminho para um arquivo existente.

:config-file "/path/to/config.edn"

`:project-dir`

Opcional - Especifique o diretório de trabalho para sua base de código. Isso substitui a introspecção automática do diretório do projeto a partir da conexão nREPL. Deve ser um caminho para um diretório existente.

:project-dir "/path/to/your/clojure/project"

`:nrepl-env-type`

Opcional - Especifique o tipo de ambiente ao qual estamos nos conectando através da conexão nREPL. Isso substitui a detecção automática. As opções válidas são:

:clj para Clojure ou ClojureScript
:bb para Babashka - Interpretador Clojure nativo e de inicialização rápida para scripts
:basilisp para Basilisp - Um dialeto Lisp compatível com Clojure voltado para Python 3.9+
:scittle para Scittle - Execute ClojureScript diretamente de tags de script do navegador

:nrepl-env-type :bb

`:shadow-cljs-repl-message`

Opcional - Controla se a mensagem de status do modo REPL do shadow-cljs é incluída nos resultados de avaliação (padrão: true). Quando conectado a um nREPL shadow-cljs, uma mensagem de status sobre o modo CLJS é prefixada a cada resultado de avaliação. Defina como false para desabilitar esta mensagem.

:shadow-cljs-repl-message false

`:config-profile`

Opcional - Carrega um perfil de configuração integrado que ajusta a disponibilidade e as descrições das ferramentas. Útil para adaptar o ClojureMCP a casos de uso específicos.

Perfis disponíveis:

:cli-assist - Conjunto mínimo de ferramentas para assistentes de codificação CLI (Claude Code, Codex, Gemini CLI). Desabilita ferramentas redundantes e configura clojure_edit como fallback para quando o Edit nativo falha.
:cli-assist-full - Como o :cli-assist, mas promove as ferramentas read_file, clojure_edit, clojure_edit_replace_sexp e paren_repair do clojure-mcp a ferramentas de primeira classe (sem enquadramento de "fallback") para um fluxo de trabalho orientado a agentes. Suas instruções orientam o assistente a rotear todas as edições de arquivos Clojure pelas ferramentas clojure, o que evita o conflito "arquivo modificado desde a leitura" do editor host sem necessidade de configuração de permissões do host.

:config-profile :cli-assist

`:enable-tools`

Opcional - Lista de permissões de palavras-chave de ferramentas. Quando fornecida, substitui qualquer valor de :enable-tools da configuração. Apenas as ferramentas listadas estarão disponíveis.

:enable-tools [:clojure_eval :read_file]

`:disable-tools`

Opcional - Lista de bloqueio de palavras-chave de ferramentas. Quando fornecida, substitui qualquer valor de :disable-tools da configuração. As ferramentas listadas serão desabilitadas.

:disable-tools [:bash :dispatch_agent]

`:add-tools`

Opcional - Força a habilitação de ferramentas específicas após a resolução da configuração. Remove ferramentas da lista de desabilitação e as adiciona à lista de habilitação, se houver uma ativa. Isso é útil para reabilitar seletivamente ferramentas que um perfil de configuração desabilita.

:add-tools [:my_custom_agent]

`:remove-tools`

Opcional - Força a desabilitação de ferramentas específicas após a resolução da configuração. Adiciona ferramentas à lista de desabilitação e as remove da lista de habilitação, se houver uma ativa. Isso é útil para desabilitar seletivamente ferramentas sem substituir toda a configuração.

:remove-tools [:clojure_eval]

Ordem de aplicação da filtragem de ferramentas

Configuração carregada (fusão de home + projeto + perfil)
:enable-tools/:disable-tools das opções substituem os valores da configuração (se fornecidos)
:remove-tools aplicado (força desabilitação)
:add-tools aplicado (força habilitação — vence sobre :remove-tools em caso de sobreposição)
As variáveis de ambiente ENABLE_TOOLS/DISABLE_TOOLS ainda vencem sobre tudo

Consulte Filtragem de Componentes para detalhes sobre como as listas de habilitação/desabilitação funcionam nos arquivos de configuração.

Exemplo de Uso

# Basic usage with just port
clojure -Tmcp start :port 7888

# With automatic nREPL server startup and port discovery
# Perfect for CLI assistants - run this from your project directory
clojure -Tmcp start :start-nrepl-cmd '["lein" "repl" ":headless"]'

# For deps.edn projects (from project directory)
clojure -Tmcp start :start-nrepl-cmd '["clojure" "-M:nrepl"]'

# Auto-start with explicit port (uses fixed port, no parsing)
clojure -Tmcp start :port 7888 :start-nrepl-cmd '["clojure" "-M:nrepl"]'

# Attach to port 7888 if available, otherwise spawn a fallback nREPL on
# an ephemeral port. Useful for Claude Desktop when you don't always
# have an editor-managed REPL running.
clojure -Tmcp start :not-cwd true :port 7888 :fallback-nrepl true

# For Claude Desktop: must provide project-dir since it doesn't run from your project
clojure -Tmcp start :start-nrepl-cmd '["lein" "repl" ":headless"]' :project-dir '"/path/to/your/clojure/project"'

# With custom host and project directory
clojure -Tmcp start :port 7888 :host '"0.0.0.0"' :project-dir '"/path/to/project"'

# Using a custom config file
clojure -Tmcp start :port 7888 :config-file '"/path/to/custom-config.edn"'

# Specifying Babashka environment
clojure -Tmcp start :port 7888 :nrepl-env-type :bb

# Using cli-assist profile for CLI coding assistants
clojure -Tmcp start :config-profile :cli-assist

# Like cli-assist, but clojure-mcp's read/edit tools are first-class (agent-driven workflow)
clojure -Tmcp start :config-profile :cli-assist-full

# cli-assist with a custom agent tool re-enabled
clojure -Tmcp start :config-profile :cli-assist :add-tools '[:my_custom_agent]'

# cli-assist but also remove clojure_eval
clojure -Tmcp start :config-profile :cli-assist :remove-tools '[:clojure_eval]'

# Full override — only these two tools
clojure -Tmcp start :enable-tools '[:clojure_eval :read_file]'

Nota: Os valores de string precisam ser devidamente citados para o shell, daí a sintaxe '"value"' para strings.

⚙️ Configuração

O servidor Clojure MCP suporta configuração mínima específica do projeto por meio de um arquivo .clojure-mcp/config.edn no diretório raiz do seu projeto. Essa configuração fornece controles de segurança e opções de personalização para o servidor MCP.

Localização do Arquivo de Configuração

Crie um arquivo .clojure-mcp/config.edn na raiz do seu projeto:

your-project/
├── .clojure-mcp/
│   └── config.edn
├── src/
├── deps.edn
└── ...

Opções de Configuração

A configuração é extensivamente documentada aqui.

Exemplo de Configuração

{:allowed-directories ["."
                       "src"
                       "test"
                       "resources"
                       "dev"
                       "/absolute/path/to/shared/code"
                       "../sibling-project"]
 :write-file-guard :partial-read
 :cljfmt false
 :bash-over-nrepl false}

Detalhes da Configuração

Resolução de Caminhos:

Caminhos relativos (como "src", "../other-project") são resolvidos em relação à raiz do seu projeto
Caminhos absolutos (como "/home/user/shared") são usados como estão
O diretório raiz do projeto é automaticamente incluído nos diretórios permitidos

Segurança:

As ferramentas validam todas as operações de arquivo em relação aos diretórios permitidos
Tentativas de acessar arquivos fora dos diretórios permitidos falharão com um erro
Isso evita acesso acidental a arquivos sensíveis do sistema
a ferramenta Bash não respeita esses limites, portanto, tenha cuidado

Comportamento Padrão:

Sem um arquivo de configuração, apenas o diretório do projeto e seus subdiretórios são acessíveis
O diretório de trabalho do nREPL é automaticamente adicionado aos diretórios permitidos

Nota: A configuração é carregada quando o servidor MCP inicia. Reinicie o servidor (ou o Agente de Chat) após fazer alterações na configuração.

📝 Licença

Eclipse Public License - v 2.0

Este programa e os materiais acompanhantes são disponibilizados sob os termos da Eclipse Public License 2.0, disponível em http://www.eclipse.org/legal/epl-2.0

Resumo da Licença

✅ Use livremente em projetos pessoais, ferramentas internas de negócios e desenvolvimento
✅ Modifique e distribua - melhorias e forks são bem-vindos
✅ Uso comercial - empresas podem usar isto comercialmente sem restrições
✅ Licenciamento flexível - pode ser combinado com código proprietário
📤 Compartilhe melhorias - o código-fonte deve ser disponibilizado quando distribuído

Clojure MCP

Documentação

Clojure MCP: Desenvolvimento Orientado por REPL com Assistência de IA

Sumário

O que é ClojureMCP?

Como eu uso?

Principais Recursos

Ajuda e Recursos da Comunidade

📋 Instalação

Pré-requisitos

Instalar ClojureMCP

Assistentes CLI

Adicionando ClojureMCP com :cli-assist

Verificar a instalação iniciando o servidor

Claude Desktop

Iniciar um nREPL no seu projeto

Configurar o Claude Desktop

Testar a configuração

IMPORTANTE: Desative os recursos do Claude Desktop

Outros Clientes além do Claude Desktop

Iniciando uma nova conversa no Claude Desktop

Gerenciamento do Resumo do Projeto

Como Funciona

Resumir e Retomar Sessão de Chat

Como Funciona

Fluxo de Trabalho de Uso

Uso Avançado com Múltiplas Sessões

Trabalhando com Múltiplos REPLs

Chaves de API LLM

Definindo Variáveis de Ambiente

Configurando Chaves LLM para o Claude Desktop

🧰 Ferramentas Disponíveis

Ferramentas Somente Leitura

Avaliação de Código

Ferramentas de Edição de Arquivos

Ferramentas de Agente (Requerem Chaves de API)

Ferramentas Experimentais

Principais Recursos das Ferramentas

Leitura Inteligente de Arquivos (read_file)

Edição Ciente da Estrutura (clojure_edit)

Avaliação de Código (clojure_eval)

Comandos Shell (bash)

Sistema de Agentes (dispatch_agent)

Bloco de Anotações (scratch_pad)

🔧 Personalização

Opções de CLI

:port

:host

:not-cwd

:start-nrepl-cmd

:fallback-nrepl

:fallback-nrepl-cmd

:fallback-nrepl-dir

:config-file

:project-dir

:nrepl-env-type

:shadow-cljs-repl-message

:config-profile

:enable-tools

:disable-tools

:add-tools

:remove-tools

Ordem de aplicação da filtragem de ferramentas

Exemplo de Uso

⚙️ Configuração

Localização do Arquivo de Configuração

Opções de Configuração

Exemplo de Configuração

Detalhes da Configuração

📝 Licença

Resumo da Licença

Adicionando ClojureMCP com `:cli-assist`

Leitura Inteligente de Arquivos (`read_file`)

Edição Ciente da Estrutura (`clojure_edit`)

Avaliação de Código (`clojure_eval`)

Comandos Shell (`bash`)

Sistema de Agentes (`dispatch_agent`)

Bloco de Anotações (`scratch_pad`)

`:port`

`:host`

`:not-cwd`

`:start-nrepl-cmd`

`:fallback-nrepl`

`:fallback-nrepl-cmd`

`:fallback-nrepl-dir`

`:config-file`

`:project-dir`

`:nrepl-env-type`

`:shadow-cljs-repl-message`

`:config-profile`

`:enable-tools`

`:disable-tools`

`:add-tools`

`:remove-tools`