@fractary/codex-mcp 0.10.3 → 0.10.4

package/README.md

@@ -4,33 +4,23 @@ MCP (Model Context Protocol) server for Fractary Codex knowledge management.
 
 ## Overview
 
-This package provides a standalone MCP server that exposes Fractary Codex functionality as tools for AI agents and applications. It supports both stdio and HTTP/SSE transports for integration with Claude Code, LangChain, and other MCP-compatible clients.
+This package provides a standalone MCP server that exposes Fractary Codex functionality as tools for AI agents. Supports both stdio and HTTP/SSE transports.
 
 ## Installation
 
-### Global Installation
-
 ```bash
+# Global
 npm install -g @fractary/codex-mcp-server
-```
 
-### Direct Usage (npx)
-
-```bash
+# Direct usage
 npx @fractary/codex-mcp-server
 ```
 
-### As Dependency
-
-```bash
-npm install @fractary/codex-mcp-server
-```
-
-## Usage
+## Quick Start
 
 ### Claude Code Integration
 
-Add to your `.claude/settings.json`:
+Add to `.claude/settings.json`:
 
 ```json
 {
@@ -43,298 +33,78 @@ Add to your `.claude/settings.json`:
 }
 ```
 
-### Stdio Mode (Default)
+### Stdio Mode
 
 ```bash
 fractary-codex-mcp --config .fractary/config.yaml
 ```
 
-The server communicates via stdin/stdout using the MCP protocol.
-
 ### HTTP Mode
 
 ```bash
 fractary-codex-mcp --port 3000 --host localhost
 ```
 
