MCP Tools Reference

Overview

dacli provides 10 MCP tools for interacting with documentation projects via the Model Context Protocol. These tools enable LLMs to navigate, read, search, and modify documentation.

Navigation Tools

get_structure

Get the hierarchical document structure.

Table 1. Parameters
Parameter	Type	Default	Description
`max_depth`	int \| null	null	Maximum depth to return (must be >= 0). Use 1 for top-level only.

Returns

{
  "sections": [
    {
      "path": "introduction",
      "title": "Introduction",
      "level": 1,
      "children": [
        {
          "path": "introduction.goals",
          "title": "Goals",
          "level": 2,
          "children": []
        }
      ]
    }
  ],
  "total_sections": 15
}

Example

get_structure(max_depth=2)

get_sections_at_level

Get all sections at a specific nesting level.

Table 2. Parameters
Parameter	Type	Description
`level`	int	Nesting level (must be >= 1). 1 = chapters, 2 = sections, etc.

Returns

{
  "level": 1,
  "sections": [
    {"path": "introduction", "title": "Introduction"},
    {"path": "architecture", "title": "Architecture"}
  ],
  "count": 2
}

Content Access Tools

get_section

Read the content of a specific section.

Table 3. Parameters
Parameter	Type	Description
`path`	string	Hierarchical path using dot notation (e.g., `introduction.goals`)

Returns

{
  "path": "introduction.goals",
  "title": "Goals",
  "content": "== Goals\n\nThis section describes...",
  "location": {
    "file": "/docs/chapters/01_introduction.adoc",
    "start_line": 15,
    "end_line": 42
  },
  "format": "asciidoc"
}

Error Response (with suggestions)

{
  "error": {
    "code": "PATH_NOT_FOUND",
    "message": "Section 'intro' not found",
    "details": {
      "requested_path": "intro",
      "suggestions": ["introduction", "intro-page"]
    }
  }
}

get_elements

Get code blocks, tables, images, and other elements.

Table 4. Parameters
Parameter	Type	Default	Description
`element_type`	string \| null	null	Filter by type: `admonition`, `code`, `image`, `list`, `plantuml`, `table`
`section_path`	string \| null	null	Filter by section path

Returns

{
  "elements": [
    {
      "type": "code",
      "location": {
        "file": "/docs/example.adoc",
        "line": 25
      },
      "parent_section": "examples.python"
    }
  ],
  "count": 5
}

Examples

# Get all code blocks
get_elements(element_type="code")

# Get elements in a specific section
get_elements(section_path="architecture.components")

Search

search

Full-text search across documentation.

Table 5. Parameters
Parameter	Type	Default	Description
`query`	string	-	Search query (case-insensitive)
`scope`	string \| null	null	Path prefix to limit search scope
`max_results`	int	50	Maximum results to return (must be >= 0)

Returns

{
  "query": "authentication",
  "results": [
    {
      "path": "security.authentication",
      "line": 45,
      "context": "...implements OAuth2 authentication...",
      "score": 0.95
    }
  ],
  "total_results": 3
}

Example

search(query="database", scope="architecture")

Document Manipulation

update_section

Update the content of a section with optimistic locking support.

Table 6. Parameters
Parameter	Type	Default	Description
`path`	string	-	Section path using dot notation
`content`	string	-	New section content
`preserve_title`	bool	true	Keep original title if content doesn’t include one
`expected_hash`	string \| null	null	Hash for optimistic locking

Returns

{
  "success": true,
  "path": "introduction.goals",
  "location": {
    "file": "/docs/01_intro.adoc",
    "line": 15
  },
  "previous_hash": "a1b2c3d4",
  "new_hash": "e5f6g7h8"
}

Optimistic Locking Workflow

Read section with get_section - note the content
Compute or receive hash of current content
Call update_section with expected_hash
If hash mismatch, update fails with conflict error

insert_content

Insert content relative to a section.

Table 7. Parameters
Parameter	Type	Description
`path`	string	Reference section path
`position`	string	`before`, `after`, or `append`
`content`	string	Content to insert

Position Options

before - Insert before section heading (adds blank line after content if needed)
after - Insert after section end, including all child sections
append - Append at end of section’s own content (before children)

Returns

{
  "success": true,
  "inserted_at": {
    "file": "/docs/chapter.adoc",
    "line": 50
  },
  "previous_hash": "a1b2c3d4",
  "new_hash": "e5f6g7h8"
}

Meta-Information

get_metadata

Get project or section metadata.

Table 8. Parameters
Parameter	Type	Default	Description
`path`	string \| null	null	Section path, or null for project metadata

Project Metadata (no path)

{
  "path": null,
  "total_files": 15,
  "total_sections": 87,
  "total_words": 12450,
  "last_modified": "2026-01-20T14:30:00+00:00",
  "formats": ["asciidoc", "markdown"]
}

Section Metadata (with path)

{
  "path": "architecture.decisions",
  "title": "Architecture Decisions",
  "file": "/docs/chapters/09_decisions.adoc",
  "word_count": 2340,
  "last_modified": "2026-01-19T10:15:00+00:00",
  "subsection_count": 5
}

get_dependencies

Get include dependencies between documentation files.

Parameters

None

Returns

{
  "include_tree": {
    "arc42.adoc": [
      "chapters/01_introduction.adoc",
      "chapters/02_constraints.adoc"
    ]
  },
  "cross_references": []
}

Note	`cross_references` is reserved for future use and currently returns an empty list.

validate_structure

Validate the documentation structure.

Parameters

None

Returns

{
  "valid": true,
  "errors": [],
  "warnings": [
    {
      "type": "orphaned_file",
      "path": "chapters/unused.adoc",
      "message": "File is not included in any document"
    }
  ],
  "validation_time_ms": 120
}

Error Types

unresolved_include - Include directive points to missing file
circular_include - Circular include chain detected

Warning Types

orphaned_file - File exists but is not referenced

Example Workflows

Exploring a New Documentation Project

# Get high-level structure
get_structure(max_depth=1)

# Get project statistics
get_metadata()

# Browse chapters
get_sections_at_level(level=1)

# Read a specific chapter
get_section(path="architecture")

Finding and Extracting Code Examples

# Find all code blocks
get_elements(element_type="code")

# Find code in specific section
get_elements(element_type="code", section_path="examples")

# Search for specific language
search(query="python")

Updating Documentation

# Read current content
get_section(path="api.endpoints")

# Update with new content (preserving title)
update_section(
  path="api.endpoints",
  content="New endpoint documentation...",
  preserve_title=true
)

# Add a new section after existing one
insert_content(
  path="api.endpoints",
  position="after",
  content="== New Endpoint\n\nDescription..."
)

Validating Documentation Quality

# Check for structural issues
validate_structure()

# Get word counts for sections
get_metadata(path="introduction")
get_metadata(path="architecture")

Path Format

Paths use dot notation without document title prefix:

Level Example Path

Level	Example Path
Document root	`""` (empty)
Chapter	`introduction`
Section	`introduction.goals`
Subsection	`introduction.goals.performance`

Document root

"" (empty)

Chapter

introduction

Section

introduction.goals

Subsection

introduction.goals.performance

Paths are case-sensitive and derived from section titles (slugified).

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.