Codedoc 📚🤖

English | Português

English

Codedoc is a lightweight, zero-configuration live documentation scanner and Model Context Protocol (MCP) server for TypeScript and NestJS projects. It automatically parses annotations embedded in your codebase to build an interactive engineering web portal and exposes your architecture to AI coding assistants (like Claude, Cursor, etc.).

Features

• Live Scanning: Recursively scans code files for /* Codedoc comment blocks and extracts metadata (titles, descriptions, tags, attention flags).
• Dual Mode Serving:
  • Standalone Server: Run it in any project folder using npx codedoc start to serve the HTML portal and MCP server over SSE.
  • Embedded NestJS Module: Import it directly as a NestJS Module (CodeDocModule) to start automatically with your host application.
• Built-in zrok Tunneling: Share your local documentation and MCP server securely on the internet with a single flag (--zrok) to plug into external AI agents.
• Full MCP Compliance: Exposes tools for LLMs to query and read codebase documentation (get_config, list_documented_files, get_file_source, search_by_tag).

How to Write Documentation (Manual Usage)

To manually document any TypeScript file, add a structured /* Codedoc block comment at the very top of the file:

/* Codedoc
 * @title <User Friendly Title>
 * @description <Clear description of the component functionality and dependencies>
 * @tags <comma-separated list of keywords, layers, or technologies>
 */

Specification Fields:

1. @title: A human-readable name of the file or component. If omitted, the scanner defaults to the file name.
2. @description: A paragraph summarizing what the code does, its main endpoints, dependencies, and integration behaviors.
3. @tags: Comma-separated tags used for filtering the dashboard and querying via the MCP server (e.g. auth, service, webhook, kafka, s3).
4. #important: Place this hashtag anywhere in the code comments to signal a crucial developer note. The scanner counts and highlights these occurrences (e.g. // #important: Cache must be invalidated upon session renewal).

Configuration (.codedoc)

Create a .codedoc JSON file in the root of your project:

{
  "title": "Arquitetura Meli Adapter",
  "subtitle": "Engineering Portal",
  "description": "System architecture and notification flows.",
  "srcDirs": ["src"],
  "excludePatterns": ["node_modules", "dist"],
  "port": 3018,
  "mcpEnabled": true
}

Usage

1. Standalone CLI mode

Start the standalone server on any directory containing a .codedoc configuration:

# Starts web portal on http://localhost:3018/codedoc
npx codedoc start

# Run on custom port
npx codedoc start --port 4000

# Start server and automatically share to the internet using zrok tunnel
npx codedoc start --zrok

2. Auto-Generation mode (AI)

Automatically write Codedoc comments for your source files:

# Auto-document using local logged-in Cursor Agent CLI (no API keys required)
npx codedoc generate --cursor

# Target a specific file or directory
npx codedoc generate --file src/auth/auth.service.ts --cursor
npx codedoc generate --dir src/notifications --cursor

# Auto-document using cloud APIs directly (requires API keys)
export GEMINI_API_KEY="your-api-key"
npx codedoc generate --gemini

# Document only specific layers (high | medium | low)
npx codedoc generate --level medium --cursor

# Force re-generation of documentation
npx codedoc generate --force --cursor

3. Embedded NestJS mode

Import Codedoc in your main app.module.ts:

import { Module } from '@nestjs/common';
import { CodeDocModule } from '@hewodigital/codedoc';

@Module({
  imports: [CodeDocModule],
})
export class AppModule {}

Codedoc will be served directly under your NestJS server instance at http://localhost:<nest_port>/codedoc.

4. Git Hooks Automation (Husky)

To keep documentation updated automatically upon every commit without developer friction, configure Husky to run Codedoc generation on staged files:

1. Install Husky and lint-staged:

npm install husky lint-staged --save-dev
npx husky init

2. Configure .lintstagedrc.json in your project root:

{
  "src/**/*.ts": [
    "npx codedoc generate --cursor --file"
  ]
}

3. Add the pre-commit hook trigger to .husky/pre-commit:

npx lint-staged

Connecting External AI Agents (MCP)

When sharing Codedoc using --zrok, you will receive a public URL. Plug it directly into your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "codedoc": {
      "url": "https://<subdomain>.share.zrok.io/codedoc/mcp/sse"
    }
  }
}

Português

O Codedoc é um escaneador de documentação viva e servidor Model Context Protocol (MCP) leve e sem necessidade de configurações complexas para projetos TypeScript e NestJS. Ele analisa anotações inseridas diretamente no código para construir um portal de engenharia interativo e expõe sua arquitetura para assistentes de IA (como Claude, Cursor, etc.).

Recursos

