Lumina Docs

Um sistema inteligente de gerenciamento de documentos estruturados projetado para grandes modelos de linguagem.

Documentação

Lumina Docs

Um sistema inteligente de gerenciamento de documentos estruturados que utiliza o protocolo MCP, projetado especificamente para resolver o problema de estouro de tokens em documentos de requisitos de grande porte e garantir a consistência do conteúdo.

Principais Recursos

Resolvendo o Problema Central

Sou um PM e recentemente tentei usar o Claude Code para escrever documentos de requisitos em formato Markdown. O trabalho foi razoavelmente bem executado, mas à medida que o documento crescia, surgiam problemas de estouro de Tokens e a estrutura do documento se tornava extremamente confusa. Felizmente, documentos de requisitos são documentos estruturados — ao escrevê-los, muitas vezes precisamos focar apenas na parte que está sendo editada no momento, sem a necessidade de ler o documento inteiro a cada vez. Foi com essa ideia em mente que usei o Claude Code para criar este MCP Server, que resolve os seguintes problemas:

✅ Resolve o problema de estouro de tokens em documentos grandes
✅ Garante consistência de conteúdo por meio de consultas estruturadas
✅ Suporta gerenciamento modular de documentos
✅ Referência inteligente de conteúdo e correspondência de padrões

Esta é uma solução especialmente projetada para grandes modelos de linguagem!!!!

Características Técnicas

Design de banco de dados leve baseado em SQLite
Interface padronizada do protocolo MCP
Gerenciamento de relacionamentos hierárquicos pai-filho
Suporte flexível a metadados
Poderosa capacidade de consulta estruturada
Escrito inteiramente com Claude Code

Como Usar

O Lumina Docs oferece um sistema de gerenciamento de documentos simples e fácil de usar, com suporte à integração com o Claude Desktop por meio do protocolo MCP. Do ponto de vista dos cenários de uso, ele oferece suporte ao uso de grandes modelos de linguagem para processar documentos de grande porte em três cenários: leitura, atualização e escrita do zero. Especificamente:

Leitura de documentos grandes: Por meio de consultas estruturadas, localize rapidamente o conteúdo necessário, evitando carregar o documento inteiro de uma só vez. Por exemplo, para documentos de requisitos de módulos de front-end, é possível consultar diretamente todas as descrições de fluxos de negócios e regras de exibição de dados relacionadas, sem precisar navegar pelo documento inteiro.
Atualização de conteúdo existente: Ao modificar um módulo funcional, é possível consultar diretamente os fluxos de negócios e regras de exibição de dados relacionados, garantindo que as alterações sigam os formatos e padrões de conteúdo existentes. Por exemplo, ao atualizar a funcionalidade de estatísticas de status do sistema, o grande modelo de linguagem pode primeiro localizar diretamente o conteúdo a ser modificado via SQL, evitando carregar todo o documento.
Escrita de novo conteúdo do zero: Ao escrever novas descrições de fluxos de negócios, é possível consultar os padrões existentes para garantir que o novo conteúdo seja consistente com o conteúdo atual. Por exemplo, ao escrever uma nova descrição de fluxo de negócios, o grande modelo de linguagem pode primeiro consultar todas as descrições existentes, analisar seu formato e conteúdo, e então criar novos nós seguindo o mesmo formato e padrões de conteúdo.

Início Rápido

1. Instalar dependências

# 克隆或下载项目
git clone <repository-url>
cd lumina-docs

# 安装依赖
pip install -e .

2. Configurar variáveis de ambiente (opcional)

# 复制环境变量模板
cp .env.example .env

# 编辑配置文件（可选，使用默认配置可直接跳过）
nano .env

3. Configurar o Claude Desktop

Método 1: Instalação automática (recomendado)

# 自动配置到Claude Desktop
./install_to_claude_desktop.sh

Método 2: Configuração manual

Se a instalação automática apresentar problemas, você pode configurar manualmente. Primeiro, determine o caminho do seu Python:

