Magento 2 GraphQL Documentation MCP Server

# 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](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: ```bash # Clone the commerce-webapi repository git clone https://github.com/AdobeDocs/commerce-webapi.git # The GraphQL docs are located at: # commerce-webapi/src/pages/graphql/ ``` ### 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: ```bash cd magento-graphql-docs-mcp ln -s /path/to/commerce-webapi/src/pages/graphql data ``` **Option B: Using Environment Variable** Set the `MAGENTO_GRAPHQL_DOCS_PATH` environment variable: ```bash export MAGENTO_GRAPHQL_DOCS_PATH="/path/to/commerce-webapi/src/pages/graphql" ``` To make this permanent, add it to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.): ```bash echo 'export MAGENTO_GRAPHQL_DOCS_PATH="/path/to/commerce-webapi/src/pages/graphql"' >> ~/.zshrc source ~/.zshrc ``` ### Step 3: Verify Documentation Access Check that the documentation path is accessible: ```bash # If using symlink: ls -la data/ # If using environment variable: ls -la $MAGENTO_GRAPHQL_DOCS_PATH/ # You should see files like: # - index.md # - release-notes.md # - schema/ (directory) # - tutorials/ (directory) # - develop/ (directory) ``` ### Step 4: Install the MCP Server ```bash cd magento-graphql-docs-mcp pip install -e . ``` ### (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): ```bash docker build -t magento-graphql-docs-mcp -f docker/Dockerfile . docker run --rm -it \ -v /absolute/path/to/commerce-webapi/src/pages/graphql:/data \ magento-graphql-docs-mcp ``` 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`): ```bash # Let the container clone docs (uses /tmp/commerce-webapi/src/pages/graphql) docker run --rm -it magento-graphql-docs-mcp # Disable auto-fetch; require a mount or preset MAGENTO_GRAPHQL_DOCS_PATH docker run --rm -it \ -e MAGENTO_GRAPHQL_DOCS_AUTO_FETCH=false \ -v /absolute/path/to/commerce-webapi/src/pages/graphql:/data \ magento-graphql-docs-mcp ``` ### Host-Side Docker Wrapper (STDIO) Use the provided wrapper to run the container and forward STDIN/STDOUT for MCP clients (no TTY added): ```bash # From repo root ./run-docker-mcp.sh ``` 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: ```json { "mcpServers": { "magento-graphql-docs": { "command": "/absolute/path/to/run-docker-mcp.sh" } } } ``` ### VS Code MCP Configuration Example VS Code MCP config using the Docker wrapper: ```json { "servers": { "magento-webapi-docs": { "type": "stdio", "command": "/absolute/path/to/run-docker-mcp.sh" } } } ``` 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. ### Docker Compose (HTTP/SSE) Use the provided `docker-compose.yml` to run the server on HTTP/SSE: ```bash docker compose up --build ``` This builds from `docker/Dockerfile`, maps `8765:8765`, and sets `MAGENTO_GRAPHQL_DOCS_TRANSPORT=http` with `MAGENTO_GRAPHQL_DOCS_HOST=0.0.0.0`. Uncomment the `volumes` block in `docker-compose.yml` to bind a local docs checkout; otherwise the image can auto-fetch the docs. Port 8765 is chosen to avoid common 8080 conflicts; adjust as needed. ### Step 5: Run and Verify ```bash # Run the server (will parse and index 350 documents on first run) magento-graphql-docs-mcp # In another terminal, run verification tests: python3 tests/verify_parser.py python3 tests/verify_db.py python3 tests/verify_server.py ``` ## Installation ### Requirements - Python 3.10 or higher - Git (to clone the documentation repository) - 350+ Magento 2 GraphQL documentation markdown files from [AdobeDocs/commerce-webapi](https://github.com/AdobeDocs/commerce-webapi) ### Detailed Setup #### 1. Clone Both Repositories ```bash # Clone the documentation source git clone https://github.com/AdobeDocs/commerce-webapi.git # Clone this MCP server cd magento-graphql-docs-mcp ``` #### 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/` directory** (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: ```bash # Method 1: Symlink (recommended for development) ln -s ~/projects/commerce-webapi/src/pages/graphql data # Method 2: Environment variable (recommended for deployment) export MAGENTO_GRAPHQL_DOCS_PATH="$HOME/projects/commerce-webapi/src/pages/graphql" # Method 3: Clone commerce-webapi as sibling directory # magento-graphql-docs-mcp/ # commerce-webapi/ # └── src/pages/graphql/ ``` #### 3. Install Dependencies ```bash pip install -e . ``` 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: ```bash # Start the MCP server magento-graphql-docs-mcp # The server will: # 1. Check if documentation has changed (compares file modification times) # 2. Parse markdown files if needed (350 files, ~3-5 seconds) # 3. Index content in SQLite with FTS5 # 4. Start listening for MCP requests over STDIO ``` On subsequent runs, if the documentation hasn't changed, startup is nearly instant (~0.87s). ### Running Over HTTP/SSE STDIO remains the default. To expose the server via HTTP with SSE (for clients that expect MCP over SSE), set the transport variables: ```bash MAGENTO_GRAPHQL_DOCS_TRANSPORT=http \ MAGENTO_GRAPHQL_DOCS_HOST=0.0.0.0 \ MAGENTO_GRAPHQL_DOCS_PORT=8765 \ magento-graphql-docs-mcp ``` `MAGENTO_GRAPHQL_DOCS_HOST` defaults to `127.0.0.1` and `MAGENTO_GRAPHQL_DOCS_PORT` defaults to `8765` when unset. Port 8765 is frequently used by other services; pick any free port (example above uses the default port 8765). ### Configuration The server uses environment variables for configuration: #### Documentation Path Set where the GraphQL documentation is located: ```bash # Option 1: Absolute path (recommended) export MAGENTO_GRAPHQL_DOCS_PATH="/Users/you/projects/commerce-webapi/src/pages/graphql" # Option 2: Relative path (from project root) export MAGENTO_GRAPHQL_DOCS_PATH="./data" # Option 3: Home directory relative export MAGENTO_GRAPHQL_DOCS_PATH="~/repos/commerce-webapi/src/pages/graphql" ``` **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: ```bash # Default: ~/.mcp/magento-graphql-docs/database.db export MAGENTO_GRAPHQL_DOCS_DB_PATH="/custom/path/magento-graphql.db" ``` The database directory will be created automatically if it doesn't exist. #### Performance Tuning (Optional) Customize search behavior and limits: ```bash # Number of search results to return (default: 5) export MAGENTO_GRAPHQL_DOCS_TOP_K=10 # Max fields per GraphQL element (default: 20) export MAGENTO_GRAPHQL_DOCS_MAX_FIELDS=30 # Max code preview length in characters (default: 400) export MAGENTO_GRAPHQL_DOCS_CODE_PREVIEW=600 ``` #### Transport & Port Control how the MCP server is exposed: - `MAGENTO_GRAPHQL_DOCS_TRANSPORT`: `stdio` (default) or `http`/`sse` to enable HTTP + SSE - `MAGENTO_GRAPHQL_DOCS_HOST`: bind address for HTTP/SSE mode (default: `127.0.0.1`) - `MAGENTO_GRAPHQL_DOCS_PORT`: HTTP/SSE port (default: `8765`) FastMCP serves SSE when `transport="http"`. ### 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): ```json { "mcpServers": { "magento-graphql-docs": { "command": "magento-graphql-docs-mcp", "env": { "MAGENTO_GRAPHQL_DOCS_PATH": "/Users/you/projects/commerce-webapi/src/pages/graphql" } } } } ``` #### Example: Using Python Module Directly ```json { "mcpServers": { "magento-graphql-docs": { "command": "python3", "args": ["-m", "magento_graphql_docs_mcp.server"], "env": { "MAGENTO_GRAPHQL_DOCS_PATH": "/path/to/commerce-webapi/src/pages/graphql" } } } } ``` #### Example: With Custom Database Path ```json { "mcpServers": { "magento-graphql-docs": { "command": "magento-graphql-docs-mcp", "env": { "MAGENTO_GRAPHQL_DOCS_PATH": "/path/to/commerce-webapi/src/pages/graphql", "MAGENTO_GRAPHQL_DOCS_DB_PATH": "/custom/databases/magento-graphql.db" } } } } ``` 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 ```bash # Run individual examples python3 examples/example_products.py python3 examples/example_customer.py python3 examples/example_cart_checkout.py # Or run all examples at once bash examples/run_all_examples.sh ``` See [examples/README.md](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:** ```python search_documentation(queries=["checkout"], category="tutorials") ``` ### 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:** ```python search_graphql_elements(query="products", element_type="query") ``` ### 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:** ```python search_examples(query="add to cart", language="graphql") ``` ### 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: ```bash # Navigate to project root cd magento-graphql-docs-mcp # Test the markdown parser python3 tests/verify_parser.py # Test database ingestion python3 tests/verify_db.py # Test MCP server and all 8 tools python3 tests/verify_server.py # Run performance benchmarks python3 tests/benchmark_performance.py ``` 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 | Query | Tool | Result | |-------|------|--------| | "How do I query products?" | search_documentation | Product query documentation | | "Show me product query details" | search_graphql_elements | products query definition | | "Complete checkout flow" | get_tutorial | Step-by-step checkout guide | | "Cart mutation examples" | search_examples | Working GraphQL cart examples | | "All B2B documentation" | list_categories + search | B2B schema documentation | ## Development ### Project Structure ``` magento-graphql-docs-mcp/ ├── magento_graphql_docs_mcp/ │ ├── __init__.py │ ├── config.py # Configuration │ ├── parser.py # Markdown + GraphQL parser │ ├── ingest.py # Database ingestion │ └── server.py # MCP server with 8 tools ├── tests/ │ ├── verify_parser.py # Parser verification │ ├── verify_db.py # Database verification │ └── verify_server.py # Server verification ├── data/ │ └── (symlink to docs) ├── pyproject.toml ├── README.md └── CLAUDE.md ``` ### Architecture ``` Markdown Files (350) ↓ Parser (frontmatter + content + GraphQL extraction) ↓ SQLite (documents + code_blocks + graphql_elements + FTS5) ↓ FastMCP Server (8 tools via STDIO) ↓ MCP Client (Claude, IDE, etc.) ``` ## 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:** ```bash git clone https://github.com/AdobeDocs/commerce-webapi.git ``` 2. **Check the path is correct:** ```bash # 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):** ```bash # 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:** ```bash # 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: ```bash cd magento-graphql-docs-mcp pip install -e . ``` **Error**: Server starts but immediately exits **Solution**: Check Python version (requires 3.10+): ```bash python3 --version # Should be 3.10 or higher ``` ### No Search Results **Issue**: Search returns no results even though documentation exists **Solutions**: 1. **Use shorter, simpler keywords:** ```bash # 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:** ```bash ls -la ~/.mcp/magento-graphql-docs/ # Should show database.db (around 30 MB) ``` 3. **Verify data was indexed:** ```bash python3 tests/verify_db.py # Should show: 350 documents, 963 code blocks, 51 GraphQL elements ``` 4. **Re-index the database:** ```bash 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: ```bash # Find and kill the process lsof ~/.mcp/magento-graphql-docs/database.db kill <PID> # Or simply remove and recreate rm ~/.mcp/magento-graphql-docs/database.db magento-graphql-docs-mcp ``` **Error**: `sqlite3.DatabaseError: database disk image is malformed` **Solution**: Database is corrupted, recreate it: ```bash rm -rf ~/.mcp/magento-graphql-docs/ magento-graphql-docs-mcp # Will recreate from scratch ``` ### 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: ```bash # Verify git isn't changing file times cd /path/to/commerce-webapi git status git pull # Update to latest if needed ``` ### Verification Failed **Issue**: `verify_server.py` fails with connection errors **Solution**: ```bash # Ensure dependencies are installed pip install -e ".[dev]" # Check MCP client libraries pip list | grep mcp # Re-run individual verifications python3 tests/verify_parser.py # Test parsing python3 tests/verify_db.py # Test database python3 tests/verify_server.py # Test MCP server ``` ### MCP Client Integration Issues **Issue**: MCP client shows "Server not found" or "Connection failed" **Solutions**: 1. **Verify command is correct:** ```bash # Test the command directly which magento-graphql-docs-mcp # or python3 -m magento_graphql_docs_mcp.server ``` 2. **Check environment variables in MCP config:** ```json { "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:** ```bash python3 tests/verify_parser.py python3 tests/verify_db.py python3 tests/verify_server.py python3 tests/benchmark_performance.py ``` 2. **Check your setup:** ```bash # 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