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

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

Search AI Tools

Install this agent skill to your Project

SKILL.md

Unsloth MCP Server Development

Project Overview

Architecture

Available Tools

Development Workflow

Running Tests

Building

Benchmarking

CLI Testing

Code Patterns

Adding a New Tool

Using Utilities

Logging

Cache

Metrics

Configuration

Configuration

Testing Strategy

Unit Tests (56 tests)

Integration Tests (10 tests)

Common Tasks

Update Version

Add New Utility

Fix Performance Issue

CI/CD

Performance Targets

Deployment

Docker

Native

MCP Settings

Troubleshooting

Tests Failing

Build Errors

Pre-commit Hooks Not Running

Resources

Quick Commands Reference

Contact & Support