scoutbook

Servidor MCP local que serve o handbook de um time (um repositório de markdown) ao Claude Code. O objetivo é dar ao Claude de cada time acesso ao "como a gente faz X aqui": estruturar CI/CD, fazer deploy, padrão de projeto, troubleshooting antes de abrir um card, etc.

O scoutbook é um motor genérico: ele não sabe nada sobre o seu time. Você aponta ele para um diretório de .md (o repo do handbook daquele time) e ele expõe três ferramentas ao Claude:

• list_handbook — lista todos os documentos (título, resumo, tags).
• read_handbook_doc — lê um documento pelo id (caminho relativo).
• search_handbook — busca por palavras-chave e devolve trechos relevantes.

Cada time tem seu próprio repo de handbook; roda-se uma instância do scoutbook por handbook.

Arquitetura

src/
  core/           # núcleo puro, sem MCP — testável isolado
    handbook.ts   # descoberta, leitura (cache por mtime) e busca por keyword
    frontmatter.ts# parser minimalista de frontmatter, sem dependências
  index.ts        # adapter MCP (stdio) que expõe o core como tools
handbook/         # conteúdo de EXEMPLO (troque pelo repo do seu time)

A busca hoje é por keyword (sem acento, case-insensitive), com ranking simples (título > tags > corpo). O core foi desenhado para trocar essa estratégia por busca semântica no futuro sem mexer no adapter.

Setup

npm install
npm run build

Para desenvolver com reload:

npm run dev            # usa ./handbook por padrão
npm run dev /caminho/para/outro/handbook

Configuração do diretório do handbook

Resolvido nesta ordem:

1. primeiro argumento da CLI (node dist/index.js /caminho/do/handbook)
2. env SCOUTBOOK_HANDBOOK_DIR
3. ./handbook (relativo ao CWD) — usado pelo conteúdo de exemplo

Conectando ao Claude Code

Copie .mcp.json.example para .mcp.json no repo do time (ou configure globalmente) e ajuste os caminhos absolutos:

{
  "mcpServers": {
    "scoutbook": {
      "command": "node",
      "args": ["/caminho/abs/para/scoutbook/dist/index.js"],
      "env": {
        "SCOUTBOOK_HANDBOOK_DIR": "/caminho/abs/para/o/repo/handbook-do-time"
      }
    }
  }
}

Formato dos documentos

Markdown puro funciona. Frontmatter é opcional e deixa o list/search mais ricos:

---
title: Como fazer deploy
tags: [deploy, producao]
summary: Passo a passo do deploy padrão do time.
---

# Como fazer deploy
...

Sem frontmatter, o título cai para o primeiro # heading (ou o nome do arquivo) e o resumo para o primeiro parágrafo.

Roadmap

• Sync do git (fase 2): manter o diretório do handbook atualizado com o repo do time (git pull no diretório apontado; depois, gerenciar o clone a partir de uma URL).
• Busca semântica opcional.
• Exposição também como MCP resources para anexo manual.