Skip to main content
Glama
Joilson-Julkoski

scoutbook

by Joilson-Julkoski
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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

Available Tools

3 tools
list_handbookListar handbookA

Lista todos os documentos do handbook do time (título, resumo e tags). Use isto primeiro para descobrir o que existe antes de ler ou buscar.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It describes the operation as listing documents with their metadata, implying a read-only behavior. It does not explicitly state non-destructiveness, but given the function name and sibling tools, it is reasonably transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences: the first states the action and result, the second provides usage guidance. No unnecessary words; every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters, no output schema, and a simple list operation, the description is complete. It covers purpose, return content, and usage sequence relative to siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, and schema coverage is 100%. The description does not need to add parameter semantics. Baseline for zero parameters is 4, and no extra detail is required.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Lista' (lists) and the resource 'todos os documentos do handbook do time' with specific fields (título, resumo, tags). It also distinguishes from siblings by advising to use this first before reading or searching.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use isto primeiro' (use this first) and contrasts with 'antes de ler ou buscar' (before reading or searching), providing clear guidance on when to use this tool versus its siblings read_handbook_doc and search_handbook.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_handbook_docLer documento do handbookA

Lê o conteúdo completo de um documento do handbook pelo seu id (o caminho relativo mostrado em list_handbook, ex: 'deploy.md').

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesId do documento — caminho relativo, ex: 'ci-cd.md'.

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It states 'reads full content' but does not disclose any behavioral traits beyond that (e.g., return format, potential errors, or that it's a read-only operation). Adequate but not informative.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is one sentence, clear, and front-loaded with the action. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, description lacks explicit return value format, but 'conteúdo completo' implies full document text. Overall adequate for a simple read tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and description repeats the parameter info without adding new meaning. Baseline is 3; no extra value added.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool reads the full content of a handbook document by its id, referencing sibling tool list_handbook for obtaining the id. It distinguishes itself from siblings (list_handbook lists, search_handbook searches).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description provides an example of id format and references list_handbook to get the id, implying use after listing. However, it does not explicitly state when to use this tool versus alternatives or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_handbookBuscar no handbookA

Busca por palavras-chave em todos os documentos do handbook e retorna os mais relevantes com trechos de contexto. Use para responder 'como o time faz X' quando não souber em qual documento está.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesTermos de busca, ex: 'como fazer deploy em produção'.

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must disclose behavior. It states returns 'mais relevantes com trechos de contexto', but does not detail pagination, sorting, or error handling. Adequate but lacks depth for a search tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no unnecessary words, front-loads the core action. Every sentence is purposeful and concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given only one parameter and no output schema, the description covers search scope, result type, and usage scenario. Could mention limitations like precision of search, but fairly complete for the complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a single parameter description. The description adds slight context about use case, but no additional semantic value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Busca por palavras-chave' and resource 'todos os documentos do handbook', distinguishing it from siblings list_handbook and read_handbook_doc which serve different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use: 'Use para responder como o time faz X quando não souber em qual documento está'. Does not mention when not to use or alternatives, but the context with siblings implies when to use the others.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedlist_handbook
    • First observedread_handbook_doc
    • First observedsearch_handbook
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: listing all documents, reading a specific document by ID, and searching across documents. No ambiguity.

Naming Consistency5/5

All tool names follow the same verb_noun pattern in snake_case (list_handbook, read_handbook_doc, search_handbook), making them predictable and consistent.

Tool Count5/5

Three tools is well-scoped for a handbook server, covering the essential operations without being overly minimal or excessive.

Completeness5/5

The tool set covers the full lifecycle expected for a read-only handbook: discover (list), retrieve (read), and search. No obvious gaps.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Dev Notes MCP Server

    al928132
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables Claude Code to save, list, and read markdown notes directly from conversations, eliminating manual file management for project ideas, debugging notes, and meeting summaries.
    -

  • vault-mcp-server

    thebackpackdevorg
    A
    license
    Not graded
    quality
    D
    maintenance
    Turns any folder of Markdown files into a searchable, structured knowledge base for Claude Code, enabling persistent memory across sessions via tools like list, read, write, edit, search, and summarize.
    MIT