@purpleraven/hits 0.2.1 → 0.2.3

package/README.md

@@ -1,116 +1,91 @@
-# HITS - Hybrid Intel Trace System
+# hits
 
 > Replicate your predecessor's brain as perfectly as possible, using the least amount of AI.
 
-## Overview
+A secure web-based knowledge management system that preserves organizational context across AI tool sessions. When your Claude session hits the token limit and you switch to a new one — HITS ensures nothing is lost.
 
-HITS is a hybrid knowledge management system designed to preserve organizational core knowledge and decision-making context. It automates project-specific handover when switching between AI tool sessions (Claude, OpenCode, Cursor, etc.).
+## What Problem Does This Solve?
 
-### Core Values
+You're working on a project with Claude Code. After a long session, you hit the token limit. A new session starts — but it has **no idea** what you did, what decisions were made, or what was left unfinished.
 
-- **Token Optimization**: Semantic compression and on-demand analysis to reduce AI costs
-- **Context Preservation**: Store decision-making processes in a Why-How-What hierarchy
-- **Failure Experience**: Record failed approaches alongside successes as Negative Paths
-- **Security Hardened**: Argon2id hashing, JWT HttpOnly cookies, CSP, Rate Limiting
-- **AI Session Handover**: Automatically transfer project context when AI sessions rotate due to token limits
-- **Centralized Storage**: All AI tool work logs are consolidated at `~/.hits/data/`
-- **Project Isolation**: Completely independent context management based on project path
+**HITS fixes this:**
 
-## Tech Stack
+1. **Record work** during each AI session (manually or via MCP tools)
+2. **Query handover** when a new session starts — it gets the full context
+3. **Knowledge trees** preserve the WHY/HOW/WHAT of every project
+4. **All AI tools share the same data** — Claude, OpenCode, Cursor, it doesn't matter
 
-| Area | Technology |
-|------|-----------|
-| **Backend** | Python 3.10+, FastAPI, Pydantic v2 |
-| **Frontend** | Svelte 5, Vite, TypeScript |
-| **Authentication** | Argon2id (passwords), JWT HS256 (HttpOnly cookies) |
-| **Storage** | File-based (`~/.hits/data/`), Redis (optional) |
-| **Security** | CSP, CORS, Rate Limiting, Secure Headers |
-
-## Installation
-
-### Requirements
-
-- Python 3.10 or later
-- Node.js 18+ (for frontend build)
-- Redis (optional — falls back to file storage)
-
-### Quick Start
-
-```bash
-cd hits
-./run.sh          # Auto-install + start server
 ```
-
-#### Development Mode
-
-```bash
-./run.sh --dev    # Vite HMR + FastAPI backend
+[OpenCode session ends]              [Claude session starts]
+        │                                    │
+   Record work:                          Query handover:
+   "Added JWT auth,                      → Previous: Added JWT auth
+    chose Argon2id over                     → Decisions: Argon2id > bcrypt
+    bcrypt, still need to                    → Pending: rate limiting
+    add rate limiting"                       → Files: auth/manager.py, ...
 ```
 
-#### Manual Installation
+## Quick Start
 
-```bash
-# Python environment
-python3 -m venv venv
-source venv/bin/activate
-pip install -r requirements.txt
+### One Command — That's It
 
-# Frontend build
-cd hits_web
-npm install
-npm run build
-cd ..
-
-# Start server
-python -m hits_core.main --port 8765
+```bash
+npx hits
 ```
 
-## Security
+That single command will:
 
-### Authentication System
+1. **Detect Python 3.10+** on your system
+2. **Create a virtual environment** automatically
+3. **Install Python dependencies** (FastAPI, Argon2id, etc.)
+4. **Start the Python backend** (FastAPI on port 8765)
+5. **Start the web server** (Express on port 8765)
+6. Open **http://127.0.0.1:8765** in your browser
 
-| Feature | Implementation |
-|---------|---------------|
-| **Password Hashing** | Argon2id (memory=64MB, iterations=3, parallelism=1) |
-| **Minimum Password Length** | 8 characters |
-| **JWT Tokens** | HttpOnly + Secure + SameSite=Lax cookies |
-| **Access Token** | 15-minute expiry |
-| **Refresh Token** | 7-day expiry, sent only to `/api/auth/refresh` |
-| **First User** | Automatically assigned admin role |
-| **Subsequent Users** | Can only be created by admin |
+### First Time Setup
 
-### Security Headers
+On first visit, you'll create an admin account:
 
 ```
