cntx-ui 2.0.15 → 3.0.1

package/README.md

@@ -1,371 +1,67 @@
 # cntx-ui
 
-Minimal file bundling and tagging tool for AI development with web interface.
+Semantic code analysis and context management for AI agents. Turns a codebase into searchable, structured context that agents can navigate efficiently.
 
-## Features
+## What it does
 
-- 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
+- **Semantic analysis** — parses your code at the function level using tree-sitter, extracts purpose, complexity, and relationships
+- **Local vector search** — embeds code chunks locally (all-MiniLM-L6-v2 via Transformers.js) for semantic similarity search with no external API calls
+- **Bundle system** — group files into logical bundles (by feature, layer, or pattern) for structured context delivery
+- **MCP server** — exposes 28+ tools to Claude Code, Claude Desktop, or any MCP-compatible client
+- **Web dashboard** — visual interface at localhost:3333 for managing bundles, browsing semantic analysis, and editing agent rules
+- **Real-time sync** — watches for file changes and keeps analysis, bundles, and embeddings current
 
-## Installation
-
-### Global Installation (Recommended)
+## Install
 
 ```bash
 npm install -g cntx-ui
 ```
 
-### Local Development Installation
-
-```bash
-git clone https://github.com/nothingdao/cntx-ui.git
-cd cntx-ui
-npm install
-```
-
 ## Usage
 
-### Initialize a Project
-
-```bash
-# Initialize cntx-ui in your project
-cntx-ui init
-
-# Start the web interface
-cntx-ui watch
-
-# Visit http://localhost:3333 to access the web UI
-```
-
-### CLI Commands
-
-```bash
-# Generate bundles
-cntx-ui bundle <name>
-
-# Check project status
-cntx-ui status
-
-# Start web server on custom port
-cntx-ui watch [port]
-
-# Start web server with MCP status tracking
-cntx-ui watch --with-mcp
-
-# Start MCP server for AI integration
-cntx-ui mcp
-
-# Add project to Claude Desktop MCP configuration
-cntx-ui setup-mcp
-```
-
-### MCP Integration
-
-cntx-ui can function as an MCP (Model Context Protocol) server, providing AI tools with direct access to your project bundles:
-
-```bash
-# Start MCP server
-cntx-ui mcp
-```
-
-**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:**
-   ```bash
-   git clone https://github.com/nothingdao/cntx-ui.git
-   cd cntx-ui
-   npm install
-   ```
-
-2. **Install web dependencies:**
-   ```bash
-   cd web
-   npm install
-   cd ..
-   ```
-
-### Development Workflow
-
-#### Running in Development Mode
-
-1. **Start the backend server:**
-   ```bash
-   npm run dev
-   ```
-
-2. **Start the frontend development server:**
-   ```bash
-   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:**
-   ```bash
-   npm run build:web
-   ```
-
-2. **Build entire project:**
-   ```bash
-   npm run build
-   ```
-
-3. **Automated build with validation:**
-   ```bash
-   ./build.sh
-   ```
-
-### Project Structure
-
-```
-cntx-ui/
-├── bin/                    # CLI executable
-├── web/                    # React frontend
-│   ├── src/
-│   │   ├── components/     # React components
-│   │   ├── hooks/          # Custom hooks
-│   │   ├── utils/          # Utility functions
-│   │   └── lib/            # Libraries and configurations
-│   ├── dist/               # Built frontend (generated)
-│   └── package.json        # Frontend dependencies
-├── server.js               # WebSocket server
-├── package.json            # Main package configuration
-├── build.sh                # Build automation script
-└── test-local.sh           # Local testing script
-```
-
-### Available Scripts
-
-| Script | Description |
-|--------|-------------|
-| `npm run dev` | Start backend server |
-| `npm run dev:web` | Start frontend dev server |
-| `npm run build` | Build entire project |
-| `npm run build:web` | Build frontend only |
-| `npm test:local` | Install and test package locally |
-
-## MCP Server Setup
-
-### Quick Setup with setup-mcp Command
-
-The easiest way to configure cntx-ui for Claude Desktop:
-
-```bash
-# Navigate to your project directory
-cd /path/to/your/project
-
-# Initialize cntx-ui if not already done
-cntx-ui init
-
-# Add this project to Claude Desktop MCP configuration
-cntx-ui setup-mcp
-```
-
-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:
-
-```bash
-# Project 1
-cd /Users/you/project1
-cntx-ui setup-mcp
-
-# Project 2  
-cd /Users/you/project2
-cntx-ui setup-mcp
-```
-
-This creates entries in your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "cntx-ui-project1": {
-      "command": "sh",
-      "args": ["-c", "cd /Users/you/project1 && node /path/to/cntx-ui/bin/cntx-ui.js mcp"],
-      "cwd": "/Users/you/project1"
-    },
-    "cntx-ui-project2": {
-      "command": "sh", 
-      "args": ["-c", "cd /Users/you/project2 && node /path/to/cntx-ui/bin/cntx-ui.js mcp"],
-      "cwd": "/Users/you/project2"
-    }
-  }
-}
-```
-
-#### Manual Configuration
-
-For manual setup, add to your Claude Desktop configuration:
-
-```json
-{
-  "mcpServers": {
-    "cntx-ui-projectname": {
-      "command": "sh",
-      "args": ["-c", "cd /path/to/your/project && cntx-ui mcp"],
-      "cwd": "/path/to/your/project"
-    }
-  }
-}
-```
-
-### 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:**
-   ```bash
-   ./test-local.sh
-   ```
-
-2. **Manual testing:**
-   ```bash
-   # 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:**
-   ```bash
-   npm version patch  # or minor/major
-   ```
-
-2. **Build and validate:**
-   ```bash
-   ./build.sh
-   ```
-
-3. **Test locally:**
-   ```bash
-   ./test-local.sh
-   ```
-
-4. **Publish to npm:**
-   ```bash
-   # Stable release
-   npm publish
-   
-   # Beta release
-   npm publish --tag beta
-   ```
-
-### Automated Publishing Workflow
-
-Use the build script for a complete workflow:
-
 ```bash
