{"id":28918353,"url":"https://github.com/gaozyun/lumina-docs","last_synced_at":"2026-05-09T19:32:33.937Z","repository":{"id":300171100,"uuid":"1004930869","full_name":"GaoZYun/lumina-docs","owner":"GaoZYun","description":"Intelligent structured document management system using MCP protocol - solving token overflow for large language models","archived":false,"fork":false,"pushed_at":"2025-06-20T07:13:10.000Z","size":60,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-20T08:26:21.882Z","etag":null,"topics":["document-management","llm","mcp","mcp-server","python","sqlite","stuctured-document"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GaoZYun.png","metadata":{"files":{"readme":"README.en.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2025-06-19T11:58:02.000Z","updated_at":"2025-06-20T07:13:13.000Z","dependencies_parsed_at":"2025-06-20T08:26:50.043Z","dependency_job_id":"1bca5df0-7f83-4ec6-b34d-e5ac1ad5d598","html_url":"https://github.com/GaoZYun/lumina-docs","commit_stats":null,"previous_names":["gaozyun/lumina-docs"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/GaoZYun/lumina-docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GaoZYun%2Flumina-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GaoZYun%2Flumina-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GaoZYun%2Flumina-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GaoZYun%2Flumina-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GaoZYun","download_url":"https://codeload.github.com/GaoZYun/lumina-docs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GaoZYun%2Flumina-docs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261224293,"owners_count":23126930,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["document-management","llm","mcp","mcp-server","python","sqlite","stuctured-document"],"created_at":"2025-06-22T02:02:46.198Z","updated_at":"2026-05-09T19:32:33.929Z","avatar_url":"https://github.com/GaoZYun.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lumina Docs\n\n[中文](README.md) | **English**\n\nAn intelligent structured document management system using the MCP protocol, designed to solve token overflow issues in large requirement documents and ensure content consistency.\n\n## Core Features\n\n**Solving Core Problems**\n\nAs a PM, I recently tried using Claude Code to write Markdown requirement documents. It worked well, but when the document scale grew larger, it would cause token overflow issues and make the document structure extremely chaotic.\nFortunately, requirement documents are structured documents. When writing, you often only need to focus on the part currently being edited, without needing to read the entire document every time. Based on this idea, I used Claude Code to create this MCP Server, which can solve the following problems:\n- ✅ Solve large document token overflow issues\n- ✅ Ensure content consistency through structured queries  \n- ✅ Support modular document management\n- ✅ Intelligent content reference and pattern matching\n\n**This is a solution specifically customized for large language models!!!!**\n\n**Technical Features**\n- Lightweight database design based on SQLite\n- Standardized interface using MCP protocol\n- Parent-child hierarchical relationship management\n- Flexible metadata support\n- Powerful structured query capabilities\n- Written entirely with Claude Code\n\n## Quick Start\n\n### 1. Install Dependencies\n```bash\n# Clone or download the project\ngit clone \u003crepository-url\u003e\ncd doc-manager\n\n# Install dependencies\npip install -e .\n```\n\n### 2. Configure Environment Variables (Optional)\n```bash\n# Copy environment variable template\ncp .env.example .env\n\n# Edit configuration file (optional, you can skip this to use default configuration)\nnano .env\n```\n\n### 3. Configure Claude Desktop\n#### Method 1: Automatic Installation (Recommended)\n```bash\n# Automatically configure to Claude Desktop\n./install_to_claude_desktop.sh\n```\n\n#### Method 2: Manual Configuration\nIf automatic installation encounters issues, you can configure manually. First determine your Python path:\n```bash\n# Find Python path\nwhich python3\n# Or if using conda\nwhich python\n```\n\nThen edit the Claude Desktop configuration file:\n```json\n{\n  \"mcpServers\": {\n    \"lumina-docs\": {\n      \"command\": \"/usr/bin/python3\",\n      \"args\": [\"-m\", \"doc_manager\"],\n      \"cwd\": \"/path/to/doc-manager\",\n      \"env\": {\n        \"PYTHONPATH\": \"/path/to/doc-manager/src\",\n        \"DOC_MANAGER_DB_PATH\": \"/path/to/doc-manager/database/documents.db\",\n        \"DOC_MANAGER_EXPORT_DIR\": \"/path/to/exports\",\n        \"DOC_MANAGER_DATA_DIR\": \"/path/to/doc-manager\",\n        \"LUMINA_DOCS_SERVER_NAME\": \"lumina-docs\",\n        \"DOC_MANAGER_DEBUG\": \"false\",\n        \"DOC_MANAGER_LOG_LEVEL\": \"INFO\"\n      }\n    }\n  }\n}\n```\n\n### 4. Use Command Line Tools\n```bash\n# View document tree structure\npython -m doc_manager.cli tree\n\n# Search for specific types of nodes\npython -m doc_manager.cli by-type business_flow\n\n# Export to Markdown\npython -m doc_manager.cli export --output requirements.md\n```\n\n## Configuration Guide\n\n### Environment Variable Configuration\n\nLumina Docs supports configuration through environment variables, making the project more flexible and suitable for different deployment environments.\n\n#### Core Configuration Items\n\n| Environment Variable | Default Value | Description |\n|---------------------|---------------|-------------|\n| `DOC_MANAGER_DB_PATH` | `\u003cdata_dir\u003e/database/documents.db` | SQLite database file path |\n| `DOC_MANAGER_EXPORT_DIR` | `~/Desktop` | Export file save directory |\n| `DOC_MANAGER_DATA_DIR` | `~/.lumina-docs` | Data file root directory |\n| `LUMINA_DOCS_SERVER_NAME` | `lumina-docs` | MCP server name |\n| `DOC_MANAGER_DEBUG` | `false` | Debug mode switch |\n| `DOC_MANAGER_LOG_LEVEL` | `INFO` | Log level |\n\n#### Configuration Methods\n\n**Method 1: Using .env file**\n```bash\n# Copy template file\ncp .env.example .env\n\n# Edit configuration\nDOC_MANAGER_DB_PATH=/path/to/your/database.db\nDOC_MANAGER_EXPORT_DIR=/path/to/exports\nDOC_MANAGER_DEBUG=true\n```\n\n**Method 2: System environment variables**\n```bash\nexport DOC_MANAGER_DB_PATH=\"/var/lib/doc-manager/documents.db\"\nexport DOC_MANAGER_EXPORT_DIR=\"/home/user/Documents/exports\"\n```\n\n**Method 3: Claude Desktop configuration**\n```json\n{\n  \"mcpServers\": {\n    \"lumina-docs\": {\n      \"command\": \"/usr/bin/python3\",\n      \"args\": [\"-m\", \"doc_manager\"],\n      \"cwd\": \"/path/to/lumina-docs\",\n      \"env\": {\n        \"PYTHONPATH\": \"/path/to/lumina-docs/src\",\n        \"DOC_MANAGER_DB_PATH\": \"/path/to/database.db\",\n        \"DOC_MANAGER_EXPORT_DIR\": \"/path/to/exports\",\n        \"DOC_MANAGER_DATA_DIR\": \"/path/to/lumina-docs\",\n        \"LUMINA_DOCS_SERVER_NAME\": \"lumina-docs\",\n        \"DOC_MANAGER_DEBUG\": \"false\",\n        \"DOC_MANAGER_LOG_LEVEL\": \"INFO\"\n      }\n    }\n  }\n}\n```\n\n\u003e **Note**: Please use the actual Python path in your system, such as `/usr/bin/python3`, `/usr/local/bin/python3`, or the full path of conda environment.\n\n### Deployment Configuration Examples\n\n#### Development Environment\n```bash\nDOC_MANAGER_DEBUG=true\nDOC_MANAGER_LOG_LEVEL=DEBUG\nDOC_MANAGER_DB_PATH=./dev-database.db\n```\n\n#### Production Environment\n```bash\nDOC_MANAGER_DATA_DIR=/var/lib/doc-manager\nDOC_MANAGER_DB_PATH=/var/lib/doc-manager/database/documents.db\nDOC_MANAGER_EXPORT_DIR=/var/lib/doc-manager/exports\nDOC_MANAGER_LOG_LEVEL=WARNING\n```\n\n#### Docker Deployment\n```yaml\n# docker-compose.yml\nservices:\n  doc-manager:\n    image: doc-manager:latest\n    environment:\n      DOC_MANAGER_DB_PATH: \"/app/data/documents.db\"\n      DOC_MANAGER_EXPORT_DIR: \"/app/data/exports\"\n      DOC_MANAGER_DATA_DIR: \"/app/data\"\n    volumes:\n      - ./data:/app/data\n```\n\n#### Multi-user Environment\n```bash\nDOC_MANAGER_DATA_DIR=/home/$USER/.local/share/doc-manager\nDOC_MANAGER_EXPORT_DIR=/home/$USER/Documents/doc-manager-exports\n```\n\n## Claude Desktop MCP Server Configuration Examples\n\n### Complete Configuration Example\n\nThe following is a complete Claude Desktop configuration file example, showing how to configure doc-manager with other MCP servers:\n\n```json\n{\n  \"mcpServers\": {\n    \"lumina-docs\": {\n      \"command\": \"/usr/bin/python3\",\n      \"args\": [\"-m\", \"doc_manager\"],\n      \"cwd\": \"/path/to/doc-manager\",\n      \"env\": {\n        \"PYTHONPATH\": \"/path/to/doc-manager/src\",\n        \"DOC_MANAGER_DB_PATH\": \"/path/to/doc-manager/database/documents.db\",\n        \"DOC_MANAGER_EXPORT_DIR\": \"/Users/username/Desktop\",\n        \"DOC_MANAGER_DATA_DIR\": \"/path/to/doc-manager\",\n        \"LUMINA_DOCS_SERVER_NAME\": \"lumina-docs\",\n        \"DOC_MANAGER_DEBUG\": \"false\",\n        \"DOC_MANAGER_LOG_LEVEL\": \"INFO\"\n      }\n    },\n    \"other-mcp-server\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/other-server/index.js\"]\n    }\n  }\n}\n```\n\n### Common Python Path Configurations\n\nChoose appropriate configuration based on your Python installation:\n\n#### System Python (macOS)\n```json\n{\n  \"command\": \"/usr/bin/python3\",\n  \"args\": [\"-m\", \"doc_manager\"]\n}\n```\n\n#### System Python (Linux)\n```json\n{\n  \"command\": \"/usr/bin/python3\",\n  \"args\": [\"-m\", \"doc_manager\"]\n}\n```\n\n#### Homebrew Python (macOS)\n```json\n{\n  \"command\": \"/opt/homebrew/bin/python3\",\n  \"args\": [\"-m\", \"doc_manager\"]\n}\n```\n\n#### Conda Environment\n```json\n{\n  \"command\": \"/Users/username/miniconda/bin/python\",\n  \"args\": [\"-m\", \"doc_manager\"]\n}\n```\n\n#### pyenv Python\n```json\n{\n  \"command\": \"/Users/username/.pyenv/versions/3.11.0/bin/python\",\n  \"args\": [\"-m\", \"doc_manager\"]\n}\n```\n\n### Troubleshooting\n\n#### Find Correct Python Path\n```bash\n# Find Python 3 path\nwhich python3\n\n# Find Python path (if using conda)\nwhich python\n\n# Check Python version\npython3 --version\n```\n\n#### Test Configuration\n```bash\n# Change to project directory\ncd /path/to/doc-manager\n\n# Test module import\nPYTHONPATH=/path/to/doc-manager/src python3 -c \"import doc_manager; print('Import successful')\"\n\n# Test server startup\nPYTHONPATH=/path/to/doc-manager/src python3 -m doc_manager --help\n```\n\n#### View Logs\nClaude Desktop MCP server log locations:\n- **macOS**: `~/Library/Logs/Claude/mcp-server-lumina-docs.log`\n- **Linux**: `~/.local/share/Claude/logs/mcp-server-lumina-docs.log`\n\n#### Common Errors and Solutions\n\n1. **`spawn python ENOENT`**\n   - Cause: Cannot find python command\n   - Solution: Use full Python path, like `/usr/bin/python3`\n\n2. **`No module named doc_manager`**\n   - Cause: PYTHONPATH configuration error\n   - Solution: Ensure PYTHONPATH points to correct src directory\n\n3. **Permission Error**\n   - Cause: Insufficient permissions for database or export directory\n   - Solution: Check directory permissions, ensure Claude Desktop can read/write\n\n### Configuration Templates\n\nThe project provides multiple configuration file templates, choose based on your environment:\n\n- `claude_desktop_config.example.json` - General template\n- `claude_desktop_config.macos.json` - macOS system Python configuration\n- `claude_desktop_config.conda.json` - Conda environment configuration\n- `claude_desktop_config.multi.json` - Multi MCP server configuration example\n\nUsage:\n```bash\n# Copy appropriate template\ncp claude_desktop_config.macos.json ~/Library/Application\\ Support/Claude/claude_desktop_config.json\n\n# Edit paths\nnano ~/Library/Application\\ Support/Claude/claude_desktop_config.json\n```\n\n## Core Concepts\n\n### Document Node Types\n- **document_root**: Document root node\n- **section**: Chapters (like project overview, requirement specification)\n- **module**: Function modules (like overview module, system monitoring module)\n- **feature**: Specific features (like system status statistics feature)\n- **business_flow**: Business process description\n- **data_display_rules**: Data display rules\n- **permission_rules**: Permission control rules\n- **architecture_design**: Architecture design\n\n### Hierarchical Structure\n```\nIntelligent Operation System Requirements Document (document_root)\n├── Project Overview (section)\n├── Function Modules (section)\n│   ├── Overview Module (module)\n│   │   ├── System Status Statistics Feature (feature)\n│   │   │   ├── Business Process Description (business_flow)\n│   │   │   └── Data Display Rules (data_display_rules)\n│   │   └── My Focused Systems Feature (feature)\n│   └── System Monitoring Module (module)\n└── Permission Design (section)\n```\n\n## Use Cases\n\nLumina Docs provides an easy-to-use document management system that supports integration with Claude Desktop through the MCP protocol. From a usage scenario perspective, it can provide support for leveraging large language models to handle large-scale documents in three scenarios: reading/updating/writing from scratch. Specifically:\n1. **Reading large documents**: Through structured queries, quickly locate the content you need and avoid loading the entire document at once. For example, for frontend module requirement documents, you can directly query all relevant business process descriptions and data display rules without browsing the entire document.\n2. **Updating existing content**: When modifying a functional module, you can directly query relevant business processes and data display rules to ensure modifications follow existing format and content specifications. For example, when updating system status statistics functions, you can first let the large language model directly locate the content to be modified through SQL, avoiding loading the entire document at once.\n3. **Writing new content from scratch**: When writing new business process descriptions, you can refer to existing patterns to ensure new content is consistent with existing content. For example, when writing new business process descriptions, you can first let the large language model query all existing business process descriptions, analyze their format and content, and then follow the same format and content specifications when creating new nodes.\n\n### 1. Quick Import of Existing Documents\n```python\n# Import single document directly using MCP tools through Claude\nimport_markdown_file(\"Project Requirements.md\", \"project_requirements\")\n\n# Batch import document directories\nimport_markdown_batch([\"docs/*.md\", \"guides/**/*.md\"])\n```\n\n### 2. Structured Queries to Ensure Consistency\n```python\n# Query all [Business Process Descriptions] as reference for new content\nnodes = db.get_nodes_by_type(\"business_flow\")\n\n# Query all [Data Display Rules] for specific module\nresults = db.search_nodes(\n    node_type=\"data_display_rules\",\n    metadata_filter={\"module\": \"overview\"}\n)\n```\n\n### 3. Consistency Check When Writing New Content\n```bash\n# Use consistency check tool\ncd examples\npython consistency_checker.py\n```\n\n### 4. Export Documents on Demand\n```bash\n# Export complete document\npython -m doc_manager.cli export --output complete.md\n\n# Export only function modules part\npython -m doc_manager.cli export --parent-id 3 --output modules.md\n```\n\n## MCP Tools List\n\n### Document Management Tools\n| Tool Name | Function Description |\n|-----------|---------------------|\n| `create_document` | Create new document (independent table) |\n| `get_documents_list` | Get all documents list |\n| `delete_document` | Delete document and its data table |\n\n### Node Management Tools\n| Tool Name | Function Description |\n|-----------|---------------------|\n| `create_node` | Create new document node |\n| `get_node` | Get specified node details |\n| `update_node` | Update existing node |\n| `delete_node` | Delete node and its child nodes |\n| `move_node` | Move node to new position |\n\n### Query and Export Tools\n| Tool Name | Function Description |\n|-----------|---------------------|\n| `get_children` | Get child nodes list |\n| `search_nodes` | Multi-condition search nodes |\n| `get_nodes_by_type` | Get nodes by type (consistency analysis) |\n| `get_node_path` | Get node complete path |\n| `get_tree_structure` | Get tree structure |\n| `export_to_markdown` | Export to Markdown format |\n\n## Command Line Tools\n\n### Basic Operations\n```bash\n# Create node\npython -m doc_manager.cli create \"New Feature\" \"feature\" --parent-id 5 --content \"Feature description\"\n\n# View node\npython -m doc_manager.cli get 1\n\n# Update node\npython -m doc_manager.cli update 1 --title \"New Title\" --content \"New content\"\n\n# Delete node\npython -m doc_manager.cli delete 1\n```\n\n### Query Operations\n```bash\n# List child nodes\npython -m doc_manager.cli list --parent-id 1\n\n# Search nodes\npython -m doc_manager.cli search --query \"business process\" --type \"business_flow\"\n\n# View tree structure\npython -m doc_manager.cli tree\n\n# Find by type\npython -m doc_manager.cli by-type data_display_rules\n```\n\n### Export Operations\n```bash\n# Export complete document\npython -m doc_manager.cli export --output requirements.md\n\n# Export specified part\npython -m doc_manager.cli export --parent-id 3 --output modules.md\n```\n\n## Project Structure\n\n```\ndoc-manager/\n├── src/\n│   └── doc_manager/\n│       ├── __init__.py           # Module initialization\n│       ├── database.py           # SQLite database operations\n│       ├── simple_server.py      # MCP server implementation\n│       ├── markdown_parser.py    # Markdown parsing and import module\n│       ├── cli.py                # Command line tools\n│       ├── config.py             # Configuration management\n│       └── __main__.py           # Server startup entry\n├── examples/\n│   ├── sample_data.py            # Sample data creation\n│   └── consistency_checker.py    # Consistency check tool\n├── database/\n│   └── documents.db              # SQLite database file\n├── docs/\n│   └── (documentation directory)\n├── .env.example                  # Environment variable template\n├── claude_desktop_config.*.json # Configuration templates\n├── pyproject.toml                # Project configuration\n├── README.md                     # Chinese documentation\n├── README.en.md                  # English documentation\n└── docker-compose.example.yml   # Docker deployment example\n```\n\n## Advanced Usage\n\n### 1. Consistency Assurance Workflow\n\nWhen writing new [Business Process Description]:\n```python\n# 1. Query existing business process descriptions\nexisting_flows = db.get_nodes_by_type(\"business_flow\")\n\n# 2. Analyze existing patterns\nfor flow in existing_flows:\n    print(f\"Reference: {flow['title']}\")\n    print(f\"Format: {flow['content'][:100]}...\")\n\n# 3. Follow existing patterns when creating new nodes\nnew_id = db.create_node(\n    title=\"New Business Process Description\",\n    node_type=\"business_flow\", \n    content=\"1. Step one\\n2. Step two\\n3. Step three\",  # Keep format consistent\n    parent_id=parent_id\n)\n```\n\n### 2. Metadata-Driven Management\n```python\n# Use metadata for precise queries\nfrontend_modules = db.search_nodes(\n    node_type=\"module\",\n    metadata_filter={\"module_type\": \"frontend\"}\n)\n\nhigh_priority_features = db.search_nodes(\n    metadata_filter={\"priority\": \"high\"}\n)\n```\n\n### 3. Batch Operations\n```python\n# Batch update metadata for same type nodes\nbusiness_flows = db.get_nodes_by_type(\"business_flow\")\nfor flow in business_flows:\n    db.update_node(\n        flow['id'],\n        metadata={**flow['metadata'], \"reviewed\": True}\n    )\n```\n\n## Best Practices\n\n1. **Naming Conventions**: Use consistent node title formats\n2. **Type Management**: Define clear node_type for different content types\n3. **Metadata Usage**: Make full use of metadata field to store additional information\n4. **Hierarchy Design**: Design reasonable parent-child relationships, avoid overly deep nesting\n5. **Consistency Checks**: Regularly run consistency check tools\n\n## Comparison with Traditional Methods\n\n| Traditional Method | Structured Method |\n|-------------------|------------------|\n| Single large file | Modular nodes |\n| Easy token overflow | Load content on demand |\n| Hard to ensure consistency | Structured query reference |\n| Modifications affect entire document | Precise modification of specific nodes |\n| Manual format maintenance | Automated export and merge |\n\n## Development and Extension\n\n### Adding New Node Types\n1. Add new node_type in database\n2. Update MCP tools schema definition\n3. Add corresponding check logic in consistency checker\n\n### Custom Export Formats\n1. Inherit DocumentDatabase class\n2. Override export_tree_to_markdown method\n3. Implement custom formatting logic\n\n## Contributing\n\nWe welcome contributions! Please feel free to submit issues and pull requests.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Feedback\n\nIf you have any questions or suggestions, please feel free to open an issue or contact the development team.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgaozyun%2Flumina-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgaozyun%2Flumina-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgaozyun%2Flumina-docs/lists"}