@carbonvoice/cv-mcp-server 1.0.0

package/dist/utils/axios-instance.js

@@ -0,0 +1,234 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.customAxios = void 0;
+exports.mutator = mutator;
+const axios_1 = __importDefault(require("axios"));
+const logger_1 = require("./logger");
+const config_1 = require("../config");
+// Create the axios instance
+const getAxiosInstance = () => {
+    const baseUrl = config_1.env.CARBON_VOICE_BASE_URL || 'https://api.carbonvoice.app';
+    if (!config_1.env.CARBON_VOICE_API_KEY) {
+        throw {
+            statusCode: 0,
+            body: {
+                error: {
+                    code: 'CONFIGURATION_ERROR',
+                    message: 'CARBON_VOICE_API_KEY is not set',
+                    details: { api_key: config_1.env.CARBON_VOICE_API_KEY },
+                },
+            },
+        };
+    }
+    const instance = axios_1.default.create({
+        baseURL: baseUrl,
+        headers: {
+            'Content-Type': 'application/json',
+            'x-api-key': config_1.env.CARBON_VOICE_API_KEY,
+        },
+    });
+    // Add request interceptor for logging
+    instance.interceptors.request.use((config) => {
+        logger_1.logger.debug('Making API request', {
+            url: config.url,
+            method: config.method,
+            params: config.params,
+            data: config.data,
+            headers: { ...config.headers, 'x-api-key': '[REDACTED]' },
+        });
+        return config;
+    }, (error) => {
+        var _a, _b;
+        logger_1.logger.error('Request setup error', {
+            url: (_a = error.config) === null || _a === void 0 ? void 0 : _a.url,
+            method: (_b = error.config) === null || _b === void 0 ? void 0 : _b.method,
+            message: error.message,
+        });
+        return Promise.reject(error);
+    });
+    // Add response interceptor for logging
+    instance.interceptors.response.use((response) => {
+        logger_1.logger.debug('API response received', {
+            url: response.config.url,
+            method: response.config.method,
+            status: response.status,
+            statusText: response.statusText,
+        });
+        return response;
+    }, (error) => {
+        var _a, _b, _c, _d, _e, _f;
+        if (axios_1.default.isAxiosError(error)) {
+            const axiosError = handleAxiosError(error);
+            // Log the error with all relevant details
+            logger_1.logger.error('API request failed', {
+                error: axiosError,
+                url: (_a = error.config) === null || _a === void 0 ? void 0 : _a.url,
+                method: (_b = error.config) === null || _b === void 0 ? void 0 : _b.method,
+                status: (_c = error.response) === null || _c === void 0 ? void 0 : _c.status,
+                statusText: (_d = error.response) === null || _d === void 0 ? void 0 : _d.statusText,
+                requestData: (_e = error.config) === null || _e === void 0 ? void 0 : _e.data,
+                responseData: (_f = error.response) === null || _f === void 0 ? void 0 : _f.data,
+            });
+        }
+        else {
+            logger_1.logger.error('Unexpected error in API request', error);
+        }
+        return Promise.reject(error);
+    });
+    return instance;
+};
+// Error handling function
+function handleAxiosError(error) {
+    if (error.response) {
+        const statusCode = error.response.status;
+        const errorData = error.response.data;
+        // Handle different HTTP status codes
+        switch (statusCode) {
+            case 400:
+                return {
+                    statusCode,
+                    body: {
+                        error: {
+                            code: 'BAD_REQUEST',
+                            message: (errorData === null || errorData === void 0 ? void 0 : errorData.message) || 'Invalid request parameters',
+                            details: (errorData === null || errorData === void 0 ? void 0 : errorData.details) || errorData,
+                        },
+                    },
+                };
+            case 401:
+                return {
+                    statusCode,
+                    body: {
+                        error: {
+                            code: 'UNAUTHORIZED',
+                            message: 'Authentication required',
+                            details: { reason: 'Invalid or missing API key' },
+                        },
+                    },
+                };
+            case 403:
+                return {
+                    statusCode,
+                    body: {
+                        error: {
+                            code: 'FORBIDDEN',
+                            message: 'Access denied',
+                            details: { reason: 'Insufficient permissions' },
+                        },
+                    },
+                };
+            case 404:
+                return {
+                    statusCode,
+                    body: {
+                        error: {
+                            code: 'NOT_FOUND',
+                            message: (errorData === null || errorData === void 0 ? void 0 : errorData.message) || 'Resource not found',
+                            details: errorData === null || errorData === void 0 ? void 0 : errorData.details,
+                        },
+                    },
+                };
+            case 429:
+                return {
+                    statusCode,
+                    body: {
+                        error: {
+                            code: 'RATE_LIMITED',
+                            message: 'Too many requests',
+                            details: { retryAfter: error.response.headers['retry-after'] },
+                        },
+                    },
+                };
+            case 500:
+            case 502:
+            case 503:
+            case 504:
+                return {
+                    statusCode,
+                    body: {
+                        error: {
+                            code: 'SERVER_ERROR',
+                            message: 'Internal server error',
+                            details: { originalError: errorData },
+                        },
+                    },
+                };
+            default:
+                return {
+                    statusCode,
+                    body: {
+                        error: {
+                            code: 'UNKNOWN_ERROR',
+                            message: (errorData === null || errorData === void 0 ? void 0 : errorData.message) || 'An unexpected error occurred',
+                            details: errorData,
+                        },
+                    },
+                };
+        }
+    }
+    else if (error.request) {
+        return {
+            statusCode: 0,
+            body: {
+                error: {
+                    code: 'NETWORK_ERROR',
+                    message: 'No response received from server',
+                    details: {
+                        request: error.request,
+                        message: error.message,
+                    },
+                },
+            },
+        };
+    }
+    else {
+        return {
+            statusCode: 0,
+            body: {
+                error: {
+                    code: 'REQUEST_ERROR',
+                    message: error.message || 'Error setting up the request',
+                    details: { originalError: error },
+                },
+            },
+        };
+    }
+}
+// Create the singleton instance
+const axiosInstance = getAxiosInstance();
+// Define the mutator function that Orval expects
+async function mutator({ url, method, params, data, headers, }) {
+    try {
+        const response = await axiosInstance({
+            url,
+            method,
+            params,
+            data,
+            headers,
+        });
+        return response.data;
+    }
+    catch (error) {
+        if (axios_1.default.isAxiosError(error)) {
+            const axiosError = handleAxiosError(error);
+            throw axiosError;
+        }
+        // Handle non-axios errors
+        const errorMessage = error instanceof Error ? error.message : 'An unexpected error occurred';
+        throw {
+            statusCode: 0,
+            body: {
+                error: {
+                    code: 'UNKNOWN_ERROR',
+                    message: errorMessage,
+                    details: { originalError: error },
+                },
+            },
+        };
+    }
+}
+// Export the instance for other uses
+exports.customAxios = axiosInstance;

