Unsloth MCP Server

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

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

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

Development Workflow

Running Tests

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

Building

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

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

CLI Testing

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

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

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

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

{
  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']
  }
}

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

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);
}

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

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

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

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

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

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

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

Configuration

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

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

Configuration

Config files (priority order):

1. Environment variables (UNSLOTH_*)
2. ./config.json
3. ~/.unsloth-mcp-config.json
4. Default values

Example config.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

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

Add New Utility

1. Create src/utils/your-utility.ts
2. Export class and singleton
3. Add tests in src/__tests__/your-utility.test.ts
4. Import in src/index.ts
5. Document in README

Fix Performance Issue

1. Run benchmarks: npm run bench
2. Compare with baseline
3. Identify bottleneck
4. Optimize
5. Run benchmarks again
6. 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

Deployment

Docker

docker-compose build
docker-compose up unsloth-mcp

Native

npm install
npm run build
npm start

MCP Settings

{
  "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

# 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