Q-Chat

A powerful chat application built with Node.js, using Ollama API and the qwen3:8b model. This npm package provides a complete chat interface with modern UI and extensible architecture.

Features

• 🚀 Real-time Chat: Interactive chat interface with AI assistant
• 🤖 Multiple Models: Support for various Ollama models (qwen3:8b, mistral:7b, etc.)
• 📝 Markdown Support: Rich text rendering with code highlighting
• 🎨 Modern UI: Dark theme with responsive design
• 🔧 Debug Mode: Built-in debugging capabilities
• 📱 Responsive: Works on desktop and mobile devices
• 🛠️ v1.0.3 Fixes:
  • Fixed model list display issues (no more undefined)
  • Improved JSON handling for different environments
  • Enhanced error handling and debugging output
  • Fixed static file serving in development mode

Quick Start

Prerequisites

• Node.js (>=14.0.0)
• Ollama installed and running (optional, uses mock data by default)

Installation

npm install q-chat

Basic Usage

const { startServer } = require('q-chat');

// Start the server
startServer({
    port: 3000,
    debug: true  // Enable debug mode
});

Development Mode

# Clone the repository
git clone <repository-url>
cd q-chat

# Install dependencies
npm install

# Start development server (backend + frontend)
npm run dev

# Access the application
# Frontend: http://localhost:5173
# Backend API: http://localhost:3000/api

API Documentation

Core Endpoints

GET /api/models

Returns available Ollama models.

Response:

{
    "success": true,
    "data": [
        {
            "name": "qwen3:8b",
            "size": "7B",
            "modified": "2023-11-01"
        }
    ]
}

POST /api/chat

Send a chat message to the AI model.

Request Body:

{
    "message": "Hello, how are you?",
    "model": "qwen3:8b"
}

Response:

{
    "success": true,
    "data": {
        "id": 1234567890,
        "role": "assistant",
        "content": "I'm doing well, thank you!",
        "timestamp": "2023-11-05T10:30:00.000Z",
        "model": "qwen3:8b"
    },
    "history": [...]
}

GET /api/history

Get chat history.

DELETE /api/history

Clear chat history.

Extension Endpoints

GET /api/tree/connect

Directory tree integration interface.

GET /api/editor/connect

Code editor integration interface.

GET /api/mcp/connect

MCP (Model Context Protocol) integration interface.

Development

Project Structure

q-chat/
├── src/
│   ├── backend/
│   │   └── server.js          # Main server file
│   └── frontend/
│       ├── index.html         # Main HTML file
│       ├── styles.css         # CSS styles
│       └── script.js          # Frontend JavaScript
├── test/
│   ├── server.test.js         # Backend tests
│   └── frontend.test.js       # Frontend tests
├── dist/                      # Build output
├── package.json
└── README.md

Scripts

# Development
npm run dev              # Start both backend and frontend
npm run dev:backend      # Start backend only
npm run dev:frontend     # Start frontend only

# Build
npm run build            # Build both backend and frontend
npm run build:backend    # Build backend only
npm run build:frontend   # Build frontend only

# Testing
npm test                 # Run all tests
npm run test:watch       # Run tests in watch mode

# Linting
npm run lint             # Run ESLint

# Preview
npm run preview          # Preview built application

Debug Mode

Enable debug mode to see detailed logs:

# Environment variable
DEBUG=true npm run dev

# Command line flag
npm run dev -- --debug

# URL parameter (frontend)
http://localhost:5173?debug=true

Extensibility

Directory Tree Integration

To integrate a directory tree component:

1. Call /api/tree/connect for available methods
2. Implement tree rendering component
3. Handle expand/collapse operations

Code Editor Integration

To integrate a code editor:

1. Call /api/editor/connect for available methods
2. Integrate Monaco Editor or CodeMirror
3. Implement file operations

MCP Integration

To integrate MCP tools:

1. Call /api/mcp/connect for available methods
2. Implement tool execution interface
3. Handle tool registration and execution

Testing

Run the test suite:

npm test

Test coverage includes:

• Backend API endpoints
• Frontend functionality (simulated)
• Error handling
• Edge cases

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• Create an issue on GitHub
• Check the documentation
• Enable debug mode for troubleshooting

Changelog

v1.0.0

• Initial release
• Basic chat functionality
• Mock Ollama integration
• Modern UI with dark theme
• Markdown support
• Debug mode
• Test suite