# 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).

## Setup

```bash
npm install
npm run build
```

Para desenvolver com reload:

```bash
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.

```bash
# 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`.

```json
{
  "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.

```json
{
  "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:

```markdown
---
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`).