From cc34894ae453d539d64b9149641b9b772469b47b Mon Sep 17 00:00:00 2001 From: Arthur Ria Date: Tue, 25 Aug 2026 11:12:14 +0200 Subject: [PATCH] =?UTF-8?q?L4.0=20:=20corrige=20api://catalog=20qui=20ense?= =?UTF-8?q?ignait=20le=20pi=C3=A8ge=20D3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit La resource api://catalog, lue par les sessions Claude, contredisait les décisions actées : - exemple QueryExecute en QueryType 1 (D3 interdit de le recopier) ; - Select/Take dans l'expression, contraire à la répartition expression/options et à D13 (projections instables) ; - entité fantôme Aliases (corrigée partout ailleurs au lot 2) ; - exemple Command avec suffixe d'assembly, cause de FileLoadException (D14) ; - réponse Workflow décrite avec des champs inexistants (Category, Status, Definition) au lieu des clés réelles minuscules id/name/version/ applicationName/commonInfo (D4, D5) ; - section Configuration décrivant l'ancien .env mono-profil (D8). L'exemple passe en QueryType 0 avec les règles de répartition, la liste d'entités renvoie vers get_entity_metadata comme source de vérité, la réponse AD documente l'enveloppe { entities: [...] }. Vérifié via le protocole (resources/read api://catalog) : contient "QueryType": 1 : false contient Aliases : false renvoie vers get_entity_metadata : true tools/list : 23 outils, resources : inchangées. Co-Authored-By: Claude Fable 5 --- src/resources/apis.js | 161 +++++++++++++++++------------------------- 1 file changed, 63 insertions(+), 98 deletions(-) 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. `; }