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.
**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)
The generated help page at \`https://<host>/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", "<tenant>", 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.
`;
}