@ebowwa/claude-code-config-mcp 1.0.0

package/src/types.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigFileType = exports.HookFileSchema = exports.ClaudeMdSchema = exports.SettingsConfigSchema = exports.KeybindingsConfigSchema = exports.KeybindingSchema = void 0;
+var zod_1 = require("zod");
+// ============================================================================
+// Claude Code Configuration Types & Schemas
+// ============================================================================
+/**
+ * Keybinding schema
+ */
+exports.KeybindingSchema = zod_1.z.object({
+    key: zod_1.z.string().describe('Keyboard shortcut (e.g., "ctrl+s", "cmd+k")'),
+    command: zod_1.z.string().describe('Command to execute'),
+    when: zod_1.z.string().optional().describe('Context condition'),
+});
+/**
+ * Keybindings configuration schema
+ */
+exports.KeybindingsConfigSchema = zod_1.z.object({
+    $schema: zod_1.z.string().optional(),
+    keybindings: zod_1.z.record(zod_1.z.string(), exports.KeybindingSchema),
+});
+/**
+ * Settings configuration schema (generic structure)
+ */
+exports.SettingsConfigSchema = zod_1.z.object({
+    $schema: zod_1.z.string().optional(),
+    // Additional settings fields will be validated based on actual Claude Code settings structure
+});
+/**
+ * CLAUDE.md content schema
+ */
+exports.ClaudeMdSchema = zod_1.z.object({
+    content: zod_1.z.string().min(1),
+    frontmatter: zod_1.z.record(zod_1.z.string(), zod_1.z.string()).optional(),
+});
+exports.HookFileSchema = zod_1.z.object({
+    name: zod_1.z.string(),
+    event: zod_1.z.string(),
+    enabled: zod_1.z.boolean(),
+    content: zod_1.z.string(),
+});
+/**
+ * Config file types
+ */
+var ConfigFileType;
+(function (ConfigFileType) {
+    ConfigFileType["CLAUDE_MD_GLOBAL"] = "CLAUDE_MD_GLOBAL";
+    ConfigFileType["CLAUDE_MD_PROJECT"] = "CLAUDE_MD_PROJECT";
+    ConfigFileType["KEYBINDINGS"] = "KEYBINDINGS";
+    ConfigFileType["SETTINGS"] = "SETTINGS";
+    ConfigFileType["HOOKS"] = "HOOKS";
+})(ConfigFileType || (exports.ConfigFileType = ConfigFileType = {}));

package/src/types.ts