-Content-Security-Policy: default-src 'self'; script-src 'self'; ...
-X-Content-Type-Options: nosniff
-X-Frame-Options: DENY
-Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
-Referrer-Policy: strict-origin-when-cross-origin
-Permissions-Policy: camera=(), microphone=(), geolocation=()
+┌──────────────────────────────────────┐
+│         🌳 HITS                      │
+│    Hybrid Intel Trace System         │
+│                                      │
+│  ┌────────────────────────────────┐  │
+│  │  Username: [____________]      │  │
+│  │  Password: [____________]      │  │
+│  │                                │  │
+│  │  [ Create Account ]            │  │
+│  │                                │  │
+│  │  First account = admin role    │  │
+│  └────────────────────────────────┘  │
+└──────────────────────────────────────┘
 ```
 
-### Rate Limiting
+### Custom Port
 
-- Login endpoint: 10 requests/minute (per IP)
-- Responds with 429 Too Many Requests when exceeded
+```bash
+npx hits --port 9000
+# or
+HITS_PORT=9000 npx hits
+```
 
-### Data Protection
+## Requirements
 
-| Item | Permissions | Description |
-|------|-------------|-------------|
-| `~/.hits/.auth/users.json` | 600 | User data (owner only) |
-| `~/.hits/.pepper` | 600 | HMAC pepper (owner only) |
-| `~/.hits/.jwt_secret` | 600 | JWT signing key (owner only) |
-| `~/.hits/.auth/` | 700 | Auth directory (owner only) |
+| Requirement | Version | Why |
+|-------------|---------|-----|
+| **Node.js** | ≥ 18 | Runs the web server and manages the Python process |
+| **Python** | ≥ 3.10 | Runs the FastAPI backend (auto-installed into venv) |
 
-## Web UI
+That's it. No database required — HITS uses file-based storage at `~/.hits/data/`.
 
-### Layout
+## What You Get
+
+### Web UI
 
 ```
 ┌─────────────┬───────────────────────────────────┐
-│  Sidebar    │  Header (tabs + user menu)         │
+│  Sidebar    │  Header (tabs + user menu 🌐 lang) │
 │             ├───────────────────────────────────┤
 │  📂 Projects│                                   │
 │  ────────── │  Main content area                 │
@@ -121,64 +96,193 @@ Permissions-Policy: camera=(), microphone=(), geolocation=()
 └─────────────┴───────────────────────────────────┘
 ```
 
-### Features
+**Knowledge Tree** — Organize project knowledge as Why-How-What nodes:
 
-- **Knowledge Tree**: Manage Why-How-What nodes by category (full CRUD)
-- **Timeline**: Project work logs, grouped by date, with search
-- **Handover**: Auto-generated handover summary when a project is selected
-- **Project Switching**: Instant context switch via sidebar
-- **User Management**: Password change, logout
+```
+📁 Authentication
+  ├── WHY  "Need secure user auth for web UI"
+  ├── HOW  "Argon2id hashing + JWT HttpOnly cookies"
+  └── WHAT "POST /api/auth/login → Set-Cookie"
+      └── ❌ Negative Path: "Tried bcrypt first — too fast, GPU-vulnerable"
+```
 
-## AI Session Handover
+**Timeline** — Chronological work log, grouped by date, filterable by project
 
-### How It Works
+**Handover** — Auto-generated summary of a project's context, ready to paste into a new AI session
 
-```
-[OpenCode Session]                  [Claude Session]
-       │                                  │
-   Perform work                        Session start
-       │                                  │
-   Record work ──────────────────────→ Query handover
-   POST /api/work-log               GET /api/handover
-   project_path: /my-project        project_path: /my-project
-       │                                  │
-       └──→ ~/.hits/data/ ←──┘            │
-            (centralized)            Understand previous context
-                                          │
-                                     Continue work seamlessly
+**i18n** — Korean/English toggle (🌐 button in header)
+
+### MCP Tools for AI Assistants
+
+HITS includes an MCP server so your AI can read and write handover data directly. No need to clone the repo — it works right out of the npm package.
+
+#### Register with OpenCode (`~/.config/opencode/opencode.json`)
+
+```json
+{
+  "mcp": {
+    "hits": {
+      "type": "local",
+      "command": ["npx", "hits-mcp"]
+    }
+  }
+}
 ```
 
