Lumina Docs

一个使用MCP协议的智能结构化文档管理系统，专为解决大型需求文档的token超长问题和保证内容一致性而设计。

我是一个PM，最近尝试用 Claude Code 去写Markdown 格式的需求文档，它的工作完成得还可以，但当文档规模越来越大的时候，会导致 Tokens 超出限制的问题，也会导致文档结构极度混乱。 好在需求文档是一种结构化的文档，在编写的时候往往只需要关注当前正在编辑的部分，无需每次都阅读全文，正是在这个思路之下，我使用 Claude Code 做了这样一个 MCP Server 它能够解决的问题是：

- ✅ 解决大文档token超长问题
- ✅ 通过结构化查询保证内容一致性
- ✅ 支持模块化文档管理
- ✅ 智能的内容参考和模式匹配

- 基于SQLite的轻量级数据库设计
- MCP协议标准化接口
- 父子层级关系管理
- 灵活的元数据支持
- 强大的结构化查询能力
- 纯 Claude Code 编写

Lumina Docs 提供了一个简单易用的文档管理系统，支持通过MCP协议与Claude Desktop集成。从使用场景角度来说，它在阅读/更新/从头编写三个场景下能够为利用大语言模型处理大规模文档提供支持，具体来说：
- 阅读大文档：通过结构化查询，快速定位到需要的内容，避免一次性加载整个文档。例如对于前端模块的需求文档，可以直接查询到所有相关的业务流程说明和数据展示规则，而无需浏览整个文档。
- 更新现有内容：在修改某个功能模块时，可以直接查询到相关的业务流程和数据展示规则，确保修改时遵循现有的格式和内容规范。例如在更新系统状态统计功能时，可以先让大语言模型通过 SQL 直接定位到要修改的内容，避免一次加载全部文档。
- 从头编写新内容：在编写新的业务流程说明时，可以参考现有的模式，确保新内容与现有内容保持一致。例如在编写新的业务流程说明时，可以先让大语言模型查询到所有现有的业务流程说明，分析其格式和内容，然后创建新的节点时遵循相同的格式和内容规范。

# 克隆或下载项目 git clone <repository-url> cd lumina-docs # 安装依赖 pip install -e .

# 复制环境变量模板 cp .env.example .env # 编辑配置文件（可选，使用默认配置可直接跳过） nano .env

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

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

{ "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" } } } }

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

Lumina Docs 支持通过环境变量进行配置，使项目更灵活、更适合不同的部署环境。

# 复制模板文件 cp .env.example .env # 编辑配置 DOC_MANAGER_DB_PATH=/path/to/your/database.db DOC_MANAGER_EXPORT_DIR=/path/to/exports DOC_MANAGER_DEBUG=true

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

{ "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" } } } }

注意: 请使用系统中实际的 Python 路径，如/usr/bin/python3、/usr/local/bin/python3或 conda 环境的完整路径。
- 重启 Claude Desktop
- 查看日志文件，确认没有错误
- 在 Claude Desktop 中测试：

请获取当前所有文档列表

- claude_desktop_config.example.json- 通用模板
- claude_desktop_config.macos.json- macOS 系统 Python 配置
- claude_desktop_config.conda.json- Conda 环境配置
- claude_desktop_config.multi.json- 多 MCP 服务器配置示例

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

- document_root: 文档根节点
- section: 章节（如项目概述、需求说明）
- module: 功能模块（如总览模块、系统监控模块）
- feature: 具体功能（如系统状态统计功能）
- business_flow: 业务流程说明
- data_display_rules: 数据展示规则
- permission_rules: 权限控制规则
- architecture_design: 架构设计

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

# 通过Claude直接使用MCP工具导入单个文档 import_markdown_file("项目需求.md", "project_requirements") # 批量导入文档目录 import_markdown_batch(["docs/.md", "guides//.md"])

# 查询所有【业务流程说明】作为新内容的参考 nodes = db.get_nodes_by_type("business_flow") # 查询特定模块的所有【数据展示规则】 results = db.search_nodes( node_type="data_display_rules", metadata_filter={"module": "overview"} )

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

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

# 创建节点 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

# 列出子节点 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

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

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 # 项目说明

# 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 )

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

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

- 命名规范: 使用一致的节点标题格式
- 类型管理: 为不同内容类型定义清晰的node_type
- 元数据使用: 充分利用metadata字段存储额外信息
- 层级设计: 合理设计父子关系，避免过深的嵌套
- 一致性检查: 定期运行一致性检查工具
- 在数据库中添加新的node_type
- 更新MCP工具的schema定义
- 在一致性检查器中添加相应检查逻辑
- 继承DocumentDatabase类
- 重写export_tree_to_markdown方法
- 实现自定义的格式化逻辑

Local-first MCP server that indexes folders, PDFs, code, and past AI conversations — and exposes them as a single grounded-search tool. Runs fully offline.

Extract text content from local PDF, DOCX, and PPTX files to build a knowledge base.

Provides an MCP interface for the LDIMS document management system.

Provides comprehensive access to an Obsidian vault, allowing AI agents to read, write, search, and manage notes via the Local REST API plugin.

Production-ready RAG out of the box to search and retrieve data from your own documents.

Vectorize MCP server for advanced retrieval, Private Deep Research, Anything-to-Markdown file extraction and text chunking.

Access technical documentation for libraries and frameworks, formatted in clean markdown for LLM consumption.

A Retrieval-Augmented Generation (RAG) server for document processing, vector storage, and intelligent Q&A, powered by the Model Context Protocol.

Codicil indexes a repo's Markdown/YAML/TOML docs into a local Chroma store and exposes query_docs/reindex_docs over MCP. Uses Ollama embeddings when available; with zero infra beyond that, it degrades to live keyword search off disk instead of failing.

An MCP server for document ingestion, chunking, semantic search, and note management.