@fractary/codex-mcp-server

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.

Installation

Global Installation

npm install -g @fractary/codex-mcp-server

Direct Usage (npx)

npx @fractary/codex-mcp-server

As Dependency

npm install @fractary/codex-mcp-server

Usage

Claude Code Integration

Add to your .claude/settings.json:

{
  "mcpServers": {
    "fractary-codex": {
      "command": "npx",
      "args": ["-y", "@fractary/codex-mcp-server", "--config", ".fractary/codex.yaml"]
    }
  }
}

Stdio Mode (Default)

fractary-codex-mcp --config .fractary/codex.yaml

The server communicates via stdin/stdout using the MCP protocol.

HTTP Mode

fractary-codex-mcp --port 3000 --host localhost

The server exposes an SSE (Server-Sent Events) endpoint for HTTP clients.

Configuration

Create a .fractary/codex.yaml configuration file:

cache:
  dir: .codex-cache
  maxMemorySize: 104857600  # 100 MB
  defaultTtl: 3600          # 1 hour

storage:
  providers:
    - type: local
      basePath: ./knowledge
    - type: github
      token: ${GITHUB_TOKEN}

Environment Variables

• FRACTARY_CONFIG: Path to configuration file (default: .fractary/codex.yaml)
• GITHUB_TOKEN: GitHub personal access token for GitHub storage provider

Available Tools

The MCP server exposes the following tools:

codex_document_fetch

Fetch a document from the Codex knowledge base by URI.

{
  "uri": "codex://org/project/path/to/file.md",
  "branch": "main",
  "noCache": false
}

codex_search

Search for documents in the knowledge base.

{
  "query": "authentication",
  "org": "fractary",
  "project": "codex",
  "limit": 10,
  "type": "docs"
}

codex_cache_list

List cached documents.

{
  "org": "fractary",
  "project": "codex",
  "includeExpired": false
}

codex_cache_clear

Clear cached documents by pattern.

{
  "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

npm run build

Watch Mode

npm run dev

Type Check

npm run typecheck

Testing

npm test
npm run test:watch
npm run test:coverage

Linting

npm run lint
npm run format

Programmatic Usage

You can also use the MCP server programmatically:

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:

{
  "mcpServers": {
    "fractary-codex": {
      "command": "npx",
      "args": ["@fractary/codex", "mcp", "--config", ".fractary/codex.yaml"]
    }
  }
}

After:

{
  "mcpServers": {
    "fractary-codex": {
      "command": "npx",
      "args": ["-y", "@fractary/codex-mcp-server", "--config", ".fractary/codex.yaml"]
    }
  }
}

The functionality remains identical; only the package name has changed.

License

MIT

Related Packages

• @fractary/codex - Core SDK
• @fractary/codex-cli - CLI tool

Documentation

• Command Reference - Complete command reference for all interfaces
• API Reference - Complete API documentation
• Naming Conventions - Naming standards across all interfaces
• MCP Migration Guide - Migrating from old MCP tool names
• Troubleshooting - Common issues and solutions

Links

• GitHub Repository
• Issue Tracker
• MCP Specification