-### MCP Configuration
+#### Register with Claude Code
 
-Add to your OpenCode or Claude MCP settings:
+```bash
+claude mcp add hits -- npx hits-mcp
+```
+
+#### Register with Any MCP Client
 
 ```json
 {
-  "hits": {
-    "type": "local",
-    "command": ["python", "-m", "hits_core.mcp.server"],
-    "cwd": "/path/to/hits"
+  "mcpServers": {
+    "hits": {
+      "command": "npx",
+      "args": ["hits-mcp"]
+    }
   }
 }
 ```
 
-MCP Tools:
-- `hits_record_work`: Record work entry
-- `hits_get_handover`: Get handover summary
-- `hits_search_works`: Search past work
-- `hits_list_projects`: List projects
-- `hits_get_recent`: Get recent work
+> **How it works:** `npx hits-mcp` auto-detects Python, creates a venv inside the npm package, installs dependencies, and spawns the MCP server over stdio — all automatically on first run.
+
+#### 5 MCP Tools
+
+| Tool | What It Does |
+|------|-------------|
+| `hits_record_work` | Record a work entry (auto-detects project path from CWD) |
+| `hits_get_handover` | Get handover summary for the current project |
+| `hits_search_works` | Search past work by keyword |
+| `hits_list_projects` | List all projects with recorded work |
+| `hits_get_recent` | Get the most recent work entries |
+
+#### Example AI Workflow
+
+```
+User: "Continue working on the auth system"
+
+AI (auto-calls hits_get_handover):
+  → Previous session added Argon2id password hashing
+  → Decisions: Argon2id (not bcrypt), JWT HS256, HttpOnly cookies
+  → Pending: Rate limiting, password change endpoint
+
+AI: "I see the auth system uses Argon2id + JWT. Let me add rate limiting..."
+
+(later)
+
+AI (auto-calls hits_record_work):
+  → Recorded: "Added rate limiting (10 req/min on login endpoint)"
+```
+
+### REST API
+
+All features are also accessible via HTTP API:
+
+```bash
+# Health check
+curl http://localhost:8765/api/health
+
+# Record work
+curl -X POST http://localhost:8765/api/work-log \
+  -H "Content-Type: application/json" \
+  -b cookies.txt \
+  -d '{
+    "performed_by": "claude",
+    "request_text": "Added rate limiting to login endpoint",
+    "context": "10 req/min per IP, 429 response on limit",
+    "project_path": "/home/user/my-project",
+    "tags": ["security", "api"]
+  }'
+
+# Get handover summary
+curl "http://localhost:8765/api/handover?project_path=/home/user/my-project" \
+  -b cookies.txt
+
+# Search past work
+curl "http://localhost:8765/api/work-logs/search?q=auth" \
+  -b cookies.txt
+```
+
+## Security
+
+HITS is built with security as a first-class concern:
+
+| Feature | Implementation |
+|---------|---------------|
+| **Password Hashing** | Argon2id (64MB memory, 3 iterations, parallelism=1) |
+| **JWT Tokens** | HttpOnly + Secure + SameSite=Lax cookies |
+| **Access Token** | 15-minute expiry |
+| **Refresh Token** | 7-day expiry, restricted to `/api/auth/refresh` path |
+| **Brute Force Protection** | 10 login attempts/minute per IP |
+| **Security Headers** | CSP, X-Frame-Options: DENY, HSTS preload, nosniff |
+| **Data Protection** | Auth files stored with `chmod 600` (owner-only) |
+| **First User Policy** | First registered user becomes admin; subsequent users need admin approval |
+
+## How It Works Under the Hood
+
+```
+npx hits
+  │
+  ├── 1. findPython()       → Detect Python 3.10+ on system
+  ├── 2. setupPython()      → Create venv, install deps
+  ├── 3. startBackend()     → Spawn FastAPI process (port 8765)
+  └── 4. startExpress()     → Serve frontend + proxy /api → FastAPI
+
+  Browser                    Express (8765)           FastAPI (8765 internal)
+     │                           │                         │
+     ├── GET /             ───→  static (Svelte SPA)       │
+     ├── GET /some/route   ───→  SPA fallback              │
+     └── GET /api/*        ───→  proxy  ──────────────→   FastAPI routes
+         POST /api/*       ───→  proxy  ──────────────→   FastAPI routes
+```
+
+All data is stored centrally:
 
