fm-mcp

fm-mcp

Um servidor MCP que permite que agentes de codificação, como Claude Code e Codex, deleguem tarefas simples de texto ao modelo local para Apple Foundation Models, o fm que acompanha o macOS 27. É gratuito, privado e funciona offline.

mcp-name: io.github.yrangana/fm-mcp

Site: yrangana.github.io/fm-mcp, com o que aprendemos ao construí-lo: os limites medidos do modelo local.

Por quê

Agentes de codificação gastam tokens remotos pagos em tarefas simples, como resumir um log ou extrair campos de um documento. Um modelo pequeno já presente no seu Mac pode fazer grande parte disso de graça, e seu texto nunca sai da máquina. O fm-mcp permite que o agente delegue esse trabalho e informa claramente o que o modelo pequeno não consegue fazer.

Instalação

O fm-mcp é um beta público (0.1.x): funciona e é testado, mas os detalhes das ferramentas podem mudar entre versões. CHANGELOG.md lista o que mudou.

Você precisa de um Mac com Apple Silicon (Macs com Intel não são suportados), macOS 27 com Apple Intelligence ativado, e a licença do fm aceita uma vez (fm license). Essa é toda a política de suporte: o fm-mcp doctor verifica cada um desses itens, e nada além disso é suportado.

Ainda não tem Homebrew? Instale-o pelo brew.sh primeiro. O instalador pede para instalar as ferramentas de linha de comando do Xcode: aceite e deixe terminar.

brew install yrangana/tap/fm-mcp
fm-mcp install    # sets up Claude Code and Codex
fm-mcp doctor     # checks everything fm-mcp needs

Depois, inicie uma nova sessão do Claude Code ou Codex. O fm-mcp inicia o servidor do modelo (fm serve) por conta própria na primeira vez que uma ferramenta é chamada e o encerra quando a sessão termina.

Outras formas de obter o binário:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/yrangana/fm-mcp/releases/latest/download/fm-mcp-installer.sh | sh
cargo install fm-mcp

O que o fm-mcp install altera

• Claude Code: adiciona o servidor MCP fm-mcp ao ~/.claude.json (por meio do claude mcp add quando o comando claude está presente) e instala a habilidade fm-delegate em ~/.claude/skills/.
• Codex: adiciona [mcp_servers.fm-mcp] ao ~/.codex/config.toml e uma seção marcada em ~/.codex/AGENTS.md (ou em AGENTS.override.md, se você usar um).

Ele faz backup de cada arquivo antes de alterá-lo e imprime todos os caminhos que tocou; executá-lo novamente não altera nada. --claude ou --codex seleciona um agente, --dry-run mostra as alterações sem gravar, e --no-guidance pula a habilidade e a seção do AGENTS.md. fm-mcp install --uninstall remove tudo o que ele adicionou.

A habilidade e a seção do AGENTS.md informam ao agente quando delegar. Sem elas, o agente vê apenas as descrições das ferramentas e delega pior.

Ou: o plugin do Claude Code

O plugin dá ao Claude Code o servidor MCP e a habilidade, sem o fm-mcp install. Ele ainda precisa do binário no seu PATH, então instale-o primeiro (Homebrew acima); caso contrário, o Claude Code reporta que o servidor falhou ao conectar.

/plugin marketplace add yrangana/fm-mcp
/plugin install fm-mcp@fm-mcp

Use o plugin ou o fm-mcp install para Claude Code, não ambos: juntos, eles dão ao Claude Code dois servidores fm-mcp. Com o plugin, execute fm-mcp install --codex para configurar apenas o Codex.

Outros clientes MCP

O fm-mcp é um servidor MCP stdio simples, então outros clientes que executam servidores locais no mesmo Mac podem usá-lo. O fm-mcp install não os configura, e eles não recebem a orientação de delegação: o agente decide apenas pelas descrições das ferramentas. Cada cliente abaixo foi testado em um Mac real; outros podem funcionar, mas não foram testados.

Claude Desktop (testado com 2.31226.1, 2026-10-11). Em Configurações › Desenvolvedor › Editar Config, adicione isto ao mcpServers em claude_desktop_config.json, depois saia e reabra o Claude Desktop:

"fm-mcp": {
  "command": "/opt/homebrew/bin/fm-mcp",
  "args": []
}

Use o caminho completo (which fm-mcp o imprime). O fm-mcp ajuda mais com arquivos no seu Mac: dê ao Claude o caminho do arquivo e ele passa o path, então o texto nunca passa pelo Claude. Para uma página web, o Claude Desktop lê a página primeiro, então delegar não economiza nada.

