docToolchain/AsciiDoc-MCP-old

AsciiDoc MCP Server

A Model Context Protocol (MCP) server that provides structured access to AsciiDoc documents for Large Language Models (LLMs).

Overview

This MCP server implements the architecture outlined in for providing specialized AsciiDoc document analysis capabilities to LLMs. It enables AI assistants to understand document structure, resolve include dependencies, validate cross-references, and perform semantic analysis of AsciiDoc content.

Features

The server provides the following tools:

Core Document Analysis

• analyze_document_structure - Parse and analyze the hierarchical structure of AsciiDoc documents, including heading levels and section organization
• find_includes - Discover and resolve include directives and their dependencies recursively
• extract_metadata - Extract document attributes, author information, and file metadata
• search_content - Perform semantic search within AsciiDoc documents with context

Planned Features (Future Releases)

• validate_cross_references - Validate internal cross-references and links
• analyze_assets - Analyze embedded images, diagrams, and other assets

Installation

From Source

1. Clone the repository:

git clone https://github.com/docToolchain/AsciiDoc-MCP.git
cd AsciiDoc-MCP

2. Install the package:

pip install -e .

Using uvx (Recommended)

uvx --from git+https://github.com/docToolchain/AsciiDoc-MCP asciidoc-mcp-server

Usage

As an MCP Server

Configure your MCP client (like Claude Desktop) to use the AsciiDoc MCP server:

{
  "mcpServers": {
    "asciidoc-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/docToolchain/AsciiDoc-MCP", "asciidoc-mcp-server"]
    }
  }
}

Standalone Usage

You can also run the server directly:

asciidoc-mcp-server

Combined with Serena MCP

This server is designed to work alongside Serena MCP for comprehensive code and documentation analysis:

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/oraios/serena", "serena-mcp-server"]
    },
    "asciidoc-mcp": {
      "command": "uvx", 
      "args": ["--from", "git+https://github.com/docToolchain/AsciiDoc-MCP", "asciidoc-mcp-server"]
    }
  }
}

Example Usage

Analyze Document Structure

# Tool: analyze_document_structure
{
  "file_path": "docs/manual.adoc",
  "include_content": true
}

Returns hierarchical structure of headings, sections, and optionally their content.

Find Include Dependencies

# Tool: find_includes
{
  "file_path": "main.adoc",
  "recursive": true
}

Returns all include directives and their resolved paths, useful for understanding document dependencies.

Extract Metadata

# Tool: extract_metadata
{
  "file_path": "document.adoc"
}

Returns document attributes, author information, revision details, and file metadata.

Search Content

# Tool: search_content
{
  "query": "architecture decision",
  "file_path": "docs/decisions.adoc",
  "case_sensitive": false
}

Searches for content with context, showing surrounding lines for better understanding.

Development

Requirements

• Python 3.8+
• MCP SDK
• AsciiDoc Python package

Setup Development Environment

1. Clone and install in development mode:

git clone https://github.com/docToolchain/AsciiDoc-MCP.git
cd AsciiDoc-MCP
pip install -e ".[dev]"

2. Run tests:

pytest

3. Format code:

black src/
ruff check src/

Architecture

The server consists of:

• server.py - Main MCP server implementation with tool registration and request handling
• asciidoc_processor.py - Core AsciiDoc processing logic and document analysis
• __init__.py - Package initialization and version information

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Ensure code formatting with Black and Ruff
6. Submit a pull request

License

MIT License - see LICENSE file for details.

Related Projects

• Serena MCP - Code intelligence MCP server
• docToolchain - Documentation toolchain
• AsciiDoc - Text document format
• Model Context Protocol - Protocol specification