-## API Endpoints
+```
+~/.hits/
+├── data/                ← All project data
+│   ├── work_logs/       ← AI session work logs (JSON)
+│   ├── trees/           ← Knowledge trees
+│   └── workflows/       ← Workflows
+├── .auth/               ← User accounts (chmod 700)
+│   └── users.json       ← User data (chmod 600)
+├── .pepper              ← HMAC pepper (chmod 600)
+└── .jwt_secret          ← JWT signing key (chmod 600)
+
+Override with HITS_DATA_PATH environment variable
+```
+
+## CLI Options
+
+```
+npx hits [options]
+
+Options:
+  -p, --port <port>   Server port (default: 8765)
+  -d, --dev           Development mode (verbose logging)
+  -s, --setup         Install dependencies only, don't start
+  -h, --help          Show help
+
+Environment:
+  HITS_PORT           Server port override
+  HITS_PYTHON         Path to python executable (default: auto-detect)
+  HITS_DATA_PATH      Data storage path (default: ~/.hits/data)
+```
+
+## API Reference
 
 ### Authentication
 
 | Method | Path | Description |
 |--------|------|-------------|
-| GET | `/api/auth/status` | Check auth status |
-| POST | `/api/auth/register` | Register user |
-| POST | `/api/auth/login` | Login (sets HttpOnly cookies) |
-| POST | `/api/auth/logout` | Logout |
+| GET | `/api/auth/status` | Check if auth is initialized, current login status |
+| POST | `/api/auth/register` | Register user (first user = admin) |
+| POST | `/api/auth/login` | Login — sets HttpOnly cookies |
+| POST | `/api/auth/logout` | Logout — clears cookies |
 | POST | `/api/auth/refresh` | Refresh access token |
 | GET | `/api/auth/me` | Get current user info |
 | PUT | `/api/auth/password` | Change password |
@@ -188,8 +292,8 @@ MCP Tools:
 | Method | Path | Description |
 |--------|------|-------------|
 | POST | `/api/work-log` | Create work log |
-| GET | `/api/work-logs` | List work logs (supports `project_path` filter) |
-| GET | `/api/work-logs/search?q=...` | Search work logs |
+| GET | `/api/work-logs` | List logs (filter by `project_path`) |
+| GET | `/api/work-logs/search?q=...` | Search logs by keyword |
 | GET | `/api/work-log/{id}` | Get single entry |
 | PUT | `/api/work-log/{id}` | Update entry |
 | DELETE | `/api/work-log/{id}` | Delete entry |