Devin (antigo Windsurf) (testado com Devin.app 3.8.20, 2026-10-11). Adicione isto ao mcpServers em ~/.config/devin/mcp_config.json:

"fm-mcp": {
  "type": "stdio",
  "command": "/opt/homebrew/bin/fm-mcp",
  "args": []
}

Ferramentas

Ferramenta	O que faz	Quanto suporta
summarise	Condensa logs, documentos, notas e transcrições em um resumo: um parágrafo ou no máximo 7 marcadores. Não é um registro completo.	Cerca de 30.000 palavras de prosa, mas apenas cerca de 1.000 linhas de um log denso. Entradas longas são divididas e combinadas, o que leva um ou dois minutos e pode perder detalhes.
extract	Extrai campos nomeados de um texto como JSON, a partir de um JSON Schema que você fornece. Funciona melhor com um schema plano.	Cerca de 3.500 palavras de prosa.
classify	Classifica um texto em rótulos que você escolhe (um rótulo ou vários com multi).	Cerca de 3.500 palavras de prosa.
ocr	Lê o texto em uma imagem PNG, JPEG, HEIC, TIFF, GIF ou BMP. Não é PDF.	Uma imagem.

summarise, extract e classify aceitam text, ou um path para um arquivo de texto (até 1 MB) para que o agente nunca precise ler o arquivo. docs/TOOLS.md lista todos os parâmetros, com exemplos de chamadas.

Limites

• Modelo pequeno, contexto pequeno: cerca de 8K tokens, compartilhados entre a entrada e a resposta. Logs cheios de IDs e números usam muito mais tokens por palavra do que prosa.
• Não serve para código, matemática, raciocínio, fatos que o texto não contém, ou qualquer coisa onde uma resposta errada seja cara e você não possa verificá-la.
• Ele comete erros. Resumos podem perder ou distorcer detalhes. O extract frequentemente retorna null para um campo que o texto não contém, mas não de forma confiável: em faturas curtas, um número de pedido ausente assumiu o nome do fornecedor em 10 de 25 execuções. Quando o modelo trava em um campo, o fm-mcp mantém os campos concluídos, define o campo travado como null e informa isso; essa chamada leva cerca de 15 s. Peça apenas campos que o texto provavelmente tenha. Schemas aninhados são menos confiáveis que os planos. Verifique o que importa.
• Uma solicitação por vez. O modelo é compartilhado por todas as sessões no Mac, então as chamadas ficam na fila: um extract curto leva 1–2 s, um summarise longo um minuto ou mais.
• Filtro de segurança: o modelo local às vezes recusa entrada inofensiva. O fm-mcp reporta isso claramente, e o agente faz a tarefa sozinho.

Privacidade

Tudo roda no seu Mac. O fm-mcp fala com o fm serve por um socket Unix local e não envia nada pela rede. Seu texto vai apenas para o modelo local. SECURITY.md tem os detalhes e como reportar um problema de segurança de forma privada.

Solução de problemas

Execute fm-mcp doctor. Ele verifica o Mac, o macOS, o fm, a licença, o modelo, uma solicitação de teste e a configuração de ambos os agentes, e diz como corrigir qualquer falha.

Problema	Correção
Licença não aceita	Execute fm license uma vez.
Modelo indisponível	Ative o Apple Intelligence nas Configurações do Sistema e aguarde o download do modelo terminar.
Uma ferramenta diz que o modelo "travou"	Geralmente um schema com campos que o texto não contém, ou outra sessão usando o modelo. Tente um schema mais plano.
Uma ferramenta expira em entrada longa	Aumente o limite: defina FM_MCP_REQUEST_TIMEOUT_SECS (padrão 120) no ambiente do servidor MCP.
Você precisa de mais detalhes	Defina FM_MCP_LOG=debug no ambiente do servidor MCP. O fm-mcp registra logs apenas em stderr (o stdout carrega o protocolo MCP).

Desinstalação

fm-mcp install --uninstall
brew uninstall fm-mcp

Desenvolvimento

git clone https://github.com/yrangana/fm-mcp.git
cd fm-mcp
cargo build --release
./target/release/fm-mcp install    # points your agents at this build

cargo test --features fake-fm      # needs no Apple Intelligence: uses a fake fm
cargo clippy --all-targets --all-features -- -D warnings
cargo fmt --check
scripts/real_fm_smoke.sh           # checks against the real fm on this Mac

AGENTS.md tem a arquitetura, os fatos testados sobre o fm serve e as regras do projeto. docs/MANUAL_TEST.md é o checklist para cada versão.

Licença

MIT. O fm-mcp não é afiliado ou endossado pela Apple. Ele chama a ferramenta fm instalada no seu Mac e não inclui nada da Apple.