# 查找 Python 路径
which python3
# 或者如果使用 conda
which python

Em seguida, edite o arquivo de configuração do Claude Desktop:

{
  "mcpServers": {
    "lumina-docs": {
      "command": "/usr/bin/python3",
      "args": ["-m", "doc_manager"],
      "cwd": "/path/to/lumina-docs",
      "env": {
        "PYTHONPATH": "/path/to/lumina-docs/src",
        "DOC_MANAGER_DB_PATH": "/path/to/lumina-docs/database/documents.db",
        "DOC_MANAGER_EXPORT_DIR": "/path/to/exports",
        "DOC_MANAGER_DATA_DIR": "/path/to/lumina-docs",
        "LUMINA_DOCS_SERVER_NAME": "lumina-docs",
        "DOC_MANAGER_DEBUG": "false",
        "DOC_MANAGER_LOG_LEVEL": "INFO"
      }
    }
  }
}

6. Usar a ferramenta de linha de comando

# 查看文档树结构
python -m doc_manager.cli tree

# 搜索特定类型的节点
python -m doc_manager.cli by-type business_flow

# 导出为Markdown
python -m doc_manager.cli export --output requirements.md

Instruções de Configuração

Configuração de Variáveis de Ambiente

O Lumina Docs suporta configuração por meio de variáveis de ambiente, tornando o projeto mais flexível e adequado a diferentes ambientes de implantação.

Itens de Configuração Principais

Variável de Ambiente	Valor Padrão	Descrição
`DOC_MANAGER_DB_PATH`	`<data_dir>/database/documents.db`	Caminho do arquivo do banco de dados SQLite
`DOC_MANAGER_EXPORT_DIR`	`~/Desktop`	Diretório de salvamento de arquivos exportados
`DOC_MANAGER_DATA_DIR`	`~/.lumina-docs`	Diretório raiz dos arquivos de dados
`LUMINA_DOCS_SERVER_NAME`	`lumina-docs`	Nome do servidor MCP
`DOC_MANAGER_DEBUG`	`false`	Interruptor do modo de depuração
`DOC_MANAGER_LOG_LEVEL`	`INFO`	Nível de registro de log

Métodos de Configuração

Método 1: Usar arquivo .env

# 复制模板文件
cp .env.example .env

# 编辑配置
DOC_MANAGER_DB_PATH=/path/to/your/database.db
DOC_MANAGER_EXPORT_DIR=/path/to/exports
DOC_MANAGER_DEBUG=true

Método 2: Variáveis de ambiente do sistema

export DOC_MANAGER_DB_PATH="/var/lib/doc-manager/documents.db"
export DOC_MANAGER_EXPORT_DIR="/home/user/Documents/exports"

Método 3: Configuração do Claude Desktop

{
  "mcpServers": {
    "lumina-docs": {
      "command": "/usr/bin/python3",
      "args": ["-m", "doc_manager"],
      "cwd": "/path/to/lumina-docs",
      "env": {
        "PYTHONPATH": "/path/to/lumina-docs/src",
        "DOC_MANAGER_DB_PATH": "/path/to/lumina-docs/database/documents.db",
        "DOC_MANAGER_EXPORT_DIR": "/path/to/exports",
        "DOC_MANAGER_DATA_DIR": "/path/to/lumina-docs",
        "LUMINA_DOCS_SERVER_NAME": "lumina-docs",
        "DOC_MANAGER_DEBUG": "false",
        "DOC_MANAGER_LOG_LEVEL": "INFO"
      }
    }
  }
}

Observação: Use o caminho real do Python no seu sistema, como /usr/bin/python3, /usr/local/bin/python3 ou o caminho completo do ambiente conda.

Verificação da Configuração

Após a configuração, você pode verificar das seguintes formas:

Reiniciar o Claude Desktop
Verificar o arquivo de log, confirmando que não há erros
Testar no Claude Desktop:
```
请获取当前所有文档列表
```

Verificar as ferramentas disponíveis:

document-manager 有哪些可用的工具？