@@ -0,0 +1,237 @@
+import { z } from 'zod';
+
+// ============================================================================
+// Claude Code Configuration Types & Schemas
+// ============================================================================
+
+/**
+ * Keybinding schema
+ */
+export const KeybindingSchema = z.object({
+  key: z.string().describe('Keyboard shortcut (e.g., "ctrl+s", "cmd+k")'),
+  command: z.string().describe('Command to execute'),
+  when: z.string().optional().describe('Context condition'),
+});
+
+export type Keybinding = z.infer<typeof KeybindingSchema>;
+
+/**
+ * Keybindings configuration schema
+ */
+export const KeybindingsConfigSchema = z.object({
+  $schema: z.string().optional(),
+  keybindings: z.record(z.string(), KeybindingSchema),
+});
+
+export type KeybindingsConfig = z.infer<typeof KeybindingsConfigSchema>;
+
+/**
+ * Settings configuration schema (generic structure)
+ */
+export const SettingsConfigSchema = z.object({
+  $schema: z.string().optional(),
+  // Additional settings fields will be validated based on actual Claude Code settings structure
+});
+
+export type SettingsConfig = z.infer<typeof SettingsConfigSchema>;
+
+/**
+ * CLAUDE.md content schema
+ */
+export const ClaudeMdSchema = z.object({
+  content: z.string().min(1),
+  frontmatter: z.record(z.string(), z.string()).optional(),
+});
+
+export type ClaudeMd = z.infer<typeof ClaudeMdSchema>;
+
+/**
+ * Hook file types
+ */
+export type HookEvent =
+  | 'SessionStart'
+  | 'SessionEnd'
+  | 'UserPromptSubmit'
+  | 'PreToolUse'
+  | 'PostToolUse'
+  | 'PreCompact'
+  | 'Stop'
+  | 'SubagentStop'
+  | 'Notification';
+
+export const HookFileSchema = z.object({
+  name: z.string(),
+  event: z.string(),
+  enabled: z.boolean(),
+  content: z.string(),
+});
+
+export type HookFile = z.infer<typeof HookFileSchema>;
+
+/**
+ * File operation results
+ */
+export interface FileReadResult {
+  success: true;
+  data: string;
+  path: string;
+  size: number;
+  modified: Date;
+}
+
+export interface FileWriteResult {
+  success: true;
+  path: string;
+  backup?: string;
+}
+
+export interface FileErrorResult {
+  success: false;
+  error: {
+    code: string;
+    message: string;
+    category: 'TRANSIENT' | 'PERMISSION' | 'VALIDATION' | 'SYSTEM' | 'UNKNOWN';
+    retryable: boolean;
+    userAction?: string;
+  };
+}
+
+export type FileOperationResult = FileReadResult | FileWriteResult | FileErrorResult;
+
+/**
+ * Config file types
+ */
+export enum ConfigFileType {
+  CLAUDE_MD_GLOBAL = 'CLAUDE_MD_GLOBAL',
+  CLAUDE_MD_PROJECT = 'CLAUDE_MD_PROJECT',
+  KEYBINDINGS = 'KEYBINDINGS',
+  SETTINGS = 'SETTINGS',
+  HOOKS = 'HOOKS',
+}
+
+/**
+ * Config file metadata
+ */
+export interface ConfigFileMeta {
+  type: ConfigFileType;
+  path: string;
+  exists: boolean;
+  size?: number;
+  modified?: Date;
+}
+
+/**
+ * Atomic write options
+ */
+export interface AtomicWriteOptions {
+  createBackup?: boolean;
+  backupDir?: string;
+  encoding?: BufferEncoding;
+}
+
+// ============================================================================
+// MCP Server Configuration Types
+// ============================================================================
+
+/**
+ * MCP transport types
+ */
+export type MCPTransport = 'stdio' | 'sse' | 'http' | 'ws' | 'websocket';
+
+/**
+ * Environment variable for MCP server
+ */
+export interface MCPEnvVar {
+  name: string;
+  value: string;
+}
+
+/**
+ * MCP Server configuration
+ */
+export interface MCPServerConfig {
+  /** Command to run (for stdio transport) */
+  command?: string;
+  /** Arguments for the command */
+  args?: string[];
+  /** URL for HTTP/SSE/WebSocket transport */
+  url?: string;
+  /** Transport type */
+  transport?: MCPTransport;
+  /** Environment variables */
+  env?: Record<string, string> | MCPEnvVar[];
+  /** Headers for HTTP transport */
+  headers?: Record<string, string>;
+  /** Human-readable description */
+  description?: string;
+  /** Whether the server is always enabled (bypasses project-scoped approval) */
+  alwaysAllow?: boolean;
+  /** Timeout in milliseconds */
+  timeout?: number;
+}
+
+/**
+ * MCP Servers configuration (from ~/.config/claude-code/config.json)
+ */
+export interface MCPServersConfig {
+  mcpServers: Record<string, MCPServerConfig>;
+}
+
+/**
+ * MCP Server with metadata
+ */
+export interface MCPServerWithMeta extends MCPServerConfig {
+  name: string;
+  health?: 'connected' | 'disconnected' | 'error';
+  error?: string;
+}
+
+/**
+ * MCP add options
+ */
+export interface MCPAddOptions {
+  name: string;
+  command?: string;
+  args?: string[];
+  url?: string;
+  transport?: MCPTransport;
+  env?: Record<string, string> | MCPEnvVar[];
+  headers?: Record<string, string>;
+  description?: string;
+  alwaysAllow?: boolean;
+  timeout?: number;
+}
+
+/**
+ * MCP install source types
+ */
+export type MCPInstallSource = 'npm' | 'github' | 'local' | 'url';
+
+/**
+ * MCP config target (which config file to modify)
+ */
+export type MCPTarget = 'cli' | 'app' | 'both';
+
+/**
+ * MCP install options
+ */
+export interface MCPInstallOptions {
+  /** Source type (auto-detected if not specified) */
+  source?: MCPInstallSource;
+  /** Package name (npm) or repo URL (github) or local path */
+  package: string;
+  /** Name for the MCP server (defaults to package name) */
+  name?: string;
+  /** Version to install (for npm) */
+  version?: string;
+  /** Environment variables for the server */
+  env?: Record<string, string>;
+  /** Description for the server */
+  description?: string;
+  /** Arguments to pass to the server */
+  args?: string[];
+  /** Global packages directory (defaults to ~/.claude/mcp-servers) */
+  installDir?: string;
+  /** Force reinstallation */
+  force?: boolean;
+}