-The server exposes an SSE (Server-Sent Events) endpoint for HTTP clients.
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `codex_document_fetch` | Fetch document by URI |
+| `codex_search` | Search documents |
+| `codex_cache_list` | List cached documents |
+| `codex_cache_clear` | Clear cache by pattern |
+
+## Documentation
+
+**Full documentation**: [docs/mcp-server/](../../docs/mcp-server/)
+
+- [Configuration](../../docs/mcp-server/#configuration)
+- [Archive Configuration](../../docs/mcp-server/#archive-configuration)
+- [Tools Reference](../../docs/mcp-server/#available-tools)
+- [Programmatic Usage](../../docs/mcp-server/#programmatic-usage)
+- [Troubleshooting](../../docs/mcp-server/#troubleshooting)
 
 ## Configuration
 
-Create a `.fractary/config.yaml` configuration file:
+Uses `.fractary/config.yaml`:
 
 ```yaml
-# Organization configuration
 organizationSlug: fractary
 
-# Cache configuration
 cache:
   dir: .fractary/codex/cache
-  maxMemorySize: 104857600  # 100 MB
-  defaultTtl: 3600          # 1 hour
+  defaultTtl: 3600
 
-# 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/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
-
-The MCP server exposes the following tools:
-
-### codex_document_fetch
-
-Fetch a document from the Codex knowledge base by URI.
-
-```json
-{
-  "uri": "codex://org/project/path/to/file.md",
-  "branch": "main",
-  "noCache": false
-}
-```
-
-### codex_search
-
-Search for documents in the knowledge base.
-
-```json
-{
-  "query": "authentication",
-  "org": "fractary",
-  "project": "codex",
-  "limit": 10,
-  "type": "docs"
-}
-```
-
-### codex_cache_list
-
-List cached documents.
-
-```json
-{
-  "org": "fractary",
-  "project": "codex",
-  "includeExpired": false
-}
-```
-
-### codex_cache_clear
-
-Clear cached documents by pattern.
-
-```json
-{
-  "pattern": "docs/**"
-}
-```
-
-## Architecture
-
-The MCP server bridges the Codex SDK with the MCP protocol:
-
-```
-┌─────────────────────────────────────┐
-│   MCP Client (Claude Code, etc.)   │
-└─────────────┬───────────────────────┘
-              │ JSON-RPC (stdio/HTTP)
-              ▼
-┌─────────────────────────────────────┐
-│  @fractary/codex-mcp-server         │
-│  ┌───────────────────────────────┐  │
-│  │ MCP Protocol Handler          │  │
-│  │   (StdioTransport / SSE)     │  │
-│  └─────────────┬─────────────────┘  │
-│                │                     │
-│  ┌─────────────▼─────────────────┐  │
-│  │ Tool Registration Bridge      │  │
-│  │   (registerCodexTools)        │  │
-│  └─────────────┬─────────────────┘  │
-└────────────────┼─────────────────────┘
-                 │
-                 ▼
-┌─────────────────────────────────────┐
-│       @fractary/codex (SDK)         │
-│  ┌─────────┐  ┌──────────────┐     │
-│  │ Cache   │  │  Storage     │     │
-│  │ Manager │  │  Manager     │     │
-│  └─────────┘  └──────────────┘     │
-└─────────────────────────────────────┘
 ```
 
 ## Development
 
-### Build
-
 ```bash
+# Build
 npm run build
-```
-
-### Watch Mode
 
-```bash
+# Watch mode
 npm run dev
-```
 
-### Type Check
-
-```bash
-npm run typecheck
-```
-
-### Testing
-
-```bash
+# Test
 npm test
-npm run test:watch
-npm run test:coverage
-```
-
-### Linting
-
-```bash
-npm run lint
-npm run format
-```
-
-## Programmatic Usage
-
-You can also use the MCP server programmatically:
-
-```typescript
-import { Server } from '@modelcontextprotocol/sdk/server/index.js'
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
-import { CacheManager, StorageManager } from '@fractary/codex'
-import { registerCodexTools } from '@fractary/codex-mcp-server'
-
-// Initialize SDK managers
-const storage = StorageManager.create({ /* config */ })
-const cache = CacheManager.create({ /* config */ })
-cache.setStorageManager(storage)
-
-// Create MCP server
-const server = new Server(
-  { name: 'fractary-codex', version: '0.1.0' },
-  { capabilities: { tools: {}, resources: {} } }
-)
 
-// Register Codex tools
-registerCodexTools(server, { cache, storage })
-
-// Connect transport
-const transport = new StdioServerTransport()
-await server.connect(transport)
-```
-
-## Migration from SDK-Embedded MCP
-
-If you were using the MCP server from `@fractary/codex` (versions ≤0.1.x), update your configuration:
-
-**Before:**
-```json
-{
-  "mcpServers": {
-    "fractary-codex": {
-      "command": "npx",
-      "args": ["@fractary/codex", "mcp", "--config", ".fractary/config.yaml"]
-    }
-  }
-}
-```
-
-**After:**
-```json
-{
-  "mcpServers": {
-    "fractary-codex": {
-      "command": "npx",
-      "args": ["-y", "@fractary/codex-mcp-server", "--config", ".fractary/config.yaml"]
-    }
-  }
-}
+# Type check
+npm run typecheck
 ```
 
-The functionality remains identical; only the package name has changed.
-
 ## License
 
 MIT
 
-## Related Packages
+## Related
 
 - [@fractary/codex](https://www.npmjs.com/package/@fractary/codex) - Core SDK
 - [@fractary/codex-cli](https://www.npmjs.com/package/@fractary/codex-cli) - CLI tool
-
-## Links
-
-- [GitHub Repository](https://github.com/fractary/codex)
-- [Issue Tracker](https://github.com/fractary/codex/issues)
 - [MCP Specification](https://modelcontextprotocol.io)

package/dist/cli.cjs

@@ -12702,12 +12702,24 @@ var DirectionalSyncConfigSchema = external_exports.object({
   /** Patterns to exclude (optional) */
   exclude: external_exports.array(external_exports.string()).optional()
 });
+var FromCodexSyncConfigSchema = DirectionalSyncConfigSchema.refine(
+  (config) => {
+    const includeValid = config.include.every(
+      (pattern) => pattern.startsWith("codex://")
+    );
+    const excludeValid = !config.exclude || config.exclude.every((pattern) => pattern.startsWith("codex://"));
+    return includeValid && excludeValid;
+  },
+  {
+    message: 'from_codex patterns must use codex:// URI format (e.g., "codex://{org}/{codex_repo}/docs/**"). Plain paths like "docs/**" are not valid for from_codex.'
+  }
+);
 var DirectionalSyncSchema = external_exports.object({
   // New format (v0.7.0+) - Recommended
-  // Patterns for files to push from this project to codex
+  // Patterns for files to push from this project to codex (plain paths)
   to_codex: DirectionalSyncConfigSchema.optional(),
-  // Patterns for files to pull from codex to this project
-  from_codex: DirectionalSyncConfigSchema.optional(),
+  // Patterns for files to pull from codex to this project (codex:// URIs required)
+  from_codex: FromCodexSyncConfigSchema.optional(),
   // Global exclude patterns (applied to both directions)
   exclude: external_exports.array(external_exports.string()).optional(),
   // Legacy format (deprecated, backward compatible)
@@ -12735,25 +12747,9 @@ var AuthConfigSchema = external_exports.object({
   /** GitHub authentication configuration */
   github: GitHubAuthConfigSchema.optional()
 });
-var SourceConfigSchema = external_exports.object({
-  /** Source type */
-  type: external_exports.enum(["github", "s3", "http", "local"]),
-  /** Environment variable containing the authentication token */
-  token_env: external_exports.string().optional(),
-  /** Direct token value (not recommended, use token_env instead) */
-  token: external_exports.string().optional(),
-  /** Branch to fetch from (for GitHub sources) */
-  branch: external_exports.string().optional(),
-  /** Base URL (for HTTP sources) */
-  base_url: external_exports.string().optional(),
-  /** Bucket name (for S3 sources) */
-  bucket: external_exports.string().optional(),
-  /** Prefix/path within bucket (for S3 sources) */
-  prefix: external_exports.string().optional()
-});
-var DependencyConfigSchema = external_exports.object({
-  /** Sources within this dependency */
-  sources: external_exports.record(SourceConfigSchema)
+var RemoteConfigSchema = external_exports.object({
+  /** Authentication token - can be direct value or ${ENV_VAR} reference */
+  token: external_exports.string().optional()
 });
 var CodexConfigSchema = external_exports.object({
   organizationSlug: external_exports.string(),
@@ -12771,8 +12767,9 @@ var CodexConfigSchema = external_exports.object({
   archive: ArchiveConfigSchema.optional(),
   // Authentication configuration
   auth: AuthConfigSchema.optional(),
-  // Dependencies configuration (external projects)
-  dependencies: external_exports.record(DependencyConfigSchema).optional()
+  // Remote repositories configuration (external projects)
+  // Keys are org/project identifiers, values configure authentication
+  remotes: external_exports.record(RemoteConfigSchema).optional()
 }).strict();
 var FileSourceSchema = external_exports.object({
   type: external_exports.enum(["s3", "r2", "gcs", "local"]),
@@ -13780,30 +13777,31 @@ var StorageManager = class {
     }
     this.priority = config.priority || (config.filePlugin && config.s3Archive ? ["file-plugin", "local", "s3-archive", "github", "http"] : config.filePlugin ? ["file-plugin", "local", "github", "http"] : config.s3Archive ? ["local", "s3-archive", "github", "http"] : ["local", "github", "http"]);
   }
+  /**
+   * Resolve a token value, expanding ${VAR} references to environment variables
+   */
+  resolveTokenValue(token) {
+    const envVarMatch = token.match(/^\$\{([^}]+)\}$/);
+    if (envVarMatch && envVarMatch[1]) {
+      const envVarName = envVarMatch[1];
+      return process.env[envVarName];
+    }
+    return token;
+  }
   /**
    * Resolve authentication token for a reference
    *
-   * Looks up dependency-specific authentication or falls back to default
+   * Looks up remote-specific authentication or falls back to default
    */
   resolveToken(reference) {
     if (!this.codexConfig) {
       return void 0;
     }
-    const dependencyKey = `${reference.org}/${reference.project}`;
-    if (this.codexConfig.dependencies?.[dependencyKey]) {
-      const dependency = this.codexConfig.dependencies[dependencyKey];
-      for (const [, sourceConfig] of Object.entries(dependency.sources)) {
-        if (sourceConfig.type === "github") {
-          if (sourceConfig.token_env) {
-            const token = process.env[sourceConfig.token_env];
-            if (token) {
-              return token;
-            }
-          }
-          if (sourceConfig.token) {
-            return sourceConfig.token;
-          }
-        }
+    const remoteKey = `${reference.org}/${reference.project}`;
+    if (this.codexConfig.remotes?.[remoteKey]?.token) {
+      const token = this.resolveTokenValue(this.codexConfig.remotes[remoteKey].token);
+      if (token) {
+        return token;
       }
     }
     const defaultTokenEnv = this.codexConfig.auth?.github?.default_token_env || "GITHUB_TOKEN";
@@ -13862,7 +13860,7 @@ var StorageManager = class {
    * Fetch content for a reference
    *
    * Tries providers in priority order until one succeeds.
-   * Automatically resolves authentication based on dependency configuration.
+   * Automatically resolves authentication based on remote configuration.
    */
   async fetch(reference, options) {
     const resolvedOptions = this.resolveFetchOptions(reference, options);
@@ -13894,7 +13892,7 @@ var StorageManager = class {
    * Check if content exists for a reference
    *
    * Returns true if any provider reports the content exists.
-   * Automatically resolves authentication based on dependency configuration.
+   * Automatically resolves authentication based on remote configuration.
    */
   async exists(reference, options) {
     const resolvedOptions = this.resolveFetchOptions(reference, options);