• Varredura Automática (Live): Varre recursivamente arquivos de código em busca de comentários /* Codedoc e extrai metadados (título, descrição, tags, pontos de atenção).
• Modo de Execução Duplo:
  • Servidor Autônomo (Standalone): Rode em qualquer pasta de projeto com npx codedoc start para subir o portal HTML e o servidor MCP via SSE.
  • Módulo NestJS Integrado: Importe o módulo (CodeDocModule) para que o portal e o MCP rodem embutidos na inicialização do seu app.
• Túnel zrok Embutido: Exponha sua documentação local e o servidor MCP na internet com um único comando (--zrok) para conectar com agentes externos.
• Compatibilidade MCP: Ferramentas prontas para que as IAs listem e leiam o código documentado (get_config, list_documented_files, get_file_source, search_by_tag).

Como Escrever a Documentação (Uso Manual)

Para documentar manualmente qualquer arquivo TypeScript, insira um comentário formatado /* Codedoc no topo do arquivo:

/* Codedoc
 * @title <Título Amigável do Componente>
 * @description <Descrição detalhada do papel e comportamento do código na arquitetura>
 * @tags <lista de tags, camadas ou tecnologias separadas por vírgula>
 */

Especificação de Campos:

1. @title: Nome amigável do arquivo/componente. Se omitido, a varredura usará o próprio nome do arquivo físico.
2. @description: Um parágrafo resumindo as responsabilidades do código, integrações e dependências.
3. @tags: Tags separadas por vírgula usadas para filtrar o painel e realizar buscas através do servidor MCP (ex: auth, service, webhook, kafka, s3).
4. #important: Insira esta hashtag em qualquer comentário ao longo do arquivo para marcar pontos de atenção crítica para os devs. O Codedoc compila e destaca essas marcas (ex: // #important: O token expira a cada 6 horas).

Configuração (.codedoc)

Crie o arquivo .codedoc em formato JSON na raiz do seu projeto:

{
  "title": "Arquitetura Meli Adapter",
  "subtitle": "Portal de Engenharia",
  "description": "Fluxos de notificações e arquitetura do sistema.",
  "srcDirs": ["src"],
  "excludePatterns": ["node_modules", "dist"],
  "port": 3018,
  "mcpEnabled": true
}

Como Executar

1. Modo CLI Autônomo (Standalone)

Inicie o servidor de documentação isolado a partir de qualquer pasta que possua um arquivo .codedoc:

# Inicia o portal em http://localhost:3018/codedoc
npx codedoc start

# Executa em porta customizada
npx codedoc start --port 4000

# Inicia o servidor e cria automaticamente um túnel público na internet usando zrok
npx codedoc start --zrok

2. Modo Geração Automática (IA)

Escreva documentação automaticamente usando modelos de Inteligência Artificial:

# Gera documentação usando o Cursor Agent CLI local (não precisa de chaves API)
npx codedoc generate --cursor

# Especifica um arquivo ou diretório alvo
npx codedoc generate --file src/auth/auth.service.ts --cursor
npx codedoc generate --dir src/notifications --cursor

# Gera documentação consumindo as APIs de nuvem diretamente (requer chaves)
export GEMINI_API_KEY="sua-chave-api"
npx codedoc generate --gemini

# Documenta apenas arquivos de certas camadas (--level high | medium | low)
npx codedoc generate --level medium --cursor

# Força a re-geração de blocos existentes
npx codedoc generate --force --cursor

3. Modo Embutido no NestJS

Importe o Codedoc no seu app.module.ts principal:

import { Module } from '@nestjs/common';
import { CodeDocModule } from '@hewodigital/codedoc';

@Module({
  imports: [CodeDocModule],
})
export class AppModule {}

O portal ficará disponível na porta do seu servidor NestJS em http://localhost:<nest_port>/codedoc.

4. Automação com Git Hooks (Husky)

Para manter as especificações e documentações sempre atualizadas de forma transparente a cada commit, você pode integrar o Codedoc com o Husky e lint-staged:

1. Instale o Husky e lint-staged:

npm install husky lint-staged --save-dev
npx husky init

2. Crie/edite o arquivo .lintstagedrc.json na raiz do projeto:

{
  "src/**/*.ts": [
    "npx codedoc generate --cursor --file"
  ]
}

3. Adicione o gatilho de pre-commit no arquivo .husky/pre-commit:

npx lint-staged

Conectando Agentes de IA Externos (MCP)

Ao compartilhar o Codedoc via --zrok, você receberá uma URL pública. Configure-a no arquivo de perfil do seu cliente MCP (como o claude_desktop_config.json do Claude Desktop):

{
  "mcpServers": {
    "codedoc": {
      "url": "https://<subdomain>.share.zrok.io/codedoc/mcp/sse"
    }
  }
}