cntx-ui

Minimal file bundling and tagging tool for AI development with web interface.

Features

• File bundling and organization for AI development workflows

• Web-based UI for managing bundles and configurations

• Model Context Protocol (MCP) server for AI integration

• Hidden files management

• Cursor rules integration

• WebSocket-based real-time updates

• CLI tools for automation

Installation

Global Installation (Recommended)

Local Development Installation

Usage

Initialize a Project

CLI Commands

MCP Integration

cntx-ui can function as an MCP (Model Context Protocol) server, providing AI tools with direct access to your project bundles:

Available MCP Resources:

• cntx://bundle/<name> - Access any bundle as XML content

• cntx://file/<path> - Access individual project files

Available MCP Tools:

• list_bundles - List all available bundles

• get_bundle - Retrieve specific bundle content

• generate_bundle - Regenerate a bundle

• get_file_tree - Get project file structure

• get_project_status - Get current project status

Development

Prerequisites

• Node.js >= 18.0.0

• npm

Setup Development Environment

1. Clone and install dependencies:

   git clone https://github.com/nothingdao/cntx-ui.git cd cntx-ui npm install

2. Install web dependencies:

   cd web npm install cd ..

Development Workflow

Running in Development Mode

1. Start the backend server:

   npm run dev

2. Start the frontend development server:

   npm run dev:web

   The web interface will be available at http://localhost:5173 (Vite dev server)

Building the Project

1. Build web interface only:

   npm run build:web

2. Build entire project:

   npm run build

3. Automated build with validation:

   ./build.sh

Project Structure

Available Scripts

MCP Server Setup

Quick Setup with setup-mcp Command

The easiest way to configure cntx-ui for Claude Desktop:

This automatically adds your project to Claude Desktop's configuration file and allows you to work with multiple projects simultaneously.

Claude Desktop Integration

Multi-Project Setup (Recommended)

You can use cntx-ui across multiple projects by running setup-mcp in each project directory:

This creates entries in your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

Manual Configuration

For manual setup, add to your Claude Desktop configuration:

Other MCP Clients

For other MCP-compatible clients, use:

• Command: cntx-ui mcp

• Transport: stdio

• Working Directory: Your project root

MCP Workflow

1. Setup: Run cntx-ui setup-mcp in each project you want to use with Claude Desktop

2. Visual Configuration: Use cntx-ui watch to configure bundles via web UI

3. AI Integration: AI clients connect via MCP to access bundles across all configured projects

4. Real-time Updates: Changes in web UI immediately available to AI tools

5. Multi-Project: Claude Desktop can access bundles from all configured projects simultaneously

Testing

Local Testing

1. Run automated test suite:

   ./test-local.sh

2. Manual testing:

   # Build and pack npm run build npm pack # Install globally for testing npm install -g ./cntx-ui-*.tgz # Test in a new project mkdir test-project && cd test-project cntx-ui init cntx-ui watch

Test Coverage

The test suite covers:

• Project initialization

• Bundle generation

• Web server functionality

• API endpoints

• File management operations

Publishing

Prerequisites for Publishing

• npm account with publish permissions

• Clean git working directory

• All tests passing

Publishing Steps

1. Update version:

   npm version patch # or minor/major

2. Build and validate:

   ./build.sh

3. Test locally:

   ./test-local.sh

4. Publish to npm:

   # Stable release npm publish # Beta release npm publish --tag beta

Automated Publishing Workflow

Use the build script for a complete workflow:

Configuration

Environment Variables

• PORT - Override default server port (default: 3333)

• NODE_ENV - Set environment (development/production)

Project Configuration

cntx-ui creates these files in your project:

• .cntx/config.json - Main configuration

• .cntxignore - Files to ignore

• .cursorrules - Cursor editor rules

Contributing

1. Fork the repository

2. Create a feature branch

3. Make changes following the existing code style

4. Run tests: ./test-local.sh

5. Submit a pull request

Technology Stack

• Backend: Node.js, WebSocket (ws)

• Frontend: React 19, TypeScript, Vite

• UI: Tailwind CSS, Radix UI

• State Management: TanStack Query

• Build Tools: Vite, TypeScript compiler

License

MIT

Support

• GitHub Issues: Report bugs or request features

• Documentation: Check the web interface for detailed usage guides