scoutbook

Servidor MCP 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 ou mais diretórios de .md (o repo do handbook de cada time) e ele expõe estas 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.

• list_linked_handbooks — lista os handbooks cadastrados (nome, origem, caminho).

• update_handbook — sincroniza (git pull) um handbook linkado via git.

Existem dois jeitos de rodar: stdio (um processo por client, igual antes) ou daemon HTTP (um processo só, sempre de pé, servindo vários handbooks e vários clients ao mesmo tempo).

Arquitetura

src/
  core/
    handbook.ts    # descoberta, leitura (cache por mtime) e busca por keyword
    frontmatter.ts # parser minimalista de frontmatter, sem dependências
    registry.ts    # CRUD do registry de handbooks linkados (~/.scoutbook/registry.json)
    git.ts          # clone raso / update (git pull) dos handbooks linkados via git
  cli.ts            # comandos: link, unlink, list-links, update, start, stop, status, restart
  daemon.ts         # ciclo de vida do processo HTTP destacado (pid file, log)
  index.ts          # adapter MCP: modo stdio (default) e modo HTTP (usado por 'start')

A busca é por keyword (sem acento, case-insensitive), com ranking simples (título > tags > corpo).

Related MCP server: vault-mcp-server

Setup

npm install
npm run build

Para desenvolver com reload:

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

Modo daemon (recomendado)

Um processo só, sempre disponível, com um ou mais handbooks linkados.

# linkar um handbook local
npx scoutbook link time-x /caminho/para/handbook-do-time-x

# ou linkar direto de um repo git (clona em ~/.scoutbook/repos/<nome>)
npx scoutbook link time-y https://github.com/org/handbook-time-y --git

npx scoutbook list-links        # ver o que está linkado
npx scoutbook update time-y     # git pull no link (só funciona pra links --git)
npx scoutbook update            # atualiza todos os links git de uma vez

npx scoutbook start             # sobe destacado em http://127.0.0.1:4390/mcp
npx scoutbook status            # rodando (pid ..., porta ...) | parado
npx scoutbook stop
npx scoutbook restart

start aceita --port <n> (ou env SCOUTBOOK_PORT) pra mudar a porta, e bind é sempre em 127.0.0.1 — não expõe o handbook na rede.

Com um único handbook linkado, as tools funcionam sem precisar informar qual é. Com mais de um, cada chamada de list_handbook/read_handbook_doc/search_handbook/update_handbook precisa do parâmetro handbook (o nome usado no link) — use list_linked_handbooks pra descobrir os nomes.

Log fica em ~/.scoutbook/scoutbook.log, registry em ~/.scoutbook/registry.json.

Modo stdio (compatível com configs antigas)

Um processo novo por conexão — é como o scoutbook funcionava antes do modo daemon, e continua funcionando igual, sem precisar de link nenhum.

Resolvido nesta ordem:

1. primeiro argumento da CLI (node dist/index.js /caminho/do/handbook)

2. env SCOUTBOOK_HANDBOOK_DIR

3. --handbook <nome> — usa um link específico do registry

4. único link cadastrado no registry, se houver exatamente um

5. ./handbook (relativo ao CWD) — fallback de desenvolvimento

Conectando ao Claude Code

Daemon (recomendado): aponte pro processo já rodando — veja .mcp.json.daemon.example.

{
  "mcpServers": {
    "scoutbook": {
      "type": "http",
      "url": "http://127.0.0.1:4390/mcp"
    }
  }
}

stdio: copie .mcp.json.example para .mcp.json no repo do time 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

• Busca semântica opcional.

• Exposição também como MCP resources para anexo manual.

• Process manager opcional (systemd --user/launchd) pra subir o daemon no login — hoje é sempre manual (scoutbook start).