Unsloth MCP Server Development

Project-specific guidance for the Unsloth MCP Server codebase.

Project Overview

A production-ready MCP (Model Context Protocol) server that enables Claude to fine-tune LLMs using Unsloth.

Location: /home/user/unsloth-mcp-server

Key Stats:

•Version: 2.1.0
•12 MCP tools
•66 tests (100% passing)
•7 test suites
•TypeScript with strict mode
•Full CI/CD pipeline

Architecture

code

src/
├── index.ts           # Main MCP server (1414 lines)
├── cli.ts             # CLI tool (245 lines)
├── utils/            # Utility modules
│   ├── logger.ts     # Winston logging
│   ├── validation.ts # Input validation
│   ├── security.ts   # Security controls
│   ├── metrics.ts    # Performance tracking
│   ├── config.ts     # Configuration system
│   ├── cache.ts      # Dual-layer cache
│   └── progress.ts   # Progress tracking
└── __tests__/        # Test suites
    ├── validation.test.ts
    ├── security.test.ts
    ├── metrics.test.ts
    ├── cache.test.ts
    ├── config.test.ts
    ├── progress.test.ts
    └── integration.test.ts

Available Tools

•check_installation - Verify Unsloth is installed
•list_supported_models - List available models (with caching)
•load_model - Load model with optimizations
•finetune_model - Fine-tune with LoRA
•generate_text - Generate text from model
•export_model - Export to GGUF/Ollama/vLLM/HF
•train_superbpe_tokenizer - Train SuperBPE tokenizer
•get_model_info - Get model architecture details
•compare_tokenizers - Compare tokenization efficiency
•benchmark_model - Benchmark performance
•list_datasets - Search Hugging Face datasets
•prepare_dataset - Prepare dataset for training

Development Workflow

Running Tests

bash

npm test                  # All tests
npm test:watch           # Watch mode
npm test:coverage        # With coverage
npm test -- integration  # Just integration tests

Building

bash

npm run build            # Compile TypeScript
npm run lint             # Type check + ESLint
npm run lint:fix         # Auto-fix issues
npm run format           # Format with Prettier

Benchmarking

bash

npm run bench            # Run performance benchmarks
npm run bench:compare baseline.json results.json  # Compare

CLI Testing

bash

npm run cli help         # Show help
npm run cli check        # Check installation
npm run cli models       # List models
npm run cli config       # Show config
npm run cli metrics      # Show metrics

Code Patterns

Adding a New Tool

•Add validation in src/utils/validation.ts:

typescript

case 'your_new_tool':
  validators.requiredField(args, 'required_param');
  validators.optionalPositive(args, 'optional_param', 'Optional param');
  break;

•Add tool definition in src/index.ts (ListToolsRequestSchema):

typescript

{
  name: 'your_new_tool',
  description: 'Clear description of what it does',
  inputSchema: {
    type: 'object',
    properties: {
      required_param: {
        type: 'string',
        description: 'Parameter description'
      }
    },
    required: ['required_param']
  }
}

•Add handler in src/index.ts (CallToolRequestSchema):

typescript

case 'your_new_tool': {
  const { required_param } = args as { required_param: string };

  const script = `
import json
try:
    # Your Python code here
    result = {"success": True}
    print(json.dumps(result))
except Exception as e:
    print(json.dumps({"error": str(e)}))
`;

  const result = await this.executeUnslothScript(script);
  return this.createSuccessResponse(name, startTime, result);
}

•Add tests in src/__tests__/validation.test.ts:

typescript

describe('your_new_tool', () => {
  it('should validate required parameters', () => {
    expect(() =>
      validateToolInputs('your_new_tool', {
        required_param: 'value',
      })
    ).not.toThrow();
  });

  it('should reject missing parameters', () => {
    expect(() => validateToolInputs('your_new_tool', {})).toThrow('required_param is required');
  });
});

Using Utilities

Logging

typescript

import logger from './utils/logger.js';

logger.info('Operation started', { param: value });
logger.debug('Debug info', { details });
logger.error('Error occurred', { error: err.message });

