DocNav MCP Server
DocNav is a Model Context Protocol (MCP) server which empowers LLM Agents to read, analyze, and manage lengthy documents intelligently, mimicking human-like comprehension and navigation capabilities.
Features
- Document Navigation: Navigate through document sections, headings, and content structure
- Content Extraction: Extract and summarize specific document sections
- Search & Query: Find specific content within documents using intelligent search
- Multi-format Support: Currently supports Markdown (.md) files, with planned support for PDF and other formats
- MCP Integration: Seamless integration with MCP-compatible LLMs and applications
Architecture
DocNav follows a modular, extensible architecture:
- Core MCP Server: Main server implementation using the MCP protocol
- Document Processors: Pluggable processors for different file types
- Navigation Engine: Handles document structure analysis and navigation
- Content Extractors: Extract and format content from documents
- Search Engine: Provides search and query capabilities across documents
Installation
Prerequisites
- Python 3.10+
- uv package manager
Setup
- Clone the repository:
git clone https://github.com/shenyimings/DocNav-MCP.git
cd DocNav-MCP
- Install dependencies:
Usage
Starting the MCP Server
Connect to the MCP server
{
"mcpServers": {
"docnav": {
"command": "{{PATH_TO_UV}}", // Run `which uv` and place the output here
"args": [
"--directory",
"{{PATH_TO_SRC}}",
"run",
"server.py"
]
}
}
}
load_document: Load a document for navigation and analysis- Args:
file_path (path to document file) - Returns: Success message with auto-generated document ID
get_outline: Get document outline/table of contents- Args:
doc_id (document identifier), max_depth (max heading depth, default 3) - Returns: Formatted document outline
- Tip: Use first after loading a document to understand structure
read_section: Read content of a specific document section- Args:
doc_id (document identifier), section_id (e.g., 'h1_0', 'h2_1') - Returns: Section content with subsections
search_document: Search for specific content within a document- Args:
doc_id (document identifier), query (search term or phrase) - Returns: Formatted search results with context
navigate_section: Get navigation context for a section- Args:
doc_id (document identifier), section_id (section to navigate to) - Returns: Navigation context with parent, siblings, children
list_documents: List all currently loaded documents- Returns: List of loaded documents with metadata
get_document_stats: Get statistics about a loaded document- Args:
doc_id (document identifier) - Returns: Document statistics and structure info
remove_document: Remove a document from the navigator- Args:
doc_id (document identifier) - Returns: Success or error message
Example Usage
# Load a document
result = await tools.load_document("path/to/document.md")
# Get document outline
outline = await tools.get_outline(doc_id)
# Get specific section content
section = await tools.read_section(doc_id, section_id)
# Search within document
results = await tools.search_document(doc_id, "search query")
Development
Project Structure
docnav-mcp/
--- server.py # Main MCP server
--- docnav/
------- __init__.py # Package initialization
------- models.py # Data models
------- navigator.py # Document navigation engine
------- processors/
------- __init__.py # Processor package
------- base.py # Base processor interface
------- markdown.py # Markdown processor
--- tests/
------- ... # Test files
Development Guidelines
See CLAUDE.md for detailed development guidelines including:
- Code quality standards
- Testing requirements
- Package management with uv
- Formatting and linting rules
Adding New Document Processors
- Create a new processor class inheriting from
BaseProcessor - Implement the required methods:
can_process, process, extract_section, search - Register the processor in the
DocumentNavigator - Add comprehensive tests
Running Tests
# Run all tests
uv run tests/run_tests.py
Code Quality
# Format code
uv run --frozen ruff format .
# Check linting
uv run --frozen ruff check .
# Type checking
uv run --frozen pyright
Roadmap
Contributing
- Fork the repository
- Create a feature branch
- Follow the development guidelines in CLAUDE.md
- Add tests for new functionality
- Submit a pull request
License
This project is licensed under the Apache-2.0 License - see the LICENSE file for details.
Support
For issues and questions:
- Open an issue on GitHub
- Check the documentation in CLAUDE.md
- Review existing issues and discussions