package/dist/utils/errors.js

@@ -0,0 +1,22 @@
+"use strict";
+// import { ErrorResponse } from '../interfaces';
+Object.defineProperty(exports, "__esModule", { value: true });
+// export const handleError = (error: any): ErrorResponse => {
+//   const status = error.status;
+//   //   return {
+//   //     isError: true,
+//   //     content: [{ type: 'text', text: `Error: ${error.message}` }],
+//   //   };
+//   const resource = 'user';
+//   const id = 'xxx-1234';
+//   return {
+//     statusCode: 404,
+//     body: {
+//       error: {
+//         code: 'RESOURCE_NOT_FOUND',
+//         message: `The requested ${resource} with ID ${id} was not found.`,
+//         details: { resource, id },
+//       },
+//     },
+//   } as any;
+// };

package/dist/utils/format-to-mcp-tool-response.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatToMCPToolResponse = void 0;
+const logger_1 = require("./logger");
+const isErrorWithDetails = (error) => {
+    return typeof error === 'object' && error !== null;
+};
+const formatToMCPToolResponse = (data) => {
+    try {
+        return {
+            content: [{ type: 'text', text: JSON.stringify(data) }],
+        };
+    }
+    catch (error) {
+        logger_1.logger.error('Error formatting response:', { data, error });
+        let code = 'UNKNOWN_ERROR';
+        let message = 'Error formatting response';
+        let details;
+        if (isErrorWithDetails(error)) {
+            code = (error === null || error === void 0 ? void 0 : error.code) || code;
+            message = (error === null || error === void 0 ? void 0 : error.message) || message;
+            details = error === null || error === void 0 ? void 0 : error.details;
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        error: {
+                            code,
+                            message,
+                            details,
+                        },
+                    }),
+                },
+            ],
+        };
+    }
+};
+exports.formatToMCPToolResponse = formatToMCPToolResponse;

package/dist/utils/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./logger"), exports);
+__exportStar(require("./format-to-mcp-tool-response"), exports);
+__exportStar(require("./axios-instance"), exports);

package/dist/utils/logger.js