@@ -199,10 +303,10 @@ MCP Tools:
 | Method | Path | Description |
 |--------|------|-------------|
 | GET | `/api/handover?project_path=...` | Get project handover summary |
-| GET | `/api/handover/projects` | List projects |
-| GET | `/api/handover/project-stats?project_path=...` | Get project stats |
+| GET | `/api/handover/projects` | List all projects |
+| GET | `/api/handover/project-stats?project_path=...` | Get project statistics |
 
-### Knowledge Categories
+### Knowledge
 
 | Method | Path | Description |
 |--------|------|-------------|
@@ -210,127 +314,72 @@ MCP Tools:
 | POST | `/api/knowledge/category` | Create category |
 | PUT | `/api/knowledge/category/{name}` | Update category |
 | DELETE | `/api/knowledge/category/{name}` | Delete category |
-| POST | `/api/knowledge/category/{name}/nodes` | Add node |
+| POST | `/api/knowledge/category/{name}/nodes` | Add node to category |
 | PUT | `/api/knowledge/category/{name}/nodes/{idx}` | Update node |
 | DELETE | `/api/knowledge/category/{name}/nodes/{idx}` | Delete node |
 
-### performed_by Values
-
-| AI Tool | Value |
-|---------|-------|
-| OpenCode | `opencode` |
-| Claude Code | `claude` |
-| Cursor | `cursor` |
-| Manual | `manual` |
-
-## Architecture
-
-```
-┌──────────────────────────────────────────────────────────┐
-│                   hits_web (Svelte 5 + Vite)              │
-│              Material Dark theme · TypeScript              │
-│  ┌──────────┬──────────┬──────────────────────────┐       │
-│  │ Sidebar  │ Knowledge│ HandoverPanel            │       │
-│  │ Projects │ Tree     │ Handover summary view    │       │
-│  │ Filter   │ Timeline │                          │       │
-│  └──────────┴──────────┴──────────────────────────┘       │
-│         ↕ API Client (fetch + HttpOnly cookies)           │
-├──────────────────────────────────────────────────────────┤
-│                   hits_core (Apache 2.0)                  │
-│  ┌──────────┬──────────┬──────────┬──────────┐           │
-│  │  Models  │ Storage  │    AI    │ Auth     │           │
-│  │  Tree    │ Redis    │ Compress │ Argon2id │           │
-│  │  Node    │ File     │ SLM/LLM  │ JWT      │           │
-│  │  WorkLog │(~/.hits) │ Filter   │ Middleware│           │
-│  └──────────┴──────────┴──────────┴──────────┘           │
-│  ┌──────────┬──────────┬──────────┐                      │
-│  │  API     │ Collector│   MCP    │                      │
-│  │ FastAPI  │ Git/Shell│ Server   │                      │
-│  │ + Static │ AI Sess. │ 5 Tools  │                      │
-│  │  Serve   │          │          │                      │
-│  └──────────┴──────────┴──────────┘                      │
-│  ┌──────────────────────────────┐                        │
-│  │       Service Layer          │                        │
-│  │  TreeService  HandoverService│                        │
-│  │  KnowledgeService            │                        │
-│  └──────────────────────────────┘                        │
-└──────────────────────────────────────────────────────────┘
-```
-
-## Knowledge Tree Structure
-
-### Why-How-What Hierarchy
+## Troubleshooting
 
-```
-├── WHY (Intent/Purpose)
-│   ├── "Why was this system built?"
-│   └── "What is the business goal?"
-│
-├── HOW (Logic/Method)
-│   ├── "How was it implemented?"
-│   └── "What decisions were made?"
-│
-└── WHAT (Execution/Tasks)
-    ├── "What specifically does it do?"
-    └── "Actionable tasks"
-```
+### "Python 3.10+ not found"
 
