mdreview

npx add-mcp 'https://app.mdreview.space/mcp'

mdreview-service

Um microsserviço conteinerizado de revisão de markdown. Um agente envia markdown via POST, recebe uma URL de revisão para um humano e consulta feedback via HTTP. Um único serviço gerencia várias revisões, isoladas por id. Sem criação de processos por revisão, sem sistema de arquivos compartilhado com o agente.

Página inicial: mdreview.space (servida via GitHub Pages por meio de .github/workflows/pages.yml; código-fonte em web/site/).

Documentação: mdreview.space/docs: integração, guias e solução de problemas, renderizada pelo próprio renderizador de markdown do serviço (código-fonte em web/site/docs/).

Começando: hospedado ou auto-hospedado

Duas formas de usar o mdreview; escolha uma.

1. Hospedado (online). Uma instância gerenciada roda em mdreview.space (aplicativo em app.mdreview.space). Entre com qualquer endereço de e-mail (você recebe um link de uso único; não há lista de convites). Três formas de conectar seu agente.

Conector personalizado do claude.ai (sem token). No claude.ai, abra Configurações, Conectores, Adicionar conector personalizado e insira:

https://app.mdreview.space/mcp

O Claude abre o login do mdreview; insira seu e-mail, siga o link de uso único e aprove a conexão na página de consentimento. Funciona no claude.ai na web, no Desktop e no mobile. Revogue a qualquer momento na página da Conta.

Plugin do Claude Code. Dentro do Claude Code, execute:

/plugin marketplace add ranawaqas-ai/mdreview-service
/plugin install mdreview@mdreview

Ele solicita um token (gere um na página da Conta após entrar) e o mantém no seu chaveiro. As atualizações do plugin chegam por meio de /plugin update; o wrapper não se atualiza dentro de um plugin.

Instalador. Na máquina que executa seu agente (requer o CLI claude + python3), com um token da página da Conta:

curl -fsSL https://mdreview.space/install.sh | MDREVIEW_TOKEN=mdr_xxx sh

Isso busca o wrapper MCP somente com stdlib em ~/.mdreview e o registra no Claude Code no escopo do usuário; saia e reabra o Claude Code e você estará conectado. Omita MDREVIEW_TOKEN=… para ser solicitado a inseri-lo. (Para configurar manualmente ou para um cliente MCP que não seja o Claude Code, veja Servidor MCP.)

2. Auto-hospedado (local). Clone e execute você mesmo (sem conta, sem autenticação, em localhost). Veja Executar e aponte o MCP MDREVIEW_BASE do seu agente para http://localhost:8137. Este é o caminho se você quiser tudo na sua própria máquina.

Somente Python stdlib (imagem pequena, sem instalações via pip). Autocontido: os renderizadores marked, Mermaid, KaTeX, highlight.js e footnotes são incorporados e servidos de /static, então o navegador não precisa de CDN. O visualizador renderiza Markdown da mesma forma que um site Jekyll/MathJax: matemática LaTeX (inline $…$ / \(…\), display $$…$$ / \[…\]; prosa/moeda $ literal à esquerda), diagramas Mermaid, notas de rodapé GFM (refs [^id] → uma seção ordenada de referências de retorno) e código em blocos com realce de sintaxe (um tema duplo que funciona em painéis claros e escuros).

Executar

make up        # serves on http://localhost:8137
# or:
docker build -f infra/Dockerfile -t mdreview-service .
docker run -d -p 8137:8080 -v mdreview-data:/data mdreview-service

make up (compose) é o caminho canônico local com Docker; ele serve na porta 8137 e reutiliza o volume nomeado mdreview-data, então uma reconstrução/recriação preserva suas revisões.

Verificação de saúde: curl localhost:8137/healthz -> {"ok":true}.

Feedback e fonte persistem no volume /data entre reinicializações.

Migrando um contêiner legado executado manualmente

Se você tem uma instância mais antiga iniciada manualmente (docker run em uma porta não padrão, como :8139), mova-a para o fluxo canônico do compose sem perder dados: o volume mdreview-data é reutilizado como está:

docker rm -f mdreview     # stop the hand-run container (the mdreview-data volume survives)
make up                   # compose recreates it on 8137, mounting the same mdreview-data volume

Como o volume do compose agora é declarado com um name: mdreview-data explícito (não um infra_mdreview-data com prefixo de projeto), make up monta exatamente o volume que seu contêiner antigo possuía. Confirme com curl localhost:8137/healthz e verifique se suas revisões ainda estão listadas.

O fluxo

1. Agente: POST /api/reviews {markdown, title} -> {id, review_url, feedback_url, ...}
2. O agente entrega review_url a um humano.
3. O humano abre, seleciona texto ou clica em um número de parágrafo, digita anotações (salvas automaticamente).
4. O agente consulta GET /api/reviews/{id}/status e depois GET /api/reviews/{id}/feedback.
5. O agente aplica edições e PUT /api/reviews/{id}/source {markdown} -> a página do humano recarrega ao vivo e as notas abordadas são riscadas. Repita conforme necessário.

Configuração (env)

Var	Padrão	Significado
PORT	8080	porta de escuta no contêiner
MDREVIEW_DATA	/data	diretório de armazenamento (monte um volume)
MDREVIEW_PUBLIC_BASE	vazio	se definido (ex.: https://review.example.com), review_url/feedback_url o usam; caso contrário, o cabeçalho Host da solicitação é usado
MDREVIEW_ENABLE_LATEX	desativado	opt-in: habilita o modo de revisão de artigos LaTeX (veja abaixo). Requer a imagem mdreview-service-latex (Tectonic); a imagem slim padrão não tem ferramentas LaTeX

Guias do operador

Os runbooks que costumavam ficar aqui foram movidos para que esta página permaneça legível:

Guia	O que cobre
API HTTP	Cada rota, formato de solicitação e resposta
Servidor MCP	Executar o servidor stdio, testes de fumaça
Revisão de artigos LaTeX	Habilitar, modelos, loop de compilação, runbook da imagem
Watcher	O watcher do agente, modo de base confiável, execuções conteinerizadas
Sistema de design	§01-§10, as regras de UI que os tickets citam
Execuções autônomas	Como os agentes enviam mudanças aqui

Notas

• Multi-tenant por id, então revisões concorrentes nunca colidem. Sem autenticação (destinado a redes confiáveis/locais); coloque atrás de um proxy reverso com autenticação se for expor.
• O painel (/) e GET /api/reviews listam todas as revisões: ok para a postura de rede confiável, mas um motivo para manter autenticação na frente quando exposto.
• O wrapper MCP acima foi projetado em docs/future-mcp.md, mantido como registro de design/decisão.
• Para detalhes de integração do agente, veja CLAUDE.md.
• Uma versão CLI não-Docker, por arquivo, vive em ../mdreview (escreve feedback em um arquivo ao lado da fonte). Este serviço é a forma em rede e multi-sessão.

Licença

Licença Apache 2.0.

Política de Privacidade

O serviço hospedado em app.mdreview.space armazena seu e-mail de conta, suas revisões e comentários e registros de segurança de login. Não usa cookies de análise ou rastreamento, não vende seus dados e não os usa para treinar modelos de IA. A política completa, incluindo retenção, exclusão e serviços de terceiros, está em https://mdreview.space/privacy/. Perguntas vão para rana.waqas.works@gmail.com. Uma instância auto-hospedada mantém todos os dados na sua máquina.