Modelos de Arquivos de Configuração

O projeto fornece vários modelos de arquivos de configuração, que podem ser escolhidos de acordo com seu ambiente:

claude_desktop_config.example.json - Modelo genérico
claude_desktop_config.macos.json - Configuração do Python do sistema macOS
claude_desktop_config.conda.json - Configuração do ambiente Conda
claude_desktop_config.multi.json - Exemplo de configuração com múltiplos servidores MCP

Como usar:

# 复制合适的模板
cp claude_desktop_config.macos.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

# 编辑路径
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Conceitos Principais

Tipos de Nós de Documento

document_root: Nó raiz do documento
section: Seção (como visão geral do projeto, descrição de requisitos)
module: Módulo funcional (como módulo de visão geral, módulo de monitoramento do sistema)
feature: Funcionalidade específica (como funcionalidade de estatísticas de status do sistema)
business_flow: Descrição do fluxo de negócios
data_display_rules: Regras de exibição de dados
permission_rules: Regras de controle de permissão
architecture_design: Design de arquitetura

Relacionamento Hierárquico

智能运维系统需求文档 (document_root)
├── 项目概述 (section)
├── 功能模块 (section)
│   ├── 总览模块 (module)
│   │   ├── 系统状态统计功能 (feature)
│   │   │   ├── 业务流程说明 (business_flow)
│   │   │   └── 数据展示规则 (data_display_rules)
│   │   └── 我关注的系统功能 (feature)
│   └── 系统监控模块 (module)
└── 权限设计 (section)

Cenários de Uso

1. Importação rápida de documentos existentes

# 通过Claude直接使用MCP工具导入单个文档
import_markdown_file("项目需求.md", "project_requirements")

# 批量导入文档目录
import_markdown_batch(["docs/*.md", "guides/**/*.md"])

2. Consulta estruturada para garantir consistência

# 查询所有【业务流程说明】作为新内容的参考
nodes = db.get_nodes_by_type("business_flow")

# 查询特定模块的所有【数据展示规则】
results = db.search_nodes(
    node_type="data_display_rules",
    metadata_filter={"module": "overview"}
)

2. Verificação de consistência ao escrever novo conteúdo

# 使用一致性检查工具
cd examples
python consistency_checker.py

3. Exportação de documentos sob demanda

# 导出完整文档
python -m doc_manager.cli export --output complete.md

# 只导出功能模块部分
python -m doc_manager.cli export --parent-id 3 --output modules.md

Lista de Ferramentas MCP

Ferramentas de Gerenciamento de Documentos

Nome da Ferramenta	Descrição da Função
`create_document`	Criar novo documento (tabela independente)
`get_documents_list`	Obter lista de todos os documentos
`delete_document`	Excluir documento e suas tabelas de dados

Ferramentas de Importação Markdown

Nome da Ferramenta	Descrição da Função
`import_markdown_file`	Importar um único arquivo Markdown, com análise automática da estrutura hierárquica
`import_markdown_batch`	Importar vários arquivos Markdown em lote, com suporte a correspondência por curingas

Ferramentas de Gerenciamento de Nós

Nome da Ferramenta	Descrição da Função
`create_node`	Criar novo nó de documento
`get_node`	Obter detalhes de um nó específico
`update_node`	Atualizar nó existente
`delete_node`	Excluir nó e seus subnós
`move_node`	Mover nó para nova posição

Ferramentas de Consulta e Exportação

Nome da Ferramenta	Descrição da Função
`get_children`	Obter lista de subnós
`search_nodes`	Buscar nós com múltiplas condições
`get_nodes_by_type`	Obter nós por tipo (análise de consistência)
`get_node_path`	Obter caminho completo do nó
`get_tree_structure`	Obter estrutura em árvore
`export_to_markdown`	Exportar no formato Markdown

Ferramenta de Linha de Comando

Operações Básicas

# 创建节点
python -m doc_manager.cli create "新功能" "feature" --parent-id 5 --content "功能描述"

