Doc Search

The Doc Search tool browses and searches documentation shipped with installed Magento modules. It provides the AI client with usage guides, required workflows, and common pitfalls — information that cannot be auto-discovered through REST API schemas or database structure.

Modules supply documentation as markdown files placed in their etc/mcp/ directory. The tool automatically discovers all such files across all installed modules.

Access control

Access to this tool is controlled by the MCP Tools -> Built in -> System -> Module Docs ACL resource. Enable or disable it in System -> Permissions -> User Roles -> [Role] -> Role Resources.

---

When to use

When the Doc Search tool is enabled, the MCP server instructs AI clients to always search documentation first before calling any other tool. This ensures the AI client follows module-specific workflows and avoids common mistakes.

The typical workflow is:

1. Search — find relevant documentation for the current task
2. Read — retrieve the specific section with instructions
3. Proceed — use other tools (REST API, GraphQL, etc.) following the documented workflow

---

Actions

The tool has three actions:

list

Discovers available documentation files. Can be filtered by module name or keyword.

Parameter	Description	Type	Required
action	Set to list	string	Yes
module	Filter by module name (e.g., Mirasvit_McpTool)	string	No
query	Filter by keyword (searches in title, description, and module name)	string	No

---

get

Retrieves the table of contents (TOC) of a document, or the content of a specific section.

Parameter	Description	Type	Required
action	Set to get	string	Yes
id	Document identifier in format Module_Name/filename (e.g., Mirasvit_McpTool/rest-api-filtering).	string	Yes
section	Section identifier. Omit to get the TOC. Use ALL to retrieve the entire document.	string	No

---

search

Full-text search across all documentation. Returns matching sections ranked by relevance, with context snippets around the matching keywords.

Parameter	Description	Type	Required
action	Set to search	string	Yes
query	Search keywords	string	Yes
doc	Document identifier to limit search to a specific document	string	No

---

Recommended workflow

The best approach for using Doc Search:

1. search — find relevant sections by keyword (e.g., action=search, query="bulk product import")
2. get with id only — retrieve the document's TOC to understand its structure
3. get with id and section — read a specific section's content

---

How modules provide documentation

Any Magento module can ship documentation for this tool by placing markdown files in its etc/mcp/ directory:

vendor/module-name/
└── etc/
    └── mcp/
        ├── feature-one.md
        └── feature-two.md

File format

Each markdown file should follow this structure:

• Start with a single # Title heading
• First paragraph after the title serves as the description (shown in listing results)
• Use ## headings for each feature or topic
• Use ### headings for subsections (Workflow, Pitfalls, Configuration, etc.)

What to document

Documentation should cover things that AI clients cannot auto-discover through other tools:

• Business context and key concepts
• Multi-step workflows ("to do X, first call Y, then Z")
• Entity relationships that are not obvious from the API schema
• Configuration guidance and best practices
• Common pitfalls and non-obvious behavior

There is no need to document REST API endpoint lists, entity field definitions, database table structures, or GraphQL queries — those are already discoverable through the other built-in tools.

File naming

• Use lowercase, hyphenated filenames (e.g., report-builder.md)
• Files starting with _ are ignored by the tool (useful for templates or drafts)
• Small modules can use a single file; larger modules should use one file per major feature area

---

Example output

Listing documents:

[
  {
    "id": "Mirasvit_McpTool/rest-api-filtering",
    "module": "Mirasvit_McpTool",
    "title": "REST API Filtering",
    "description": "How to use searchCriteria for filtering, sorting, and pagination in REST API calls."
  }
]

Search results:

[
  {
    "doc_id": "Mirasvit_McpTool/rest-api-filtering",
    "module": "Mirasvit_McpTool",
    "section": "filter-groups",
    "section_title": "Filter Groups",
    "snippet": "...Use filter groups to combine multiple conditions with AND/OR logic..."
  }
]

Table of contents:

{
  "id": "Mirasvit_McpTool/rest-api-filtering",
  "module": "Mirasvit_McpTool",
  "title": "REST API Filtering",
  "content_length": 4250,
  "sections": [
    {"id": "ALL", "title": "Full Document", "content_length": 4250},
    {"id": "filter-groups", "title": "Filter Groups", "level": 2, "content_length": 1200},
    {"id": "sort-orders", "title": "Sort Orders", "level": 2, "content_length": 800}
  ]
}