Magento 2 GraphQL Documentation MCP Server

A local STDIO MCP server that provides tools to search and retrieve Magento 2 GraphQL API documentation from local markdown files.

📖 New to setup? See SETUP.md for a step-by-step quick start guide.

Features

• Search Documentation: Full-text search across 350+ GraphQL documentation pages

• Get Complete Documents: Retrieve full documentation with metadata

• Search GraphQL Elements: Find queries, mutations, types, and interfaces

• Get Element Details: View complete schema element definitions with examples

• Browse Categories: Navigate documentation hierarchy (schema, develop, usage, tutorials)

• Access Tutorials: Get step-by-step learning paths (e.g., checkout workflow)

• Search Code Examples: Find working code examples in GraphQL, JSON, JavaScript

• Discover Related Docs: Find related documentation automatically

• Offline Operation: Works entirely offline using local markdown files

• Fast Startup: Only re-indexes if documentation files have changed (<5 seconds)

How it Works

1. Parsing: On startup, the server parses markdown files with YAML frontmatter

2. Extraction: Extracts metadata, code blocks, and GraphQL schema elements

3. Indexing: Stores data in SQLite with FTS5 full-text search indexes

4. Searching: Provides intelligent search across documentation, code, and schema

Quick Start

Step 1: Clone the Documentation Repository

The MCP server requires access to the Adobe Commerce GraphQL documentation markdown files. Clone the official repository:

Step 2: Set Up the Documentation Path

You have two options for configuring the documentation path:

Option A: Using a Symlink (Recommended)

Create a symlink in the project directory:

Option B: Using Environment Variable

Set the MAGENTO_GRAPHQL_DOCS_PATH environment variable:

To make this permanent, add it to your shell profile (~/.bashrc, ~/.zshrc, etc.):

Step 3: Verify Documentation Access

Check that the documentation path is accessible:

Step 4: Install the MCP Server

(Optional) Build and Run with Docker

If you prefer Docker, build the image and mount your docs path to /data (or set MAGENTO_GRAPHQL_DOCS_PATH to another location):

Auto-fetch fallback: if you do not mount docs, the container can clone them on start. Control this with MAGENTO_GRAPHQL_DOCS_AUTO_FETCH (default: true):

Host-Side Docker Wrapper (STDIO)

Use the provided wrapper to run the container and forward STDIN/STDOUT for MCP clients (no TTY added):

What it does:

• Builds the magento-graphql-docs-mcp image automatically if it is missing

• Mounts MAGENTO_GRAPHQL_DOCS_PATH (or ./data) to /data if it exists; otherwise relies on auto-fetch

• Keeps STDIO clean for MCP clients; prints connection instructions on start

• Respects MAGENTO_GRAPHQL_DOCS_AUTO_FETCH (set to false to require a mounted path)

Point your MCP client command to the wrapper path. Example Claude Desktop config:

VS Code MCP Configuration

Example VS Code MCP config using the Docker wrapper:

After adding the server entry, open the VS Code MCP/Tools panel and press “Start” for magento-webapi-docs to launch the container-backed STDIO server.

Step 5: Run and Verify

Installation

Requirements

• Python 3.10 or higher

• Git (to clone the documentation repository)

• 350+ Magento 2 GraphQL documentation markdown files from AdobeDocs/commerce-webapi

Detailed Setup

1. Clone Both Repositories

2. Configure Documentation Path

The server looks for documentation in this order (with path validation on startup):

1. Environment variable MAGENTO_GRAPHQL_DOCS_PATH (if set, validates path exists)

2. ./data/ (symlink or directory with .md files in project root)

3. ../commerce-webapi/src/pages/graphql/ (sibling directory auto-detection)

If no valid path is found, the server will fail with a helpful error message explaining all three setup options.

Choose the method that works best for your setup:

3. Install Dependencies

This installs:

• fastmcp - MCP server framework

• sqlite-utils - Database management

• pydantic - Data validation

• python-frontmatter - YAML frontmatter parsing

• markdown-it-py - Markdown processing

Usage

Running the Server

Once configured, start the server:

On subsequent runs, if the documentation hasn't changed, startup is nearly instant (~0.87s).

Configuration

The server uses environment variables for configuration:

Documentation Path

Set where the GraphQL documentation is located:

Default: The server looks for documentation in these locations (in order, with validation):

1. MAGENTO_GRAPHQL_DOCS_PATH environment variable (validated on startup)

