dacli - API Specification

{
  "root": {
    "path": "",
    "title": "MCP Documentation Server",
    "level": 0,
    "children": [
      {
        "path": "introduction",
        "title": "1. Introduction",
        "level": 1,
        "children": [
          {
            "path": "introduction.goals",
            "title": "1.1 Goals",
            "level": 2,
            "children": []
          }
        ]
      }
    ]
  },
  "total_sections": 42
}

{
  "path": "introduction.goals",
  "title": "1.1 Goals",
  "content": "= Goals\n\nThe main goals of this project are...",
  "location": {
    "file": "chapters/01_introduction.adoc",
    "start_line": 15,
    "end_line": 42
  },
  "format": "asciidoc"
}

{
  "error": {
    "code": "PATH_NOT_FOUND",
    "message": "Section 'introduction.goals' not found",
    "details": {
      "requested_path": "introduction.goals",
      "suggestions": ["introduction.quality-goals", "introduction.stakeholders"]
    }
  }
}

{
  "level": 1,
  "sections": [
    {
      "path": "introduction",
      "title": "1. Introduction"
    },
    {
      "path": "constraints",
      "title": "2. Constraints"
    }
  ],
  "count": 12
}

{
  "type": "code",
  "elements": [
    {
      "type": "code",
      "path": "architecture.decisions",
      "index": 0,
      "location": {
        "file": "chapters/09_decisions.adoc",
        "start_line": 25,
        "end_line": 35
      },
      "attributes": {
        "language": "python",
        "content": "def example():\n    return 'hello world'"
      }
    }
  ],
  "count": 1
}

**Response 400:**
[source,json]

'''

==== search

Searches documentation content.

**Use Case:** UC-04

[cols="1,3"]
|===
| Parameter | Description

| `query` (string, required)
| Search term (case-insensitive)

| `scope` (string, optional)
| Restriction to path prefix (e.g., "/architecture")

| `max_results` (int >= 0, optional)
| Maximum results to return (default: 20). Must be non-negative.
|===

**Response 200:**
[source,json]

=== Content Manipulation Tools

==== update_section

Updates the content of a section.

**Use Case:** UC-03

[cols="1,3"]
|===
| Parameter | Description

| `path` (string, required)
| Hierarchical path to section (e.g., "introduction.goals")

| `content` (string, required)
| New section content

| `preserve_title` (bool, optional)
| Whether to preserve the original section title (default: true). When true, the original title is kept regardless of content. When false, the title from the provided content is used (content must include a section title starting with `=` or `#`, otherwise the update fails with error).

| `expected_hash` (string, optional)
| Hash for optimistic locking - update fails if current content hash doesn't match
|===

**Response 200:**
[source,json]

**Response 404:**
[source,json]

**Response 500:**
[source,json]

'''

==== insert_content

Inserts content relative to a section.

**Use Case:** UC-09

[cols="1,3"]
|===
| Parameter | Description

| `path` (string, required)
| Hierarchical path to reference section

| `position` (string, required)
| Where to insert: "before" (adds blank line after content if next line is heading), "after" (inserts after section end *including all child sections*), or "append" (inserts at end of section's own content, before children)

| `content` (string, required)
| Content to insert
|===

**Response 200:**
[source,json]

'''

==== update_element (planned)

[NOTE]
====
This tool is planned but not yet implemented.
====

Replaces a specific element (code block, table, etc.).

**Use Case:** UC-10

[cols="1,3"]
|===
| Parameter | Description

| `path` (string, required)
| Hierarchical path to section

| `index` (int, required)
| Index of element within section (0-based)

| `content` (string, required)
| New element content
|===

=== Meta-Information Tools

==== get_metadata

Retrieves metadata about the project or a specific section.

**Use Case:** UC-06

[cols="1,3"]
|===
| Parameter | Description

| `path` (string, optional)
| Path to section. If None, returns project-level metadata.
|===

**Response 200 (Project):**
[source,json]

**Response 200 (Section):**
[source,json]

'''

==== get_dependencies

Retrieves include dependencies between documentation files.

**Use Case:** UC-06 (Extension)

**Response 200:**
[source,json]

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

'''

==== validate_structure

Validates the document structure.

**Use Case:** UC-07

**Response 200:**
[source,json]

**Response 200 (with errors):**
[source,json]

=== System Tools (planned)

[NOTE]
====
The following tools are planned but not yet implemented. The MCP server currently rebuilds the index automatically after write operations.
====

==== get_health (planned)

Returns server health status and index information.

==== reindex (planned)

Triggers manual reindexing of the documentation.

== CLI Interface

NOTE: The CLI specification is in a separate file: `06_cli_specification.adoc`

The CLI interface allows using all MCP tools via the command line,
especially for LLMs without MCP support.

== Error Code Reference

Error responses are returned as dictionaries with an `error` key:

[cols="1,3"]
|===
| Code | Description

| `PATH_NOT_FOUND` | Requested section path does not exist
| `ELEMENT_NOT_FOUND` | Element at specified index does not exist
| `INVALID_TYPE` | Unknown element type
| `INVALID_POSITION` | Invalid insert position (must be "before", "after", or "append")
| `WRITE_FAILED` | Write operation failed (file permission, disk full, etc.)
|===

== Tool Summary

.Implemented MCP Tools
[cols="2,3"]
|===
| Tool | Description

| `get_structure` | Get hierarchical document structure
| `get_section` | Read content of a specific section
| `get_sections_at_level` | Get all sections at a nesting level
| `search` | Search documentation content
| `get_elements` | Get code blocks, tables, images, etc.
| `get_metadata` | Get project or section metadata
| `validate_structure` | Validate document structure
| `update_section` | Update section content
| `insert_content` | Insert content before/after sections
| `get_dependencies` | Get include dependencies
|===

.Planned Tools
[cols="2,3"]
|===
| Tool | Description

| `update_element` | Replace a specific element (code, table)
| `get_health` | Server health status
| `reindex` | Trigger manual reindexing
|===