Lumina Docs

Un sistema inteligente de gestión de documentos estructurados diseñado para modelos de lenguaje de gran escala.

Documentación

Lumina Docs

Un sistema inteligente de gestión de documentos estructurados que utiliza el protocolo MCP, diseñado específicamente para resolver el problema de tokens excesivamente largos en documentos de requisitos de gran tamaño y garantizar la consistencia del contenido.

Características principales

Problema central que resuelve

Soy un PM y recientemente intenté usar Claude Code para redactar documentos de requisitos en formato Markdown. El trabajo se completaba razonablemente bien, pero cuando el documento crecía en tamaño, surgía el problema de exceder el límite de tokens y la estructura del documento se volvía extremadamente caótica. Afortunadamente, los documentos de requisitos son documentos estructurados: al redactarlos, normalmente solo es necesario centrarse en la parte que se está editando actualmente, sin necesidad de leer todo el documento cada vez. Bajo esta idea, utilicé Claude Code para crear este MCP Server, que puede resolver los siguientes problemas:

✅ Resuelve el problema de tokens excesivamente largos en documentos grandes
✅ Garantiza la consistencia del contenido mediante consultas estructuradas
✅ Admite gestión modular de documentos
✅ Referencia inteligente de contenido y coincidencia de patrones

¡¡¡¡Esta es una solución diseñada específicamente para grandes modelos de lenguaje!!!!

Características técnicas

Diseño de base de datos ligera basada en SQLite
Interfaz estandarizada del protocolo MCP
Gestión de relaciones jerárquicas padre-hijo
Soporte flexible de metadatos
Potente capacidad de consulta estructurada
Escrito íntegramente con Claude Code

Cómo usar

Lumina Docs proporciona un sistema de gestión de documentos sencillo y fácil de usar que admite integración con Claude Desktop mediante el protocolo MCP. Desde la perspectiva de los casos de uso, ofrece soporte para el procesamiento de documentos a gran escala con grandes modelos de lenguaje en tres escenarios: lectura, actualización y redacción desde cero. Específicamente:

Lectura de documentos grandes: mediante consultas estructuradas, localiza rápidamente el contenido necesario, evitando cargar todo el documento de una sola vez. Por ejemplo, para un documento de requisitos del módulo frontend, se pueden consultar directamente todas las descripciones de flujos de negocio y reglas de visualización de datos relacionadas, sin necesidad de revisar todo el documento.
Actualización de contenido existente: al modificar un módulo funcional, se pueden consultar directamente los flujos de negocio y las reglas de visualización de datos relacionados, garantizando que las modificaciones sigan los formatos y estándares de contenido existentes. Por ejemplo, al actualizar la función de estadísticas de estado del sistema, se puede hacer que el gran modelo de lenguaje localice directamente el contenido a modificar mediante SQL, evitando cargar todo el documento de una vez.
Redacción de contenido nuevo desde cero: al redactar nuevas descripciones de flujos de negocio, se pueden consultar los patrones existentes para garantizar que el contenido nuevo sea coherente con el existente. Por ejemplo, al redactar una nueva descripción de flujo de negocio, se puede hacer que el gran modelo de lenguaje consulte todas las descripciones de flujos de negocio existentes, analice su formato y contenido, y luego cree el nuevo nodo siguiendo el mismo formato y estándares de contenido.

Inicio rápido

1. Instalar dependencias

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

# 安装依赖
pip install -e .

2. Configurar variables de entorno (opcional)

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

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

3. Configurar Claude Desktop

Método 1: Instalación automática (recomendado)

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

Método 2: Configuración manual

Si la instalación automática presenta problemas, puedes configurarlo manualmente. Primero, determina tu ruta de Python:

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

Luego edita el archivo de configuración de 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 herramientas de línea de comandos

# 查看文档树结构
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

Configuración

Configuración de variables de entorno

Lumina Docs admite configuración mediante variables de entorno, lo que hace que el proyecto sea más flexible y más adecuado para diferentes entornos de despliegue.

Elementos de configuración principales

Variable de entorno	Valor predeterminado	Descripción
`DOC_MANAGER_DB_PATH`	`<data_dir>/database/documents.db`	Ruta del archivo de base de datos SQLite
`DOC_MANAGER_EXPORT_DIR`	`~/Desktop`	Directorio de guardado de archivos exportados
`DOC_MANAGER_DATA_DIR`	`~/.lumina-docs`	Directorio raíz de archivos de datos
`LUMINA_DOCS_SERVER_NAME`	`lumina-docs`	Nombre del servidor MCP
`DOC_MANAGER_DEBUG`	`false`	Interruptor de modo de depuración
`DOC_MANAGER_LOG_LEVEL`	`INFO`	Nivel de registro

Métodos de configuración

Método 1: Usar archivo .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: Variables de entorno del sistema

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