2. ./data/ directory in project root (must contain .md files)

3. ../commerce-webapi/src/pages/graphql/ (sibling directory auto-detection)

Database Location

Customize where the SQLite database is stored:

The database directory will be created automatically if it doesn't exist.

Performance Tuning (Optional)

Customize search behavior and limits:

Using with an MCP Client

Configure your MCP client (e.g., Claude Desktop, Cline, etc.) to use this server.

Example: Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

Example: Using Python Module Directly

Example: With Custom Database Path

After configuration, restart your MCP client to activate the server.

Usage Examples

The examples/ directory contains practical usage examples demonstrating all MCP tools:

Available Examples

1. Product Queries (examples/example_products.py)

   • Search product documentation

   • Find product GraphQL queries and types

   • Explore ProductInterface details

   • Search product code examples

2. Customer Queries (examples/example_customer.py)

   • Search customer documentation

   • Find customer mutations (create, update)

   • Explore authentication and tokens

   • Find customer address operations

3. Cart & Checkout (examples/example_cart_checkout.py)

   • Search cart documentation

   • Complete checkout workflow tutorial

   • Find cart mutations and queries

   • Explore checkout step-by-step

Running Examples

See examples/README.md for detailed documentation.

MCP Tools

1. search_documentation

Search for documentation pages using keywords.

Parameters:

• queries: List of 1-3 short keyword queries (e.g., ["product", "cart"])

• category: Optional filter (schema, develop, usage, tutorials)

• subcategory: Optional filter (products, cart, customer, etc.)

• content_type: Optional filter (guide, reference, tutorial, schema)

Example:

2. get_document

Get complete documentation page by file path.

Parameters:

• file_path: Relative path to document (e.g., "schema/products/queries/products.md")

Returns: Full document content with metadata, frontmatter, and markdown.

3. search_graphql_elements

Search for GraphQL queries, mutations, types, or interfaces.

Parameters:

• query: Search term

• element_type: Optional filter (query, mutation, type, interface, union)

Example:

4. get_element_details

Get complete details about a specific GraphQL element.

Parameters:

• element_name: Element name (e.g., "products", "createCustomer")

• element_type: Optional type filter

Returns: Full element definition with fields, parameters, source document, and code examples.

5. list_categories

List all documentation categories with document counts.

Returns: Hierarchical category tree showing all available documentation areas.

6. get_tutorial

Get complete tutorial with all steps in order.

Parameters:

• tutorial_name: Tutorial name (e.g., "checkout")

Returns: Sequential tutorial steps with code examples and explanations.

7. search_examples

Search for code examples by topic and language.

Parameters:

• query: Search term

• language: Optional language filter (graphql, json, javascript, php, bash)

Example:

8. get_related_documents

Find documents related to a specified document.

Parameters:

• file_path: File path of source document

Returns: Related documents based on category and keywords.

Verification Scripts

Test each component independently.

Important: Run all tests from the project root directory:

Running tests from other directories will cause import errors.

Database Schema

The server uses SQLite with the following tables:

• documents: All documentation pages with FTS5 index

• code_blocks: Code examples from documentation

• graphql_elements: Extracted GraphQL schema elements with FTS5 index

• metadata: Ingestion tracking

Performance

Based on benchmarks (run python3 tests/benchmark_performance.py):

• Startup Time: 0.87s (when data unchanged) | 3-5s (first run or files changed)

• Search Speed: 5.5ms average (FTS5 direct: 0.7ms)

• Document Retrieval: 8.2ms

• GraphQL Element Search: 3.4ms

• Database Size: ~30 MB for 350 documents

• Indexed Content: 350 documents, 963 code blocks, 51 GraphQL elements

All performance targets exceeded: <5s startup ✓, <100ms searches ✓

Example Queries

Development

Project Structure

Architecture

Advantages

vs Web Scraping

• ✅ Offline operation (no network required)

• ✅ Fast startup (3-5s vs 30-60s)

• ✅ Local control (works with custom docs)

• ✅ No HTML parsing complexity

vs REST API MCP

• ✅ Includes tutorials and guides (not just API specs)

• ✅ Code examples searchable

• ✅ Narrative content for learning

• ✅ Tutorial workflows

Unique Features

• 📚 350 documents indexed

• 🔍 8 specialized search tools

• 💡 Tutorial support

• 📝 Code example search

• 🔗 Related document discovery

• ⚡ Fast FTS5 search

