asciidoc-mcp by raifdmueller - MCP Server

MCP Documentation Server

A Model Context Protocol (MCP) server for efficient LLM interaction with large AsciiDoc and Markdown documentation projects.

Features

Hierarchical Navigation: Access document structure without loading entire files
Include Resolution: Automatically resolves AsciiDoc include directives
Content Search: Search across all documentation content
Structured Access: Get specific sections by path notation
Content Manipulation: Update and insert sections directly
File Watching: Automatic updates when files change
Web Interface: Visual document structure browser
Token Efficient: Only load the content you need

Quick Start

Install dependencies:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Test the implementation:
```
python3 test_basic.py
```

Configure in Claude Code: Add to your ~/.claude.json:

{
  "mcpServers": {
    "asciidoc-docs-server": {
      "command": "/path/to/asciidoc-mcp/venv/bin/python3",
      "args": ["-m", "src.mcp_server", "/path/to/your/docs"],
      "env": {
        "ENABLE_WEBSERVER": "true"
      }
    }
  }
}

Use the tools: The server will automatically:
- Start on first MCP initialize request
- Launch a web interface on http://localhost:8080 (or next available port)
- Open your default browser to view the documentation structure
- Provide MCP tools for document navigation and manipulation

API Tools

Navigation Tools

`get_structure`

Get document table of contents up to specified depth.

{"max_depth": 3}

`get_section`

Get specific section content by path.

{"path": "introduction.overview"}

`get_sections`

Get all sections at a specific level.

{"level": 2}

`search_content`

Search for content across all documentation.

{"query": "architecture"}

Content Manipulation Tools

`update_section`

Update section content directly in source files.

{"path": "introduction.overview", "content": "New content here"}

`insert_section`

Insert new section relative to existing section.

{
  "parent_path": "introduction", 
  "title": "New Section", 
  "content": "Section content",
  "position": "append"
}

Web API Endpoints

The server provides REST API endpoints for the web interface and external integration:

Navigation Endpoints

`GET /api/structure`

Get complete document structure with files and sections.

curl http://localhost:8080/api/structure

Response:

{
  "document.adoc": {
    "file_info": {...},
    "sections": [...]
  }
}

`GET /api/section/{section_id}`

Get specific section content with optional full document context.

Parameters:

context: Optional parameter controlling response format
- "section" (default): Returns only the specific section content
- "full": Returns the complete document with section positioning metadata

Basic usage:

curl http://localhost:8080/api/section/document.section-1

Enhanced usage (Issue #57):

curl http://localhost:8080/api/section/document.section-1?context=full

Response formats:

Standard response (context=section):

{
  "id": "document.section-1",
  "title": "Section Title",
  "level": 2,
  "content": "Section content only...",
  "children": [...],
  "source_file": "/path/to/document.adoc",
  "line_start": 10,
  "line_end": 25
}

Full context response (context=full):

{
  "id": "document.section-1",
  "title": "Section Title", 
  "level": 2,
  "content": "Section content only...",
  "children": [...],
  "source_file": "/path/to/document.adoc",
  "line_start": 10,
  "line_end": 25,
  "full_content": "Complete document content...",
  "section_position": {
    "line_start": 10,
    "line_end": 25
  }
}

The context=full parameter enables advanced navigation features:

Complete document view: Shows the section within its full document context
Auto-scrolling: Frontend can use section_position to scroll to the specific section
Section highlighting: Visual emphasis of the selected section within the document

Metadata Endpoints

`GET /api/metadata`

Get project metadata and document information.

curl http://localhost:8080/api/metadata

`GET /api/dependencies`

Get document include dependencies and cross-references.

curl http://localhost:8080/api/dependencies

`GET /api/validate`

Validate document structure consistency.

curl http://localhost:8080/api/validate

Path Notation

Sections are accessed using dot notation:

"introduction" - Section with title "Introduction"
"introduction.overview" - Subsection "Overview" under "Introduction"
"1.2.3" - Third subsection of second section of first chapter

Supported Formats

AsciiDoc: .adoc, .asciidoc files
Markdown: .md files
Includes: AsciiDoc include::file.adoc[] directives

Configuration

Include Depth: Maximum 4 levels (configurable)
File Discovery: Automatically finds main documentation files
File Watching: Real-time updates on file changes
Web Interface: Available on localhost:8080 (configurable)

Project Structure

src/
├── document_parser.py    # Core parsing engine
├── mcp_server.py        # MCP protocol implementation
├── file_watcher.py      # File change monitoring
├── content_editor.py    # Content manipulation
├── web_server.py        # Web visualization (auto-starts with MCP server)
test_basic.py            # Basic functionality tests
.mcp.json               # MCP configuration example

Development

The implementation follows the PRD requirements with minimal, focused code. Core components:

DocumentParser: Handles AsciiDoc/Markdown parsing and include resolution
MCPDocumentationServer: Implements the MCP protocol and API tools, auto-starts webserver
FileWatcher: Monitors file changes for automatic updates
ContentEditor: Handles direct file modifications
WebServer: Provides visual document structure browser (runs as daemon thread)
Section: Data structure for hierarchical document representation

Testing

Run the basic test suite:

python3 test_basic.py

This creates temporary test documents and verifies:

Document parsing and structure extraction
Section hierarchy and path generation
MCP server API functionality
Content search capabilities
Content manipulation features
File watching capabilities