Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (ctxb) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

CTXB — Context Blob Generator & MCP Server

A CLI that parses source repositories (TypeScript, JavaScript, Python, Go) into compact .ctxb context blobs, plus an MCP server that exposes those blobs to AI tools at runtime.

Quick Start

# Run directly with npx (no install needed)
npx ctxb --repo-folder ./my-app

# Or install globally
npm install -g ctxb
ctxb --repo-folder ./my-app

# Start the MCP server (used by AI tools, not run manually)
ctxb-mcp --context-folder ./my-app-context-blob

Generator CLI

ctxb --repo-folder <path> [options]

Options:
  --repo-folder, -s <path>       Source repo to parse (required)
  --context-folder, -o <path>    Output directory (default: <repo>-context-blob)
  --languages, -l <langs>        Comma-separated: ts,js,py,go (default: all)
  --no-incremental               Force full regeneration
  --include-tests                Include test files
  --no-enrichment                Skip Layer 2 enrichment
  --verbose, -v                  Verbose output

Output structure:

my-app-context-blob/
  _dict.ctxb      # Shared package dictionary
  _graph.ctxb     # Dependency graph
  _meta.ctxb      # Generation metadata
  src/
    foo.ctxb      # Per-file context (mirrors source tree)
    bar.ctxb

MCP Server

The MCP server loads a generated context blob folder into memory and serves it over stdio using the Model Context Protocol. Any MCP-compatible AI tool can connect to it.

Available Tools

Tool	Description
`get_file_context`	Full decoded context for a file (fuzzy path match)
`get_dependencies`	What a file imports, N levels deep
`get_dependents`	What imports a file, N levels deep
`search_exports`	Find which files export a given name
`get_codebase_overview`	Language/role breakdown, top deps, graph stats
`find_path`	Shortest dependency chain between two files
`get_files_by_role`	All files with a given role (service, component, etc.)
`get_related_context`	A file + all its dependencies' context

Setup by AI Tool

After generating context blobs, configure your AI tool to use the MCP server:

Claude Code

Add to your project's .mcp.json or configure via CLI:

claude mcp add ctxb -- ctxb-mcp --context-folder /absolute/path/to/my-app-context-blob

Or manually create/edit .mcp.json in your project root:

{
  "mcpServers": {
    "ctxb": {
      "command": "ctxb-mcp",
      "args": ["--context-folder", "/absolute/path/to/my-app-context-blob"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "ctxb": {
      "command": "ctxb-mcp",
      "args": ["--context-folder", "/absolute/path/to/my-app-context-blob"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "ctxb": {
      "command": "ctxb-mcp",
      "args": ["--context-folder", "/absolute/path/to/my-app-context-blob"]
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json in your project root:

{
  "servers": {
    "ctxb": {
      "type": "stdio",
      "command": "ctxb-mcp",
      "args": ["--context-folder", "/absolute/path/to/my-app-context-blob"]
    }
  }
}

Multiple Repos

If you work across multiple repos, add a separate MCP server entry for each:

{
  "mcpServers": {
    "ctxb-backend": {
      "command": "ctxb-mcp",
      "args": ["--context-folder", "/path/to/backend-context-blob"]
    },
    "ctxb-frontend": {
      "command": "ctxb-mcp",
      "args": ["--context-folder", "/path/to/frontend-context-blob"]
    }
  }
}

Testing with MCP Inspector

To verify the server works before connecting it to your AI tool:

npx @modelcontextprotocol/inspector ctxb-mcp --context-folder /path/to/my-app-context-blob

This opens a web UI where you can invoke each tool and inspect the responses.

Supported Languages

Language	Extensions
TypeScript	`.ts`, `.tsx`
JavaScript	`.js`, `.jsx`, `.mjs`, `.cjs`
Python	`.py`
Go	`.go`

File Roles

Files are automatically classified into roles: service, component, middleware, util, config, model, type, hook, page, provider, constant, test.