-## Development
+Install Python 3.10 or later:
+```bash
+# Ubuntu/Debian
+sudo apt install python3.12
 
-### Development Mode
+# macOS
+brew install python@3.12
 
-```bash
-./run.sh --dev    # Vite HMR + FastAPI
+# Or set manually:
+export HITS_PYTHON=/usr/bin/python3.12
 ```
 
-### Testing
+### "Frontend not built"
 
+This shouldn't happen with the npm package (frontend is pre-built). If it does:
 ```bash
-./run.sh --test   # Run pytest
+npx hits --setup
 ```
 
-### Frontend Development
+### "ModuleNotFoundError: No module named 'hits_core'"
 
+Python dependencies failed to install. Try:
 ```bash
-cd hits_web
-npm install        # Install dependencies
-npm run dev        # Vite dev server (http://localhost:5173)
-npm run build      # Production build
+npx hits --setup
 ```
 
-## License
+### Redis Connection Failed
 
-| Package | License | Commercial Use |
-|---------|---------|---------------|
-| `hits_core` | Apache 2.0 | ✅ Free |
-| `hits_web` | Apache 2.0 | ✅ Free |
+Not a problem — HITS automatically uses file-based storage. Redis is optional.
 
-## Troubleshooting
+## Development
 
-### Node.js Not Found
+If you're working on HITS itself:
 
 ```bash
-# Ubuntu/Debian
-curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
-sudo apt install -y nodejs
-```
+git clone https://github.com/lhjnano/hits.git
+cd hits
 
-### Redis Connection Failed
+# Backend setup
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
 
-HITS works fine without Redis. It automatically falls back to file-based storage.
+# Frontend build
+cd hits_web && npm install && npm run build && cd ..
 
-### Where Is Data Stored?
+# Development mode (Vite HMR + FastAPI)
+./run.sh --dev
 
+# Run tests
+./run.sh --test
 ```
-~/.hits/
-├── data/                ← Default location for all data
-│   ├── work_logs/       ← AI session work logs
-│   ├── trees/           ← Knowledge trees
-│   └── workflows/       ← Workflows
-├── .auth/               ← Authentication data
-│   └── users.json       ← User info (permissions 600)
-├── .pepper              ← HMAC pepper (permissions 600)
-└── .jwt_secret          ← JWT signing key (permissions 600)
 
