@fractary/codex-mcp 0.7.1 → 0.8.0

package/README.md

@@ -64,23 +64,86 @@ The server exposes an SSE (Server-Sent Events) endpoint for HTTP clients.
 Create a `.fractary/codex/config.yaml` configuration file:
 
 ```yaml
+# Organization configuration
+organizationSlug: fractary
+
+# Cache configuration
 cache:
   dir: .fractary/codex/cache
   maxMemorySize: 104857600  # 100 MB
   defaultTtl: 3600          # 1 hour
 
+# Storage providers
 storage:
   providers:
     - type: local
       basePath: ./knowledge
     - type: github
       token: ${GITHUB_TOKEN}
+
+# Archive configuration (optional)
+# Enables transparent access to archived documents in S3/R2/GCS
+archive:
+  projects:
+    fractary/auth-service:
+      enabled: true
+      handler: s3              # s3, r2, gcs, or local
+      bucket: fractary-archives
+      patterns:                # Optional: limit to specific patterns
+        - specs/**
+        - docs/**
+    fractary/api-gateway:
+      enabled: true
+      handler: r2
+      bucket: api-archives
+```
+
+### Archive Configuration
+
+The archive feature enables transparent access to archived documents stored in cloud storage (S3, R2, GCS). When enabled, Codex automatically falls back to the archive when documents are not found locally or in GitHub.
+
+**Key Features:**
+- **Transparent URIs**: Same `codex://org/project/path` URI works for both active and archived documents
+- **Storage Priority**: Local → Archive → GitHub → HTTP (automatic fallback)
+- **Per-Project Config**: Different projects can use different storage backends and buckets
+- **Pattern Matching**: Optional patterns limit which files are archived
+
+**Configuration Fields:**
+- `enabled`: Boolean - Whether archive is active for this project
+- `handler`: String - Storage backend: `s3`, `r2`, `gcs`, or `local`
+- `bucket`: String (optional) - Cloud storage bucket name
+- `prefix`: String (optional) - Path prefix in bucket (default: `archive/`)
+- `patterns`: Array (optional) - Glob patterns to match (e.g., `specs/**`, `*.md`)
+
+**Archive Path Structure:**
+```
+archive/{type}/{org}/{project}/{original-path}
+
+Examples:
+  specs/WORK-123.md → archive/specs/fractary/auth-service/specs/WORK-123.md
+  docs/api.md       → archive/docs/fractary/auth-service/docs/api.md
 ```
 
