@vibetools/dokploy-mcp 2.1.1 → 2.2.0

package/dist/codemode/context/search-context.js

@@ -1,29 +1,61 @@
-import { dokployCatalog, getCatalogEndpoint, getCatalogEndpointsByTag, } from '../../generated/dokploy-catalog.js';
+import { dokployCatalog } from '../../generated/dokploy-catalog.js';
 import { procedureSchemas } from '../../generated/dokploy-schemas.js';
+import { applyCatalogResponseHints, getCatalogResponseHints, } from '../overrides/catalog-overrides.js';
+import { applyProcedureInputMetadata, getEffectiveProcedureSchema, } from '../overrides/procedure-overrides.js';
+import { getVirtualCatalogEndpoints, getVirtualProcedureSchema, } from '../overrides/virtual-procedures.js';
+function createCatalogEndpointView(endpoint) {
+    return applyCatalogResponseHints(applyProcedureInputMetadata(endpoint));
+}
+function createCatalogIndexes(endpoints) {
+    const byTag = {};
+    const byProcedure = {};
+    const byPath = {};
+    for (const [index, endpoint] of endpoints.entries()) {
+        byProcedure[endpoint.procedure] = index;
+        byPath[endpoint.path] = index;
+        const tagIndexes = byTag[endpoint.tag] ?? [];
+        tagIndexes.push(index);
+        byTag[endpoint.tag] = tagIndexes;
+    }
+    return {
+        byTag,
+        byProcedure,
+        byPath,
+    };
+}
 export function createSearchCatalogView() {
+    const endpoints = [
+        ...dokployCatalog.endpoints.map(createCatalogEndpointView),
+        ...getVirtualCatalogEndpoints().map(applyCatalogResponseHints),
+    ];
+    const indexes = createCatalogIndexes(endpoints);
     return {
-        endpoints: dokployCatalog.endpoints,
-        byTag: dokployCatalog.byTag,
-        byProcedure: dokployCatalog.byProcedure,
-        byPath: dokployCatalog.byPath,
+        endpoints,
+        byTag: indexes.byTag,
+        byProcedure: indexes.byProcedure,
+        byPath: indexes.byPath,
         get: (id) => {
-            const endpoint = getCatalogEndpoint(id);
+            const index = indexes.byProcedure[id] ?? indexes.byPath[id];
+            const endpoint = index === undefined ? null : endpoints[index];
             if (!endpoint)
                 return null;
             const procedure = endpoint.procedure;
-            const schema = procedureSchemas[procedure];
+            const schema = getVirtualProcedureSchema(procedure) ??
+                getEffectiveProcedureSchema(procedure) ??
+                procedureSchemas[procedure];
             return {
                 ...endpoint,
                 inputSchema: schema?.inputSchema ?? null,
                 outputSchema: schema?.outputSchema ?? null,
             };
         },
-        getByTag: (tag) => getCatalogEndpointsByTag(tag),
+        getByTag: (tag) => (indexes.byTag[tag] ?? []).map((index) => endpoints[index]).filter(Boolean),
         searchText: (query) => {
             const normalized = query.trim().toLowerCase();
             if (normalized.length === 0)
                 return [];
-            return dokployCatalog.endpoints.filter((endpoint) => {
+            return endpoints.filter((endpoint) => {
+                const hints = getCatalogResponseHints(endpoint.procedure);
                 const haystack = [
                     endpoint.procedure,
                     endpoint.path,
@@ -32,6 +64,10 @@ export function createSearchCatalogView() {
                     endpoint.description ?? '',
                     ...endpoint.requiredInputs,
                     ...endpoint.optionalInputs,
+                    ...(hints?.commonResponseFields ?? []),
+                    ...(hints?.responseHints ?? []),
+                    ...(hints?.examples ?? []),
+                    ...(hints?.notes ?? []),
                 ]
                     .join(' ')
                     .toLowerCase();

package/dist/codemode/gateway/api-gateway.js

@@ -1,5 +1,6 @@
 import { ApiError, api } from '../../api/client.js';
 import { procedureSchemas } from '../../generated/dokploy-schemas.js';
+import { getEffectiveProcedureSchema, mapProcedureInput, transformProcedureResponse, validateProcedureInput, } from '../overrides/procedure-overrides.js';
 import { formatGatewayError } from './error-format.js';
 import { finishTrace, startTrace } from './trace.js';
 const RETRYABLE_STATUS_CODES = new Set([429, 502, 503, 504]);
@@ -50,10 +51,11 @@ function validateTypedSchema(value, schemaObject, path) {
         case 'array':
             return validateArraySchema(value, schemaObject, path);
         case 'string':
-            return validatePrimitive(value, 'string', path);
+            return validateStringSchema(value, schemaObject, path);
         case 'number':
+            return validateNumberSchema(value, schemaObject, path);
         case 'integer':
-            return validatePrimitive(value, 'number', path);
+            return validateIntegerSchema(value, schemaObject, path);
         case 'boolean':
             return validatePrimitive(value, 'boolean', path);
         case 'null':
@@ -69,12 +71,36 @@ function validateObjectSchema(value, schemaObject, path) {
     const objectValue = value;
     const properties = schemaObject.properties ?? {};
     const required = schemaObject.required ?? [];
+    const additionalProperties = schemaObject.additionalProperties;
+    return [
+        ...validateRequiredObjectKeys(objectValue, required, path),
+        ...validateUnexpectedObjectKeys(objectValue, properties, additionalProperties, path),
+        ...validateObjectProperties(objectValue, properties, path),
+    ];
+}
+function validateRequiredObjectKeys(objectValue, required, path) {
     const errors = [];
     for (const key of required) {
         if (!(key in objectValue) || objectValue[key] == null) {
             errors.push(`${path ? `${path}.` : ''}${key} is required`);
         }
     }
+    return errors;
+}
+function validateUnexpectedObjectKeys(objectValue, properties, additionalProperties, path) {
+    if (additionalProperties !== false) {
+        return [];
+    }
+    const errors = [];
+    for (const key of Object.keys(objectValue)) {
+        if (!(key in properties)) {
+            errors.push(`${path ? `${path}.` : ''}${key} is not allowed`);
+        }
+    }
+    return errors;
+}
+function validateObjectProperties(objectValue, properties, path) {
+    const errors = [];
     for (const [key, propertySchema] of Object.entries(properties)) {
         if (key in objectValue) {
             errors.push(...validateAgainstSchema(objectValue[key], propertySchema, path ? `${path}.${key}` : key));
@@ -88,6 +114,14 @@ function validateArraySchema(value, schemaObject, path) {
     }
     const itemSchema = schemaObject.items;
     const errors = [];
+    const minItems = typeof schemaObject.minItems === 'number' ? schemaObject.minItems : undefined;
+    const maxItems = typeof schemaObject.maxItems === 'number' ? schemaObject.maxItems : undefined;
+    if (minItems !== undefined && value.length < minItems) {
+        errors.push(`${path || 'value'} must contain at least ${minItems} items`);
+    }
+    if (maxItems !== undefined && value.length > maxItems) {
+        errors.push(`${path || 'value'} must contain at most ${maxItems} items`);
+    }
     for (const [index, entry] of value.entries()) {
         errors.push(...validateAgainstSchema(entry, itemSchema, `${path || 'value'}[${index}]`));
     }
@@ -96,8 +130,61 @@ function validateArraySchema(value, schemaObject, path) {
 function validatePrimitive(value, type, path) {
     return typeof value === type ? [] : [`${path || 'value'} must be a ${type}`];
 }
+function validateStringSchema(value, schemaObject, path) {
+    const primitiveErrors = validatePrimitive(value, 'string', path);
+    if (primitiveErrors.length > 0) {
+        return primitiveErrors;
+    }
+    const stringValue = value;
+    const errors = [];
+    const minLength = typeof schemaObject.minLength === 'number' ? schemaObject.minLength : undefined;
+    const maxLength = typeof schemaObject.maxLength === 'number' ? schemaObject.maxLength : undefined;
+    const pattern = typeof schemaObject.pattern === 'string' ? schemaObject.pattern : undefined;
+    if (minLength !== undefined && stringValue.length < minLength) {
+        errors.push(`${path || 'value'} must have length >= ${minLength}`);
+    }
+    if (maxLength !== undefined && stringValue.length > maxLength) {
+        errors.push(`${path || 'value'} must have length <= ${maxLength}`);
+    }
+    if (pattern && !new RegExp(pattern).test(stringValue)) {
+        errors.push(`${path || 'value'} must match pattern ${pattern}`);
+    }
+    return errors;
+}
+function validateNumberSchema(value, schemaObject, path) {
+    const primitiveErrors = validatePrimitive(value, 'number', path);
+    if (primitiveErrors.length > 0) {
+        return primitiveErrors;
+    }
+    return validateNumericBounds(value, schemaObject, path);
+}
+function validateIntegerSchema(value, schemaObject, path) {
+    const primitiveErrors = validatePrimitive(value, 'number', path);
+    if (primitiveErrors.length > 0) {
+        return primitiveErrors;
+    }
+    const numberValue = value;
+    const errors = [];
+    if (!Number.isInteger(numberValue)) {
+        errors.push(`${path || 'value'} must be an integer`);
+    }
+    errors.push(...validateNumericBounds(numberValue, schemaObject, path));
+    return errors;
+}
+function validateNumericBounds(value, schemaObject, path) {
+    const errors = [];
+    const minimum = typeof schemaObject.minimum === 'number' ? schemaObject.minimum : undefined;
+    const maximum = typeof schemaObject.maximum === 'number' ? schemaObject.maximum : undefined;
+    if (minimum !== undefined && value < minimum) {
+        errors.push(`${path || 'value'} must be >= ${minimum}`);
+    }
+    if (maximum !== undefined && value > maximum) {
+        errors.push(`${path || 'value'} must be <= ${maximum}`);
+    }
+    return errors;
+}
 export async function invokeProcedureWithApi(procedure, input = {}, requestApi = api) {
-    const schema = procedureSchemas[procedure];
+    const schema = getEffectiveProcedureSchema(procedure) ?? procedureSchemas[procedure];
     if (!schema) {
         throw formatGatewayError({
             type: 'validation_error',
@@ -106,6 +193,7 @@ export async function invokeProcedureWithApi(procedure, input = {}, requestApi =
         });
     }
     const validationErrors = validateAgainstSchema(input, schema.inputSchema);
+    validationErrors.push(...validateProcedureInput(procedure, input));
     if (validationErrors.length > 0) {
         throw formatGatewayError({
             type: 'validation_error',
@@ -115,13 +203,15 @@ export async function invokeProcedureWithApi(procedure, input = {}, requestApi =
     }
     const trace = startTrace(procedure, schema.method);
     const maxRetries = resolveGatewayRetryCount();
+    const requestInput = mapProcedureInput(procedure, input);
     try {
         let attempt = 0;
         while (true) {
             try {
-                const data = schema.method === 'GET'
-                    ? await requestApi.get(schema.path, input)
-                    : await requestApi.post(schema.path, input);
+                const response = schema.method === 'GET'
+                    ? await requestApi.get(schema.path, requestInput)
+                    : await requestApi.post(schema.path, requestInput);
+                const data = transformProcedureResponse(procedure, input, response);
                 return {
                     data,
                     trace: finishTrace(trace),

package/dist/codemode/overrides/catalog-overrides.d.ts

@@ -0,0 +1,10 @@
+import type { CatalogEndpoint } from '../../generated/dokploy-catalog.js';
+export interface CatalogResponseHints {
+    commonResponseFields?: string[];
+    responseHints?: string[];
+    examples?: string[];
+    notes?: string[];
+}
+export type CatalogEndpointWithHints = CatalogEndpoint & CatalogResponseHints;
+export declare function getCatalogResponseHints(procedure: string): CatalogResponseHints | null;
+export declare function applyCatalogResponseHints(endpoint: CatalogEndpoint): CatalogEndpointWithHints;

package/dist/codemode/overrides/catalog-overrides.js

@@ -0,0 +1,79 @@
+const catalogResponseHints = {
+    'application.one': {
+        commonResponseFields: [
+            'name',
+            'appName',
+            'applicationStatus',
+            'mounts',
+            'watchPaths',
+            'domains',
+            'deployments',
+        ],
+        responseHints: [
+            'Heavy detail endpoint for application config, runtime status, mounts, domains, and deployment history.',
+            'Deployment history can dominate token usage because entries may include long commit messages.',
+        ],
+        examples: [
+            'await dokploy.application.one({ applicationId: "app-123" })',
+            'await dokploy.application.one({ applicationId: "app-123", select: ["name", "watchPaths"], deploymentLimit: 1 })',
+            'catalog.get("application.one")',
+        ],
+        notes: [
+            'Generated OpenAPI output schema is currently incomplete for this endpoint, so these are common observed fields rather than a full contract.',
+            'MCP adds optional shaping inputs for this endpoint: select, includeDeployments, and deploymentLimit.',
+        ],
+    },
+    'application.many': {
+        commonResponseFields: ['items', 'total'],
+        responseHints: [
+            'MCP-only virtual helper that reads several applications by delegating to application.one.',
+            'Preserves input order and supports the same shaping inputs as application.one.',
+        ],
+        examples: [
+            'await dokploy.application.many({ applicationIds: ["app-1", "app-2"], select: ["name", "watchPaths"] })',
+        ],
+        notes: [
+            'This helper is available in execute workflows and is not backed by a Dokploy HTTP endpoint.',
+        ],
+    },
+    'project.all': {
+        commonResponseFields: ['projectId', 'name', 'environments'],
+        responseHints: ['Commonly returns projects with nested environments and service references.'],
+        examples: ['await dokploy.project.all({})'],
+    },
+    'project.overview': {
+        commonResponseFields: ['projectId', 'name', 'environments'],
+        responseHints: [
+            'MCP-only virtual helper that returns a compact per-environment and per-application project state view.',
+            'Per application it focuses on applicationId, name, appName, applicationStatus, domains, mounts, watchPaths, and lastDeployment.',
+        ],
+        examples: ['await dokploy.project.overview({ projectId: "project-1" })'],
+        notes: [
+            'This helper is available in execute workflows and is not backed by a Dokploy HTTP endpoint.',
+        ],
+    },
+    'project.one': {
+        commonResponseFields: ['projectId', 'name', 'description', 'environments'],
+        responseHints: ['Project detail endpoint used to inspect one project and its environments.'],
+        notes: [
+            'Generated OpenAPI output schema is currently incomplete for this endpoint, so nested service details may not be visible from the schema alone.',
+        ],
+    },
+    'deployment.all': {
+        commonResponseFields: ['deploymentId', 'title', 'status', 'createdAt'],
+        responseHints: ['Returns deployment history entries ordered for inspection workflows.'],
+        examples: ['await dokploy.deployment.all({ applicationId: "app-123" })'],
+    },
+    'compose.search': {
+        commonResponseFields: ['items', 'total'],
+        responseHints: ['Search endpoints commonly return paginated results with items and total.'],
+        examples: ['await dokploy.compose.search({ name: "wordpress", limit: 5 })'],
+    },
+};
+export function getCatalogResponseHints(procedure) {
+    return catalogResponseHints[procedure] ?? null;
+}
+export function applyCatalogResponseHints(endpoint) {
+    const hints = getCatalogResponseHints(endpoint.procedure);
+    return hints ? { ...endpoint, ...hints } : endpoint;
+}