@@ -0,0 +1,111 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLogger = exports.stream = exports.logger = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const winston_1 = __importDefault(require("winston"));
+const config_1 = require("../config");
+// Custom log levels
+const levels = {
+    error: 0,
+    warn: 1,
+    info: 2,
+    http: 3,
+    debug: 4,
+};
+// Colors for console output
+const colors = {
+    error: 'red',
+    warn: 'yellow',
+    info: 'green',
+    http: 'magenta',
+    debug: 'white',
+};
+// Add colors to winston
+winston_1.default.addColors(colors);
+// Console format with colors
+const consoleFormat = winston_1.default.format.combine(winston_1.default.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss:SSS' }), winston_1.default.format.colorize({ all: true }), winston_1.default.format.printf(({ timestamp, level, message, ...metadata }) => {
+    let output = `${timestamp} ${level}: ${message}`;
+    if (Object.keys(metadata).length > 0) {
+        output += '\n' + JSON.stringify(metadata, null, 2);
+    }
+    return output;
+}));
+// File format (JSON)
+const fileFormat = winston_1.default.format.combine(winston_1.default.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss:SSS' }), winston_1.default.format.json());
+const getLogLevel = () => {
+    return config_1.env.LOG_LEVEL || 'info';
+};
+// Create file transports
+// const logDir = path.join(process.cwd(), 'logs');
+// Prefer env var, fallback to project-relative folder
+const logDir = process.env.LOG_DIR || path_1.default.join(process.cwd(), 'logs');
+if (!fs_1.default.existsSync(logDir)) {
+    fs_1.default.mkdirSync(logDir, { recursive: true });
+}
+console.error('logs_dir', logDir);
+if (!fs_1.default.existsSync(logDir)) {
+    fs_1.default.mkdirSync(logDir, { recursive: true });
+}
+// Create log files
+const errorLogFile = path_1.default.join(logDir, 'error.log');
+const combinedLogFile = path_1.default.join(logDir, 'combined.log');
+const fileTransports = [
+    // Error log file
+    new winston_1.default.transports.File({
+        filename: errorLogFile,
+        level: 'error',
+        maxsize: 5 * 1024 * 1024, // 5MB
+        maxFiles: 5,
+        tailable: true,
+    }),
+    // Combined log file - set to same level as logger
+    new winston_1.default.transports.File({
+        filename: combinedLogFile,
+        level: getLogLevel(), // Use same level as logger
+        maxsize: 5 * 1024 * 1024, // 5MB
+        maxFiles: 5,
+        tailable: true,
+    }),
+];
+const consoleTransport = process.env.MCP_STDIO_MODE === 'true'
+    ? [
+        new winston_1.default.transports.Console({
+            format: consoleFormat,
+        }),
+    ]
+    : [];
+// Create the logger
+exports.logger = winston_1.default.createLogger({
+    level: getLogLevel(),
+    levels,
+    format: fileFormat,
+    transports: [...consoleTransport, ...fileTransports],
+});
+// Add a startup log to verify the logger is working
+// logger.debug('Logger initialized', {
+//   currentLevel: getLogLevel(),
+//   availableLevels: levels,
+//   transports: logger.transports.map((t) => ({
+//     level: t.level,
+//   })),
+//   logDir,
+//   logFiles: {
+//     error: errorLogFile,
+//     combined: combinedLogFile,
+//   },
+// });
+// Export a stream object for Morgan
+exports.stream = {
+    write: (message) => {
+        exports.logger.http(message.trim());
+    },
+};
+// Helper to create child loggers with context
+const createLogger = (context) => {
+    return exports.logger.child({ context });
+};
+exports.createLogger = createLogger;

package/dist/utils/zod-schema-transformer.js

@@ -0,0 +1,66 @@
+"use strict";
+// import { OpenAPIV3 } from 'openapi-types';
+// import { z } from 'zod';
+Object.defineProperty(exports, "__esModule", { value: true });
+// function generateZodSchema(schema: OpenAPIV3.SchemaObject): z.ZodType<any> {
+//   if (!schema) {
+//     return z.any();
+//   }
+//   switch (schema.type) {
+//     case 'string':
+//       return schema.enum
+//         ? z.enum(schema.enum as [string, ...string[]])
+//         : z.string();
+//     case 'number':
+//     case 'integer':
+//       return z.number();
+//     case 'boolean':
+//       return z.boolean();
+//     case 'array':
+//       return z.array(generateZodSchema(schema.items as OpenAPIV3.SchemaObject));
+//     case 'object':
+//       if (schema.properties) {
+//         const shape: { [key: string]: z.ZodType<any> } = {};
+//         for (const [key, prop] of Object.entries(schema.properties)) {
+//           const isRequired = schema.required?.includes(key);
+//           shape[key] = isRequired
+//             ? generateZodSchema(prop as OpenAPIV3.SchemaObject)
+//             : generateZodSchema(prop as OpenAPIV3.SchemaObject).optional();
+//         }
+//         return z.object(shape);
+//       }
+//       return z.record(z.any());
+//     default:
+//       return z.any();
+//   }
+// }
+// export const transformer = async (args: any) => {
+//   if (!args || !args.schema) {
+//     throw new Error(
+//       'Transformer received undefined or missing schema! Args: ' +
+//         JSON.stringify(args),
+//     );
+//   }
+//   const schemas: { [key: string]: z.ZodType<any> } = {};
+//   // Process all schemas in the OpenAPI document
+//   if (args.schema.components?.schemas) {
+//     for (const [name, schema] of Object.entries(
+//       args.schema.components.schemas,
+//     )) {
+//       schemas[name] = generateZodSchema(schema as OpenAPIV3.SchemaObject);
+//     }
+//   }
+//   // Generate the output file content
+//   const output = `import { z } from 'zod';
+// // Generated Zod schemas
+// ${Object.entries(schemas)
+//   .map(([name, schema]) => `export const ${name}Schema = ${schema.toString()};`)
+//   .join('\n')}
+// // Type exports
+// ${Object.entries(schemas)
+//   .map(([name]) => `export type ${name} = z.infer<typeof ${name}Schema>;`)
+//   .join('\n')}
+// `;
+//   return output;
+// };
+// export default transformer;

package/dist/utils/zod-transformer.js

@@ -0,0 +1,24 @@
+"use strict";
+// import { generateZodClientFromOpenAPI } from 'openapi-zod-client';
+Object.defineProperty(exports, "__esModule", { value: true });
+// const transformer = async (args: any) => {
+//   if (!args || !args.schema) {
+//     throw new Error(
+//       'Transformer received undefined or missing schema! Args: ' +
+//         JSON.stringify(args),
+//     );
+//   }
+//   if (!args.path) {
+//     throw new Error(
+//       'Transformer received undefined or missing path! Args: ' +
+//         JSON.stringify(args),
+//     );
+//   }
+//   return generateZodClientFromOpenAPI({
+//     openApiDoc: args.schema,
+//     distPath: args.path,
+//   });
+// };
+// // Use both CommonJS and ESM exports for compatibility
+// module.exports = transformer;
+// export default transformer;

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@carbonvoice/cv-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for using the Carbon Voice Simplified API",
+  "author": "Carbon Voice",
+  "license": "ISC",
+  "private": false,
+  "homepage": "https://getcarbon.app",
+  "bugs": "https://github.com/PhononX/cv-mcp-server/issues",
+  "main": "dist/stdio.js",
+  "bin": {
+    "mcp-server-carbonvoice": "./dist/stdio.js"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc && chmod 755 dist/stdio.js",
+    "start": "node dist/index.js",
+    "pre": "npm run build",
+    "mcp:inspector": "npx --env-file=.env @modelcontextprotocol/inspector node dist/stdio.js",
+    "dev": "dotenv -e .env -- node dist/index.js",
+    "debug": "dotenv -e .env -- nodemon --watch src --ext ts --exec \"node --loader ts-node/esm\" src/server.ts",
+    "debug:stdio": "dotenv -e .env -- nodemon --watch src --ext ts --exec \"node --loader ts-node/esm\" src/stdio.ts",
+    "auto:build": "nodemon --watch src --ext ts --exec npm run build",
+    "pregenerate:api": "tsc src/utils/zod-transformer.ts --outDir dist/utils && mv dist/utils/zod-transformer.js dist/utils/zod-transformer.cjs",
+    "generate:api": "npm run pregenerate:api && orval --config orval.config.ts",
+    "lint:fix": "eslint src --fix"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "mcp-server-carbonvoice",
+    "carbonvoice",
+    "carbonvoice-mcp-server"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "axios": "^1.9.0",
+    "dotenv": "^16.5.0",
+    "openapi-zod-client": "^1.18.3",
+    "winston": "^3.17.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.29.0",
+    "@orval/zod": "^7.9.0",
+    "@types/handlebars": "^4.0.40",
+    "@types/node": "^22.15.29",
+    "@typescript-eslint/eslint-plugin": "^8.33.1",
+    "@typescript-eslint/parser": "^8.33.1",
+    "eslint": "^9.29.0",
+    "eslint-config-prettier": "^10.1.5",
+    "eslint-plugin-prettier": "^5.4.1",
+    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "eslint-plugin-unused-imports": "^4.1.4",
+    "globals": "^16.2.0",
+    "nodemon": "^3.1.10",
+    "orval": "^7.9.0",
+    "prettier": "^3.5.3",
+    "ts-node": "^10.9.2",
+    "ts-node-dev": "^2.0.0",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.34.1",
+    "zod": "^3.25.58"
+  }
+}