+**Example Usage:**
+```typescript
+// Reference archived spec (same URI as before archiving)
+const result = await fetch('codex://fractary/auth-service/specs/WORK-123.md')
+// Codex checks: local → S3 archive → GitHub → HTTP
+// Returns content from archive if not found locally
+```
+
+**Requirements:**
+- [fractary CLI](https://github.com/fractary/cli) installed and configured
+- Cloud storage credentials (AWS credentials for S3, Cloudflare for R2, etc.)
+- Archive structure must mirror project structure
+
 ### Environment Variables
 
 - `FRACTARY_CONFIG`: Path to configuration file (default: `.fractary/codex/config.yaml`)
 - `GITHUB_TOKEN`: GitHub personal access token for GitHub storage provider
+- `FRACTARY_CLI`: Path to fractary CLI executable (default: `fractary`)
+- `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`: AWS credentials for S3
+- `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_API_TOKEN`: Cloudflare credentials for R2
 
 ## Available Tools
 

package/dist/cli.cjs

@@ -12238,6 +12238,7 @@ var safeDump = renamed("safeDump", "dump");
 
 // ../../sdk/js/dist/index.js
 var import_promises = __toESM(require("fs/promises"), 1);
+var import_util4 = require("util");
 var __defProp2 = Object.defineProperty;
 var __getOwnPropNames2 = Object.getOwnPropertyNames;
 var __esm2 = (fn, res) => function __init() {
@@ -12638,6 +12639,16 @@ var DirectionalSyncSchema = external_exports.object({
   default_to_codex: external_exports.array(external_exports.string()).optional(),
   default_from_codex: external_exports.array(external_exports.string()).optional()
 });
+var ArchiveProjectConfigSchema = external_exports.object({
+  enabled: external_exports.boolean(),
+  handler: external_exports.enum(["s3", "r2", "gcs", "local"]),
+  bucket: external_exports.string().optional(),
+  prefix: external_exports.string().optional(),
+  patterns: external_exports.array(external_exports.string()).optional()
+});
+var ArchiveConfigSchema = external_exports.object({
+  projects: external_exports.record(ArchiveProjectConfigSchema)
+});
 var CodexConfigSchema = external_exports.object({
   organizationSlug: external_exports.string(),
   directories: external_exports.object({
@@ -12647,7 +12658,9 @@ var CodexConfigSchema = external_exports.object({
   }).optional(),
   rules: SyncRulesSchema.optional(),
   // Directional sync configuration
-  sync: DirectionalSyncSchema.optional()
+  sync: DirectionalSyncSchema.optional(),
+  // Archive configuration
+  archive: ArchiveConfigSchema.optional()
 }).strict();
 init_matcher();
 init_matcher();
@@ -13133,6 +13146,188 @@ var HttpStorage = class {
     }
   }
 };
+var execFileAsync = (0, import_util4.promisify)(import_child_process.execFile);
+async function execFileNoThrow(command, args = [], options) {
+  try {
+    const { stdout, stderr } = await execFileAsync(command, args, {
+      ...options,
+      maxBuffer: options?.maxBuffer || 1024 * 1024 * 10
+      // 10MB default
+    });
+    return {
+      stdout: stdout || "",
+      stderr: stderr || "",
+      exitCode: 0
+    };
+  } catch (error) {
+    const exitCode = typeof error.exitCode === "number" ? error.exitCode : 1;
+    return {
+      stdout: error.stdout || "",
+      stderr: error.stderr || error.message || "",
+      exitCode
+    };
+  }
+}
+var S3ArchiveStorage = class {
+  name = "s3-archive";
+  type = "s3-archive";
+  projects;
+  fractaryCli;
+  constructor(options = {}) {
+    this.projects = options.projects || {};
+    this.fractaryCli = options.fractaryCli || "fractary";
+  }
+  /**
+   * Check if this provider can handle the reference
+   *
+   * S3 Archive provider handles references that:
+   * 1. Are for the current project (same org/project)
+   * 2. Have archive enabled in config
+   * 3. Match configured patterns (if specified)
+   */
+  canHandle(reference) {
+    if (!reference.isCurrentProject) {
+      return false;
+    }
+    const projectKey = `${reference.org}/${reference.project}`;
+    const config = this.projects[projectKey];
+    if (!config || !config.enabled) {
+      return false;
+    }
+    if (config.patterns && config.patterns.length > 0) {
+      return this.matchesPatterns(reference.path, config.patterns);
+    }
+    return true;
+  }
+  /**
+   * Fetch content from S3 archive via fractary-file CLI
+   */
+  async fetch(reference, options) {
+    const opts = mergeFetchOptions(options);
+    const projectKey = `${reference.org}/${reference.project}`;
+    const config = this.projects[projectKey];
+    if (!config) {
+      throw new Error(`No archive config for project: ${projectKey}`);
+    }
+    const archivePath = this.calculateArchivePath(reference, config);
+    try {
+      const result = await execFileNoThrow(
+        this.fractaryCli,
+        [
+          "file",
+          "read",
+          "--remote-path",
+          archivePath,
+          "--handler",
+          config.handler,
+          ...config.bucket ? ["--bucket", config.bucket] : []
+        ],
+        {
+          timeout: opts.timeout
+        }
+      );
+      if (result.exitCode !== 0) {
+        throw new Error(`fractary-file read failed: ${result.stderr}`);
+      }
+      const content = Buffer.from(result.stdout);
+      return {
+        content,
+        contentType: detectContentType(reference.path),
+        size: content.length,
+        source: "s3-archive",
+        metadata: {
+          archivePath,
+          bucket: config.bucket,
+          handler: config.handler
+        }
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`Failed to fetch from archive: ${message}`);
+    }
+  }
+  /**
+   * Check if archived file exists
+   *
+   * Note: This currently downloads the file to check existence.
+   * TODO: Optimize by using fractary-file 'stat' or 'head' command when available
+   * to avoid downloading full file for existence checks.
+   */
+  async exists(reference, options) {
+    const projectKey = `${reference.org}/${reference.project}`;
+    const config = this.projects[projectKey];
+    if (!config) {
+      return false;
+    }
+    try {
+      await this.fetch(reference, { ...options, timeout: 5e3 });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Calculate archive path from reference
+   *
+   * Pattern: {prefix}/{type}/{org}/{project}/{original-path}
+   *
+   * Examples (with default prefix "archive/"):
+   *   specs/WORK-123.md → archive/specs/org/project/specs/WORK-123.md
+   *   docs/api.md → archive/docs/org/project/docs/api.md
+   *
+   * Examples (with custom prefix "archived-docs/"):
+   *   specs/WORK-123.md → archived-docs/specs/org/project/specs/WORK-123.md
+   */
+  calculateArchivePath(reference, config) {
+    const type2 = this.detectType(reference.path);
+    const prefix = config.prefix || "archive/";
+    const trimmedPrefix = prefix.trim();
+    if (!trimmedPrefix) {
+      throw new Error("Archive prefix cannot be empty or whitespace-only");
+    }
+    const normalizedPrefix = trimmedPrefix.endsWith("/") ? trimmedPrefix : `${trimmedPrefix}/`;
+    return `${normalizedPrefix}${type2}/${reference.org}/${reference.project}/${reference.path}`;
+  }
+  /**
+   * Detect artifact type from path
+   *
+   * Used to organize archives by type
+   */
+  detectType(path6) {
+    if (path6.startsWith("specs/")) return "specs";
+    if (path6.startsWith("docs/")) return "docs";
+    if (path6.includes("/logs/")) return "logs";
+    return "misc";
+  }
+  /**
+   * Check if path matches any of the patterns
+   *
+   * Supports glob-style patterns:
+   * - specs/** (all files in specs/)
+   * - *.md (all markdown files)
+   * - docs/*.md (markdown files in docs/)
+   */
+  matchesPatterns(path6, patterns) {
+    for (const pattern of patterns) {
+      if (this.matchesPattern(path6, pattern)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Check if path matches a single pattern
+   */
+  matchesPattern(path6, pattern) {
+    const DOUBLE_STAR = "\0DOUBLE_STAR\0";
+    let regexPattern = pattern.replace(/\*\*/g, DOUBLE_STAR);
+    regexPattern = regexPattern.replace(/[.[\](){}+^$|\\]/g, "\\$&");
+    regexPattern = regexPattern.replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]");
+    regexPattern = regexPattern.replace(new RegExp(DOUBLE_STAR, "g"), ".*");
+    const regex = new RegExp(`^${regexPattern}$`);
+    return regex.test(path6);
+  }
+};
 var StorageManager = class {
   providers = /* @__PURE__ */ new Map();
   priority;
@@ -13140,7 +13335,10 @@ var StorageManager = class {
     this.providers.set("local", new LocalStorage(config.local));
     this.providers.set("github", new GitHubStorage(config.github));
     this.providers.set("http", new HttpStorage(config.http));
-    this.priority = config.priority || ["local", "github", "http"];
+    if (config.s3Archive) {
+      this.providers.set("s3-archive", new S3ArchiveStorage(config.s3Archive));
+    }
+    this.priority = config.priority || (config.s3Archive ? ["local", "s3-archive", "github", "http"] : ["local", "github", "http"]);
   }
   /**
    * Register a custom storage provider
@@ -14364,7 +14562,7 @@ function expandEnvVars(obj) {
   return obj;
 }
 var program2 = new Command();
-program2.name("fractary-codex-mcp").description("MCP server for Fractary Codex knowledge management").version("0.4.0").option("--config <path>", "Path to config file", ".fractary/codex/config.yaml").action(async (options) => {
+program2.name("fractary-codex-mcp").description("MCP server for Fractary Codex knowledge management").version("0.8.0").option("--config <path>", "Path to config file", ".fractary/codex/config.yaml").action(async (options) => {
   let config = {};
   try {
     const configFile = (0, import_fs.readFileSync)(options.config, "utf-8");
@@ -14375,7 +14573,16 @@ program2.name("fractary-codex-mcp").description("MCP server for Fractary Codex k
       console.error(`Warning: Could not load config file: ${options.config}`);
     }
   }
-  const storage = createStorageManager(config.storage);
+  const storageConfig = {
+    ...config.storage || {}
+  };
+  if (config.archive) {
+    storageConfig.s3Archive = {
+      projects: config.archive.projects || {},
+      fractaryCli: process.env.FRACTARY_CLI || "fractary"
+    };
+  }
+  const storage = createStorageManager(storageConfig);
   const cache = createCacheManager({
     cacheDir: config.cache?.cacheDir || ".fractary/codex/cache",
     ...config.cache
@@ -14385,7 +14592,7 @@ program2.name("fractary-codex-mcp").description("MCP server for Fractary Codex k
   }
   const server = new McpServer({
     name: "fractary-codex",
-    version: "0.4.0",
+    version: "0.8.0",
     cache,
     storage
   });