-Override with HITS_DATA_PATH environment variable
-```
+## License
+
+Apache 2.0 — free for commercial use.
+
+## Links
+
+- **GitHub**: [https://github.com/lhjnano/hits](https://github.com/lhjnano/hits)
+- **Issues**: [https://github.com/lhjnano/hits/issues](https://github.com/lhjnano/hits/issues)

package/bin/hits-mcp.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+
+/**
+ * HITS MCP Server - Node.js Wrapper
+ *
+ * Launches the HITS Python MCP server over stdio transport.
+ * Auto-detects Python, creates venv, installs deps — same as `npx hits`.
+ *
+ * Usage:
+ *   npx hits-mcp
+ *
+ * Or in MCP config:
+ *   { "command": ["npx", "hits-mcp"] }
+ *
+ * Environment:
+ *   HITS_PYTHON       Path to python executable (default: auto-detect)
+ *   HITS_DATA_PATH    Data storage path (default: ~/.hits/data)
+ */
+
+import { spawn, execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { platform } from 'node:os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = __dirname;
+const isWin = platform() === 'win32';
+
+// ─── Python Detection (same logic as server.js) ────────────────
+
+function findPython() {
+  const envPython = process.env.HITS_PYTHON;
+  if (envPython && existsSync(envPython)) return envPython;
+
+  const candidates = isWin
+    ? ['python', 'python3', 'py']
+    : ['python3', 'python'];
+
+  for (const cmd of candidates) {
+    try {
+      const ver = execSync(`${cmd} --version`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] });
+      const match = ver.match(/Python (\d+)\.(\d+)/);
+      if (match && (parseInt(match[1]) > 3 || (parseInt(match[1]) === 3 && parseInt(match[2]) >= 10))) {
+        return cmd;
+      }
+    } catch {}
+  }
+  return null;
+}
+
+// ─── Venv Management ────────────────────────────────────────────
+
+const VENV_DIR = join(ROOT, 'venv');
+const PYTHON_BIN = isWin
+  ? join(VENV_DIR, 'Scripts', 'python.exe')
+  : join(VENV_DIR, 'bin', 'python');
+
+function runCommand(cmd, args, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(cmd, args, { stdio: 'inherit', ...opts });
+    proc.on('close', (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`Command failed: ${cmd} ${args.join(' ')} (exit ${code})`));
+    });
+    proc.on('error', reject);
+  });
+}
+
+async function ensurePython() {
+  const pythonCmd = findPython();
+  if (!pythonCmd) {
+    console.error('[hits-mcp] Error: Python 3.10+ not found.');
+    console.error('[hits-mcp] Install: https://www.python.org/downloads/');
+    process.exit(1);
+  }
+
+  // Create venv if needed
+  if (!existsSync(PYTHON_BIN)) {
+    console.error(`[hits-mcp] Creating virtual environment... (${pythonCmd})`);
+    await runCommand(pythonCmd, ['-m', 'venv', VENV_DIR], { cwd: ROOT });
+  }
+
+  // Check if deps are installed
+  try {
+    execSync(
+      `${PYTHON_BIN} -c "import fastapi, pydantic, argon2, jose"`,
+      { stdio: 'ignore' }
+    );
+  } catch {
+    console.error('[hits-mcp] Installing Python dependencies...');
+    await runCommand(PYTHON_BIN, ['-m', 'pip', 'install', '-q', '--upgrade', 'pip'], { cwd: ROOT });
+    await runCommand(PYTHON_BIN, ['-m', 'pip', 'install', '-q', '-r', join(ROOT, 'requirements.txt')], { cwd: ROOT });
+    console.error('[hits-mcp] Dependencies installed.');
+  }
+}
+
+// ─── Launch MCP Server ──────────────────────────────────────────
+
+async function main() {
+  await ensurePython();
+
+  // Spawn Python MCP server with stdio transport
+  const proc = spawn(PYTHON_BIN, ['-m', 'hits_core.mcp.server'], {
+    cwd: ROOT,
+    stdio: 'inherit',  // stdin/stdout/stderr all connected to parent (MCP stdio)
+    env: {
+      ...process.env,
+      PYTHONPATH: ROOT,
+    },
+  });
+
+  proc.on('error', (err) => {
+    console.error(`[hits-mcp] Failed to start: ${err.message}`);
+    process.exit(1);
+  });
+
+  proc.on('exit', (code, signal) => {
+    if (signal) {
+      console.error(`[hits-mcp] Terminated by signal: ${signal}`);
+    }
+    process.exit(code || 0);
+  });
+
+  // Forward signals
+  process.on('SIGINT', () => proc.kill('SIGINT'));
+  process.on('SIGTERM', () => proc.kill('SIGTERM'));
+}
+
+main().catch((err) => {
+  console.error(`[hits-mcp] Fatal: ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@purpleraven/hits",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "HITS - Hybrid Intel Trace System. AI session handover with secure web UI.",
   "keywords": [
     "knowledge-management",
@@ -12,7 +12,8 @@
   "author": "HITS Team",
   "type": "module",
   "bin": {
-    "hits": "bin/hits.js"
+    "hits": "bin/hits.js",
+    "hits-mcp": "bin/hits-mcp.js"
   },
   "scripts": {
     "start": "node bin/hits.js",
@@ -51,7 +52,7 @@
   "devDependencies": {},
   "repository": {
     "type": "git",
-    "url": "git+https://lhjnano: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@github.com/lhjnano/hits.git"
+    "url": "git+https://github.com/lhjnano/hits.git"
   },
   "bugs": {
     "url": "https://github.com/lhjnano/hits/issues"