unsloth-mcp-server

name	unsloth-mcp-server
description	Work with the Unsloth MCP Server codebase. Use when maintaining, extending, or debugging this specific MCP server implementation. Provides architecture knowledge, code patterns, and development workflows.

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

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

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