item-wms-public-api-tool 2.0.4

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "item-wms-public-api-tool",
+  "version": "2.0.4",
+  "description": "Public APIs for auth, EDI import, queries, uploads, and item master data.",
+  "main": "dist/index.js",
+  "bin": {
+    "item-wms-public-api-tool": "dist/index.js"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc",
+    "dev": "tsc -w",
+    "sync:api": "node scripts/sync-openapi.js",
+    "start": "node dist/index.js",
+    "lint": "echo \"lint not configured\"",
+    "test": "echo \"tests not configured\""
+  },
+  "keywords": [
+    "wms",
+    "mcp",
+    "api",
+    "cli"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "commander": "^12.0.0",
+    "yaml": "^2.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/scripts/sync-openapi.js

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+const fs = require('fs');
+const path = require('path');
+const http = require('http');
+const https = require('https');
+let YAML = null;
+try {
+  // Optional dependency; fallback to JSON if not installed.
+  // eslint-disable-next-line global-require
+  YAML = require('yaml');
+} catch (error) {
+  YAML = null;
+}
+
+const DEFAULT_OPENAPI_URL = 'http://127.0.0.1:4523/export/openapi/2?version=3.0';
+
+const SOURCE_URL = process.env.APIFOX_OPENAPI_URL || DEFAULT_OPENAPI_URL;
+const SOURCE_FILE = process.env.APIFOX_OPENAPI_FILE;
+
+const SNAPSHOT_PATH = process.env.OPENAPI_SNAPSHOT_PATH
+  || path.join('api', 'openapi.apifox.yaml');
+const OPENAPI_OUTPUT_PATH = process.env.OPENAPI_OUTPUT_PATH || 'openapi.yaml';
+const MCP_OUTPUT_PATH = process.env.MCP_OUTPUT_PATH || 'mcp.json';
+
+const PATH_PREFIX = process.env.APIFOX_PATH_PREFIX || '/v1/public/';
+const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete'];
+
+function isJsonLike(raw) {
+  const trimmed = raw.trimStart();
+  return trimmed.startsWith('{') || trimmed.startsWith('[');
+}
+
+function normalizeToolName(method, pathName) {
+  const normalizedPath = pathName.replace(/[^a-zA-Z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+  return `${method.toLowerCase()}_${normalizedPath.toLowerCase()}`;
+}
+
+function fetchText(url, redirects = 0) {
+  if (redirects > 5) {
+    return Promise.reject(new Error(`Too many redirects for ${url}`));
+  }
+  return new Promise((resolve, reject) => {
+    const lib = url.startsWith('https') ? https : http;
+    const req = lib.get(url, (res) => {
+      const { statusCode, headers } = res;
+      if (statusCode && statusCode >= 300 && statusCode < 400 && headers.location) {
+        res.resume();
+        return resolve(fetchText(headers.location, redirects + 1));
+      }
+      if (statusCode && statusCode >= 400) {
+        res.resume();
+        return reject(new Error(`Request failed: ${statusCode} ${url}`));
+      }
+      let data = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => {
+        data += chunk;
+      });
+      res.on('end', () => resolve(data));
+    });
+    req.on('error', reject);
+  });
+}
+
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+function parseOpenApi(raw) {
+  if (!raw || !raw.trim()) {
+    throw new Error('OpenAPI content is empty.');
+  }
+  if (isJsonLike(raw)) {
+    return JSON.parse(raw);
+  }
+  if (!YAML) {
+    throw new Error('YAML parser not installed. Install "yaml" or export OpenAPI as JSON.');
+  }
+  return YAML.parse(raw);
+}
+
+function stringifyOpenApi(openapi) {
+  if (YAML) {
+    return YAML.stringify(openapi);
+  }
+  return JSON.stringify(openapi, null, 2);
+}
+
+function resolveSchema(schema, components, seen = new Set()) {
+  if (!schema || typeof schema !== 'object') {
+    return schema;
+  }
+  if (schema.$ref && typeof schema.$ref === 'string') {
+    const match = schema.$ref.match(/^#\/components\/schemas\/(.+)$/);
+    if (!match) {
+      return { ...schema };
+    }
+    const name = match[1];
+    if (seen.has(name)) {
+      return { ...schema };
+    }
+    const target = components && components.schemas ? components.schemas[name] : undefined;
+    if (!target) {
+      return { ...schema };
+    }
+    seen.add(name);
+    const resolved = resolveSchema(target, components, seen);
+    seen.delete(name);
+    return resolved;
+  }
+
+  if (Array.isArray(schema.allOf)) {
+    const merged = schema.allOf.reduce((acc, item) => mergeSchema(acc, resolveSchema(item, components, seen)), {
+      type: 'object',
+      properties: {}
+    });
+    const combined = mergeSchema(merged, schema);
+    delete combined.allOf;
+    return combined;
+  }
+
+  const copy = { ...schema };
+  if (Array.isArray(copy.anyOf)) {
+    copy.anyOf = copy.anyOf.map((item) => resolveSchema(item, components, seen));
+  }
+  if (Array.isArray(copy.oneOf)) {
+    copy.oneOf = copy.oneOf.map((item) => resolveSchema(item, components, seen));
+  }
+  if (copy.properties && typeof copy.properties === 'object') {
+    const nextProps = {};
+    for (const [key, value] of Object.entries(copy.properties)) {
+      nextProps[key] = resolveSchema(value, components, seen);
+    }
+    copy.properties = nextProps;
+  }
+  if (copy.items) {
+    copy.items = resolveSchema(copy.items, components, seen);
+  }
+  return copy;
+}
+
+function mergeSchema(base, extra) {
+  const merged = { ...base, ...extra };
+  merged.properties = {
+    ...(base && base.properties ? base.properties : {}),
+    ...(extra && extra.properties ? extra.properties : {})
+  };
+  if (extra && extra.anyOf) {
+    merged.anyOf = extra.anyOf;
+  } else if (base && base.anyOf) {
+    merged.anyOf = base.anyOf;
+  }
+  if (extra && extra.required) {
+    merged.required = extra.required;
+  } else if (base && base.required) {
+    merged.required = base.required;
+  }
+  return merged;
+}
+
+function ensureObjectSchema(schema) {
+  if (!schema || typeof schema !== 'object') {
+    return { type: 'object', properties: {} };
+  }
+  if (!schema.type && !schema.properties) {
+    return { type: 'object', properties: {}, ...schema };
+  }
+  if (schema.type && schema.type !== 'object' && !schema.properties) {
+    return { type: 'object', properties: { body: schema }, required: ['body'] };
+  }
+  if (!schema.properties) {
+    return { ...schema, properties: {} };
+  }
+  return schema;
+}
+
+function buildInputSchema(operation, parameters, components) {
+  const requestSchema = operation.requestBody
+    && operation.requestBody.content
+    && operation.requestBody.content['application/json']
+    && operation.requestBody.content['application/json'].schema;
+  const resolvedSchema = resolveSchema(requestSchema, components);
+  const baseSchema = ensureObjectSchema(resolvedSchema);
+  const requiredSet = new Set(baseSchema.required || []);
+  const properties = { ...(baseSchema.properties || {}) };
+
+  for (const param of parameters) {
+    if (!param || !param.name) {
+      continue;
+    }
+    if (!properties[param.name]) {
+      properties[param.name] = resolveSchema(param.schema, components) || { type: 'string' };
+    }
+    if (param.required) {
+      requiredSet.add(param.name);
+    }
+  }
+
+  const inputSchema = { ...baseSchema, properties };
+  if (requiredSet.size > 0) {
+    inputSchema.required = Array.from(requiredSet);
+  } else {
+    delete inputSchema.required;
+  }
+  return inputSchema;
+}
+
+function buildTools(openapi) {
+  const tools = [];
+  const operations = openapi.paths || {};
+  for (const [pathName, pathItem] of Object.entries(operations)) {
+    if (PATH_PREFIX && !pathName.startsWith(PATH_PREFIX)) {
+      continue;
+    }
+    const commonParams = Array.isArray(pathItem.parameters) ? pathItem.parameters : [];
+    for (const method of HTTP_METHODS) {
+      const operation = pathItem[method];
+      if (!operation) {
+        continue;
+      }
+      const baseName = normalizeToolName(method, pathName);
+      let name = baseName;
+      let counter = 2;
+      while (tools.find((tool) => tool.name === name)) {
+        name = `${baseName}_${counter}`;
+        counter += 1;
+      }
+      const parameters = [
+        ...commonParams,
+        ...(Array.isArray(operation.parameters) ? operation.parameters : [])
+      ];
+      const description = operation.summary || operation.description || `${method.toUpperCase()} ${pathName}`;
+      const inputSchema = buildInputSchema(operation, parameters, openapi.components);
+      tools.push({ name, description, inputSchema });
+    }
+  }
+  tools.sort((a, b) => a.name.localeCompare(b.name));
+  return tools;
+}
+
+async function loadSource() {
+  if (SOURCE_FILE) {
+    return fs.readFileSync(SOURCE_FILE, 'utf8');
+  }
+  return fetchText(SOURCE_URL);
+}
+
+async function main() {
+  const raw = await loadSource();
+  ensureDir(path.dirname(SNAPSHOT_PATH));
+  fs.writeFileSync(SNAPSHOT_PATH, raw.endsWith('\n') ? raw : `${raw}\n`);
+
+  const openapi = parseOpenApi(raw);
+  if (!openapi || !openapi.paths) {
+    throw new Error('Invalid OpenAPI content: missing "paths".');
+  }
+
+  const openapiYaml = stringifyOpenApi(openapi);
+  fs.writeFileSync(OPENAPI_OUTPUT_PATH, openapiYaml.endsWith('\n') ? openapiYaml : `${openapiYaml}\n`);
+
+  const existingMcp = fs.existsSync(MCP_OUTPUT_PATH)
+    ? JSON.parse(fs.readFileSync(MCP_OUTPUT_PATH, 'utf8'))
+    : {
+        id: 'wms.item.public',
+        name: 'item-wms-public-api-tool',
+        version: '0.1.0',
+        description: 'Public APIs for auth, EDI import, queries, uploads, and item master data.',
+        entrypoint: 'item-wms-public-api-tool'
+      };
+
+  const tools = buildTools(openapi);
+  const nextMcp = { ...existingMcp, tools };
+  fs.writeFileSync(MCP_OUTPUT_PATH, `${JSON.stringify(nextMcp, null, 2)}\n`);
+
+  console.log('OK: OpenAPI snapshot saved:', SNAPSHOT_PATH);
+  console.log('OK: openapi.yaml updated:', OPENAPI_OUTPUT_PATH);
+  console.log('OK: mcp.json updated:', MCP_OUTPUT_PATH);
+  if (tools.length === 0) {
+    console.warn('WARN: No tools generated. Check APIFOX_PATH_PREFIX or OpenAPI paths.');
+  }
+}
+
+main().catch((error) => {
+  console.error('ERROR: sync-openapi failed:', error.message);
+  process.exit(1);
+});

package/src/cli.ts

@@ -0,0 +1,353 @@
+// src/cli.ts
+import { Command } from "commander";
+import * as fs from 'fs';
+import * as path from 'path';
+import {
+  DEFAULT_BASE_URL,
+  DEFAULT_COMPANY_ID,
+  DEFAULT_CUSTOMER_ID,
+  DEFAULT_FACILITY_ID
+} from "./config";
+import {
+  buildOpenApiIndex,
+  callOpenApiOperation,
+  loadOpenApiSpec,
+  type McpTool,
+  type OpenApiIndex,
+  type OpenApiOperation
+} from "./openapi-tools";
+
+type ParamPair = {
+  key: string;
+  value: any;
+};
+
+const RESERVED_COMMANDS = new Set(["list", "describe", "call", "help"]);
+
+function parseJsonString(value: string, label: string): any {
+  try {
+    return JSON.parse(value);
+  } catch (error) {
+    throw new Error(`${label} must be valid JSON: ${(error as Error).message}`);
+  }
+}
+
+function readJsonFile(filePath: string, label: string): any {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`File not found: ${filePath}`);
+  }
+  const fileContent = fs.readFileSync(filePath, 'utf8');
+  return parseJsonString(fileContent, label);
+}
+
+function resolveJsonInput(value: string | undefined, filePath: string | undefined, label: string): any {
+  if (value && filePath) {
+    throw new Error(`Provide either ${label} or ${label}File, not both`);
+  }
+  if (value) {
+    return parseJsonString(value, label);
+  }
+  if (filePath) {
+    return readJsonFile(filePath, `${label}File`);
+  }
+  return undefined;
+}
+
+function parseValue(raw: string): any {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return '';
+  }
+  const jsonNumber = /^-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?$/;
+  const shouldParse =
+    trimmed.startsWith('{') ||
+    trimmed.startsWith('[') ||
+    trimmed === 'true' ||
+    trimmed === 'false' ||
+    trimmed === 'null' ||
+    jsonNumber.test(trimmed) ||
+    (trimmed.startsWith('"') && trimmed.endsWith('"'));
+
+  if (shouldParse) {
+    try {
+      return JSON.parse(trimmed);
+    } catch (error) {
+      return raw;
+    }
+  }
+
+  return raw;
+}
+
+function parseParamPair(pair: string): ParamPair {
+  const index = pair.indexOf('=');
+  if (index <= 0) {
+    throw new Error(`Invalid param format: ${pair}. Use key=value`);
+  }
+  const key = pair.slice(0, index).trim();
+  if (!key) {
+    throw new Error(`Invalid param format: ${pair}. Key is required`);
+  }
+  const rawValue = pair.slice(index + 1);
+  return { key, value: parseValue(rawValue) };
+}
+
+function collectParams(value: string, previous: string[]): string[] {
+  return previous.concat(value);
+}
+
+function resolveOpenApiPath(): string | null {
+  const candidates = [
+    process.env.WMS_OPENAPI_PATH,
+    process.env.OPENAPI_PATH,
+    path.resolve(__dirname, '..', 'openapi.yaml'),
+    path.resolve(process.cwd(), 'openapi.yaml')
+  ];
+
+  for (const candidate of candidates) {
+    if (candidate && fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+function readPackageVersion(): string | undefined {
+  const candidates = [
+    path.resolve(__dirname, '..', 'package.json'),
+    path.resolve(process.cwd(), 'package.json')
+  ];
+
+  for (const candidate of candidates) {
+    if (!fs.existsSync(candidate)) {
+      continue;
+    }
+    try {
+      const raw = fs.readFileSync(candidate, 'utf8');
+      const data = JSON.parse(raw) as { version?: string };
+      if (data.version) {
+        return data.version;
+      }
+    } catch (error) {
+      continue;
+    }
+  }
+
+  return undefined;
+}
+
+function loadOpenApiIndex(): OpenApiIndex {
+  const openApiPath = resolveOpenApiPath();
+  if (!openApiPath) {
+    throw new Error('OpenAPI spec not found. Run sync:api or set WMS_OPENAPI_PATH.');
+  }
+  const spec = loadOpenApiSpec(openApiPath);
+  const hasPrefixEnv = Object.prototype.hasOwnProperty.call(process.env, 'APIFOX_PATH_PREFIX');
+  const pathPrefix = hasPrefixEnv ? process.env.APIFOX_PATH_PREFIX : '/v1/public/';
+  const normalizedPrefix = pathPrefix && pathPrefix.length > 0 ? pathPrefix : undefined;
+  return buildOpenApiIndex(spec, { pathPrefix: normalizedPrefix });
+}
+
+function buildPayload(options: { json?: string; file?: string; param?: string[] }): Record<string, any> {
+  const base = resolveJsonInput(options.json, options.file, 'json');
+  let payload: Record<string, any> = {};
+
+  if (base !== undefined) {
+    if (base && typeof base === 'object' && !Array.isArray(base)) {
+      payload = { ...base };
+    } else {
+      payload = { body: base };
+    }
+  }
+
+  const params = options.param || [];
+  for (const entry of params) {
+    const { key, value } = parseParamPair(entry);
+    payload[key] = value;
+  }
+
+  return payload;
+}
+
+function listOperations(index: OpenApiIndex): Array<{ name: string; method: string; path: string; description: string }> {
+  return Object.values(index.operations)
+    .map((operation) => ({
+      name: operation.name,
+      method: operation.method.toUpperCase(),
+      path: operation.path,
+      description: operation.description
+    }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function formatOperationLine(operation: { name: string; method: string; path: string; description: string }): string {
+  const detail = operation.description ? ` - ${operation.description}` : '';
+  return `${operation.name}\t${operation.method} ${operation.path}${detail}`;
+}
+
+function getToolByName(index: OpenApiIndex, name: string): McpTool | undefined {
+  return index.tools.find((tool) => tool.name === name);
+}
+
+function createCallAction(
+  operation: OpenApiOperation,
+  program: Command
+): (options: { json?: string; file?: string; param?: string[] }) => Promise<void> {
+  return async (options) => {
+    const payload = buildPayload(options);
+    const global = program.opts();
+    const result = await callOpenApiOperation(operation, payload, {
+      baseUrl: global.baseUrl,
+      token: global.token
+    });
+    console.log(JSON.stringify(result, null, 2));
+  };
+}
+
+/**
+ * 创建并配置CLI命令
+ */
+export function createCli(): Command {
+  const program = new Command();
+
+  program
+    .name("item-wms-public-api-tool")
+    .option("--baseUrl <url>", "API base url", process.env.WMS_BASE_URL || DEFAULT_BASE_URL)
+    .option("--token <token>", "Auth token", process.env.WMS_TOKEN)
+    .option(
+      "--companyId <id>",
+      "Default CompanyID for requests",
+      process.env.WMS_COMPANY_ID || DEFAULT_COMPANY_ID
+    )
+    .option(
+      "--facilityId <id>",
+      "Default FacilityID for requests",
+      process.env.WMS_FACILITY_ID || DEFAULT_FACILITY_ID
+    )
+    .option(
+      "--customerId <id>",
+      "Default CustomerID for requests",
+      process.env.WMS_CUSTOMER_ID || DEFAULT_CUSTOMER_ID
+    );
+
+  const version = readPackageVersion();
+  if (version) {
+    program.version(version);
+  }
+
+  let openApiIndex: OpenApiIndex | null = null;
+  let openApiError: Error | null = null;
+
+  try {
+    openApiIndex = loadOpenApiIndex();
+  } catch (error) {
+    openApiError = error as Error;
+  }
+
+  const requireIndex = (): OpenApiIndex => {
+    if (openApiIndex) {
+      return openApiIndex;
+    }
+    throw openApiError || new Error('OpenAPI spec not loaded.');
+  };
+
+  program
+    .command('list')
+    .description('List available OpenAPI operations')
+    .option('--json', 'Output JSON')
+    .action((options) => {
+      const index = requireIndex();
+      const operations = listOperations(index);
+      if (options.json) {
+        console.log(JSON.stringify(operations, null, 2));
+        return;
+      }
+      operations.forEach((operation) => {
+        console.log(formatOperationLine(operation));
+      });
+    });
+
+  program
+    .command('describe')
+    .description('Show OpenAPI details for an operation')
+    .argument('<name>', 'Operation/tool name')
+    .option('--json', 'Output JSON')
+    .action((name, options) => {
+      const index = requireIndex();
+      const operation = index.operations[name];
+      if (!operation) {
+        throw new Error(`Unknown operation: ${name}`);
+      }
+      const tool = getToolByName(index, name);
+      if (options.json) {
+        console.log(JSON.stringify({
+          name,
+          method: operation.method.toUpperCase(),
+          path: operation.path,
+          description: operation.description,
+          inputSchema: tool?.inputSchema
+        }, null, 2));
+        return;
+      }
+      console.log(`${operation.method.toUpperCase()} ${operation.path}`);
+      if (operation.description) {
+        console.log(operation.description);
+      }
+      if (tool?.inputSchema) {
+        console.log('Input schema:');
+        console.log(JSON.stringify(tool.inputSchema, null, 2));
+      }
+    });
+
+  program
+    .command('call')
+    .description('Call an OpenAPI operation by name')
+    .argument('<name>', 'Operation/tool name')
+    .option('--json <json>', 'JSON payload for all params/body')
+    .option('--file <file>', 'Path to JSON payload file')
+    .option('-p, --param <key=value>', 'Set a param (repeatable)', collectParams, [])
+    .action(async (name, options) => {
+      const index = requireIndex();
+      const operation = index.operations[name];
+      if (!operation) {
+        throw new Error(`Unknown operation: ${name}`);
+      }
+      const payload = buildPayload(options);
+      const global = program.opts();
+      const result = await callOpenApiOperation(operation, payload, {
+        baseUrl: global.baseUrl,
+        token: global.token
+      });
+      console.log(JSON.stringify(result, null, 2));
+    });
+
+  if (openApiIndex) {
+    const operations = Object.values(openApiIndex.operations)
+      .filter((operation) => !RESERVED_COMMANDS.has(operation.name))
+      .sort((a, b) => a.name.localeCompare(b.name));
+
+    operations.forEach((operation) => {
+      const summary = operation.description
+        ? `${operation.method.toUpperCase()} ${operation.path} - ${operation.description}`
+        : `${operation.method.toUpperCase()} ${operation.path}`;
+
+      program
+        .command(operation.name)
+        .description(summary)
+        .option('--json <json>', 'JSON payload for all params/body')
+        .option('--file <file>', 'Path to JSON payload file')
+        .option('-p, --param <key=value>', 'Set a param (repeatable)', collectParams, [])
+        .action(createCallAction(operation, program));
+    });
+  }
+
+  return program;
+}
+
+/**
+ * 解析CLI命令并执行
+ */
+export async function parseAndExecuteCli(): Promise<void> {
+  const program = createCli();
+  await program.parseAsync();
+}