DocNav-MCP

# DocNav MCP Server ## Project Description DocNav is a Model Context Protocol (MCP) server designed to help LLMs read, process, and navigate long-form documents. The server provides intelligent document analysis and navigation capabilities, starting with Markdown files and expanding to support PDF and other document formats. ## Key Features - **Document Navigation**: Navigate through document sections, headings, and content - **Content Extraction**: Extract and summarize document sections - **Search & Query**: Find specific content within documents - **Multi-format Support**: Initially supports Markdown (.md) files, with planned support for PDF and other formats - **MCP Integration**: Seamless integration with MCP-compatible LLMs ## Architecture The server follows a modular architecture: - **Core MCP Server**: Main server implementation using 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 ## Development Guidelines This document contains critical information about working with this codebase. Follow these guidelines precisely. ## Core Development Rules 1. Package Management - ONLY use uv, NEVER pip - Installation: `uv add package` - Running tools: `uv run tool` - Upgrading: `uv add --dev package --upgrade-package package` - FORBIDDEN: `uv pip install`, `@latest` syntax 2. Code Quality - Type hints required for all code - Public APIs must have docstrings - Functions must be focused and small - Follow existing patterns exactly - Line length: 88 chars maximum 3. Testing Requirements - Framework: `uv run --frozen pytest` - Async testing: use anyio, not asyncio - Coverage: test edge cases and errors - New features require tests - Bug fixes require regression tests - For commits fixing bugs or adding features based on user reports add: ```bash git commit --trailer "Reported-by:<name>" ``` Where `<name>` is the name of the user. - For commits related to a Github issue, add ```bash git commit --trailer "Github-Issue:#<number>" ``` - NEVER ever mention a `co-authored-by` or similar aspects. In particular, never mention the tool used to create the commit message or PR. ## Python Tools ## Code Formatting 1. Ruff - Format: `uv run --frozen ruff format .` - Check: `uv run --frozen ruff check .` - Fix: `uv run --frozen ruff check . --fix` - Critical issues: - Line length (88 chars) - Import sorting (I001) - Unused imports - Line wrapping: - Strings: use parentheses - Function calls: multi-line with proper indent - Imports: split into multiple lines 2. Type Checking - Tool: `uv run --frozen pyright` - Requirements: - Explicit None checks for Optional - Type narrowing for strings - Version warnings can be ignored if checks pass 3. Pre-commit - Config: `.pre-commit-config.yaml` - Runs: on git commit - Tools: Prettier (YAML/JSON), Ruff (Python) - Ruff updates: - Check PyPI versions - Update config rev - Commit config first ## Error Resolution 1. CI Failures - Fix order: 1. Formatting 2. Type errors 3. Linting - Type errors: - Get full line context - Check Optional types - Add type narrowing - Verify function signatures 2. Common Issues - Line length: - Break strings with parentheses - Multi-line function calls - Split imports - Types: - Add None checks - Narrow string types - Match existing patterns - Pytest: - If the tests aren't finding the anyio pytest mark, try adding PYTEST_DISABLE_PLUGIN_AUTOLOAD="" to the start of the pytest run command eg: `PYTEST_DISABLE_PLUGIN_AUTOLOAD="" uv run --frozen pytest` 3. Best Practices - Check git status before commits - Run formatters before type checks - Keep changes minimal - Follow existing patterns - Document public APIs - Test thoroughly