package/src/utils/errors.js

@@ -0,0 +1,231 @@
+"use strict";
+// ============================================================================
+// Error Handling - Categorization, retry logic, and user-friendly messages
+// ============================================================================
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorCode = exports.ErrorCategory = void 0;
+exports.categorizeError = categorizeError;
+exports.getUserAction = getUserAction;
+exports.isRetryable = isRetryable;
+exports.retryWithBackoff = retryWithBackoff;
+exports.createMCPError = createMCPError;
+exports.getErrorCode = getErrorCode;
+var ErrorCategory;
+(function (ErrorCategory) {
+    ErrorCategory["TRANSIENT"] = "TRANSIENT";
+    ErrorCategory["PERMISSION"] = "PERMISSION";
+    ErrorCategory["VALIDATION"] = "VALIDATION";
+    ErrorCategory["SYSTEM"] = "SYSTEM";
+    ErrorCategory["UNKNOWN"] = "UNKNOWN";
+})(ErrorCategory || (exports.ErrorCategory = ErrorCategory = {}));
+/**
+ * Categorize an error for appropriate handling
+ */
+function categorizeError(error) {
+    if (!(error instanceof Error)) {
+        return ErrorCategory.UNKNOWN;
+    }
+    var message = error.message.toLowerCase();
+    // Permission errors
+    if (message.includes('eacces') ||
+        message.includes('eperm') ||
+        message.includes('permission denied')) {
+        return ErrorCategory.PERMISSION;
+    }
+    // File not found (validation)
+    if (message.includes('enoent') || message.includes('no such file')) {
+        return ErrorCategory.VALIDATION;
+    }
+    // Transient errors (retryable)
+    if (message.includes('eagain') ||
+        message.includes('etimedout') ||
+        message.includes('econnreset') ||
+        message.includes('econnrefused') ||
+        message.includes('timeout') ||
+        message.includes('temporary failure')) {
+        return ErrorCategory.TRANSIENT;
+    }
+    // System errors
+    if (message.includes('enospc') ||
+        message.includes('disk full') ||
+        message.includes('eisdir') ||
+        message.includes('enotdir')) {
+        return ErrorCategory.SYSTEM;
+    }
+    return ErrorCategory.UNKNOWN;
+}
+/**
+ * Get user-friendly action message for an error
+ */
+function getUserAction(category) {
+    switch (category) {
+        case ErrorCategory.PERMISSION:
+            return 'Check file permissions and ensure Claude Code has access to the config directory';
+        case ErrorCategory.VALIDATION:
+            return 'Verify the file path and try again';
+        case ErrorCategory.SYSTEM:
+            return 'Check system resources and Claude Code configuration';
+        case ErrorCategory.TRANSIENT:
+            return 'The operation failed temporarily. Please try again';
+        default:
+            return null;
+    }
+}
+/**
+ * Check if an error is retryable
+ */
+function isRetryable(error) {
+    return categorizeError(error) === ErrorCategory.TRANSIENT;
+}
+var DEFAULT_RETRY_OPTIONS = {
+    maxAttempts: 3,
+    baseDelay: 1000,
+    maxDelay: 10000,
+    jitter: true,
+};
+/**
+ * Retry an operation with exponential backoff
+ */
+function retryWithBackoff(operation_1) {
+    return __awaiter(this, arguments, void 0, function (operation, options) {
+        var lastError, _loop_1, attempt, state_1;
+        if (options === void 0) { options = DEFAULT_RETRY_OPTIONS; }
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    _loop_1 = function (attempt) {
+                        var _b, error_1, delay, finalDelay_1;
+                        return __generator(this, function (_c) {
+                            switch (_c.label) {
+                                case 0:
+                                    _c.trys.push([0, 2, , 4]);
+                                    _b = {};
+                                    return [4 /*yield*/, operation()];
+                                case 1: return [2 /*return*/, (_b.value = _c.sent(), _b)];
+                                case 2:
+                                    error_1 = _c.sent();
+                                    lastError = error_1;
+                                    // Don't retry if not retryable
+                                    if (!isRetryable(error_1)) {
+                                        throw error_1;
+                                    }
+                                    delay = Math.min(options.baseDelay * Math.pow(2, attempt), options.maxDelay);
+                                    finalDelay_1 = options.jitter
+                                        ? delay + Math.random() * 1000
+                                        : delay;
+                                    // Wait before retry
+                                    return [4 /*yield*/, new Promise(function (resolve) { return setTimeout(resolve, finalDelay_1); })];
+                                case 3:
+                                    // Wait before retry
+                                    _c.sent();
+                                    return [3 /*break*/, 4];
+                                case 4: return [2 /*return*/];
+                            }
+                        });
+                    };
+                    attempt = 0;
+                    _a.label = 1;
+                case 1:
+                    if (!(attempt < options.maxAttempts)) return [3 /*break*/, 4];
+                    return [5 /*yield**/, _loop_1(attempt)];
+                case 2:
+                    state_1 = _a.sent();
+                    if (typeof state_1 === "object")
+                        return [2 /*return*/, state_1.value];
+                    _a.label = 3;
+                case 3:
+                    attempt++;
+                    return [3 /*break*/, 1];
+                case 4: throw lastError;
+            }
+        });
+    });
+}
+function createMCPError(error) {
+    var category = categorizeError(error);
+    var message = error instanceof Error ? error.message : 'Unknown error';
+    return {
+        success: false,
+        error: {
+            category: category,
+            message: message,
+            retryable: category === ErrorCategory.TRANSIENT,
+            userAction: getUserAction(category),
+        },
+    };
+}
+/**
+ * Error codes for different scenarios
+ */
+var ErrorCode;
+(function (ErrorCode) {
+    ErrorCode["FILE_NOT_FOUND"] = "FILE_NOT_FOUND";
+    ErrorCode["PERMISSION_DENIED"] = "PERMISSION_DENIED";
+    ErrorCode["INVALID_JSON"] = "INVALID_JSON";
+    ErrorCode["VALIDATION_FAILED"] = "VALIDATION_FAILED";
+    ErrorCode["PATH_TRAVERSAL"] = "PATH_TRAVERSAL";
+    ErrorCode["DISK_FULL"] = "DISK_FULL";
+    ErrorCode["LOCKED"] = "LOCKED";
+    ErrorCode["UNKNOWN"] = "UNKNOWN";
+})(ErrorCode || (exports.ErrorCode = ErrorCode = {}));
+/**
+ * Get error code from error
+ */
+function getErrorCode(error) {
+    var category = categorizeError(error);
+    switch (category) {
+        case ErrorCategory.VALIDATION:
+            if (error instanceof Error && error.message.includes('JSON')) {
+                return ErrorCode.INVALID_JSON;
+            }
+            return ErrorCode.FILE_NOT_FOUND;
+        case ErrorCategory.PERMISSION:
+            return ErrorCode.PERMISSION_DENIED;
+        case ErrorCategory.SYSTEM:
+            if (error instanceof Error && error.message.includes('enospc')) {
+                return ErrorCode.DISK_FULL;
+            }
+            if (error instanceof Error && error.message.includes('etxtbsy')) {
+                return ErrorCode.LOCKED;
+            }
+            return ErrorCode.UNKNOWN;
+        default:
+            return ErrorCode.UNKNOWN;
+    }
+}