Cache

typescript

import { cache } from './utils/cache.js';

// Check cache first
const cached = cache.get<ModelList>('models');
if (cached) return cached;

// Compute and cache
const models = await loadModels();
cache.set('models', models, 3600); // 1 hour TTL

Metrics

typescript

import { metricsCollector } from './utils/metrics.js';

const startTime = Date.now();
// ... operation ...
metricsCollector.endTool('tool_name', startTime, true);

const stats = metricsCollector.getStats('tool_name');

Configuration

typescript

import { config } from './utils/config.js';

const serverConfig = config.get();
const cacheEnabled = serverConfig.cache.enabled;

Configuration

Config files (priority order):

•Environment variables (UNSLOTH_*)
•./config.json
•~/.unsloth-mcp-config.json
•Default values

Example config.json:

json

{
  "cache": {
    "enabled": true,
    "ttl": 3600,
    "maxSize": 1000
  },
  "logging": {
    "level": "info"
  }
}

Testing Strategy

Unit Tests (56 tests)

•Validation: 15 tests
•Security: 10 tests
•Metrics: 15 tests
•Cache: 5 tests
•Config: 5 tests
•Progress: 3 tests

Integration Tests (10 tests)

•Utilities working together
•Full workflow simulation
•Error handling across modules
•Performance under load

Common Tasks

Update Version

•Update package.json version
•Update src/index.ts version (2 places)
•Update CHANGELOG.md
•Commit: feat: bump version to X.Y.Z

Add New Utility

•Create src/utils/your-utility.ts
•Export class and singleton
•Add tests in src/__tests__/your-utility.test.ts
•Import in src/index.ts
•Document in README

Fix Performance Issue

•Run benchmarks: npm run bench
•Compare with baseline
•Identify bottleneck
•Optimize
•Run benchmarks again
•Update baseline if improved >10%

CI/CD

GitHub Actions runs on every push/PR:

•Test on Node 18.x and 20.x
•TypeScript type checking
•ESLint validation
•Build verification
•Security audit

Pre-commit hooks (Husky):

•ESLint --fix on staged .ts files
•Prettier on staged files
•TypeScript type checking

Performance Targets

Operation	Target	Actual
Validation	<0.01ms	✅ 0.005ms
Cache Get	<0.01ms	✅ 0.010ms
Cache Set	<0.02ms	✅ 0.015ms
Config Get	<0.005ms	✅ 0.005ms
Metrics	<0.01ms	✅ 0.010ms

Deployment

Docker

bash

docker-compose build
docker-compose up unsloth-mcp

Native

bash

npm install
npm run build
npm start

MCP Settings

json

{
  "mcpServers": {
    "unsloth-server": {
      "command": "node",
      "args": ["/path/to/build/index.js"],
      "env": {
        "HUGGINGFACE_TOKEN": "your_token"
      }
    }
  }
}

Troubleshooting

Tests Failing

•Check Node version (18 or 20)
•Run npm install again
•Clear cache: rm -rf .cache/

Build Errors

•Run npm run lint to see TypeScript errors
•Check tsconfig.json is valid
•Verify all imports end with .js

Pre-commit Hooks Not Running

•Run npm run prepare
•Check .husky/pre-commit exists
•Verify executable: chmod +x .husky/pre-commit

Resources

•README.md - User documentation
•PRODUCTION_GUIDE.md - Deployment guide
•CHANGELOG.md - Version history
•CONTRIBUTING.md - Contribution guidelines
•examples/ - Usage examples
•benchmarks/ - Performance benchmarks

Quick Commands Reference

bash

# Development
npm run dev          # Run in dev mode
npm run cli check    # Test CLI

# Testing
npm test             # Run all tests
npm run lint         # Check types and lint

# Building
npm run build        # Build for production

# Benchmarking
npm run bench        # Run benchmarks

# Formatting
npm run format       # Format all files

Contact & Support

•Issues: GitHub Issues
•Docs: See README.md and examples/
•Tests: Run npm test for examples