feat(api): Add Navigation API endpoints (Issue #7) (#36)

Implement the Navigation API with three endpoints:
- GET /api/v1/structure - Hierarchical document structure
- GET /api/v1/section/{path} - Get specific section by path
- GET /api/v1/sections?level=N - Get sections at level

Features:
- Pydantic response models for type-safe responses
- max_depth parameter for structure depth limiting
- 404 errors with PATH_NOT_FOUND code for missing sections
- Format detection (asciidoc/markdown) based on file extension

Acceptance Criteria:
- AC-NAV-01: Get full structure ✓
- AC-NAV-02: Get structure with depth limit ✓
- AC-NAV-03: Read existing section ✓
- AC-NAV-04: Section not found → 404 ✓
- AC-NAV-05: Get sections by level ✓

Co-authored-by: Ralf D. Müller <ralf.d.mueller@gmail.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: 3 people

src/mcp_server/api/__init__.py

@@ -0,0 +1,5 @@
+"""API module for MCP Documentation Server."""
+
+from mcp_server.api.app import create_app
+
+__all__ = ["create_app"]

src/mcp_server/api/app.py

@@ -0,0 +1,38 @@
+"""FastAPI application factory.
+
+Creates and configures the FastAPI application with all routers.
+"""
+
+from fastapi import FastAPI
+
+from mcp_server import __version__
+from mcp_server.api import navigation
+from mcp_server.structure_index import StructureIndex
+
+
+def create_app(index: StructureIndex | None = None) -> FastAPI:
+    """Create and configure the FastAPI application.
+
+    Args:
+        index: Optional pre-configured StructureIndex.
+               If None, the index must be set later.
+
+    Returns:
+        Configured FastAPI application
+    """
+    app = FastAPI(
+        title="MCP Documentation Server",
+        description="LLM interaction with large documentation projects via MCP",
+        version=__version__,
+        docs_url="/docs",
+        redoc_url="/redoc",
+    )
+
+    # Set the index for the navigation router
+    if index is not None:
+        navigation.set_index(index)
+
+    # Include routers
+    app.include_router(navigation.router)
+
+    return app

src/mcp_server/api/models.py

@@ -0,0 +1,74 @@
+"""Pydantic models for API responses.
+
+These models define the JSON response structure for the Navigation API
+as specified in 02_api_specification.adoc.
+"""
+
+from pydantic import BaseModel, Field
+
+
+class LocationResponse(BaseModel):
+    """Location of a section in a source file."""
+
+    file: str = Field(description="Relative path to the file")
+    line: int = Field(description="1-based line number")
+
+
+class SectionResponse(BaseModel):
+    """Section response for structure endpoint."""
+
+    path: str = Field(description="Hierarchical path (e.g., '/chapter-1/section-2')")
+    title: str = Field(description="Section title")
+    level: int = Field(description="Nesting depth (1 = chapter)")
+    location: LocationResponse
+    children: list["SectionResponse"] = Field(default_factory=list)
+
+
+class StructureResponse(BaseModel):
+    """Response for GET /structure endpoint."""
+
+    sections: list[SectionResponse]
+    total_sections: int = Field(description="Total number of sections in index")
+
+
+class SectionDetailResponse(BaseModel):
+    """Detailed section response for GET /section/{path}."""
+
+    path: str
+    title: str
+    level: int
+    location: LocationResponse
+    format: str = Field(description="Document format: 'asciidoc' or 'markdown'")
+
+
+class SectionSummary(BaseModel):
+    """Summary of a section (without children)."""
+
+    path: str
+    title: str
+
+
+class SectionsAtLevelResponse(BaseModel):
+    """Response for GET /sections endpoint."""
+
+    level: int
+    sections: list[SectionSummary]
+    count: int
+
+
+class ErrorDetail(BaseModel):
+    """Error detail in error response."""
+
+    code: str = Field(description="Error code (e.g., 'PATH_NOT_FOUND')")
+    message: str = Field(description="Human-readable error message")
+    details: dict | None = Field(default=None, description="Additional details")
+
+
+class ErrorResponse(BaseModel):
+    """Standardized error response."""
+
+    error: ErrorDetail
+
+
+# Allow forward references
+SectionResponse.model_rebuild()

src/mcp_server/api/navigation.py

@@ -0,0 +1,169 @@
+"""Navigation API router.
+
+Provides endpoints for navigating the document structure:
+- GET /structure - Get hierarchical document structure
+- GET /section/{path} - Get a specific section
+- GET /sections - Get sections at a specific level
+"""
+
+from fastapi import APIRouter, HTTPException, Path, Query
+
+from mcp_server.api.models import (
+    ErrorDetail,
+    ErrorResponse,
+    LocationResponse,
+    SectionDetailResponse,
+    SectionResponse,
+    SectionsAtLevelResponse,
+    SectionSummary,
+    StructureResponse,
+)
+from mcp_server.structure_index import StructureIndex
+
+router = APIRouter(prefix="/api/v1", tags=["Navigation"])
+
+# Global index reference - will be set by create_app
+_index: StructureIndex | None = None
+
+
+def set_index(index: StructureIndex) -> None:
+    """Set the global structure index."""
+    global _index
+    _index = index
+
+
+def get_index() -> StructureIndex:
+    """Get the global structure index."""
+    if _index is None:
+        raise HTTPException(
+            status_code=503,
+            detail=ErrorResponse(
+                error=ErrorDetail(
+                    code="INDEX_NOT_READY",
+                    message="Server index is not initialized",
+                )
+            ).model_dump(),
+        )
+    return _index
+
+
+@router.get(
+    "/structure",
+    response_model=StructureResponse,
+    summary="Get document structure",
+    description="Returns the hierarchical document structure.",
+)
+def get_structure(
+    max_depth: int | None = Query(
+        default=None,
+        description="Maximum depth of returned structure. None for unlimited.",
+        ge=1,
+    ),
+) -> StructureResponse:
+    """Get the hierarchical document structure."""
+    index = get_index()
+    structure = index.get_structure(max_depth=max_depth)
+
+    sections = [_section_dict_to_response(s) for s in structure["sections"]]
+
+    return StructureResponse(
+        sections=sections,
+        total_sections=structure["total_sections"],
+    )
+
+
+@router.get(
+    "/section/{path:path}",
+    response_model=SectionDetailResponse,
+    responses={
+        404: {"model": ErrorResponse, "description": "Section not found"},
+    },
+    summary="Get section by path",
+    description="Returns a specific section by its hierarchical path.",
+)
+def get_section(
+    path: str = Path(description="Hierarchical path to the section"),
+) -> SectionDetailResponse:
+    """Get a specific section by path."""
+    index = get_index()
+
+    # Normalize path - ensure it starts with /
+    normalized_path = f"/{path}" if not path.startswith("/") else path
+
+    section = index.get_section(normalized_path)
+
+    if section is None:
+        raise HTTPException(
+            status_code=404,
+            detail={
+                "error": {
+                    "code": "PATH_NOT_FOUND",
+                    "message": f"Section '{normalized_path}' not found",
+                    "details": {
+                        "requested_path": normalized_path,
+                    },
+                }
+            },
+        )
+
+    # Determine format from file extension
+    file_path = str(section.source_location.file)
+    if file_path.endswith(".md"):
+        format_type = "markdown"
+    else:
+        format_type = "asciidoc"
+
+    return SectionDetailResponse(
+        path=section.path,
+        title=section.title,
+        level=section.level,
+        location=LocationResponse(
+            file=file_path,
+            line=section.source_location.line,
+        ),
+        format=format_type,
+    )
+
+
+@router.get(
+    "/sections",
+    response_model=SectionsAtLevelResponse,
+    summary="Get sections at level",
+    description="Returns all sections at a specific nesting level.",
+)
+def get_sections(
+    level: int = Query(
+        description="Nesting level (1 = chapter, 2 = section, etc.)",
+        ge=1,
+    ),
+) -> SectionsAtLevelResponse:
+    """Get all sections at a specific level."""
+    index = get_index()
+
+    sections = index.get_sections_at_level(level)
+
+    section_summaries = [
+        SectionSummary(path=s.path, title=s.title) for s in sections
+    ]
+
+    return SectionsAtLevelResponse(
+        level=level,
+        sections=section_summaries,
+        count=len(section_summaries),
+    )
+
+
+def _section_dict_to_response(section_dict: dict) -> SectionResponse:
+    """Convert a section dictionary from index to response model."""
+    children = [_section_dict_to_response(c) for c in section_dict.get("children", [])]
+
+    return SectionResponse(
+        path=section_dict["path"],
+        title=section_dict["title"],
+        level=section_dict["level"],
+        location=LocationResponse(
+            file=section_dict["location"]["file"],
+            line=section_dict["location"]["line"],
+        ),
+        children=children,
+    )