-./build.sh
-# Follow prompts for local testing
-# If tests pass, run: npm publish
+cntx-ui init          # scaffold .cntx directory, generate .mcp.json
+cntx-ui watch         # start web server on port 3333
+cntx-ui mcp           # start MCP server on stdio
+cntx-ui bundle <name> # regenerate a specific bundle
+cntx-ui status        # show project health and bundle state
+cntx-ui setup-mcp     # configure Claude Desktop integration
 ```
 
-## Configuration
+After `cntx-ui init`, agents discover tools automatically via `.mcp.json`. The `.cntx/AGENT.md` file provides an onboarding handshake with tool reference and project overview.
 
-### Environment Variables
+## Agent interface
 
-- `PORT` - Override default server port (default: 3333)
-- `NODE_ENV` - Set environment (development/production)
+Agents interact through MCP tools or the HTTP API:
 
-### Project Configuration
+| MCP Tool | What it does |
+| :--- | :--- |
+| `agent/discover` | Architectural overview of the codebase |
+| `agent/query` | Semantic search — "where is auth handled?" |
+| `agent/investigate` | Find integration points for a new feature |
+| `agent/organize` | Audit and optimize bundle structure |
+| `list_bundles` | List all bundles with metadata |
+| `get_bundle` | Get full bundle content as XML |
+| `get_semantic_chunks` | Get all analyzed code chunks |
+| `read_file` / `write_file` | File operations with bundle context |
 
-cntx-ui creates these files in your project:
-- `.cntx/config.json` - Main configuration
-- `.cntxignore` - Files to ignore
-- `.cursorrules` - Cursor editor rules
+Full tool reference with parameters is generated in `.cntx/AGENT.md` and `.cntx/TOOLS.md`.
 
-## Contributing
+## How it works
 
-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
+1. **tree-sitter** parses source files into AST, extracts functions/types/interfaces
+2. **Heuristics engine** classifies each chunk by purpose, business domain, and technical patterns based on file paths, imports, and naming conventions
+3. **Embeddings** are generated locally and stored in SQLite for persistent vector search
+4. **Bundles** group files by glob patterns — auto-suggested on init based on project structure
+5. **MCP server** and **HTTP API** expose everything to agents with consistent response shapes
 
-## Technology Stack
+## Tech 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
+- Node.js, better-sqlite3, ws (WebSocket)
+- tree-sitter (AST parsing), Transformers.js (local embeddings)
+- React 19, TypeScript, Vite, Tailwind CSS (web dashboard)
+- Model Context Protocol (MCP) via JSON-RPC 2.0
 
 ## License
 
 MIT
-
-## Support
-
-- GitHub Issues: [Report bugs or request features](https://github.com/nothingdao/cntx-ui/issues)
-- Documentation: Check the web interface for detailed usage guides

package/bin/cntx-ui-mcp.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+# Wrapper script to run cntx-ui MCP server in current directory
+cd "$(pwd)" && npx cntx-ui mcp

package/bin/cntx-ui.js

@@ -103,7 +103,8 @@ async function main() {
       case 'watch':
       case 'w':
         const port = parseInt(args[1]) || 3333;
-        const withMcp = args.includes('--with-mcp');
+        // Enable MCP status tracking by default for the web dashboard
+        const withMcp = !args.includes('--no-mcp');
         await startServer({ port, withMcp, verbose: isVerbose });
         break;