# 查看节点
python -m doc_manager.cli get 1

# 更新节点
python -m doc_manager.cli update 1 --title "新标题" --content "新内容"

# 删除节点
python -m doc_manager.cli delete 1

Operações de Consulta

# 列出子节点
python -m doc_manager.cli list --parent-id 1

# 搜索节点
python -m doc_manager.cli search --query "业务流程" --type "business_flow"

# 查看树结构
python -m doc_manager.cli tree

# 按类型查找
python -m doc_manager.cli by-type data_display_rules

Operações de Exportação

# 导出完整文档
python -m doc_manager.cli export --output requirements.md

# 导出指定部分
python -m doc_manager.cli export --parent-id 3 --output modules.md

Estrutura do Projeto

doc-manager/
├── src/
│   └── doc_manager/
│       ├── __init__.py           # 模块初始化
│       ├── database.py           # SQLite数据库操作
│       ├── simple_server.py      # MCP服务器实现
│       ├── markdown_parser.py    # Markdown解析和导入模块
│       ├── cli.py                # 命令行工具
│       └── __main__.py           # 服务器启动入口
├── examples/
│   ├── sample_data.py            # 示例数据创建
│   └── consistency_checker.py    # 一致性检查工具
├── database/
│   └── documents.db              # SQLite数据库文件
├── docs/
│   └── (文档目录)
├── pyproject.toml                # 项目配置
└── README.md                     # 项目说明

Uso Avançado

1. Fluxo de trabalho para garantir consistência

Ao escrever uma nova 【Descrição de Fluxo de Negócios】:

# 1. 查询现有的业务流程说明
existing_flows = db.get_nodes_by_type("business_flow")

# 2. 分析现有模式
for flow in existing_flows:
    print(f"参考: {flow['title']}")
    print(f"格式: {flow['content'][:100]}...")

# 3. 创建新节点时遵循现有模式
new_id = db.create_node(
    title="新业务流程说明",
    node_type="business_flow", 
    content="1. 步骤一\n2. 步骤二\n3. 步骤三",  # 保持格式一致
    parent_id=parent_id
)

2. Gerenciamento orientado por metadados

# 使用元数据进行精确查询
frontend_modules = db.search_nodes(
    node_type="module",
    metadata_filter={"module_type": "frontend"}
)

high_priority_features = db.search_nodes(
    metadata_filter={"priority": "high"}
)

3. Operações em lote

# 批量更新相同类型节点的元数据
business_flows = db.get_nodes_by_type("business_flow")
for flow in business_flows:
    db.update_node(
        flow['id'],
        metadata={**flow['metadata'], "reviewed": True}
    )

Melhores Práticas

Padrão de nomenclatura: Use um formato consistente para títulos de nós
Gerenciamento de tipos: Defina node_type claros para diferentes tipos de conteúdo
Uso de metadados: Aproveite ao máximo o campo metadata para armazenar informações adicionais
Design hierárquico: Projete relacionamentos pai-filho de forma adequada, evitando aninhamentos excessivamente profundos
Verificação de consistência: Execute regularmente as ferramentas de verificação de consistência

Comparação com o Método Tradicional

Método Tradicional	Método Estruturado
Arquivo único grande	Nós modulares
Tokens facilmente estourados	Carregamento de conteúdo sob demanda
Dificuldade em garantir consistência	Referência por consulta estruturada
Alterações afetam o documento inteiro	Modificação precisa de nós específicos
Manutenção manual de formatos	Exportação e mesclagem automatizadas

Desenvolvimento e Extensão

Adicionar novos tipos de nós

Adicione um novo node_type no banco de dados
Atualize a definição do schema das ferramentas MCP
Adicione a lógica de verificação correspondente no verificador de consistência

Personalizar formatos de exportação

Herde a classe DocumentDatabase
Sobrescreva o método export_tree_to_markdown
Implemente sua lógica de formatação personalizada

Feedback de Problemas

Se tiver problemas ou sugestões, entre em contato com a equipe de desenvolvimento.