• 🎯 GraphQL-aware parsing

Troubleshooting

Documentation Not Found Error

Error: FileNotFoundError: Documentation directory not found!

The server now provides a helpful error message showing all three setup methods.

Solutions:

1. Verify the documentation repository is cloned:

   git clone https://github.com/AdobeDocs/commerce-webapi.git

2. Check the path is correct:

   # If using environment variable: echo $MAGENTO_GRAPHQL_DOCS_PATH ls -la $MAGENTO_GRAPHQL_DOCS_PATH # If using symlink: ls -la data/ # Should show a symlink pointing to the GraphQL docs # You should see 350+ markdown files and directories like: # - schema/ # - tutorials/ # - develop/ # - index.md

3. Set the correct path (choose one method):

   # Method 1: Environment variable (recommended for deployment) export MAGENTO_GRAPHQL_DOCS_PATH="/path/to/commerce-webapi/src/pages/graphql" # Method 2: Create symlink (recommended for development) cd magento-graphql-docs-mcp ln -s /path/to/commerce-webapi/src/pages/graphql data # Verify: ls -la data/ should show the symlink # Method 3: Clone as sibling directory (automatic) cd parent-directory git clone https://github.com/AdobeDocs/commerce-webapi.git # Server will automatically find it

4. Verify the setup:

   # The server validates paths on startup and will show helpful errors magento-graphql-docs-mcp # If path is invalid, you'll see exactly which methods were tried

Server Won't Start

Error: ModuleNotFoundError: No module named 'magento_graphql_docs_mcp'

Solution: Install the package in development mode:

Error: Server starts but immediately exits

Solution: Check Python version (requires 3.10+):

No Search Results

Issue: Search returns no results even though documentation exists

Solutions:

1. Use shorter, simpler keywords:

   # Instead of: "customer authentication token generation" # Try: ["customer", "token"] # Instead of: "how to add products to cart" # Try: ["cart", "add"]

2. Check if database was created:

   ls -la ~/.mcp/magento-graphql-docs/ # Should show database.db (around 30 MB)

3. Verify data was indexed:

   python3 tests/verify_db.py # Should show: 350 documents, 963 code blocks, 51 GraphQL elements

4. Re-index the database:

   rm ~/.mcp/magento-graphql-docs/database.db magento-graphql-docs-mcp # Will parse and re-index everything

Database Errors

Error: sqlite3.OperationalError: database is locked

Solution: Another process is using the database:

Error: sqlite3.DatabaseError: database disk image is malformed

Solution: Database is corrupted, recreate it:

Slow Performance

Issue: First startup takes >10 seconds

Solution: This is normal! First run parses 350 files. Subsequent runs are <1s.

Issue: Every startup is slow

Solution: Documentation mtime is changing. Check:

Verification Failed

Issue: verify_server.py fails with connection errors

Solution:

MCP Client Integration Issues

Issue: MCP client shows "Server not found" or "Connection failed"

Solutions:

1. Verify command is correct:

   # Test the command directly which magento-graphql-docs-mcp # or python3 -m magento_graphql_docs_mcp.server

2. Check environment variables in MCP config:

   { "mcpServers": { "magento-graphql-docs": { "command": "magento-graphql-docs-mcp", "env": { "MAGENTO_GRAPHQL_DOCS_PATH": "/FULL/PATH/to/commerce-webapi/src/pages/graphql" } } } }

   Important: Use absolute paths, not ~ or relative paths in MCP config.

3. Check logs:

   • Claude Desktop: ~/Library/Logs/Claude/ (macOS)

   • Look for error messages related to the server

Getting Help

If you're still having issues:

1. Run all verification scripts:

   python3 tests/verify_parser.py python3 tests/verify_db.py python3 tests/verify_server.py python3 tests/benchmark_performance.py

2. Check your setup:

   # Python version python3 --version # Documentation path echo $MAGENTO_GRAPHQL_DOCS_PATH ls -la $MAGENTO_GRAPHQL_DOCS_PATH | head -20 # Database ls -la ~/.mcp/magento-graphql-docs/ # Package installation pip show magento-graphql-docs-mcp

3. Create a GitHub issue with the output of the above commands.

License

MIT

Contributing

Contributions welcome! Please test all changes with verification scripts before submitting.

Support

For issues or questions:

1. Run verification scripts to diagnose issues

2. Check database location and permissions

3. Verify documentation path is correct