Mecalux/mcp-wms-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

L4.0 : corrige api://catalog qui enseignait le piège D3

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
Arthur Ria
2026-08-25 11:12:14 +02:00
parent 35b53dbef5
commit cc34894ae4
1 changed files with 63 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/resources/apis.js
+63 -98
View File
@@ -42,9 +42,13 @@ function getAPICatalog() {
The WMS provides several REST APIs for querying and modifying data. 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://<host>/ApplicationService/api\` — built from the active
profile's host (see \`get_current_wms_profile\`).
**Authentication:** OAuth 2.0 Bearer Token (automatic) **Authentication:** OAuth 2.0 Bearer Token (automatic)
The generated help page at \`https://<host>/ApplicationService/Help\` is the
authoritative reference for endpoints and fields.
--- ---
## Query API ## Query API
@@ -60,44 +64,55 @@ Execute LINQ queries against WMS entities.
\`\`\`json \`\`\`json
{ {
"Application": "EasyWMS", "Application": "EasyWMS",
"QueryType": 1, "QueryType": 0,
"Expression": "Context.{EntityType}.Select(z => z)" "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 | - **\`QueryType: 0\` (Reading) is the default** — status fields are strings
|-------------|-------------| (\`"Release"\`). \`QueryType: 1\` (Writing) exists but status fields become
| Products | Product references and SKUs | enums there: string comparisons fail. Old examples using \`1\` must not be
| Containers | Pallets, boxes, and container types | copied.
| Stocks | Available inventory by location | - **\`Where\` and \`OrderBy\` go in the Expression; \`Take\`/\`Skip\` are API
| ProductLocations | Product placement in warehouse | parameters.** \`OrderBy\` is mandatory as soon as \`Take\` is used.
| Tasks | WMS tasks (picks, puts, moves, etc.) | - **No \`Select\` projections** — the \`Select\` parameter causes server-side
| Accounts | Customer accounts | compile errors. Query full rows.
| Suppliers | Supplier information | - **No relative dates** (\`DateTime.Now\`, \`AddDays()\`) — write literal dates:
| Kits | Product kits and bundles | \`new DateTime(2026, 8, 1)\`.
| Aliases | Product aliases and alternative codes |
| InboundOrders | Inbound/receiving orders |
| Receptions | Actual receptions |
| OutboundOrders | Outbound/shipping orders |
### 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) # Filter + mandatory OrderBy (Take passed as API parameter, not in the expression)
Context.Products.Take(100).Select(z => z) Context.Products.Where(z => z.Code.Contains("ABC")).OrderBy(z => z.Id)
# Get specific fields # Status comparison — strings in Reading (QueryType 0)
Context.Products.Select(z => new { z.Id, z.Code, z.Name }) Context.OutboundOrders.Where(z => z.OutboundOrderStatus == "Release").OrderBy(z => z.Id)
# Filter and select
Context.Tasks.Where(z => z.Status == "Pending").Take(50).Select(z => z)
\`\`\` \`\`\`
### 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 \`\`\`json
[ [
{ {
"Name": "CommandName, Mecalux.ITSW.EasyWMS.Modules.Contracts", "Name": "Mecalux.ITSW.EasyWMS.Modules.MasterData.Contracts.Commands.ProductRemoveCommand",
"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",
"Properties": { "Properties": {
"Id": "product-guid-here" "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 ### MCP Tool
Use \`execute_command\` tool to execute commands. 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. Retrieve workflow definitions by application.
@@ -165,30 +161,23 @@ Retrieve workflow definitions by application.
### Request Format ### Request Format
\`\`\`json \`\`\`json
["EasyWMS", "AD", 5000, 0] ["EasyWMS", "<tenant>", 5000, 0]
\`\`\` \`\`\`
Parameters: Parameters (positional): application name, tenant code, page size, offset.
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)
### Response ### Response
Array of workflow objects with: An envelope object \`{ "entities": [...] }\` — **not** a bare array. Each
- Id, Code, Name workflow object carries lowercase keys: \`id\`, \`name\`, \`version\`,
- Category, Description \`applicationName\`, \`commonInfo\` (createdBy, createDate, updateDate). There
- Version, Status is no category, code or description field.
- Created, Modified
- Definition (JSON)
### MCP Tools ### MCP Tools
Use workflow tools to interact with workflows: - \`search_workflows\` - Search by name
- \`search_workflows\` - Search by name, code, description
- \`get_workflow_details\` - Get full workflow definition - \`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. All APIs use OAuth 2.0 authentication.
**Token Endpoint:** \`/EasySTS/OAuth/Token\` **Token Endpoint:** \`/EasySTS/OAuth/Token\`
**Grant Types:** password, refresh_token **Grant Types:** password, refresh_token (\`tenant_code\` is mandatory)
### Token Management ### Token Management
- Tokens expire after ~1200 seconds - Tokens expire after ~1200 seconds
- Automatic refresh when < 1000 seconds remaining - 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. The MCP server handles authentication automatically.
@@ -217,16 +206,10 @@ The MCP server handles authentication automatically.
- \`400\` - Bad request (invalid query/command) - \`400\` - Bad request (invalid query/command)
- \`401\` - Unauthorized (token expired or invalid) - \`401\` - Unauthorized (token expired or invalid)
- \`403\` - Forbidden (insufficient permissions) - \`403\` - Forbidden (insufficient permissions)
- \`500\` - Internal server error - \`500\` - Internal server error (incl. LINQ compile errors)
### Error Response Format 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.
\`\`\`json
{
"error": "Error message",
"details": "Detailed error information"
}
\`\`\`
--- ---
@@ -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. **Note:** Use MCP tools to interact with these APIs. Direct API calls require proper authentication handling.
`; `;
} }