Método 3: Configuración de 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"
      }
    }
  }
}

Nota: Utiliza la ruta real de Python en tu sistema, como /usr/bin/python3, /usr/local/bin/python3 o la ruta completa del entorno conda.

Verificación de configuración

Una vez completada la configuración, puedes verificarla de las siguientes maneras:

Reiniciar Claude Desktop
Revisar los archivos de registro para confirmar que no hay errores
Probar en Claude Desktop:
```
请获取当前所有文档列表
```

Verificar las herramientas disponibles:

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

Plantillas de archivos de configuración

El proyecto proporciona varias plantillas de archivos de configuración; puedes elegir según tu entorno:

claude_desktop_config.example.json - Plantilla general
claude_desktop_config.macos.json - Configuración de Python del sistema macOS
claude_desktop_config.conda.json - Configuración de entorno Conda
claude_desktop_config.multi.json - Ejemplo de configuración de múltiples servidores MCP

Cómo usarlas:

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

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

Conceptos principales

Tipos de nodos de documento

document_root: Nodo raíz del documento
section: Sección (como resumen del proyecto, especificación de requisitos)
module: Módulo funcional (como módulo de visión general, módulo de monitoreo del sistema)
feature: Función específica (como la función de estadísticas de estado del sistema)
business_flow: Descripción del flujo de negocio
data_display_rules: Reglas de visualización de datos
permission_rules: Reglas de control de permisos
architecture_design: Diseño de arquitectura

Relaciones jerárquicas

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

Casos de uso

1. Importar rápidamente documentos existentes

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

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

2. Consultas estructuradas para garantizar la consistencia

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

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

2. Verificación de consistencia al redactar contenido nuevo

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

3. Exportar documentos según necesidad

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

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

Lista de herramientas MCP

Herramientas de gestión de documentos

Nombre de la herramienta	Descripción
`create_document`	Crear un nuevo documento (tabla independiente)
`get_documents_list`	Obtener la lista de todos los documentos
`delete_document`	Eliminar un documento y su tabla de datos

Herramientas de importación de Markdown

Nombre de la herramienta	Descripción
`import_markdown_file`	Importar un único archivo Markdown, analizando automáticamente la estructura jerárquica
`import_markdown_batch`	Importar archivos Markdown por lotes, con soporte de coincidencia de comodines

Herramientas de gestión de nodos

Nombre de la herramienta	Descripción
`create_node`	Crear un nuevo nodo de documento
`get_node`	Obtener los detalles de un nodo específico
`update_node`	Actualizar un nodo existente
`delete_node`	Eliminar un nodo y sus nodos secundarios
`move_node`	Mover un nodo a una nueva posición

Herramientas de consulta y exportación

Nombre de la herramienta	Descripción
`get_children`	Obtener la lista de nodos secundarios
`search_nodes`	Buscar nodos con múltiples criterios
`get_nodes_by_type`	Obtener nodos por tipo (análisis de consistencia)
`get_node_path`	Obtener la ruta completa de un nodo
`get_tree_structure`	Obtener la estructura de árbol
`export_to_markdown`	Exportar en formato Markdown

Herramientas de línea de comandos

Operaciones 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

Operaciones 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

Operaciones de exportación

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

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

Estructura del proyecto

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 avanzado

1. Flujo de trabajo de garantía de consistencia

Al redactar una nueva 【Descripción de flujo de negocio】:

# 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. Gestión basada en metadatos

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

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

3. Operaciones por lotes

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

Mejores prácticas

Convenciones de nomenclatura: utiliza un formato coherente para los títulos de los nodos
Gestión de tipos: define node_type claros para diferentes tipos de contenido
Uso de metadatos: aprovecha al máximo el campo metadata para almacenar información adicional
Diseño jerárquico: diseña las relaciones padre-hijo de forma razonable, evitando anidamientos demasiado profundos
Verificación de consistencia: ejecuta periódicamente las herramientas de verificación de consistencia

Comparación con el enfoque tradicional

Enfoque tradicional	Enfoque estructurado
Archivo único grande	Nodos modulares
Tokens fácilmente excesivos	Carga de contenido bajo demanda
Difícil garantizar consistencia	Referencia mediante consultas estructuradas
Las modificaciones afectan a todo el documento	Modificación precisa de nodos específicos
Mantenimiento manual del formato	Exportación y fusión automatizadas

Desarrollo y extensión

Añadir nuevos tipos de nodo

Añadir un nuevo node_type en la base de datos
Actualizar la definición del schema de las herramientas MCP
Añadir la lógica de verificación correspondiente en el verificador de consistencia

Personalizar el formato de exportación

Heredar de la clase DocumentDatabase
Sobrescribir el método export_tree_to_markdown
Implementar la lógica de formato personalizada

Comentarios y soporte

Si tienes problemas o sugerencias, contacta con el equipo de desarrollo.