diff --git a/src/resources/apis.js b/src/resources/apis.js index db6f702..f5430c3 100644 --- a/src/resources/apis.js +++ b/src/resources/apis.js @@ -42,9 +42,13 @@ function getAPICatalog() { The WMS provides several REST APIs for querying and modifying data. -**Base URL:** \`${process.env.WMS_API_BASE_URL || 'https://10.255.255.2/ApplicationService/api'}\` +**Base URL:** \`https:///ApplicationService/api\` — built from the active +profile's host (see \`get_current_wms_profile\`). **Authentication:** OAuth 2.0 Bearer Token (automatic) +The generated help page at \`https:///ApplicationService/Help\` is the +authoritative reference for endpoints and fields. + --- ## Query API @@ -60,44 +64,55 @@ Execute LINQ queries against WMS entities. \`\`\`json { "Application": "EasyWMS", - "QueryType": 1, - "Expression": "Context.{EntityType}.Select(z => z)" + "QueryType": 0, + "Expression": "Context.Products.Where(z => z.Code == \\"X\\").OrderBy(z => z.Id)", + "Take": 100 } \`\`\` -### Supported Entity Types +Rules (see the query tools for details): -| Entity Type | Description | -|-------------|-------------| -| Products | Product references and SKUs | -| Containers | Pallets, boxes, and container types | -| Stocks | Available inventory by location | -| ProductLocations | Product placement in warehouse | -| Tasks | WMS tasks (picks, puts, moves, etc.) | -| Accounts | Customer accounts | -| Suppliers | Supplier information | -| Kits | Product kits and bundles | -| Aliases | Product aliases and alternative codes | -| InboundOrders | Inbound/receiving orders | -| Receptions | Actual receptions | -| OutboundOrders | Outbound/shipping orders | +- **\`QueryType: 0\` (Reading) is the default** — status fields are strings + (\`"Release"\`). \`QueryType: 1\` (Writing) exists but status fields become + enums there: string comparisons fail. Old examples using \`1\` must not be + copied. +- **\`Where\` and \`OrderBy\` go in the Expression; \`Take\`/\`Skip\` are API + parameters.** \`OrderBy\` is mandatory as soon as \`Take\` is used. +- **No \`Select\` projections** — the \`Select\` parameter causes server-side + compile errors. Query full rows. +- **No relative dates** (\`DateTime.Now\`, \`AddDays()\`) — write literal dates: + \`new DateTime(2026, 8, 1)\`. -### Example Queries +### Entity Types + +Common entities: Products, Containers, Stocks, ProductLocations, Tasks, +Accounts, Suppliers, Kits, Alias (invariant — no plural form), InboundOrders, +Receptions, OutboundOrders. + +**The authoritative list (288 entities) comes from \`get_entity_metadata\`** +(Metadata API) — entity names are resolved case-insensitively from the AD name +(Container) or the TableName (Containers). + +### Example Expressions \`\`\` -# Get all products (limited) -Context.Products.Take(100).Select(z => z) +# Filter + mandatory OrderBy (Take passed as API parameter, not in the expression) +Context.Products.Where(z => z.Code.Contains("ABC")).OrderBy(z => z.Id) -# Get specific fields -Context.Products.Select(z => new { z.Id, z.Code, z.Name }) - -# Filter and select -Context.Tasks.Where(z => z.Status == "Pending").Take(50).Select(z => z) +# Status comparison — strings in Reading (QueryType 0) +Context.OutboundOrders.Where(z => z.OutboundOrderStatus == "Release").OrderBy(z => z.Id) \`\`\` -### MCP Tool +### Counting -Use \`call_query_api\` tool to execute queries. +**Endpoint:** \`/api/QueryScalarExecute\` — same body, expression ends with +\`.Count()\` / \`.Sum(...)\`. Prefer the \`count_wms_entities\` tool for any +"how many" question. + +### MCP Tools + +\`query_wms_entities\`, \`count_wms_entities\`, \`call_query_api\`, +\`get_entity_schema\`, \`search_wms_data\`. --- @@ -114,31 +129,7 @@ Execute commands to modify WMS data. \`\`\`json [ { - "Name": "CommandName, Mecalux.ITSW.EasyWMS.Modules.Contracts", - "Properties": { - "PropertyName": "value" - } - } -] -\`\`\` - -### Common Commands - -| Command | Description | -|---------|-------------| -| ProductRemoveCommand | Remove a product | -| ProductUpdateCommand | Update product information | -| ContainerCreateCommand | Create a new container | -| TaskCancelCommand | Cancel a task | -| InboundOrderCancelCommandV2 | Cancel an inbound order | -| OutboundOrderCancelCommand | Cancel an outbound order | - -### Example Command - -\`\`\`json -[ - { - "Name": "Mecalux.ITSW.EasyWMS.Modules.MasterData.Contracts.Commands.ProductRemoveCommand, Mecalux.ITSW.EasyWMS.Modules.Contracts", + "Name": "Mecalux.ITSW.EasyWMS.Modules.MasterData.Contracts.Commands.ProductRemoveCommand", "Properties": { "Id": "product-guid-here" } @@ -146,6 +137,11 @@ Execute commands to modify WMS data. ] \`\`\` +**\`Name\` is the \`InternalCommandName\` from the Application Dictionary, used +as-is.** Never append an assembly suffix (\`, Mecalux.ITSW...Contracts\`) — it +causes a \`FileLoadException\`. Retrieve the exact name via +\`get_ad_element_details\` before executing. + ### MCP Tool Use \`execute_command\` tool to execute commands. @@ -154,7 +150,7 @@ Use \`execute_command\` tool to execute commands. --- -## Workflow API +## Workflow API (Application Dictionary) Retrieve workflow definitions by application. @@ -165,30 +161,23 @@ Retrieve workflow definitions by application. ### Request Format \`\`\`json -["EasyWMS", "AD", 5000, 0] +["EasyWMS", "", 5000, 0] \`\`\` -Parameters: -1. Application name (e.g., "EasyWMS") -2. Tenant code (e.g., "AD") -3. Page size (e.g., 5000) -4. Offset (e.g., 0 for first page) +Parameters (positional): application name, tenant code, page size, offset. ### Response -Array of workflow objects with: -- Id, Code, Name -- Category, Description -- Version, Status -- Created, Modified -- Definition (JSON) +An envelope object \`{ "entities": [...] }\` — **not** a bare array. Each +workflow object carries lowercase keys: \`id\`, \`name\`, \`version\`, +\`applicationName\`, \`commonInfo\` (createdBy, createDate, updateDate). There +is no category, code or description field. ### MCP Tools -Use workflow tools to interact with workflows: -- \`search_workflows\` - Search by name, code, description +- \`search_workflows\` - Search by name - \`get_workflow_details\` - Get full workflow definition -- \`list_workflow_categories\` - List all categories +- \`list_workflow_categories\` - List applications (workflows have no category field) --- @@ -197,13 +186,13 @@ Use workflow tools to interact with workflows: All APIs use OAuth 2.0 authentication. **Token Endpoint:** \`/EasySTS/OAuth/Token\` -**Grant Types:** password, refresh_token +**Grant Types:** password, refresh_token (\`tenant_code\` is mandatory) ### Token Management - Tokens expire after ~1200 seconds - Automatic refresh when < 1000 seconds remaining -- Credentials configured in .env file +- Credentials come from the active profile (multi-profile \`.env\`) The MCP server handles authentication automatically. @@ -217,16 +206,10 @@ The MCP server handles authentication automatically. - \`400\` - Bad request (invalid query/command) - \`401\` - Unauthorized (token expired or invalid) - \`403\` - Forbidden (insufficient permissions) -- \`500\` - Internal server error +- \`500\` - Internal server error (incl. LINQ compile errors) -### Error Response Format - -\`\`\`json -{ - "error": "Error message", - "details": "Detailed error information" -} -\`\`\` +The response body of a 500 carries the real diagnostic (e.g. the compile +error naming the context) — MCP tools surface it in their error messages. --- @@ -238,24 +221,6 @@ The MCP server handles authentication automatically. --- -## Configuration - -API settings are configured via environment variables: - -\`\`\`env -WMS_API_BASE_URL=https://10.255.255.2/ApplicationService/api -WMS_API_TOKEN_URL=https://10.255.255.2/EasySTS/OAuth/Token -WMS_API_TENANT=AD -WMS_API_USERNAME=your-username -WMS_API_PASSWORD=your-password -WORKFLOW_API_BASE=https://10.255.255.2/AD/api -WORKFLOW_PAGE_SIZE=5000 -MAX_QUERY_ROWS=1000 -QUERY_TIMEOUT=30000 -\`\`\` - ---- - **Note:** Use MCP tools to interact with these APIs. Direct API calls require proper authentication handling. `; }