Meu Script de Commit de IA e Minha Ferramenta MCP Executam o Mesmo Código. Apenas Uma Delas É Agentic.

Eu tenho duas maneiras de gerar uma mensagem de commit neste repositório. Uma é git_commit.py, um script de 20 linhas que eu executo manualmente: python git_commit.py, ele captura o diff em estágio, chama claude -p, e imprime uma mensagem de Commit Convencional. A outra é generate_commit_message, uma ferramenta exposta através de um servidor MCP, chamável por qualquer agente que tenha esse servidor configurado.

Se você simplificar ambos, eles chamam o mesmo prompt contra o mesmo modelo através do mesmo subprocesso. Por um tempo, descrevi o segundo como "a versão agentic" sem conseguir dizer o que a tornava agentic, além de vibrações e da palavra MCP estar envolvida. Isso me incomodou o suficiente para realmente olhar a diferença entre eles, e a resposta acabou sendo menor e mais específica do que eu esperava — e não é a parte que as pessoas costumam apontar.

O que realmente é diferente

Aqui está o script:

diff = subprocess.check_output(["git", "diff", "--staged"], text=True)
if not diff.strip():
    print("Nada em estágio. Execute `git add` primeiro.")
    raise SystemExit(1)

raw = subprocess.check_output(
    ["claude", "-p", SYSTEM + "\n\n" + diff],
    text=True,
).strip()

E aqui está a ferramenta:

@mcp.tool()
def generate_commit_message(diff: str) -> str:
    """Gere uma mensagem de Commits Convencionais a partir de uma string de diff do git."""
    return _claude(diff, system="...")

A chamada da IA é a mesma chamada. _claude() dentro de server.py é apenas subprocess.check_output(["claude", "-p", ...]) envolto em um helper — mesma sessão OAuth, mesmo modelo, sem chave de API envolvida de qualquer forma (este repositório não tem ANTHROPIC_API_KEY configurada; ambos os caminhos utilizam o login existente do claude CLI). Se "agentic" significasse "um LLM está envolvido," estes seriam idênticos, e toda a distinção seria marketing.

O que é diferente é uma linha: @mcp.tool(). Esse decorador está fazendo algo que o script nunca faz — está transformando a assinatura de uma função Python em um esquema que um agente pode ler sem executar a função primeiro. generate_commit_message(diff: str) -> str se torna um objeto JSON Schema com um nome, uma descrição extraída da docstring, e uma lista de parâmetros tipados, publicado sobre o protocolo MCP antes que qualquer ferramenta seja chamada. Um agente decidindo o que fazer a seguir lê esse esquema, não o corpo da função. Ele não sabe ou se importa que _claude() chama um CLI — ele sabe que a ferramenta aceita uma string chamada diff e retorna uma string, e esse é todo o contrato de interface que ele precisa raciocinar.

O script não tem nada disso. git_commit.py é uma caixa-preta para qualquer coisa, exceto um humano que já sabe executar python git_commit.py. Não há esquema, não há descobribilidade, nenhuma maneira de algo mais descobrir que ele existe a não ser ler o código-fonte ou ser informado sobre isso em um prompt. Não é um código menos capaz — é a mesma capacidade exata — mas só é acessível por um humano que já tem as instruções memorizadas.

Onde essa distinção realmente impacta

Isso importou de uma maneira muito pouco glamourosa na primeira vez que tentei deixar um agente usar ambos de forma intercambiável. Eu assumi que, uma vez que a chamada subjacente era idêntica, conectar um agente para "apenas chamar git_commit.py diretamente" através de uma ferramenta genérica de execução bash se comportaria da mesma forma que chamar a ferramenta MCP. Não se comportou, por uma razão que é óbvia em retrospecto: o modo de falha do script é um print() e um código de saída diferente de zero —

if not diff.strip():
    print("Nada em estágio. Execute `git add` primeiro.")
    raise SystemExit(1)

— o que é bom para um humano olhando para um terminal, e inútil para um agente analisando um par stdout/código de saída de uma ferramenta bash genericamente. Ele tem que adivinhar se essa string significa "condição esperada, tente outra coisa" ou "erro real, pare." A ferramenta MCP não tem esse problema porque a interface em si é tipada: um -> str de retorno significa que o agente recebe uma mensagem de volta, ponto final, e a sinalização de erro passa pelo próprio mecanismo do protocolo em vez de ser disfarçada através de declarações de impressão e códigos de saída que foram projetados para olhos humanos.

Então, a definição real que cheguei, para meus próprios propósitos: um script é agentic não porque um LLM está dentro dele, e não mesmo porque é "automatizado" — é agentic quando o limite do que ele faz é descrito em uma forma que algo além de um humano pode ler e agir antes de chamá-lo. Tudo que está acima desse limite — chamadas de subprocesso, strings de prompt, o que for — pode ser idêntico. O esquema é toda a diferença.

A parte que eu errei primeiro

Meu primeiro instinto, antes de realmente comparar os dois arquivos, foi que a "verdadeira" diferença deveria estar em quão mais inteligente ou mais estruturado era o prompt da versão MCP — como ferramentas agentic precisam de melhores prompts, mais guardrails, mo