{"_id":"@slawomirjach/adpapi-mcp-server","_rev":"32-2cd0034f33c238c5931cec661c35cd69","name":"@slawomirjach/adpapi-mcp-server","dist-tags":{"latest":"1.0.15"},"versions":{"1.0.14":{"name":"@slawomirjach/adpapi-mcp-server","version":"1.0.14","keywords":["mcp","model-context-protocol","graphql","documentation","schema","api","cli","developer-tools"],"author":{"name":"Sławomir Jach","email":"sjach@dreamlab.pl"},"license":"MIT","_id":"@slawomirjach/adpapi-mcp-server@1.0.14","maintainers":[{"name":"slawomirjach","email":"slawomir.jach@ringieraxelspringer.pl"}],"bin":{"adpapi-mcp-server":"index.js"},"dist":{"shasum":"55e6f41dc0d395d8d8dd29818e49da6c18a77d5d","tarball":"https://registry.npmjs.org/@slawomirjach/adpapi-mcp-server/-/adpapi-mcp-server-1.0.14.tgz","fileCount":20,"integrity":"sha512-Wy4uvTeZ7jmTGMaWeDGuSD4NwaH3xt2MKJgz9tUM2LG5Eroj0gPMK3nXBvxwsI2kRQq9LbxQnoRZQtxzWlorsw==","signatures":[{"sig":"MEQCIDyN8kYxhqh8WxHkCv1YEc5E0i6pE+ygBHUresmTcVR/AiBn8sf4aGpjsMgtKYFvDQonzY48wrDAca/vtxOdVLk3aA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":215535},"main":"index.js","engines":{"node":">=20"},"gitHead":"1ac41a6974eea0f2578fe12e912f18e3c37f7512","scripts":{"dev":"node index.js --url=http://localhost:3000/graphql","test":"echo \"Error: no test specified\" && exit 1","start":"node index.js"},"_npmUser":{"name":"slawomirjach","email":"slawomir.jach@ringieraxelspringer.pl"},"_npmVersion":"10.9.3","description":"MCP Documentation Server for ADP API GraphQL - provides schema docs, query examples, and intelligent search for GraphQL APIs","directories":{},"_nodeVersion":"22.20.0","dependencies":{"graphql":"^16.8.1","@graphql-tools/load-files":"^7.0.0","@modelcontextprotocol/sdk":"^1.22.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{},"_npmOperationalInternal":{"tmp":"tmp/adpapi-mcp-server_1.0.14_1763298277661_0.3265542117733713","host":"s3://npm-registry-packages-npm-production"}},"1.0.15":{"name":"@slawomirjach/adpapi-mcp-server","version":"1.0.15","description":"MCP Documentation Server for ADP API GraphQL - provides schema docs, query examples, and intelligent search for GraphQL APIs","main":"index.js","bin":{"adpapi-mcp-server":"index.js"},"author":{"name":"Sławomir Jach","email":"sjach@dreamlab.pl"},"scripts":{"start":"node index.js","dev":"node index.js --url=http://localhost:3000/graphql","test":"echo \"Error: no test specified\" && exit 1"},"engines":{"node":">=20"},"license":"MIT","keywords":["mcp","model-context-protocol","graphql","documentation","schema","api","cli","developer-tools"],"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"dependencies":{"@graphql-tools/load-files":"^7.0.0","@modelcontextprotocol/sdk":"^1.22.0","graphql":"^16.8.1"},"devDependencies":{},"_id":"@slawomirjach/adpapi-mcp-server@1.0.15","gitHead":"0f596ff6bceb10cdfa10aacf4086ac6669d6326d","_nodeVersion":"22.20.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-PaqiadpNk4jpvoxJKrv+pn5opJuPbjoozff9hBdMy32y69VB64V+ieeDIIlLCxRBNSzHk3pom8sYnUTFxMVLTw==","shasum":"e2564694fbe14e63b8977feaa3b665c6f57fc13b","tarball":"https://registry.npmjs.org/@slawomirjach/adpapi-mcp-server/-/adpapi-mcp-server-1.0.15.tgz","fileCount":20,"unpackedSize":215518,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIErDbsg9MuF7HER9Gt3KWCRPrXiWCu8Jm+kD8EL2XZpSAiEA7y6QCUdyo2h1o2Rt9wW+bAsvuidby/2K8La3SeQ869s="}]},"_npmUser":{"name":"slawomirjach","email":"slawomir.jach@ringieraxelspringer.pl"},"directories":{},"maintainers":[{"name":"slawomirjach","email":"slawomir.jach@ringieraxelspringer.pl"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/adpapi-mcp-server_1.0.15_1763298460127_0.6118437889654327"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-16T13:04:37.561Z","modified":"2025-11-16T13:07:40.540Z","1.0.0":"2025-11-16T09:38:02.935Z","1.0.1":"2025-11-16T09:52:07.035Z","1.0.2":"2025-11-16T10:03:10.554Z","1.0.3":"2025-11-16T10:21:37.853Z","1.0.4":"2025-11-16T10:24:41.023Z","1.0.5":"2025-11-16T10:29:29.126Z","1.0.6":"2025-11-16T10:34:30.535Z","1.0.7":"2025-11-16T10:50:04.925Z","1.0.8":"2025-11-16T10:55:25.093Z","1.0.9":"2025-11-16T10:58:24.613Z","1.0.10":"2025-11-16T11:04:03.924Z","1.0.11":"2025-11-16T11:58:28.480Z","1.0.12":"2025-11-16T12:32:51.033Z","1.0.13":"2025-11-16T13:01:27.588Z","1.0.14":"2025-11-16T13:04:37.859Z","1.0.15":"2025-11-16T13:07:40.328Z"},"author":{"name":"Sławomir Jach","email":"sjach@dreamlab.pl"},"license":"MIT","keywords":["mcp","model-context-protocol","graphql","documentation","schema","api","cli","developer-tools"],"description":"MCP Documentation Server for ADP API GraphQL - provides schema docs, query examples, and intelligent search for GraphQL APIs","maintainers":[{"name":"slawomirjach","email":"slawomir.jach@ringieraxelspringer.pl"}],"readme":"# ADP API MCP Documentation Server\n\nMCP (Model Context Protocol) server providing GraphQL schema documentation, query examples, and intelligent search capabilities for GraphQL APIs. Designed to help AI assistants learn and use GraphQL APIs more effectively.\n\n## Features\n\n- **Practical User Guides**: Step-by-step workflows and real-world examples for common tasks\n  - Creating advertising campaigns (Deal → Line Item → Creative)\n  - Managing audience segments\n  - Generating reports and statistics\n  - Authentication and setup\n  - CRM/OMS integration workflows\n  - Best practices and gotchas\n- **Schema Documentation**: Retrieve complete GraphQL type definitions with fields, descriptions, and deprecation warnings\n  - Automatic documentation of JSON parameter formats (filter, sort)\n  - Connection type metadata explaining custom structure\n  - Inline hints for complex parameters\n- **Intelligent Search**: Find types, operations, and fields by partial name with relevance scoring\n  - Perfect for AI agents building queries from scratch\n  - Returns full operational context with example queries\n- **Query Examples**: Access executable GraphQL queries with variables from tests and production code\n  - Auto-generated examples for operations without real-world examples\n  - Three complexity levels: simple, medium (with filter), advanced (with filter + sort)\n- **Query Execution**: Test and validate GraphQL queries against live API\n  - Read-only query execution (mutations blocked)\n  - Built-in validation and error detection\n- **Common Patterns**: Comprehensive documentation of API usage patterns\n  - Filter operators and examples (=, !=, >, <, >=, <=, in, like)\n  - Sorting patterns (asc/desc - case-sensitive!)\n  - Pagination strategies (limit/offset)\n  - Connection type structure (custom, without 'node' wrapper)\n- **Common Mistakes**: Learn from typical API usage errors\n  - Critical mistakes with corrections\n  - Sort direction case sensitivity warnings\n  - Connection structure pitfalls\n- **Domain Organization**: Browse by API domains (DAS, CRM, Video, MIA)\n  - Top operations by usage frequency\n  - Domain-specific pattern summaries\n- **Usage Frequency**: See which operations are most commonly used in production\n- **Deprecation Detection**: Identify deprecated types and operations, check if still in use\n\n## Installation\n\n```bash\nnpm install -g @slawomirjach/adpapi-mcp-server\n```\n\nOr use with npx (no installation):\n\n```bash\nGRAPHQL_URL=https://adp-api.endpoint.com/1234567/v1 \\\nGRAPHQL_AUTH_LOGIN=YOUR_LOGIN \\\nGRAPHQL_AUTH_TOKEN=YOUR_TOKEN \\\nnpx @slawomirjach/adpapi-mcp-server\n```\n\n## Quick Start\n\n### For Claude Code Users (Recommended)\n\n```bash\n# One command to add MCP server (with authentication via environment variables)\nclaude mcp add --transport stdio adpapi-docs \\\n  --env GRAPHQL_URL=https://adp-api.endpoint.com/1234567/v1 \\\n  --env GRAPHQL_AUTH_LOGIN=YOUR_LOGIN \\\n  --env GRAPHQL_AUTH_TOKEN=YOUR_TOKEN \\\n  -- npx @slawomirjach/adpapi-mcp-server\n\n# Verify it works\nclaude mcp list\n```\n\nThen use in Claude Code:\n- Type `/mcp` to check server status\n- Ask: \"What operations are available in my GraphQL API?\"\n- The server will automatically provide schema documentation and examples\n\n### Standalone Usage\n\n```bash\n# Install globally\nnpm install -g @slawomirjach/adpapi-mcp-server\n\n# Run with your GraphQL endpoint (with authentication via environment variables)\nGRAPHQL_URL=https://adp-api.endpoint.com/1234567/v1 \\\nGRAPHQL_AUTH_LOGIN=YOUR_LOGIN \\\nGRAPHQL_AUTH_TOKEN=YOUR_TOKEN \\\nadpapi-mcp-server\n\n# Or use npx (no installation needed)\nGRAPHQL_URL=https://adp-api.endpoint.com/1234567/v1 \\\nGRAPHQL_AUTH_LOGIN=YOUR_LOGIN \\\nGRAPHQL_AUTH_TOKEN=YOUR_TOKEN \\\nnpx @slawomirjach/adpapi-mcp-server\n```\n\n## Configuration\n\n### Environment Variables (Required)\n\nThe server is configured entirely through environment variables for security:\n\n**Required:**\n- `GRAPHQL_URL` - GraphQL endpoint URL\n  - Example: `https://adp-api.endpoint.com/1234567/v1`\n- `GRAPHQL_AUTH_LOGIN` - Authentication login for API access\n- `GRAPHQL_AUTH_TOKEN` - Authentication token for API access\n\n**Optional:**\n- `ACC_VARIANT` - ACC variant name (adds `x-oa-variant: DOMAIN::VARIANT` header)\n- `DEBUG` - Enable debug logging (default: `false`)\n\n### Usage Examples\n\n```bash\n# Standard usage\nGRAPHQL_URL=https://api.example.com/1234567/v1 \\\nGRAPHQL_AUTH_LOGIN=YOUR_LOGIN \\\nGRAPHQL_AUTH_TOKEN=YOUR_TOKEN \\\nadpapi-mcp-server\n\n# Local development\nGRAPHQL_URL=http://localhost:3000/graphql \\\nGRAPHQL_AUTH_LOGIN=YOUR_LOGIN \\\nGRAPHQL_AUTH_TOKEN=YOUR_TOKEN \\\nadpapi-mcp-server\n\n# With ACC variant for testing\nGRAPHQL_URL=https://api.example.com/1234567/v1 \\\nGRAPHQL_AUTH_LOGIN=YOUR_LOGIN \\\nGRAPHQL_AUTH_TOKEN=YOUR_TOKEN \\\nACC_VARIANT=test_variant \\\nadpapi-mcp-server\n\n# With debug logging\nGRAPHQL_URL=https://api.example.com/1234567/v1 \\\nGRAPHQL_AUTH_LOGIN=YOUR_LOGIN \\\nGRAPHQL_AUTH_TOKEN=YOUR_TOKEN \\\nDEBUG=true \\\nadpapi-mcp-server\n```\n\n### MCP Client Setup\n\n#### Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n**Using global installation:**\n```json\n{\n  \"mcpServers\": {\n    \"adpapi-docs\": {\n      \"command\": \"adpapi-mcp-server\",\n      \"env\": {\n        \"GRAPHQL_URL\": \"https://adp-api.endpoint.com/1234567/v1\",\n        \"GRAPHQL_AUTH_LOGIN\": \"YOUR_LOGIN\",\n        \"GRAPHQL_AUTH_TOKEN\": \"YOUR_TOKEN\"\n      }\n    }\n  }\n}\n```\n\n**Using npx (no global installation):**\n```json\n{\n  \"mcpServers\": {\n    \"adpapi-docs\": {\n      \"command\": \"npx\",\n      \"args\": [\"@slawomirjach/adpapi-mcp-server\"],\n      \"env\": {\n        \"GRAPHQL_URL\": \"https://adp-api.endpoint.com/1234567/v1\",\n        \"GRAPHQL_AUTH_LOGIN\": \"YOUR_LOGIN\",\n        \"GRAPHQL_AUTH_TOKEN\": \"YOUR_TOKEN\"\n      }\n    }\n  }\n}\n```\n\n**⚠️ Node.js Version Issue with npx:**\n\nIf you see errors like `Cannot find module '@modelcontextprotocol/sdk/server'` or `Node version: v10.x.x`, it means Claude Desktop is using an old Node.js version. This package requires Node.js >= 20.\n\n**Solution:** Use `node` command directly instead of `npx`:\n\n```json\n{\n  \"mcpServers\": {\n    \"adpapi-docs\": {\n      \"command\": \"/Users/YOUR_USERNAME/.nvm/versions/node/v22.20.0/bin/node\",\n      \"args\": [\n        \"/Users/YOUR_USERNAME/.nvm/versions/node/v22.20.0/bin/npx\",\n        \"@slawomirjach/adpapi-mcp-server\"\n      ],\n      \"env\": {\n        \"GRAPHQL_URL\": \"https://adp-api.endpoint.com/1234567/v1\",\n        \"GRAPHQL_AUTH_LOGIN\": \"YOUR_LOGIN\",\n        \"GRAPHQL_AUTH_TOKEN\": \"YOUR_TOKEN\"\n      }\n    }\n  }\n}\n```\n\nTo find your Node.js path, run:\n```bash\nwhich node  # e.g., /Users/YOUR_USERNAME/.nvm/versions/node/v22.20.0/bin/node\nwhich npx   # e.g., /Users/YOUR_USERNAME/.nvm/versions/node/v22.20.0/bin/npx\n```\n\n**Local development:**\n```json\n{\n  \"mcpServers\": {\n    \"adpapi-docs\": {\n      \"command\": \"adpapi-mcp-server\",\n      \"env\": {\n        \"GRAPHQL_URL\": \"http://localhost:3000/graphql\",\n        \"GRAPHQL_AUTH_LOGIN\": \"YOUR_LOGIN\",\n        \"GRAPHQL_AUTH_TOKEN\": \"YOUR_TOKEN\"\n      }\n    }\n  }\n}\n```\n\n#### Claude Code\n\n**Recommended: One-line command** (easiest method):\n\n```bash\n# Add MCP server with environment variables\nclaude mcp add --transport stdio adpapi-docs \\\n  --env GRAPHQL_URL=https://adp-api.endpoint.com/1234567/v1 \\\n  --env GRAPHQL_AUTH_LOGIN=YOUR_LOGIN \\\n  --env GRAPHQL_AUTH_TOKEN=YOUR_TOKEN \\\n  -- npx @slawomirjach/adpapi-mcp-server\n\n# Using global installation\nclaude mcp add --transport stdio adpapi-docs \\\n  --env GRAPHQL_URL=https://adp-api.endpoint.com/1234567/v1 \\\n  --env GRAPHQL_AUTH_LOGIN=YOUR_LOGIN \\\n  --env GRAPHQL_AUTH_TOKEN=YOUR_TOKEN \\\n  -- adpapi-mcp-server\n\n# With ACC variant\nclaude mcp add --transport stdio adpapi-docs \\\n  --env GRAPHQL_URL=https://adp-api.endpoint.com/1234567/v1 \\\n  --env GRAPHQL_AUTH_LOGIN=YOUR_LOGIN \\\n  --env GRAPHQL_AUTH_TOKEN=YOUR_TOKEN \\\n  --env ACC_VARIANT=test_variant \\\n  -- npx @slawomirjach/adpapi-mcp-server\n```\n\n**Note**: The `--` separator is important - it distinguishes Claude's flags from the MCP server command.\n\n**Verify installation:**\n```bash\n# List all MCP servers\nclaude mcp list\n\n# Check details\nclaude mcp get adpapi-docs\n\n# Remove if needed\nclaude mcp remove adpapi-docs\n```\n\n**Alternative: Manual configuration** - Create `.claude/config.json` in your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"adpapi-docs\": {\n      \"command\": \"npx\",\n      \"args\": [\"@slawomirjach/adpapi-mcp-server\"],\n      \"env\": {\n        \"GRAPHQL_URL\": \"https://adp-api.endpoint.com/1234567/v1\",\n        \"GRAPHQL_AUTH_LOGIN\": \"YOUR_LOGIN\",\n        \"GRAPHQL_AUTH_TOKEN\": \"YOUR_TOKEN\"\n      }\n    }\n  }\n}\n```\n\nAfter adding the server, check status in Claude Code with `/mcp` command.\n\n#### Cline VS Code Extension\n\nEdit `.vscode/settings.json`:\n\n```json\n{\n  \"cline.mcpServers\": {\n    \"adpapi-docs\": {\n      \"command\": \"npx\",\n      \"args\": [\"@slawomirjach/adpapi-mcp-server\"],\n      \"env\": {\n        \"GRAPHQL_URL\": \"https://adp-api.endpoint.com/1234567/v1\",\n        \"GRAPHQL_AUTH_LOGIN\": \"YOUR_LOGIN\",\n        \"GRAPHQL_AUTH_TOKEN\": \"YOUR_TOKEN\"\n      }\n    }\n  }\n}\n```\n\n## Available MCP Tools\n\n### search_schema\n\n**NEW** - Intelligent search in GraphQL schema by partial name. Perfect for AI agents building queries from scratch.\n\n**Parameters**:\n- `term` (required): Search term (can be partial, e.g., \"draft\" finds \"AdTplDraft\", \"draft_templates\")\n- `limit` (optional): Maximum results (default: 10, max: 10)\n\n**Use Cases**:\n- AI agents building queries: search \"campaign\" → get full context with example query\n- Finding operations by partial name: \"lineitem\" → finds all lineitem-related operations\n- Discovering fields: \"status\" → finds all fields containing \"status\"\n\n**Scoring Algorithm**:\n- 900-1000: Exact match\n- 700-899: Starts with term\n- 500-699: Contains term\n- Bonus for: operations > types > fields, higher usage, shorter names\n\n**Example**:\n```json\n{\n  \"term\": \"draft\",\n  \"limit\": 5\n}\n```\n\n### validate_query\n\n**NEW** - Validate GraphQL query syntax and detect common ADP API mistakes.\n\n**Parameters**:\n- `query` (required): GraphQL query to validate\n- `variables` (optional): Query variables for validation\n\n**Detects**:\n- Inline JSON parameters (should use variables)\n- Uppercase sort directions (must be lowercase)\n- Incorrect Connection structure\n- Syntax errors\n\n### get_practical_guides\n\n**NEW** - Get practical user guides and real-world workflow documentation for ADP API.\n\n**Parameters**:\n- `topic` (optional): Specific topic to retrieve. Leave empty to get the full guide.\n\n**Available Topics**:\n- `authentication` / `auth` - API authentication and getting started\n- `campaign` / `campaigns` / `advertising` - Creating advertising campaigns (Deal → Line Item → Creative)\n- `audience` / `segments` - Managing audience segments\n- `reporting` / `reports` - Generating reports and report definitions\n- `statistics` / `stats` - Real-time statistics (non-billing)\n- `custom_fields` / `customfields` - Custom fields and freeform values\n- `reservation` / `reservations` / `crm` / `oms` - Creating reservations (CRM/OMS integration)\n- `dashboard` / `dashboards` - Dashboard URL generation\n- `best_practices` / `bestpractices` - Best practices and tips\n- `overview` - API overview\n\n**Features**:\n- Step-by-step workflows for common tasks\n- Complete GraphQL examples with variables\n- Practical explanations of API concepts\n- Best practices and gotchas\n- Real-world usage patterns\n\n**Example**:\n```json\n{\n  \"tool\": \"get_practical_guides\",\n  \"params\": {\n    \"topic\": \"campaign\"\n  }\n}\n```\n\n**Use Cases**:\n- \"How do I create an advertising campaign?\"\n- \"What are the steps for managing audience segments?\"\n- \"Show me how to generate a report\"\n- \"What are best practices for using this API?\"\n\n### get_common_mistakes\n\n**NEW** - Get list of most common API usage mistakes with corrections.\n\n**Returns**:\n- 10+ common mistakes grouped by category\n- Wrong/correct examples for each\n- Severity levels (critical, high, medium)\n- Quick tips summary\n\n**Critical Mistakes**:\n- Sort uppercase (DESC/ASC vs desc/asc)\n- Inline JSON (not using variables)\n- Connection structure (using \"node\" wrapper)\n- Missing root field (dream_adserver)\n\n### get_schema\n\nRetrieve GraphQL schema documentation for a type or operation from ADP API.\n\n**Parameters**:\n- `name` (required): Type name (e.g., \"DASDeal\") or operation name (e.g., \"deals\")\n- `includeRelated` (optional): Include related operations (default: false)\n\n**Enhanced Features**:\n- For operations with JSON parameters (filter, sort), returns `jsonFormat` with:\n  - Operator documentation for filters (=, !=, >, <, >=, <=, in, like)\n  - Format examples and allowed values\n  - Inline hints pointing to `get_common_patterns`\n- For Connection return types, returns `connectionMetadata` with:\n  - Edge structure (direct vs node-wrapped)\n  - What type edges returns\n  - Pagination fields available\n  - Usage examples\n\n**Example**:\n```json\n{\n  \"tool\": \"get_schema\",\n  \"params\": {\n    \"name\": \"lineitems\",\n    \"includeRelated\": false\n  }\n}\n```\n\n**Example Response** (partial):\n```json\n{\n  \"name\": \"lineitems\",\n  \"type\": \"query\",\n  \"arguments\": [\n    {\n      \"name\": \"filter\",\n      \"type\": \"JSON\",\n      \"jsonFormat\": {\n        \"operators\": [\"=\", \"!=\", \">\", \"<\", \">=\", \"<=\", \"in\", \"like\"],\n        \"example\": \"{\\\"lineitem_type\\\": {\\\"=\\\": \\\"MAILING\\\"}}\"\n      },\n      \"hint\": \"💡 Use get_common_patterns to see filtering examples\"\n    }\n  ],\n  \"returnType\": \"DASLineitemConnection\",\n  \"connectionMetadata\": {\n    \"edgesStructure\": \"direct\",\n    \"note\": \"This API uses custom Connection structure WITHOUT node wrapper\",\n    \"edgesReturns\": \"DASLineitem\",\n    \"example\": \"edges { id name } total_count\"\n  }\n}\n```\n\n### get_examples\n\nGet executable GraphQL query examples with variables.\n\n**Parameters**:\n- `operationName` (required): Operation name (e.g., \"deals\", \"set_lineitem\")\n- `includeRealWorld` (optional): Include real-world examples from codebase (default: true)\n\n**Enhanced Features**:\n- When no real-world examples exist, automatically generates examples from schema:\n  - **Simple**: Basic query with common fields (limit: 10)\n  - **Medium**: Query with filter using operator-based syntax\n  - **Advanced**: Full query with filter, sort, and pagination\n- All generated examples are executable and follow API conventions\n- Handles Connection types correctly (no 'node' wrapper)\n\n**Example**:\n```json\n{\n  \"tool\": \"get_examples\",\n  \"params\": {\n    \"operationName\": \"lineitems\"\n  }\n}\n```\n\n**Example Response**:\n```json\n{\n  \"note\": \"No production examples found. Generated examples based on schema:\",\n  \"examplesFromCode\": [],\n  \"generatedExamples\": [\n    {\n      \"name\": \"Basic query - first 10 items\",\n      \"complexity\": \"simple\",\n      \"description\": \"Get first 10 lineitems with common fields\",\n      \"query\": \"query GetLineitems {\\n  dream_adserver {\\n    lineitems(limit: 10) {\\n      edges {\\n        lineitem_id\\n        lineitem_name\\n      }\\n      total_count\\n    }\\n  }\\n}\",\n      \"variables\": {},\n      \"source\": \"generated\"\n    },\n    {\n      \"name\": \"Filtered query - with type filter\",\n      \"complexity\": \"medium\",\n      \"query\": \"...\",\n      \"source\": \"generated\"\n    },\n    {\n      \"name\": \"Full query - with filter and sort\",\n      \"complexity\": \"advanced\",\n      \"query\": \"...\",\n      \"source\": \"generated\"\n    }\n  ]\n}\n```\n\n### get_common_patterns\n\nGet comprehensive documentation of common API usage patterns.\n\n**Parameters**: None\n\n**Returns**:\n- **Filtering**: Operator-based filter syntax with 8 operators\n  - Equality, inequality, comparisons (>, <, >=, <=)\n  - Array membership (in)\n  - Pattern matching (like with SQL wildcards)\n  - 5 real-world examples\n  - Best practice tips\n- **Sorting**: Field-based sort syntax\n  - ASC/DESC directions\n  - Multi-field sorting\n  - Examples and tips\n- **Connections**: Custom Connection structure\n  - Standard vs ADP API structure\n  - Common mistakes and corrections\n  - Working examples\n- **Pagination**: limit/offset patterns\n  - Parameter documentation\n  - Page calculation formula\n  - Multi-page examples\n- **Complete Example**: Full working query combining all patterns\n\n**Example**:\n```json\n{\n  \"tool\": \"get_common_patterns\",\n  \"params\": {}\n}\n```\n\n**Use Cases**:\n- Learning API conventions before writing first query\n- Reference for filter/sort syntax\n- Understanding Connection type structure\n- Debugging query issues\n\n### list_domains\n\nList all API domains with statistics and top operations.\n\n**Parameters**: None\n\n**Enhanced Features**:\n- Lists domains with query/example counts\n- For each domain, shows:\n  - **Top 5 operations** by usage frequency\n  - Whether examples exist for each operation\n  - Operation descriptions\n- **Common patterns summary** for the domain:\n  - Filtering approach\n  - Sorting approach\n  - Connection structure\n  - Pagination method\n\n**Example**:\n```json\n{\n  \"tool\": \"list_domains\",\n  \"params\": {}\n}\n```\n\n**Example Response** (partial):\n```json\n{\n  \"domain\": \"Core\",\n  \"queryCount\": 9,\n  \"exampleCount\": 353,\n  \"topOperations\": [\n    {\n      \"name\": \"lineitems\",\n      \"type\": \"query\",\n      \"hasExamples\": true,\n      \"usageFrequency\": 42,\n      \"description\": \"Fetch line items with filtering and sorting\"\n    }\n  ],\n  \"commonPatterns\": {\n    \"filtering\": \"Uses operator-based JSON filters: {field: {'=': value}}\",\n    \"sorting\": \"Uses field-based JSON: {field: 'ASC'|'DESC'}\",\n    \"connections\": \"Custom structure without 'node' wrapper\",\n    \"pagination\": \"Use limit and offset parameters\"\n  }\n}\n```\n\n## Usage Examples\n\n### Learning the API from Scratch\n\n**Step 1**: Get overview of common patterns\n> \"What are the common patterns for filtering and sorting in ADP API?\"\n\nServer calls `get_common_patterns` → Returns comprehensive pattern documentation\n\n**Step 2**: Explore available domains\n> \"What API domains are available?\"\n\nServer calls `list_domains` → Returns domains with top operations\n\n**Step 3**: Get examples for specific operation\n> \"Show me how to query lineitems\"\n\nServer calls `get_examples` → Returns 3 auto-generated examples (simple, medium, advanced)\n\n**Result**: You can write your first working query in 1-2 iterations instead of 7+\n\n### Query for Type Documentation\n\nAsk in your MCP client:\n> \"What fields are available on the DASDeal type?\"\n\nThe server will call `get_schema` and return complete type documentation from ADP API.\n\nFor operations with filters:\n> \"How do I filter lineitems?\"\n\nServer calls `get_schema` for \"lineitems\" → Returns `jsonFormat` with operator docs and hint to use `get_common_patterns`\n\n### Get Query Examples\n\nAsk in your MCP client:\n> \"Show me examples of how to fetch advertisers from ADP API\"\n\nThe server will call `get_examples` and return executable queries with variables.\n\nIf no real examples exist, you'll get auto-generated examples at 3 complexity levels.\n\n### Understanding Filters and Sorting\n\nAsk in your MCP client:\n> \"How do I use filters in ADP API queries?\"\n\nServer calls `get_common_patterns` → Returns complete filter documentation with operators and examples\n\n> \"Show me how to sort results\"\n\nServer calls `get_common_patterns` → Returns sort syntax and multi-field examples\n\n### Working with Connections\n\nAsk in your MCP client:\n> \"How do Connection types work in ADP API?\"\n\nServer calls `get_common_patterns` → Returns Connection structure docs, highlighting custom structure without 'node' wrapper\n\nOr check schema for specific operation:\n> \"What does the lineitems query return?\"\n\nServer calls `get_schema` → Returns `connectionMetadata` explaining the structure\n\n### Browse Domains\n\nAsk in your MCP client:\n> \"What API domains are available in ADP API?\"\n\nThe server will call `list_domains` and return domain statistics with top operations and pattern summaries.\n\n## Architecture\n\n```\nMCP Client (Claude Desktop / Cline / other)\n    ↓ stdio (JSON-RPC)\nMCP Server (@slawomirjach/adpapi-mcp-server)\n    ↓ HTTP introspection\nADP API GraphQL endpoint\n    ↓ optional: file system\n.graphql example files (if provided)\n```\n\n### How It Works\n\n1. **Initialization**: Server connects to ADP API GraphQL endpoint via introspection query\n2. **Schema Loading**: Builds searchable index of types, operations, and fields\n3. **Auto-Generation**: Creates examples for operations from schema\n4. **MCP Protocol**: Exposes tools via Model Context Protocol for AI assistants\n\n## File Structure\n\n```\nadpapi-mcp-server/\n├── index.js                     # MCP server entry point\n├── logger.js                   # Structured JSON logger\n├── schema-loader.js            # GraphQL schema introspection\n├── example-generator.js        # Auto-generate examples from schema\n├── mcp-tools.js               # MCP tool definitions and handlers\n├── common-patterns.js         # Common API pattern documentation\n├── filter-docs.js             # Filter operator documentation\n└── utils/\n    ├── frequency-analyzer.js    # Usage frequency analysis\n    └── deprecation-detector.js  # Deprecation detection\n```\n\n## Development\n\n### Local Development\n\n```bash\n# Clone and install dependencies\ngit clone <your-fork>\ncd adpapi-mcp-server\nnpm install\n\n# Run with your GraphQL endpoint (with authentication via env vars)\nGRAPHQL_URL=https://adp-api.endpoint.com/1234567/v1 \\\nGRAPHQL_AUTH_LOGIN=YOUR_LOGIN \\\nGRAPHQL_AUTH_TOKEN=YOUR_TOKEN \\\nnpm start\n\n# Or use dev script for local API\nGRAPHQL_URL=http://localhost:3000/graphql \\\nGRAPHQL_AUTH_LOGIN=YOUR_LOGIN \\\nGRAPHQL_AUTH_TOKEN=YOUR_TOKEN \\\nnpm run dev\n```\n\n### Debug Logging\n\n```bash\nGRAPHQL_URL=https://adp-api.endpoint.com/1234567/v1 \\\nGRAPHQL_AUTH_LOGIN=YOUR_LOGIN \\\nGRAPHQL_AUTH_TOKEN=YOUR_TOKEN \\\nDEBUG=true \\\nadpapi-mcp-server\n```\n\n### Adding New Tools\n\n1. Implement tool handler in `mcp-tools.js`\n2. Add tool definition to `getToolDefinitions()`\n3. Register handler in `index.js` CallToolRequestSchema handler\n4. Update README.md with tool documentation\n\n## Performance\n\n- **Startup Time**: ~3-5 seconds (schema + examples loading)\n- **Response Time**: <2 seconds for 95% of requests\n- **Memory Usage**: ~50MB peak\n- **Concurrency**: Handles 10+ concurrent requests\n\n## Troubleshooting\n\n### Server Not Starting\n\nCheck logs for errors:\n```bash\ntail -f ~/.mcp/logs/adpapi-docs.log\n```\n\nVerify ADP API is running:\n```bash\ncurl http://localhost:3000/graphql\n```\n\n### Schema Not Loading\n\nTest introspection query manually:\n```graphql\nquery {\n  __schema {\n    types {\n      name\n    }\n  }\n}\n```\n\n### Examples Not Found\n\n**Note**: The server auto-generates examples from the GraphQL schema, so you should always get usable examples for any GraphQL operation.\n\n### Queries Not Working\n\nCommon issues:\n\n**1. Using 'node' wrapper in Connection queries**\n```graphql\n# ❌ WRONG - Standard GraphQL Connection\nquery {\n  dream_adserver {\n    lineitems {\n      edges {\n        node {  # This doesn't exist in ADP API\n          lineitem_id\n        }\n      }\n    }\n  }\n}\n\n# ✅ CORRECT - ADP API custom Connection\nquery {\n  dream_adserver {\n    lineitems {\n      edges {  # Direct access to items\n        lineitem_id\n      }\n      total_count\n    }\n  }\n}\n```\n\n**2. Wrong filter format**\n```graphql\n# ❌ WRONG - Direct value\nfilter: {\n  lineitem_type: \"MAILING\"\n}\n\n# ✅ CORRECT - Operator-based\nfilter: {\n  lineitem_type: {\"=\": \"MAILING\"}\n}\n```\n\n**3. Wrong sort format**\n```graphql\n# ❌ WRONG - Object with field/order\nsort: {\n  field: \"lineitem_id\",\n  order: \"DESC\"\n}\n\n# ✅ CORRECT - Field as key, direction as value\nsort: {\n  lineitem_id: \"DESC\"\n}\n```\n\n**Solution**: Use `get_common_patterns` tool to see correct formats for all these patterns.\n\n## Node.js Version Requirement\n\nRequires Node.js >= 20\n\n```bash\nnode --version  # Should be v20.0.0 or higher\n```\n\n## Contributing\n\nContributions welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Submit a pull request\n\n## License\n\nMIT\n\n## Resources\n\n- [MCP Specification](https://spec.modelcontextprotocol.io/)\n- [npm Package](https://www.npmjs.com/package/@slawomirjach/adpapi-mcp-server)\n- [GitHub Issues](https://github.com/Ringier-Axel-Springer-PL/adplatform/issues)\n\n## Support\n\nFor issues and questions:\n- Open an issue on GitHub\n- Check existing issues for similar problems\n- Review the troubleshooting section above\n","readmeFilename":"README.md"}