Seus bundles, servidos a qualquer agente: okf-mcp 1.0.0

Chegou agora: okf é uma gem Ruby para o Open Knowledge Format, onde um bundle é um diretório de arquivos markdown e cada arquivo é um concept, uma ideia com frontmatter e links para as vizinhas (comece aqui).

Tudo o que o okf fazia pelo seu conhecimento, fazia onde um shell roda: a CLI responde no terminal, a skill dirige essa CLI dentro de um agente de código, o grafo serve um navegador. O okf-mcp 1.0.0 adiciona a superfície que não precisa de nada disso: qualquer host que fale o Model Context Protocol, Claude Desktop, Claude Code, ou o que o seu time rodar depois, lê os bundles da sua máquina diretamente.

Um gem install, e o host está conectado

$ gem install okf-mcp

Essa é a instalação inteira. A gem registra um verbo okf mcp na CLI que você já tem (ele aparece no okf help entre as extensões instaladas), e apontar um host para ele é um bloco de configuração:

{
  "mcpServers": {
    "okf": { "command": "okf", "args": ["mcp"] }
  }
}

Sem argumentos, o servidor oferece todos os bundles do seu registry, registries locais de projeto incluídos, sob os mesmos nomes: o @slug que você digita na CLI é o argumento bundle que toda ferramenta recebe. Uma identidade nas quatro superfícies, então "o handbook" é handbook em todas.

Argumentos fecham a lista em vez de abri-la. okf mcp <dir> @slug serve exatamente o que você nomeou, e nenhuma chamada de ferramenta, nenhuma URI de resource e nenhuma expansão de grupo consegue ampliar o conjunto depois. O conjunto que você escolheu no boot continua sendo o conjunto que você escolheu.

Respostas do tamanho da pergunta

As dez ferramentas mapeiam os verbos de leitura da CLI: list_bundles, dirs, index, search, read_concept, catalog, log, validate, lint, graph. A lista importa menos do que a disciplina por trás dela: toda resposta é dimensionada para uma janela de contexto, e todo limite conta a coisa que cresce.

O exemplo mais claro é o log. Perguntado "o que mudou recentemente", um primeiro corte devolvia um histórico inteiro de 119.863 bytes atrás de um total: 1, porque o total contava arquivos de log. A ferramenta lançada devolve os três grupos de data mais novos por arquivo e diz quantos cada um guarda, o que cortou essa mesma resposta para 13.491 bytes e reduziu uma sessão inteira de avaliação a cerca da metade. No resto, a mesma regra: search limita a 20 linhas ranqueadas, catalog pagina, os rollups param com um restante nomeado, e um orçamento de bytes cobre toda resposta, anunciando-se com truncated quando corta. Seu agente paga pelo que a pergunta precisa, não pela idade do projeto.

As falhas seguem a mesma linha. Um dir que não nomeia diretório algum é recusado com um conselho, nunca respondido com um zero que parece um fato, porque "a raiz do bundle não tem nada" é uma resposta errada que um agente repete com gosto. E nove das dez ferramentas declaram um schema de resultado e devolvem conteúdo estruturado ao lado do texto, então um host consome campos em vez de interpretar prosa. A décima, read_concept, devolve markdown, que já é a sua estrutura.

O mapa que o seu host pode fixar

Ferramentas são o que o modelo decide chamar. Resources são o que você anexa: o mapa raiz de cada bundle servido é okf://<slug>, cada concept é okf://<slug>/<id>, com autocompletar para as URIs serem navegáveis. Fixar o mapa de um bundle no começo de uma sessão custa algumas centenas de tokens e economiza as idas e vindas de orientação.

O servidor também traz dois prompts, a doutrina de retrieval que a skill ensina, reescrita no vocabulário das próprias ferramentas: oriente-se com dirs, desça com index, search para perguntas pontuais, leia só os vencedores. Um host Desktop nunca vê a skill, então o playbook viaja com o servidor.

Respostas ao vivo, não snapshots

O servidor guarda um bundle interpretado por raiz e só relê quando os arquivos em disco realmente mudam, então o corpo que uma ferramenta devolve é sempre o arquivo como ele está agora, por menos que uma varredura por requisição. O registry recebe o mesmo tratamento: registre, renomeie ou reaponte um bundle com o servidor rodando e o conjunto servido acompanha, sem reiniciar. Um índice de busca sobre um conjunto é descartado no momento em que qualquer membro muda, pela regra que o hub do grafo já segue: um índice retido que sobrevive ao seu bundle é uma resposta errada, não uma resposta lenta.

Somente leitura, de propósito

As dez ferramentas são somente leitura e dizem isso nas suas anotações. A autoria fica com a skill, onde um sistema de arquivos, a CLI e um editor humano estão de fato presentes. O transporte padrão é stdio, um processo por host, nada na rede; okf mcp --http serve Streamable HTTP para hosts que conectam a uma URL, e ali a postura é a do servidor do grafo: --bind 0.0.0.0 publica todos os bundles servidos para qualquer coisa que alcance a porta, e a linha de boot avisa com essas palavras em vez de imprimir uma URL com cara de segura.

O que o okf 1.13.0 carrega por baixo

O okf-mcp roda sobre o okf 1.13.0, e o release do kernel importa por si só.

Toda superfície de leitura agora recusa um symlink que aponta para fora do bundle. Antes da correção, um concept ou um index.md que fosse na verdade um symlink para outro lugar da máquina era seguido na leitura e servido na íntegra, pelo servidor do grafo, pelo okf render e pela nova superfície MCP igualmente. As leituras agora resolvem o caminho real e recusam um alvo fora da raiz do bundle. Se você serve bundles em qualquer lugar, este release vale por essa linha sozinha.

Um diretório chamado literalmente root/ voltou a ser endereçável. As views aceitam root como grafia conveniente da raiz do bundle, e essa conveniência sombreava um diretório real com esse nome, respondendo com os concepts errados e exit 0. O diretório real vence agora, em todas as views, e o okf dirs o conta do mesmo jeito que o --dir o lê.

O repositório também virou um monorepo, um diretório por gem, que é o que permite ao okf-mcp e aos próximos irmãos embarcarem ao lado do núcleo sem tocá-lo. A gem publicada não muda em natureza; os detalhes completos estão no changelog.

Experimente

$ gem install okf okf-mcp
$ okf registry set handbook ./docs
$ okf mcp

Aponte qualquer host MCP para okf mcp e pergunte a ele o que o seu time sabe. A documentação do servidor MCP cobre as ferramentas, os resources e o transporte HTTP; os bundles nunca saem da sua máquina.